Configuring token generators with an assembly tool

Prior to completing this task, you must complete the following steps:

Configure the security token in the extensions file. For example, if you are configuring a token generator for a Lightweight Third Party Authentication (LTPA) token, you must first configure the LTPA token under the Security Token section on the Extensions tab. For more information, see Configuring the security token in generator security constraints.
Configure a collection certificate store if the token generator uses the PKCS#7 token type and you want to package the certificate revocation lists (CRL) in the security token. For more information, see Configuring the collection certificate store for the generator binding.

A security token represents a set of claims that are made by a client. This set of claims might include a name, password, identity, key, certificate, group, privilege, and so on. A security token is embedded in the Simple Object Access Protocol (SOAP) message within the SOAP header. The security token within the SOAP header is propagated from the message sender to the intended message receiver.

Complete the following steps to configure either the client-side bindings for the token generator in step 2 or the server-side bindings for the token generator in step 3:

Click Window > Open Perspective > J2EE.
Optional: Locate the client-side bindings using the Project Explorer window. The Client Deployment Descriptor window is displayed. This Web service contains the bindings that you need to configure.
1. Expand the Web Services > Clients section and double-click the name of the Web service.
2. Click the WS Binding tab and expand the Security Request Generator Binding Configuration section.
Optional: Locate the server-side bindings using the Project Explorer window. The Web Services Editor window is displayed. This Web service contains the bindings that you need to configure.
1. Expand the Web Services > Services section and double-click the name of the Web service.
2. Click the Binding Configurations tab and expand the Response Generator Binding Configuration Details section.
Optional: Configure a trust anchor if you are configuring this token consumer for an X.509 security token.
1. Expand the Trust anchor section and click Add to add a new entry or click Edit to edit a selected entry. The Trust anchor dialog window is displayed.
2. Specify a name for the trust anchor configuration in the Trust anchor name field.
3. Specify a keystore password in the Key store storepass field. The keystore storepass is the password that is required to access the keystore file.
4. Specify the path to the keystore file in the Key store path field. The key store path is the directory where the keystore resides. Make sure that wherever you deploy your application that can locate your keystore file.
5. Select a key store type from the Key store type field. The key store type that you select must match the keystore file that is specified in the Key store path field.
Expand the Token generator section and click Add to add a new entry or click Edit to edit a selected entry. The Token Generator Dialog window is displayed.
Specify a unique name in the Token generator name field. For example, you might specify gen_signtgen. If this token generator is for an X.509 certificate and is used for signature generation or encryption, the token generator name is referenced in the Token field of the Key Information dialog window.
Select a token generator class in the Token generator class field. Select the token generator class that matches the type of token that you are configuring. This class must implement the com.ibm.wsspi.wssecurity.token.TokenGeneratorComponent interface. The following default token generator implementations are supported:
- com.ibm.wsspi.wssecurity.token.LTPATokenGenerator
- com.ibm.wsspi.wssecurity.token.UsernameTokenGenerator
- com.ibm.wsspi.wssecurity.token.X509TokenGenerator
Select a security token reference in the Security token field. The value in this field references the security token that is configured in the extensions file.
Select the Use value type option and select the value type in the Value type field. Select the value type of the security token that matches the type of token generator that you are configuring. When you select the value type, the assembly tool automatically enters the correct values in the Local name and URI fields depending upon the type of security token that is specified by the value type. If you select Custom Token, you must specify the local name and the namespace URI of the value type for the generated token. The following value types are supported:
- Username Token
- X509 certificate token
- X509 certificates in a PKIPath
- A list of X509 certificates and CRLs in a PKCS#7
- LTPA Token
- Custom Token
Specify the Callback handler class name in the Call back handler field. This name is the callback handler implementation class that is used to plug-in a security token framework. The specified callback handler class must implement the javax.security.auth.callback.CallbackHandler interface. The implementation of the Java™ Authentication and Authorization Service (JAAS) javax.security.auth.callback.CallbackHandler interface must provide a constructor using the following syntax:
```
MyCallbackHandler(String username, char[] password, java.util.Map properties)
```
Where:
- username specifies the user name that is passed into the configuration.
- password specifies the password that is passed into the configuration.
- properties specifies the other configuration properties that are passed into the configuration.
The following default callback handler implementations are supported:
com.ibm.wsspi.wssecurity.auth.callback.GUIPromptCallbackHandler

This callback handler uses a login prompt to gather the user name and password information. However, if you specify 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 if it is specified on this panel. Use this implementation for a Java 2 Platform, Enterprise Edition (J2EE) 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 on this panel. You 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 on this panel, WebSphere Application Server does not issue a prompt, but returns the user name and password to the token generator. Use this implementation for a J2EE 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 on this panel, 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.

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 and a key definition is required for this callback handler.

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

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 must 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.

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

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.

The callback handler implementation obtains the required security token and passes it to the token generator. The token generator inserts the security token in the Web services security header within the SOAP message. Also, the token generator is a plug-in point for the pluggable security token framework. Service providers can provide their own implementation, but the implementation must use the com.ibm.wsspi.wssecurity.token.TokenConsumerComponent interface.
Specify the basic authentication User ID in the User ID field. This user name is passed to the constructors of the callback handler implementation. The basic authentication user name and password are used if you select one of the following default callback handler implementations, as described in the previous step:
- 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
Specify the basic authentication password in the Password field. This password is passed to the constructors of the callback handler implementation.
Optional: Select the Use key store option and complete the following substeps if you previously selected one of the following callback handlers: com.ibm.wsspi.wssecurity.auth.callback.PKCS7CallbackHandler. com.ibm.wsspi.wssecurity.auth.callback.PkiPathCallbackHandler, or com.ibm.wsspi.wssecurity.auth.callback.X509CallbackHandler.
1. Specify the password for the keystore in the Key store storepass field. This password is used to access the keystore file.
2. Specify the location of the keystore in the Key store path field.
3. Specify the type of keystore in the Key store type field. The following keystore types are supported:
  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.
  
  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 encrypt keys that use cryptographic hardware to ensure protection.
  
  PKCS12
  
  Use this option if your keystore uses the PKCS#12 file format.
4. In the Keys section, click Add to add a key. You can also click Remove to remove an existing key.
5. In the Key section, specify an alias for the key in the Alias field. For example, you might specify bob. The key alias is used by the key locator to locate the key within the keystore file.
6. In the Keys section, specify a password for the key in the Key pass field. This password is needed to access the key object within the keystore file.
7. In the Keys section, specify a name in the Key name field. The key name must be a fully qualified, distinguished name. For example, you might specify CN=Bob,O=IBM,C=US.
Optional: Select the Use certificate path settings option if the token generator uses the PKCS#7 token type and you want to package the certificate revocation lists (CRL) in the security token.
1. Select the Certificate path reference option and a certificate store reference. This selection references a certificate store that is configured in the Certificate Store List section. For more information, see Configuring the collection certificate store for the generator binding.
Optional: Click Add and specify additional properties in the Property section.
If the token generator includes a nonce in the user name token, add the following name and value pair:
Name

com.ibm.wsspi.wssecurity.token.username.addNonce

Value

true

Nonce is a unique cryptographic number that is embedded in a message to help stop repeat, unauthorized attacks of user name tokens. A property is valid only when the generated token type is a user name token. This option is available for the request generator binding only.

If this token generator might include a time stamp in the user name token, add the following name and value pair:
Name

com.ibm.wsspi.wssecurity.token.username.addTimestamp

Value

true

This option is valid only when the generated token type is a user name token and it is available for the request generator binding only.

If you have defined identity assertion in the IBM extended deployment descriptor, add the following name and value pair:
Name

com.ibm.wsspi.wssecurity.token.IDAssertion.isUsed

Value

true

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 only sends the user name of the original caller for a Username token generator. For an X.509 token generator, the application server sends the original signer certification only.

If you have defined identity assertion in the IBM extended deployment descriptor and you want to use the Run As identity instead of the initial caller identity for identity assertion for a downstream call, add the following name and value pair:
Name

com.ibm.wsspi.wssecurity.token.IDAssertion.useRunAsIdentity

Value

true

This option is valid only when the generated token type is a user name token.
Click OK to save your configuration.

Configure the key information if this token generator configuration is for an X.509 security token. For more information, see Configuring key information for the generator binding.