Configuring the consumer security tokens using the WSS API
You can secure the SOAP messages, without using policy sets, by using the Web Services Security APIs. To configure the token on the consumer side, use the Web Services Security APIs (WSS API). The consumer security tokens are part of the com.ibm.websphere.wssecurity.wssapi.token interface package.
Before you begin
The pluggable token framework in WebSphere® Application Server has been redesigned so that the same framework from the WSS API can be reused. The same implementation of creating and validating security token can be used both for the Web Services Security run time and for the WSS API application code. The redesigned framework also simplifies the SPI programming model and will make it easier to add security token types.
You can use the WSS API or you can configure the tokens by using the administrative console. To configure tokens, you must have completed the following token task: configure the generator tokens, as needed.
About this task
On the generator side, the JAAS CallbackHandler and JAAS LoginModule are responsible for creating the security token. The token is created by using the JAAS LoginModule and by using JAAS CallbackHandler to pass authentication data. Then, the JAAS LoginModule creates the securityToken object, such as the UsernameToken, and passes it to the Web Services Security run time.
On the consumer side, the XML format is passed to the JAAS LoginModule for validation or authentication. then the JAAS CallbackHandler is used to pass authentication data from the Web Services Security run time to the LoginModule. After the token is authenticated and a security token object is created, then the token is passed it to the Web Services Security run time.
When using the WSS API for consumer token validation, certain default behaviors occur. The simplest way to use the WSS API is to use the default JAAS login module and callback handler. The example uses the default for them so the example does not specify the JAAS login module name.
The simplest way to use the WSS API is to use the default behavior (see the example code). The WSS API provide defaults for the token type, the token value, and the JAAS configuration name. The default token behaviors include:
Consumer token decisions | Default behavior |
---|---|
Which token type to use |
The token type specifies which type of token to use for signing and validating messages. The X.509 token is the default token type. WebSphere Application Server provides the following pre-configured consumer token types:
You can also create custom token types, as needed. |
What JAAS login configuration name to specify |
The JAAS login configuration name specifies which JAAS login configuration name to use. |
Which configuration type to use | The JAAS login module configuration type. Only the pre-configured consumer configuration types can be used for consumer token types. |
The SecurityToken class (com.ibm.websphere.wssecurity.wssapi.token.SecurityToken) is the generic token class and represents the security token that has methods to get the identity, XML format, and cryptographic keys. Using the SecurityToken class, you can apply both the signature and encryption to the SOAP message. However, to apply both, you must have two SecurityToken objects, one for the signature and one for encryption, respectively.
The following token types are subclasses of the generic security token class:
Token type | JAAS login configuration name |
---|---|
Security context token | system.wss.consume.sct |
Derived key token | system.wss.consume.dkt |
The following token types are subclasses of the binary security token class:
Token type | JAAS login configuration name |
---|---|
X.509 token | system.wss.consume.x509 |
X.509 PKI Path token | system.wss.consume.pkiPath |
X.509 PKCS7 token | system.wss.consume.pkcs7 |
- For each JAAS login token consumer configuration name, there is a respective token generator configuration name. For example, for the X509Token, the respective token generator configuration name is system.wss.generate.x509.
- The LTPA and LTPA propagation tokens are only available to a requester that is running as a server-based client. The LTPA and LTPA propagation tokens are not supported for the Java™ SE 6 or Java EE application client.
To validate the X509Token to the SOAP message on the consumer side, the <X509Token> element must be in the <wsse:Security> element.
Procedure
Results
Example
The following sample code provides the WSS API example code for decryption using the default JAAS login module and callback handler:
// Get the message context
Object msgcontext = getMessageContext();
// Generate the WSSFactory instance (step: a)
WSSFactory factory = WSSFactory.getInstance();
// Generate the WSSConsumingContext instance (step: b)
WSSConsumingContext gencont = factory.newWSSConsumingContext();
// Generate the callback handler (step: c)
X509ConsumeCallbackHandler callbackHandler = new
X509ConsumeCallbackHandler(
"",
"enc-sender.jceks",
"jceks",
"storepass".toCharArray(),
"alice",
"keypass".toCharArray(),
"CN=Alice, O=IBM, C=US");
// Generate the WSSDecryption instance (step: d)
WSSDecryption dec = factory.newWSSDecryption(X509Token.class,
callbackHandler);
// Add WSSDecryption to WSSConsumingContext (step: e)
concont.add(dec);
// Validate the WS-Security header (step: f)
concont.process(msgcontext);
What to do next
For each token type, configure the token using the WSS APIs or using the administrative console. Next, specify the similar generator tokens if you have not done so.
If both the generator and consumer tokens are configured, continue securing SOAP messages at the response consumer using the WSS APIs or configure the tokens using the administrative console.
If both the generator and consumer tokens are configured, continue securing SOAP messages either by verifying the signature or by decrypting the message, as needed. You can use either the WSS APIs or the administrative console to secure the SOAP messages.