Configure token generators using JAX-RPC to protect message authenticity at the server or cell level

The token generator on the server or cell level is used to specify the information for the token generator if these bindings are not defined at the application level. The signing information and the encryption information can share the token generator information, which is why they are all defined at the same level.

You need to understand that the keystore/alias information that you provide for the generator, and the keystore/alias information that you provide for the consumer are used for different purposes. The main difference applies to the Alias for an X.509 callback handler.

When used in association with an encryption generator, the alias supplied for the generator is used to retrieve the public key to encrypt the message. A password is not required. The alias that is entered on a callback handler associated with an encryption generator must be accessible without a password. This means that the alias must not have private key information associated with it in the keystore. When used in association with a signature generator, the alias supplied for the generator is used retrieve the private key to sign the message. A password is required.

WebSphere Application Server provides default values for bindings. We must modify the defaults for a production environment.

We can configure the token generator on the server level and the cell level. In the following steps, use the first step to access the server-level default bindings and use the second step to access the cell-level bindings.

1. Access the default bindings for the server level.

   1. Click Servers > Server Types > WebSphere application servers > server_name.

   2. Under Security, click JAX-WS and JAX-RPC security runtime.

      In a mixed node cell with a server using WAS v6.1 or earlier, click Web services: Default bindings for Web Services Security.

2. Click Security > Web services to access the default bindings on the cell level.

3. Under Default generator bindings, click Token generators.

4. Click New to create a token generator configuration, click Delete to delete an existing configuration, or click the name of an existing token generator configuration to edit its settings. For a new configuration, enter a unique name for the token generator configuration in the Token generator name field. For example, you might specify sig_tgen. This field specifies the name of the token generator element.

5. Specify a class name in the Token generator class name field. The JAAS Login Module implementation is used to create the security token on the generator side.

   Restriction: The com.ibm.wsspi.wssecurity.token.TokenGeneratorComponent interface is not used with JAX-WS web services. If we are using JAX-RPC web services, this interface is still valid.

   The token generator class name must be similar to the token consumer class name. For example, if the application requires an X.509 certificate token consumer, we can specify the com.ibm.wsspi.wssecurity.token.X509TokenConsumer class name on the Token consumer panel and the com.ibm.wsspi.wssecurity.token.X509TokenGenerator class name in this field. WebSphere Application Server provides the following default token generator class implementations:

   com.ibm.wsspi.wssecurity.token.UsernameTokenGenerator

   This implementation generates a username token.

   com.ibm.wsspi.wssecurity.token.X509TokenGenerator

   This implementation generates an X.509 certificate token.

   com.ibm.wsspi.wssecurity.token.LTPATokenGenerator

   This implementation generates a LTPA> (LTPA) token.

6. Select a certificate path option. The certificate path specifies the certificate revocation list (CRL), which is used for generating a security token that is wrapped in a PKCS#7 with a CRL. WebSphere Application Server provides the following certificate path options:

   None

   Select this option in case the CRL is not used for generating a security token. We must select this option when the token generator does not use the PKCS#7 token type.

   Dedicated signing information

   If the CRL is wrapped in a security token, select Dedicated signing information and select a collection certificate store name from the Certificate store field. The Certificate store field shows the names of collection certificate stores already defined.

   To define a collection certificate store on the cell level, see Configure the collection certificate on the server or cell level.

7. Select the Add nonce option to include a nonce in the user name token for the token generator. Nonce is a unique cryptographic number embedded in a message to help stop repeat, unauthorized attacks of user name tokens. The Add nonce option is available if specified a user name token for the token generator.

8. Select the Add timestamp option to include a time stamp in the user name token for the token generator.

9. Specify a value type local name in the Local name field. This entry specifies the local name of the value type for a security token referenced by the key identifier. This attribute is valid when Key identifier is selected as Key information type. To specify the Key information type, see Configure the key information for the generator binding using JAX-RPC on the server or cell level. WebSphere Application Server provides the following predefined X.509 certificate token configurations:

   X.509 certificate token

   http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3

   X.509 certificates in a PKIPath

   http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509PKIPathv1

   A list of X.509 certificates and CRLs in a PKCS#7

   http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#PKCS7

   LTPA

   For LTPA, the value type local name is LTPA. If we enter LTPA for the local name, specify the http://www.ibm.com/websphere/appserver/tokentype/5.0.2 uniform resource identifier (URI) value in the Value type URI field as well.

   LTPA version 2

   For LTPA version 2, the value type local name is LTPAv2. If we enter LTPAv2 for the local name, specify the http://www.ibm.com/websphere/appserver/tokentype uniform resource identifier (URI) value in the Value type URI field as well.

   LTPA_PROPAGATION

   For LTPA token propagation, the value type local name is LTPA_PROPAGATION. If we enter LTPA_PROPAGATION for the local name, specify the http://www.ibm.com/websphere/appserver/tokentype URI value in the Value type URI field as well.

   For example, when an X.509 certificate token is specified, we can use http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3 for the local name.

10. Specify the value type URI in the URI field. This entry specifies the namespace URI of the value type for a security token referenced by the key identifier. This attribute is valid when Key identifier is selected as Key information type on the Key information panel for the default generator. When the X.509 certificate token is specified, we do not need to specify the namespace URI. If another token is specified, specify the namespace URI of the value type.

11. Click OK and then Save to save the configuration.

12. Click the name of the token generator configuration.

13. Under Additional properties, click Callback handler to configure the callback handler properties. The callback handler specifies how to acquire the security token that is inserted in the Web Services Security header within the SOAP message. The token acquisition is a pluggable framework that leverages the JAAS javax.security.auth.callback.CallbackHandler interface for acquiring the security token.

    1. Specify a callback handler class implementation in the Callback handler class name field. This attribute specifies the name of the Callback handler class implementation used to plug in a security token framework. The specified callback handler class must implement the javax.security.auth.callback.CallbackHandler class. WebSphere Application Server provides the following default callback handler implementations:

       com.ibm.wsspi.wssecurity.auth.callback.GUIPromptCallbackHandler

       This callback handler uses a login prompt to gather the user name and password information. However, if specified the user name and password on this panel, a prompt is not displayed and WebSphere Application Server returns the user name and password to the token generator. Use this implementation for a Java EE application client only.

       com.ibm.wsspi.wssecurity.auth.callback.NonPromptCallbackHandler

       This callback handler does not issue a prompt and returns the user name and password if it is specified in the basic authentication section of this panel. We can use this callback handler when the web service is acting as a client.

       com.ibm.wsspi.wssecurity.auth.callback.StdinPromptCallbackHandler

       This callback handler uses a standard-in prompt to gather the user name and password. However, if the user name and password is specified in the basic authentication section of this panel, WAS does not issue a prompt, but returns the user name and password to the token generator. Use this implementation for a Java EE application client only.

       com.ibm.wsspi.wssecurity.auth.callback.LTPATokenCallbackHandler

       This callback handler is used to obtain the Lightweight Third Party Authentication (LTPA) security token from the Run As invocation Subject. This token is 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 in the basic authentication section of this panel, WebSphere Application Server authenticates the user name and password to obtain the LTPA security token. It obtains the security token this way 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. IBM recommends that we do not use this callback handler on a Java EE application client.

       com.ibm.wsspi.wssecurity.auth.callback.X509CallbackHandler

       This callback handler is used to create the X.509 certificate that is inserted in the Web Services Security header within the SOAP message as a binary security token. A keystore file and a key definition are required for this callback handler.

       com.ibm.wsspi.wssecurity.auth.callback.PKCS7CallbackHandler

       This callback handler is used to create X.509 certificates that are 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 file is required for this callback handler. 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. For more information on configuring the collection certificate store, see Configure the collection certificate on the server or cell level.

       com.ibm.wsspi.wssecurity.auth.callback.PkiPathCallbackHandler

       This callback handler is used to create X.509 certificates that are 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 file 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.

       For an X.509 certificate token, you might specify the com.ibm.wsspi.wssecurity.auth.callback.X509CallbackHandler implementation.

    2. Optional: Select the Use identity assertion option. Select this option if we have identity assertion defined in the IBM extended deployment descriptor. This option indicates that only the identity of the initial sender is required and inserted into the Web Services Security header within the SOAP message. For example, WebSphere Application Server sends only the user name of the original caller for a user name token generator. For an X.509 token generator, the application server sends the original signer certification only.

    3. Optional: Select the Use RunAs identity option. Select this option if the following conditions are true:

       • You have identity assertion defined in the IBM extended deployment descriptor.

       • You want to use the Run As identity instead of the initial caller identity for identity assertion for a downstream call.

    4. Optional: Specify a basic authentication user ID and password in the User ID and Password fields. This entry specifies the user name and password that is passed to the constructors of the callback handler implementation. The basic authentication user ID and password are used if specified one of the following default callback handler implementations provided by WebSphere Application Server:

       • com.ibm.wsspi.wssecurity.auth.callback.GUIPromptCallbackHandler

       • com.ibm.wsspi.wssecurity.auth.callback.LTPATokenCallbackHandler

       • com.ibm.wsspi.wssecurity.auth.callback.NonPromptCallbackHandler

       • com.ibm.wsspi.wssecurity.auth.callback.StdinPromptCallbackHandler

    5. Optional: Specify a keystore password and path. The keystore and its related information are necessary when the key or certificate is used for generating a token. For example, the keystore information is required if you select one of the following default callback handler implementations provided by WebSphere Application Server:

       • com.ibm.wsspi.wssecurity.auth.callback.PKCS7CallbackHandler

       • com.ibm.wsspi.wssecurity.auth.callback.PkiPathCallbackHandler

       • com.ibm.wsspi.wssecurity.auth.callback.X509CallbackHandler

       The keystore files contain public and private keys, root certificate authority (CA) certificates, intermediate CA certificates, and so on. Keys that are retrieved from the keystore file are used to sign and validate or encrypt and decrypt messages or message parts. To retrieve a key from a keystore file, specify the keystore password, the keystore path, and the keystore type.

14. Select a keystore type from the Type field. WebSphere Application Server provides the following options:

    JKS

    Use this option if you are not using Java Cryptography Extensions (JCE) and if the keystore file uses the Java Keystore (JKS) format.

    JCEKS

    Use this option if you are using Java Cryptography Extensions.

    (zos) JCERACFKS

    Use JCERACFKS if the certificates are stored in a SAF key ring (z/OS only).

    PKCS11KS (PKCS11)

    Use this format if the keystore file uses the PKCS#11 file format. Key store files using this format might contain RSA keys on cryptographic hardware or might encrypt the keys that use cryptographic hardware to ensure protection.

    PKCS12KS (PKCS12)

    Use this option if the keystore file uses the PKCS#12 file format.

15. Click OK and then Save to save the configuration.

16. Click the name of the token generator configuration.

17. Under Additional properties, click Callback handler > Keys.

18. Click New to create a key configuration, click Delete to delete an existing configuration, or click the name of an existing key configuration to edit its settings. For a new configuration, enter a unique name for the key configuration in the Key name field. This name refers to the name of the key object stored within the keystore file.

19. Specify an alias for the key object in the Key alias field. Use the alias when the key locator searches for the key objects in the keystore.

20. Specify the password that is associated with the key in the Key password field.

21. Click OK and Save to save the configuration.

Results

You have configured the token generators at the server or the cell level.

What to do next

Specify a similar token consumer configuration.

Subtopics

• Token generator collection
  Use this page to view the token generators. The information is used on the generator side only to generate the security token.

• Token generator configuration settings
  Use this page to specify the information for the token generator. The information is used at the generator side only to generate the security token.

• Algorithm URI collection
  Use this page to view a list of uniform resource identifier (URI) algorithms for XML digital signature or XML encryption mapped to an algorithm factory engine class. With algorithm mappings, service providers can use other cryptographic algorithms for digest value calculation, digital signature signing and verification, data encryption and decryption, and key encryption and decryption.

• Algorithm URI configuration settings
  Use this page to specify the algorithm uniform resource identifier (URI) and its usage type.

• Algorithm mapping collection
  We can view a list of custom uniform resource identifier (URI) algorithms for digest value calculation, signature, key encryption, and data encryption. The application server maps these algorithms to an implementation of the algorithm factory engine interface. With algorithm mappings, service providers can extend the cryptographic algorithms for XML digital signature and XML encryption.

• Algorithm mapping configuration settings
  Use this page to view a list of custom uniform resource identifier (URI) algorithms for digest value calculation, signature, key encryption, and data encryption. The application server maps these algorithms to an implementation of the algorithm factory engine interface. With algorithm mappings, service providers can extend the cryptographic algorithms for XML digital signature and XML encryption.

• Default bindings and security runtime properties
  Use this page to specify the configuration on the cell level in a WAS Network Deployment environment. In addition, use this page to define the default generator bindings, default consumer bindings, and additional properties such as key locators, the collection certificate store, trust anchors, trusted ID evaluators, algorithm mappings, and login mappings.

Related tasks

Enable or disable single sign-on interoperability mode for the LTPA token

Configure the collection certificate on the server or cell level

Configure programmatic logins for Java Authentication and Authorization Service