WAS v8.5 > Develop applications > Develop web services - Security (WS-Security) > Develop applications that use Web Services Security > Develop message-level security for JAX-WS web services > Secure web services applications using the WSS APIs at the message level > Secure messages at the response consumer using WSS APIs > Validating the consumer token to protect message authenticity

Configure the consumer security tokens using the WSS API

We can secure the SOAP messages, without using policy sets, 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.

The pluggable token framework in WebSphere Application Server has been redesigned so 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.

We can use the WSS API or we can configure the tokens using the dmgr console. To configure tokens, you must have completed the following token task: configure the generator tokens, as needed. On the generator side, the JAAS CallbackHandler and JAAS LoginModule are responsible for creating the security token. The token is created using the JAAS LoginModule and 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:

Default token behaviors. Several token characteristics are configured by default.

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.

WAS provides the following pre-configured consumer token types:

We 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, we 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:

Subclasses of the SecurityToken. Use the subclasses to represent the security token.

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:

Subclasses to the BinarySecurityToken. Use the subclasses to represent the binary security token.

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

To validate the X509Token to the SOAP message on the consumer side, the <X509Token> element must be in the <wsse:Security> element.

  1. To validate the securityToken package, com.ibm.websphere.wssecurity.wssapi.token, first ensure the application server is installed.
  2. If using the default values, configures the tokens for the Web Services Security token consumer process. , for each token type, the process is similar to the following token consumer process:

    1. Uses WSSFactory.getInstance() to get the WSS API implementation instance.

    2. Creates the WSSConsumingContext instance from the WSSFactory instance. Note the WSSConsumingContext must always be called in a JAX-WS client application.

    3. Creates a JAAS CallbackHandler with information required to validate the security token. Review the token class information for which parameters are required or optional. For example, for an X.509 token, you could configure the following:

      X.509 token options. Use the X.509 configuration options to control the behavior of the token.

      Token Information Description
      keyStoreRef Indicates the reference name of the keystore stored in the cryptographic card. It can be specified when the card is set to the hardware.
      keyStorePath Indicates the path of the keystore file. It is not necessary to specify the keyStorePath if the keyStoreRef is set.
      keyStorePassword Indicates the password of the keystore file.
      keyStoreType Indicates the type of keystore file.
      alias Indicates the alias of the key.
      keyPassword Indicates the password of the key.
      keyName Indicates the subject name of the key.

    4. Sets the callback handler into WSSDecryption, WSSVerification, or WSSConsumingContext.

    5. If the callback handler is set into the WSSDecryption or WSSVerification, adds either one into WSSConsumingContext.
    6. Calls WSSConsumingContext.process().

  3. If using other than the default values, configures the tokens for the Web Services Security token consumer process. For each token type, the process is similar to the following token consumer process:

    1. If we do not use the default JAAS login module and callback handler, you need to prepare a custom one and register the name of JAAS login configuration using the dmgr console in advance.

    2. Uses WSSFactory.getInstance() to get the WSS API implementation instance.

    3. Creates the WSSConsumingContext instance from the WSSFactory instance. Note the WSSConsumingContext must always be called in a JAX-WS client application.

    4. Creates a callback handler with information required to validate the security token. Review the token class information for which parameters are required or optional. For example, for a X.509 token, we can configure the following:

      X.509 token options. Use the X.509 configuration options to control the behavior of the token.

      Token Information Description
      keyStoreRef Indicates the reference name of the keystore stored in the cryptographic card. It can be specified when the card is set to the hardware.
      keyStorePath Indicates the path of the keystore file. It is not necessary to specify the keyStorePath if the keyStoreRef is set.
      keyStorePassword Indicates the password of the keystore file.
      keyStoreType Indicates the type of keystore file.
      alias Indicates the alias of the key.
      keyPassword Indicates the password of the key.
      keyName Indicates the subject name of the key.

    5. Sets JAAS configuration name and callback handler into WSSDecryption or WSSVerification, or WSSConsumingContext.

    6. If JAAS configuration name and callback handler are set into the WSSDecryption or WSSVerification, adds either one into WSSConsumingContext.
    7. Calls WSSConsumingContext.process().


Results

If there is an error condition, a WSSException is provided. If successful, the WSSConsumingContext.process() is called, and the security token on the consumer side is validated (authenticated).


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);

For each token type, configure the token using the WSS APIs or using the dmgr console. Next, specify the similar generator tokens if we 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 dmgr 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. We can use either the WSS APIs or the dmgr console to secure the SOAP messages.


Related concepts:

Security token
Username token
Derived key token
Security context token


Related


Secure messages at the response consumer using WSS APIs


Reference:

Protection token settings (generator or consumer)
Callback handler settings for JAX-WS


+

Search Tips   |   Advanced Search