Integrating ALES with Application Environments

Configuring the Web Services SSM

This section describes how to configure and use a Web Services Security Service Module (WS-SSM), after you have completed the installation and post-installation procedures described in Installing Security Service Modules. It includes the following sections:

Overview of the Web Services SSM

The Web Services SSM provides an application programming interface (API) that allows security developers to write custom application clients that invoke AquaLogic Enterprise Security services through SOAP. These interfaces support the most commonly required security functions, such as authentication, authorization, and auditing, and are organized into services that are logically grouped by functionality. A Web Services client can use the Web Services SSM (which incorporates the Security Services APIs, the Security Framework, and the configured security providers) to make access control decisions for the web server to which it is connected. Then you can use the AquaLogic Enterprise Security Administration Server to configure and deploy a security configuration to protect the web server application resources. Thus, the Web Services SSM enables security administrators and web developers to perform security tasks for applications running on a web server.

The Web Services SSM includes a set of examples that illustrate Web Services client development in different environments. The examples are located in BEA_HOME/ales22-ssm/examples:

ssmWorkshop

Demonstrates how to access the ALES Web Services SSM through its published WSDL in a WebLogic Workshop 8.1 or 9.x environment.

ssmNET

Demonstrates how to access the ALES Web Services SSM through its published WSDL in the .NET 1.1 or 2.0 environment.

javaWebServiceClient

Demonstrates a simple Java client that accesses the ALES Web Services SSM for authorization.

XACMLClient

Demonstrates how to access the ALES Web Services SSM using the XACML protocol.

For more information about developing security services for Web Services client applications, see Programming Security for Web Services.

Web Services Security Service APIs

The Web Services Security Service APIs enable access to the ALES security framework. These APIs provide the following security services:

Authentication Service

There are two variations of authentication, JAAS-based and identity assertion. JAAS-based authentication collects evidence (credentials) from a user in order to establish user identity.

Identity assertion authentication consumes a trusted token object to establish identity. The Web Services SSM supports both types of authentication.

Authorization Service

In addition to providing a simple permit or denied decision on a URL, the authorization service also has the ability to return attributes into the request as determined by the access control policy implemented. Because the inclusion of coding in the application to handle these attributes creates an undue coupling between the application and security infrastructure, the SSM inserts these returned attributes into the HTTP request header. Depending upon the technology used (ASP, CGI, ISAPI), these headers can be extracted and used by the application.

Auditing Service

The auditing service audits all transactions through the security subsystem. Every URL accessed is sent through the auditing infrastructure.

Role Mapping Service

Although roles are primarily used in authorization, some applications may wish to have access to the roles to which a user is mapped for the purposes of role-based personalization. In order to provide this information to the running applications, the Web Services SSM adds a list of roles to the HTTP request header. Depending upon the technology used (ASP, CGI, ISAPI), the application can extract this list of roles from the header and use it.

Credential Service

The credential service returns sensitive credentials to an application so that the application can use systems that require a secondary (or tertiary) layer of authentication. The Web Services SSM extracts mapped credentials from the security system and makes them available in the HTTP header for use by the application. Depending upon the technology used (ASP, CGI, ISAPI), the application can extract the credential headers and use them to authenticate to other back-end systems.

Configuring and Deploying Policy for the Web Services SSM

You configure and deploy policy on a Web Services SSM in the same way as you would on an IIS Web Server SSM or an Apache Web Server SSM. For information about the Web Server SSM procedures, see 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\ales22-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:

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.

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:

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.

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:

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:

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

Adding New Identity Assertion Types

To add support for new assertion types to the Web Services SSM:

Now, when you restart the Web Services SSM, it will use the new holder implementation and the mapping entries to convert back and forth between the token's XML and Java representations.

public class TestCredHolderImpl implements CredentialHolder
{
    private String m_cookie;
    public static final String m_Type = "TestIA";

    public void setCookie(String cookie)
    {
        m_cookie = cookie;
    }

    public String getCookie()
    {
        return m_cookie;
    }

    public Object getObject()
    {
        return getCookie();
    }

    public void setObject(Object cred)
    {
        setCookie((String)cred);
    }
    public String getType()
    {
        return TestCredentialHolderImpl.m_Type;
    }
    public String getAsString()
    {
        return m_cookie;
    }
}