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:
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
:
Demonstrates how to access the ALES Web Services SSM through its published WSDL in a WebLogic Workshop 8.1 or 9.x environment.
Demonstrates how to access the ALES Web Services SSM through its published WSDL in the .NET 1.1 or 2.0 environment.
Demonstrates a simple Java client that accesses the ALES Web Services SSM for authorization.
Demonstrates how to access the ALES Web Services SSM using the XACML protocol.
Note: | For a Web Services client developed on Axis, use Axis 1.2 or later. For more information, see the Apache Axis site: http://ws.apache.org/axis/ . |
For more information about developing security services for Web Services client applications, see Programming Security for Web Services.
The Web Services Security Service APIs enable access to the ALES security framework. These APIs provide the following security services:
Note: | The following topics provide a very brief description of these APIs. For more information, see Programming Security for Web Services. |
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.
Note: | For more information on JAAS, see Sun's documentation at http://java.sun.com/products/jaas/. |
Identity assertion authentication consumes a trusted token object to establish identity. The Web Services SSM supports both types of authentication.
Note: | The Web Services SSM does not support custom callback types. |
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.
The auditing service audits all transactions through the security subsystem. Every URL accessed is sent through the auditing infrastructure.
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.
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.
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.
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.
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
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
.
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.
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.
To configure the WS-SSM for two-way SSL communication:
%SSM_INST_HOME%/ssl/trust.jks
file.
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:
domain(<YOUR_ALES_DOMAIN>)
.aliasPrefix
XML attribute. If there is no aliasPrefix
attribute, then the WS-SSM trusts all CAs stored in the trust.jks
.%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.%SSM_INST_HOME%\apps
directory.apps
directory:%SSM_INST_HOME%\adm\ssmwsInstance.bat -s
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. |
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.
keytool -genkey -dname "cn=WS-SSM Client" -alias "WS-SSM Client" -keystore clientkeystore.jks -validity 365
keytool -certreq -alias "WS-SSM Client" -file WS-SSM-Client.csr -keystore clientkeystore.jks
WS-SSM-Client.csr
file to a CA for signing or sign it by your own CA.CA.crt
):keytool -import -file CA.crt -alias Trusted-CA -keystore clientkeystore.jks
WS-SSM-Client.crt
):keytool -import -file WS-SSM-Client.crt -keystore clientkeystore.jks -alias "WS-SSM Client"
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:
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:
trust.jks
file):keytool -import -file CA.crt -alias Trusted-CA -keystore trust.jks
keytool -import -file WS-SSM-Client.crt -alias Trusted-WS-Client -keystore peer.jks
%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.
To add support for new assertion types to the Web Services SSM:
com.bea.security.ssmws.credentials
namespace. In this procedure, we use a class named com.bea.security.ssmws.credentials.TestCredHolderImpl
and a custom identity assertion type named TestIA
as an example. See Listing 6-2 for an example holder class.WLESws.wrapper.conf
configuration file, which is located in BEA_HOME
/ales22-ssm/webservice-ssm/
instance-name
/config
. For example, if the holder class is contained in a file named ssmwsCustomAssertion.jar
, add a line like this to WLESws.wrapper.conf:
wrapper.java.classpath.40=C:/bea/ales22-ssm/webservice-ssm/lib/ssmwsCustomAssertion.jar
Note: | The wrapper.java.classpath lines must increment sequentially. |
castor.xml
file in the BEA_HOME
/ales22-ssm/webservice-ssm/lib/com/bea/security/ssmws/soap
directory. Add an entry like the following inside the <mapping>
XML element:<class name="com.bea.security.ssmws.credentials.TestCredHolderImpl">
<map-to cst:xml="TestIA" />
<field name="cookie" type="java.lang.String" >
<bind-xml node="text"/>
</field>
</class>
castor.xml
file in the BEA_HOME
/ales22-ssm/webservice-ssm/lib/com/bea/security/ssmws/credentials
directory. Add an entry like the following inside the <mapping>
XML element<class name="com.bea.security.ssmws.credentials.TestCredHolderImpl">
<map-to cst:xml="TestIA"
cst:ns-uri="http://security.bea.com/ssmws/ssm-soap-types-1.0.xsd" />
<field name="cookie" type="java.lang.String" >
<bind-xml node="text"/>
</field>
</class>
og4j.properties
file in the BEA_HOME
/ales22-ssm/webservice-ssm/
instance-name
/config
directory. Change this line:log4j.appender.A1.Threshold=ERROR
log4j.appender.A1.Threshold=DEBUG
log4j.logger.com.bea.security.ssmws.server=DEBUG
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;
}
}