Validating the consumer token to protect message authenticity

The token consumer information is used on the consumer side to incorporate and validate the security token. The Username token, X509 tokens, and LTPA tokens by default are used for message authenticity.

Before you begin

The token processing and pluggable token architecture in the Web Service Security runtime for IBM WebSphere Application Server Version 6.1 Feature Pack for Web Services has been redesigned to reuse the same security token interface and Java Authentication and Authorization Service (JAAS) Login Module from the Web Services Security APIs (WSS API). The same implementation of token creation and validation can be used in both the WSS API and the WSS SPI in the Web Service Security runtime.

In the Feature Pack for Web Services, the new design removes the need for the following interface: com.ibm.wsspi.wssecurity.token.TokenConsumingComponent. However, if your WebSphere Application Server Version 6.1 applications continue to use JAX-RPC instead of the Feature Pack for Web Services, this interface is still valid.

Note that the key name (KeyName) element is not supported in the Feature Pack for Web Services because there is no KeyName policy assertion defined in the current OASIS Web Services Security draft specification. For similar reasons, a SAML token is not supported in the Feature Pack for Web Services out of the box.

About this task

Using the new design in the Feature Pack for Web Services, the JAAS callback handler (CallbackHandler) and the JAAS login module (LoginModule) are responsible for creating the security token on the generator side and validating (authenticating) the security token on the consumer side.

For example, on the generator side, the Username token is created by the JAAS LoginModule and using the JAAS CallbackHandler to pass the authentication data. The JAAS LoginModule creates the Username SecurityToken object and passes it to the Web services security runtime.

Then, on the consumer side, the Username Token XML format is passed to the JAAS LoginModule for validation or authentication and the JAAS CallbackHandler is used to pass authentication data from the Web services security runtime to the LoginModule. After the token is authenticated, a Username SecurityToken object is created and passed it to the Web Service Security runtime.

Note: WebSphere Application Server does not support a stackable login module with the WebSphere Application Server default login module implementation, meaning adding the login module before or after the WebSphere Application Server login module implementation. If you want to stack the login module implementations, you must develop the required login modules because there is no default implementation.
The com.ibm.websphere.wssecurity.wssapi.token package provided by WebSphere Application Server includes support for these classes:
  • Security token (SecurityTokenImpl)
  • Binary security token (BinarySecurityTokenImpl)
In addition, WebSphere Application Server provides the following pre-configured sub-interfaces for security tokens:
  • Derived key token
  • Security context token (SCT)
  • Username token
  • LTPA token propagation
  • LTPA token
  • X509PKCS7 token
  • X509PKIPath token
  • X509v3 token

The Username token, the X.509 tokens, and the LTPA tokens are used by default for message authenticity. The derived key token and the X.509 tokens are used by default for signing and encryption.

The WSS API and WSS SPI are only supported on the client. To specify the security token type on the consumer side, you can also configure policy sets using the administrative console. You can also use the WSS APIs or policy sets for matching generator security tokens.

The default Login Module and Callback implementations are designed to be used as a pair, meaning both a generator and a consumer part. To use the default implementations, select the appropriate generator and consumer security token in a pair. For example, select system.wss.generate.x509 in the token generator and system.wss.consume.x509 in the token consumer when the X.509 token is required.

To configure the consumer-side security token, use the appropriate pre-configured token consumer interface from the WSS APIs to complete the following token configuration process steps:

Procedure

  1. Generates the wssFactory instance.
  2. Generates the wssConsumingContext instance.

    The WSSConsumingContext interface stores the components for consuming Web Services Security (WS-Security), such as verification, decryption, the security token, and the time stamp. When the validate() method is called, all of these components are validated.

  3. Creates the consumer-side components, such as the WSSVerification and the WSSDecryption objects.
  4. Specifies a JAAS configuration by specifying the name of the JAAS login configuration. The Java Authentication and Authorization Service (JAAS) configuration specifies the name of the JAAS configuration. The JAAS configuration specifies how the token logs in on the consumer side. Do not remove the predefined system or application login configurations. However, within these configurations, you can add module class names and specify the order in which WebSphere Application Server loads each module.
  5. Specifies a token consumer class name. The token consumer class name specifies the required information to validate the SecurityToken. The Username token, the X.509 tokens, and the LTPA tokens are used by default for message authenticity.
  6. Specifies the settings for the callback handler by specifying a callback handler class name and also specifies the callback handler keys. This class name is the name of the callback handler implementation class that is used for the plug-in to the security token framework.
    WebSphere Application Server provides the following default callback handler implementations for the consumer side:
    com.ibm.websphere.wssecurity.callbackhandler.PropertyCallback
    This class is a callback for handling the name-value pair in elements in the Web Services Security (WS-Security) configuration XMI files.
    ccom.ibm.websphere.wssecurity.callbackhandler.UNTConsumeCallbackHandler
    This class is a callback handler for the Username token on the consumer side. This instance is used to set into WSSConsumingContext object to validate a Username token. Use this implementation for a Java 2 Platform, Enterprise Edition (J2EE) application client only.
    com.ibm.websphere.wssecurity.callbackhandler.X509ConsumeCallbackHandler
    This class is a callback handler that is used to validate the X.509 certificate that is inserted in the Web services security header within the SOAP message as a binary security token on the consumer side. This instance is used to generate the WSSVerification object and WSSDecryption objects, set the objects into WSSConsumingContext object to validate the X.509 binary security tokens. A keystore and a key definition are required for this callback handler. If you use this implementation, a key store password, path, and type must have been provided on the generator side.
    com.ibm.websphere.wssecurity.callbackhandler.LTPAConsumeCallbackHandler
    This class is a callback handler for the Lightweight Third Party Authentication (LTPA) tokens on the consumer side. This instance is used to generate the WSSVerification and WSSDecryption objects to validate an LTPA token.

    This callback handler is used to validate the LTPA security token inserted in the Web services security header within the SOAP message as a binary security token. However, if the user name and password are specified, WebSphere Application Server authenticates the user name and password to obtain the LTPA security token rather than obtaining it from the Run As Subject. Use this callback handler only when the Web service is acting as a client on the application server. It is recommended that you do not use this callback handler on a J2EE application client. If you use this implementation, a basic authentication user ID and password must have been provided on the generator side.

  7. If a X.509 token is specified, additional token information is also specified.
    keyStoreRef The reference name of the keystore that is used for the key locator.
    keyStorePath The keystore file path from which the keystore is loaded, if needed. It is recommended that you use the ${USER_INSTALL_ROOT} in the path name as this variable expands to the WebSphere Application Server path on your machine. This path is required when you use the X.509 tokens callback handler implementations.
    keyStorePassword The password that is used to check the integrity of the keystore, or the keystore password that is used to unlock the keystore and to access the keystore file. The keystore and its configuration are used for some of the default callback handler implementations that are provided by WebSphere Application Server.
    keyStoreType The keystore type of keystore that is used for the key locator. This selection indicates the format that is used by the keystore file. The following values are available for selection:
    JKS
    Use this option if the keystore uses the Java Keystore (JKS) format.
    JCEKS
    Use this option if the Java Cryptography Extension is configured in the software development kit (SDK). The default IBM JCE is configured in WebSphere Application Server. This option provides stronger protection for stored private keys by using Triple DES encryption.
    JCERACFKS
    Use JCERACFKS if the certificates are stored in a SAF key ring (z/OS only).
    PKCS11KS (PKCS11)
    Use this format if your keystore uses the PKCS#11 file format. Keystores using this format might contain RSA keys on cryptographic hardware or might contain encrypt keys that use cryptographic hardware to ensure protection.
    PKCS12KS (PKCS12)
    Use this option if your keystore uses the PKCS#12 file format.
    alias The key alias name. The key alias is used by the key locator to find the key within the keystore file.
    keyPassword The key password that is used for recovering the key. This password is needed to access the key object within the keystore file.
    keyName The name of the key. For digital signatures, the key name is used by the request generator or response consumer signing information to determine which key is used to digitally sign the message. For encryption, the key name is used to determine the key used for encryption. The key name must be a fully qualified, distinguished name (DN). For example, CN=Bob,O=IBM,C=US.
    trustAnchorPath The file path from which the trust anchor is loaded.
    trustAnchorType The type of trust anchor.
    trustAnchorPassword The password that is used to check the integrity of the trust anchor or the password used to unlock the keystore.
    certStores A list of certificate stores. A collection certificate store includes a list of untrusted, intermediary certificates and certificate revocation lists (CRLs). The collection certificate store is used to validate the certificate path of the incoming X.509-formatted security tokens.
    provider The security provider.

    The following can be specified for a X.509 token:

    1. Without any keystore.
    2. With a trust anchor. A trust anchor specifies a list of keystore configurations that contain trusted root certificates. These configurations are used to validate the certificate path of incoming X.509-formatted security tokens. For example, when you select the trust anchor or the certificate store of a trusted certificate, you must configure the trust anchor and the certificate store before setting the certificate path.
    3. With a keystore that is used for the key locator.

      First, you must have created the keystore file, by using a key tool utility, for example. The keystore is used to retrieve the X.509 certificate. This entry specifies the password that is used to access the keystore file. Keystore objects within trust anchors contain trusted root certificates that are used by the CertPath API to validate the trustworthiness of a certificate chain. The names of the trust anchor and the collection certificate store are created in the certificate path under your token consumer.

    4. With a keystore that is used for the key locator and the trust anchor.
    5. With a map that includes key-value pairs. For example, you might specify the value type name and the value type Uniform Resource Identifier (URI). The value type specifies the namespace URI of the value type for the consumer token, and represents the token type of this class:
      ValueType: http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509
      Specifies an X.509 certificate token.
      ValueType: http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509PKIPathv1
      Specifies X.509 certificates in a public key infrastructure (PKI) path. This callback handler is used to create X.509 certificates encoded with the PkiPath format. The certificate is inserted in the Web services security header within the SOAP message as a binary security token. A keystore is required for this callback handler. A CRL is not supported by the callback handler; therefore, the collection certificate store is not required or used. If you use this implementation, you must provide a key store password, path, and type on this panel.
      ValueType: http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#PKCS7
      Specifies a list of X.509 certificates and certificate revocation lists in a PKCS#7 format. This callback handler is used to create X.509 certificates encoded with the PKCS#7 format. The certificate is inserted in the Web services security header in the SOAP message as a binary security token. A keystore is required for this callback handler. You can specify a certificate revocation list (CRL) in the collection certificate store. The CRL is encoded with the X.509 certificate in the PKCS#7 format. If you use this implementation, you must provide a key store password, path, and type.

      For some tokens, WebSphere Application Server provides a predefined local name for the value type. When you specify the following local name, you do not need to specify a value type URI:

      ValueType: http://www.ibm.com/websphere/appserver/tokentype/5.0.2
      For an LTPA token, you can use LTPA for the value type local name. This local name causes http://www.ibm.com/websphere/appserver/tokentype/5.0.2 to be specified for the value type Uniform Resource Identifier (URI).
      ValueType: http://www.ibm.com/websphere/appserver/tokentype/5.0.2
      For LTPA token propagation, you can use LTPA_PROPAGATION for the value type local name. This local name causeshttp://www.ibm.com/websphere/appserver/tokentype to be specified for the value type Uniform Resource Identifier (URI).
  8. If the Username token is specified as the token consumer class name, the following token information can be specified:
    1. Whether to specify the nonce.

      This option indicates whether a Nonce is included for the token consumer. Nonce is a unique, cryptographic number that is embedded in a message to help stop repeat, unauthorized attacks of Username tokens. Nonce is valid only when the validating token type is a Username token, and it is available only for the response consumer binding.

    2. Specifies the keyword of the time stamp. This option indicates whether to verify a time stamp in the Username token. The time stamp is valid only when the incorporated token type is a Username token.
    3. Specifies a map that includes key-value pairs. For example, you might specify the value type name and the value type Uniform Resource Identifier (URI). The value type specifies the namespace URI of the value type for the consumer token, and represents the token type of this class:
      URI value type: http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameToken
      Specifies a Username token.
  9. Sets the components into the wssConsumingContext object.
  10. Invokes the wssConsumingContext.process() method.

Results

Using the WSS APIs, you have configured the token consumer.

What to do next

You must specify a similar token generator configuration, if not already completed.



In this information ...


IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic Task topic    

Terms and conditions for information centers | Feedback

Last updatedLast updated: Aug 31, 2013 1:23:07 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-nd-dist&topic=twbs_configtokenconjaxws
File name: twbs_configtokenconjaxws.html