Setting Up To Use XWS-Security With the Sample Applications

This addendum discusses creating and running applications that use the XWS-Security framework, and deploying these applications onto the Sun Java System Application Server Platform Edition 8. For deployment onto other containers, read the README.txt file for the example applications for more information.

Follow these steps to set up your system to create, run, and deploy the sample applications included in this release that use the XWS-Security framework.

Make sure that you are running the Java WSDP 1.5 on the Java 2 Platform, Standard Edition version 1.4.2 or higher. If not, you can download the JDK from:
http://java.sun.com/j2se/.

Set system properties as described in Setting System Properties.

If you are using version 1.4.x of the Java SDK, configure a JCE provider as discussed in Configuring a JCE Provider.

Follow the steps in Setting Up the Application Server For the Examples.

Setting System Properties

The asant (or ant) build files for the XWS-Security samples shipped with this release rely on certain environment variables being set correctly. Make sure that the following environment variables are set to the locations specified in this list. If you are not sure how to set these environment variables, refer to the file <JWSDP_HOME>/xws-security/docs/samples.html for more specific information.

Set JAVA_HOME to the location of your J2SE installation directory, for example, /home/<your_name>/j2sdk1.4.2_04/.

Set JWSDP_HOME to the location of your Java WSDP 1.5 installation directory, for example, /home/<your_name>/jwsdp-1.5/.

Set SJSAS_HOME to the location of your Application Server installation directory, for example, /home/<your_name>/SUNWappserver/. If you are deploying onto a different container, set SJSWS_HOME or TOMCAT_HOME instead.

Set ANT_HOME to the location where the asant (or ant) executable can be found. If you are running on the Application Server, this will be <SJSAS_HOME>/bin/. If you are running on a different container, this location will probably be <JWSDP_HOME>/apache-ant/bin/.

Set the PATH variable so that it contains these directories: <JWSDP_HOME>/jwsdp-shared/bin/, <SJSAS_HOME>/bin/, <ANT_HOME>/, and <JAVA_HOME>/bin/.

Configuring a JCE Provider

The Java Cryptography Extension (JCE) provider included with J2SE 1.4.x does not support RSA encryption. Because the XWS-Security sample applications use RSA encryption, you must download and install a JCE provider that does support RSA encryption in order for these sample applications to run, if you are using encryption, and if you are using a version of the Java SDK prior to version 1.5.0.

Note: RSA is public-key encryption technology developed by RSA Data Security, Inc. The acronym stands for Rivest, Shamir, and Adelman, the inventors of the technology.

If you are running the Application Server on version 1.5 of the Java SDK, the JCE provider is already configured properly. If you are running the Application Server on version 1.4.x of the Java SDK, follow these steps to add a JCE provider statically as part of your JDK environment:

Download and install a JCE provider JAR (Java ARchive) file.

Copy the JCE provider JAR file to <JAVA_HOME>/jre/lib/ext/.

Stop the Application Server (or other container). If the Application Server is not stopped, and restarted later in this process, the JCE provider will not be recognized by the Application Server.

Edit the <JAVA_HOME>/jre/lib/security/java.security properties file in any text editor. Add the JCE provider you've just downloaded to this file. The java.security file contains detailed instructions for adding this provider. Basically, you need to add a line of the following format in a location with similar properties:

security.provider.<n>=<provider class name>

In this example, <n> is the order of preference to be used by the Application Server when evaluating security providers. Set <n> to 2 for the JCE provider you've just added.

For example, if you've downloaded ABC JCE provider, and the Java class name of the ABC provider's main class is org.abc.ABCProvider, add this line.

security.provider.2=org.abc.ABCProvider

Make sure that the Sun security provider remains at the highest preference, with a value of 1.

security.provider.1=sun.security.provider.Sun

Adjust the levels of the other security providers downward so that there is only one security provider at each level.

The following is an example of a java.security file that provides the necessary JCE provider and keeps the existing providers in the correct locations.

security.provider.1=sun.security.provider.Sun security.provider.2=org.abc.ABCProvider security.provider.3=com.sun.net.ssl.internal.ssl.Prov ider security.provider.4=com.sun.rsajca.Provider security.provider.5=com.sun.crypto.provider.SunJCE security.provider.6=sun.security.jgss.SunProvider

Save and close the file.

Set the provider permissions for this JCE provider in the server policy file of the Application Server as described in Setting Up the Application Server For the Examples.

Restart the Application Server (or other container). To save time with stopping and restarting the server, you can complete the steps in Setting Up the Application Server For the Examples before restarting the Application Server.

Setting Up the Application Server For the Examples

To set up the container for running the XWS-Security sample applications included with this release, you need to specify on which container you are running the asant (or ant) build targets, and you must point the container to the keystore and truststore files to be used to run the XWS-Security sample applications. For the sample applications, these are the keystore and truststore files included in the /xws-security/etc/ directory. For further discussion of using keystores and truststores with XWS-Security applications, read Keystore and Truststore Files with XWS-Security.

This tutorial describes deployment to the Application Server. For information on setting up other containers, refer to the README.txt file located in the top-level directory for each sample application.

Stop the Application Server.

Add the following permissions to the server policy file of the Application Server. This file can be found at <SJSAS_HOME>/domains/domain1/config/server.policy.

Add the following code near the end of the file for the jaas-sample sample application.

grant codeBase "file:${com.sun.aas.instanceRoot}/applications/j2ee-modules/jaassample/WEB-INF/-" { permission javax.security.auth.AuthPermission "modifyPrincipals"; permission javax.security.auth.AuthPermission "modifyPrivateCredentials"; permission javax.security.auth.PrivateCredentialPermission "* * \"*\"","read"; permission javax.security.auth.AuthPermission "getSubject"; permission javax.security.auth.AuthPermission "createLoginContext.XWS_SECURITY_SERVER"; };

Add the following code near the end of the file for the simple sample application.

If you are using a 3rd party JCE provider, include the putProvider security permission for that application here as well so that signature and encryption work. The word <Provider> in the last permission should be replaced by the standard name of the third-party JCE provider. For example, if the third party JCE provider specified in java.security file has a standard name ABC, replace <Provider> with ABC. If you are using version 1.5 or higher of the Java SDK, do not include the putProvider for the JCE provider.

grant codeBase "file:${com.sun.aas.instanceRoot}/applications/j2ee-modules/securesimple/WEB-INF/-" { permission javax.security.auth.AuthPermission "modifyPrincipals"; permission javax.security.auth.AuthPermission "modifyPrivateCredentials"; permission javax.security.auth.AuthPermission "modifyPublicCredentials"; permission javax.security.auth.PrivateCredentialPermission "* * \"*\"","read"; permission javax.security.auth.AuthPermission "getSubject"; permission java.security.SecurityPermission "putProviderProperty.<Provider>"; };

Save and exit the policy file.

Restart the Application Server.

Keystore and Truststore Files with XWS-Security

For the simple sample, the keystore, truststore, and symmetric-key databases used by that example are located in the <JWSDP_HOME>/xws-security/etc/ directory. The locations of these files have been configured in the <JWSDP_HOME>/xws-security/etc/client-security-env.properties and <JWSDP_HOME>/xws-security/etc/server-security-env.properties files for the client and server respectively. These property files are used by the SecurityEnvironmentHandler to handle the Callbacks.

To plug in your own keystores and truststores for an application, make sure that the certificates are of version 3, and that the client truststore contains the certificate of the certificate authority that issued the server's certificate, and vice versa.

XWS-Security requires version 3 (v3) certificates when the keyReferenceType attribute (specified on a xwss:X509Token element) has a value of Identifier, which indicates the use of an X.509 SubjectKeyIdentifier extension. For all other values of the keyReferenceType attribute, a v1 certificate can also be used. Version 3 includes requirements specified by the WSS X509 Token Profile.

Setting Build Properties

To run the sample applications, you must edit the sample build.properties file for that sample application and specify information that is unique to your system and to your installation of Java WSDP 1.5 and the Application Server (or other container).

To edit the build.properties file for the example you want to run, follow these steps:

Change to directory for the sample application you want to run: <JWSDP_HOME>/xws-security/samples/<example>/.

Copy the build.properties.sample file to build.properties.

Edit the build.properties file, checking that the following properties are set correctly for your system:

javahome: Set this to the directory where J2SE version 1.4.2 or higher is installed.

sjsas.home: If you are running under the Application Server, set this to the directory where the Application Server is installed and make sure there is not a comment symbol (#) to the left of this entry. If you are running under a different container, set the location for its install directory under the appropriate property name (tomcat.home or sjsws.home) and uncomment that entry instead. Only one of the container home properties should be uncommented at any one time.

username, password: Enter the appropriate username and password values for a user assigned to the role of admin for the container instance being used for this sample. A user with this role is authorized to deploy applications onto the Application Server.

endpoint.host, endpoint.port: If you changed the default host and/or port during installation of the Application Server (or other container), change these properties to the correct values for your host and port. If you installed the Application Server using the default values, these properties will already be set to the correct values.

VS.DIR=If you are running under the Sun Java System Web Server, enter the directory for the virtual server. If you are running under any other container, you do not need to modify this property.

jwsdp.home: Set this property to the directory where Java WSDP is installed. The keystore and truststore URL's for the client are configured relative to this property.

http.proxyHost, http.proxyPort: If you are using remote endpoints, set these properties to the correct proxy server address and port. If you are not using remote endpoints, put a comment character (#) before these properties. A proxy server will follow the format of myserver.mycompany.com. The proxy port is the port on which the proxy host is running, for example, 8080.

Save and exit the build.properties file.

All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.