Skip navigation.

eDocs Home > BEA AquaLogic Enterprise Security 2.1 Documentation > Installing Web Server and Web Services Security Service Modules > Configuring the Web Services SSM

Installing Web Server and Web Services Security Service Modules

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents View as PDF   Get Adobe Reader

Configuring the Web Services SSM

This section covers the configuration tasks that you must perform after completing the post installation procedures as described in Post Installation Tasks

Web Services Security Service Module (SSM) configuration consists of the following tasks:

 

Configuring and Deploying Policy for the Web Services SSM

You configure and deploy policy on a Web Services SSM the same as you would on an IIS Web Server SSM or an Apache Web Server SSM. To see the Web Server SSM procedures, go to Configuring and Deploying Policy for the Web Server SSM

 

Binding the Web Services SSM to a Web Services Client

The Web Services SSM can be used to protect application resources on customer designed and implemented web services clients. The Web Services Application Programming Interface (API) is provided for this purpose. For a description of the Web Services API, see Programming Security for Web Services.

 

Configuring SSL in the Web Services SSM

When you create a new WS-SSM instance, the WS-SSM is accessible via the HTTP protocol. The protocol is best for development and for debugging purposes, but should not be used in a production environment. For a production environment, BEA recommends that you use either one-way SSL or two-way SSL (SSL with client authentication).

This section describes how to enable one-way and two-way SSL communication between a Web Services SSM and its client. It is assumed that the reader has basic knowledge of the SSL protocol, Certificate Authorities (CA), X.509 certificates and Java Key Stores (JKS).

In this section, %SSM_INST_HOME% represents the installation folder of the WS-SSM instance in the file system, for example, c:\bea\ales21-ssm\webservice-ssm\instance\wsssm

Configuring One-Way SSL

When you configure a WS-SSM to use one-way SSL communication, the WS-SSM sends its identity certificate, and the CA that signed the identity certificate must be trusted by the client. The WS-SSM does not authenticate the client; thus, the client does not have to have its own certificate.

To configure a WS-SSM to use one-way SSL:

  1. Stop the WS-SSM if it is running
  2. Delete the contents of the %SSM_INST_HOME%\apps directory.
  3. Run the following command to regenerate the content of the apps directory:
    4. %SSM_INST_HOME%\adm\ssmwsInstance.bat -h
  4. Restart the WS-SSM.

The JKS of the certificates (identities) and the alias that uniquely identifies the identity within the store is defined by the <identity> XML element in the %SSM_INST_HOME%\apps\ssmws-asi\SAR-INF\config.xml file. By default, the key store file is %SSM_INST_HOME%\ssl\identity.jks and the alias is wles-ssm.

WARNING: Do not delete the identity.jks file, as it is used by other ALES servers to authenticate the WS-SSM. However, you can add any number of additional certificates to that file and reference them by unique aliases.

To access the WS-SSM using SSL, the client must use the HTTPS protocol, rather than HTTP. The client must also be configured to trust the server's certificate; otherwise the connection will be closed. This requires that the CA that signed the server's certificate must be in the client's trusted JKS.

The client's trusted JKS is defined by the system property javax.net.ssl.trustStore and the JKS password is defined by the system property javax.net.ssl.trustStorePassword property. (These properties are defined in the Java Secure Socket Extension (JSSE) documentation.) You can specify these system properties by running the WS-SSM Java client with command line arguments such as:

-Djavax.net.ssl.trustStore=C:\jks\trust.jks
-Djavax.net.ssl.trustStorePassword="secretword"

For testing purposes, the client can use the %SSM_INST_HOME%\ssl\trust.jks JKS, which contains the CA that was used to sign the default server's identity.

Configuring Two-Way SSL

In two-way SSL (SSL with client authentication), the WS-SSM and the client must each present the other with a trusted certificate. Configuring two-way SSL is similar to configuring one-way SSL, but addition steps have to be taken to allow the WS-SSM server to trust the client.

Configuring a WS-SSM for Two-Way SSL

To configure the WS-SSM for two-way SSL communication:

  1. Add the CA that signed the client's certificate to the trusted CA list of the WS-SSM. By default this list is the %SSM_INST_HOME%/ssl/trust.jks file.

    2. The WS-SSM's JKS for trusted CAs is defined by the <trust> element in the %SSM_INST_HOME%\apps\ssmws-asi\SAR-INF\config.xml configuration file. You can specify the filter for the alias prefixes inside the trusted JKS using the aliasPrefix XML attribute. If you specify an aliasPrefix attribute, then only the aliases that start with the given prefix will be used. By default the prefix of the alias must start with domain(<YOUR_ALES_DOMAIN>). You can use one of these two approaches when adding a new trusted CA certificate:

  1. Add the client's identity to the WS-SSM's trusted peer list. By default this list is the %SSM_INST_HOME%/ssl/peer.jks file. The JKS location is determined by the <peer> XML element inside the %SSM_INST_HOME%\apps\ssmws-asi\SAR-INF\config.xml file.
  2. Stop the WS-SSM if it is running
  3. Delete the contents of the %SSM_INST_HOME%\apps directory.
  4. Run the following command to regenerate the content of the apps directory:
    5. %SSM_INST_HOME%\adm\ssmwsInstance.bat -s
  5. Restart the WS-SSM.

WARNING: Do not delete the trust.jks or peer.jks files, as they are used for communication between the WS-SSM and other ALES servers. The best practice is to add new certificates to the same files and reference them by unique aliases.

Configuring a Web Services Client for Two-Way SSL

In contrast to one-way SSL, in the case of two-way SSL, the client has to supply its certificate (identity) upon the server's request. The JKS location that stores the identity is defined by the javax.net.ssl.keyStore system property. The password for decrypting the identity is defined by the javax.net.ssl.keyStorePassword system property. For more information, see the Java Secure Socket Extension (JSSE) documentation.

For development and testing purposes, you can use the %SSM_INST_HOME%\ssl\identity.jks key store, as it contains the certificate under the wles-ssm alias that it trusted by the server in its default configuration; moreover, the CA that signed the certificate is also trusted. You should never use this approach in production.

The steps necessary to create and use a Web Services client with two-way SSL can vary; the final goal is to create a JKS file that contains the right certificate chain and the private key. This section describes an example of how set up a Web Services client for two-way SSL. In the example, we use the keytool utility is used that is shipped with the standard Java Development Kit (JDK). For complete information about this utility, consult the Sun Microsystems keytool documentation.

To create the client's identity store.

  1. Create your private/public key pair, self-signed certificate and a new JKS to store it.
    2. keytool -genkey -dname "cn=WS-SSM Client" -alias "WS-SSM Client" -keystore clientkeystore.jks -validity 365
  2. Create Certificate Signing Request:

    3. keytool -certreq -alias "WS-SSM Client" -file WS-SSM-Client.csr -keystore clientkeystore.jks

  3. Send the WS-SSM-Client.csr file to a CA for signing or sign it by your own CA.
  4. Import the CA's certificate (CA.crt):
    5. keytool -import -file CA.crt -alias Trusted-CA -keystore clientkeystore.jks
  5. Import the signed Certificate Reply from the CA (WS-SSM-Client.crt):
    6. keytool -import -file WS-SSM-Client.crt -keystore clientkeystore.jks -alias "WS-SSM Client"
  6. Delete the CA's certificate, which is no longer needed:
    7. keytool -delete -alias Trusted-CA -keystore clientkeystore.jks

You can test the key store by executing the following command: 

keytool -list -keystore clientkeystore.jks -v

The output should be similar to the output in Listing 6-1:

Listing 6-1 Example Keytool List Output

Keystore type: jks
Keystore provider: SUN
Your keystore contains 1 entry
Alias name: ws-ssm client
Creation date: Apr 14, 2006
Entry type: keyEntry
Certificate chain length: 2
Certificate[1]:
Owner: CN=WS-SSM Client
Issuer: CN=exampleCN, OU=exampleOU, O="exampleO", L=San Exemplo, ST=California, C=US
Serial number: 1
Valid from: Fri Apr 14 12:45:11 EDT 2006 until: Sat Apr 14 12:45:11 EDT 2007
Certificate fingerprints:
         MD5:  BD:2F:C4:9E:27:CB:3A:8F:D4:8E:FB:EA:4E:86:6E:9C
         SHA1: 11:56:D9:94:A0:E2:9B:BC:AD:EF:FD:83:0A:39:5F:0C:0A:B0:9D:22
Certificate[2]:
Owner: CN=exampleCN, OU=exampleOU, O="exampleO", L=San Exemplo, ST=California, C=US
Issuer: CN=exampleCN, OU=exampleOU, O="exampleO", L=San Exemplo, ST=California, C=US
Serial number: -7abad5cc20db248d7901d4359b06dbb5
Valid from: Thu Mar 09 18:42:33 EST 2006 until: Sat Mar 10 18:42:33 EST 2018
Certificate fingerprints:
         MD5:  CF:F8:EA:64:84:02:6F:AD:C4:2E:2B:4B:AC:20:7B:76
         SHA1: 7C:5A:C1:9F:E5:03:26:7E:D7:50:8A:72:20:24:8A:7E:0F:D8:22:CF
*******************************************

At this point, the client can use the clientkeystore.jks file as the client's identity key store.

To make the WS-SSM trust the client identity:

  1. Import the CA's certificate to the server's trust key store (the trust.jks file):
    2. keytool -import -file CA.crt -alias Trusted-CA -keystore trust.jks
  2. Import the client's identity certificate to the server's key store of trusted peers (peer.jks)
    3. keytool -import -file WS-SSM-Client.crt -alias Trusted-WS-Client -keystore peer.jks
  3. In the %SSM_INST_HOME%\apps\ssmws-asi\SAR-INF\config.xml configuration file, remove the aliasPrefix XML attribute under the <trust> element.

Now you should be able to establish two-way SSL communication using the client's key store created in the example.

 

What's Next

You have completed the configuration tasks for the Web Services Security Service Module (SSM). You can now start the SSM processes.

 

Skip navigation bar  Back to Top Previous Next