Protecting message authenticity at the application level by configuring token generators using JAX-RPC

Configure token generators using JAX-RPC to protect message authenticity at the application level

When specified the token generators at the application level, the information is used on the generator side to generate the security token.

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.

Complete the following steps to configure the token generator on the application level:

Locate the token generator panel in the console.

Click Applications > Application Types > WebSphere enterprise applications > application_name.

Under Manage modules, click URI_name.

Under Web Services Security Properties we can access the token generators for the following bindings:

For the request generator (sender) binding, click Web services: Client security bindings. Under Request generator (sender) binding, click Edit custom.

For the response generator (sender) binding, click Web services: Server security bindings. Under Response generator (sender) binding, click Edit custom.

Under Additional properties, click Token generators.

Click New to create a token generator configuration, select an existing 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 in the Token generator name field. For example, you might specify gen_signtgen.

Specify a class name in the Token generator class name field. The token generator class must implement the com.ibm.wsspi.wssecurity.token.TokenGeneratorComponent interface. The token generator class name for the request generator and the response generator must be similar to the token consumer class name for the request consumer and the response consumer. For example, if the application requires a username token consumer, we can specify the com.ibm.wsspi.wssecurity.token.UsernameTokenConsumer class name on the token consumer panel for the application level and the com.ibm.wsspi.wssecurity.token.UsernameTokenGenerator class name in this field.

Optional: Select a part reference in the Part reference field. The part reference indicates the name of the security token defined in the deployment descriptor.
Important: On the application level, if we do not specify a security token in the deployment descriptor, the Part reference field is not displayed. If we define a security token called user_tgen in the deployment descriptor, user_tgen is displayed as an option in the Part reference field. We can specify a security token in the deployment descriptor when you assemble the application using an assembly tool.

Select either None or Dedicated signing information for the certificate path. Select None when the token generator does not use the PKCS#7 token type. When the token generator uses the PKCS#7 token type and to package certificate revocation lists (CRLs) in the security token, select Dedicated signing information and select a certificate store. To configure a collection certificate store and certificate revocation lists for the generator bindings on the application level...

Click Applications > Application Types > WebSphere enterprise applications > application_name.

Under Related Items, click EJB Modules or Web Modules > URI_name.

Under Additional Properties we can access the collection certificate store configuration for the following bindings:

For the request generator (sender) binding, click Web services: Client security bindings. Under Request generator (sender) binding, click Edit custom.

For the response generator (sender) binding, click Web services: Server security bindings. Under Response generator (sender) binding, click Edit custom.

Under Additional properties, click Collection certificate store.

also see the information about configuring a collection certificate store.

Optional: Select the Add nonce option. This option indicates whether a nonce is included 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 valid only when the generated token type is a user name token and is available only for the request generator binding.
If we select the Add nonce option, we can specify the following properties under Additional properties. These properties are used by the request consumer.

nonce properties. Use the nonce properties to include

Property name Default value Explanation
com.ibm.ws.wssecurity.config.token. BasicAuth.Nonce.cacheTimeout 600 seconds Timeout value, in seconds, for the nonce value that is cached on the server.
com.ibm.ws.wssecurity.config.token. BasicAuth.Nonce.clockSkew 0 seconds Time, in seconds, before the nonce time stamp expires.
com.ibm.ws.wssecurity.config.token. BasicAuth.Nonce.maxAge 300 seconds Clock skew value, in seconds, to consider when WebSphere Application Server checks the timeliness of the message.

On the cell and server levels, we can specify these additional properties for a nonce on the Default bindings for Web Services Security panel within the console.

For the cell level, click Security > Web services.

For the server level, click Servers > Server Types > WebSphere application servers > server_name. 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.

Optional: Select the Add timestamp option. This option indicates whether to insert a time stamp into the user name token. The Add timestamp option is valid only when the generated token type is a user name token and is available only for the request generator binding.

Specify the value type local name in the Local name field. For a user name token and an X.509 certificate security token, WebSphere Application Server provides predefined local names for the value type. When specified any of the following local names, we do not need to specify a value type URI:

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

This local name specifies a user name token.

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

This local name specifies an X.509 certificate token.

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

This local name specifies X.509 certificates in a public key infrastructure (PKI) path.

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

This local name specifies a list of X.509 certificates and certificate revocation lists in a PKCS#7 format.

For an LTPA token, we can use LTPA for the value type local name and http://www.ibm.com/websphere/appserver/tokentype/5.0.2 for the value type Uniform Resource Identifier (URI). For LTPA token propagation, we can use LTPA_PROPAGATION for the value type local name and http://www.ibm.com/websphere/appserver/tokentype for the value type URI.

Optional: Specify the value type URI in the URI field. This entry specifies the namespace URI of the value type for the generated token.

Click OK and Save to save the configuration.

Click the name of the token generator configuration.

Under Additional properties, click Callback handler.

Specify the settings for the callback handler.

Specify a class name in the Callback handler class name field. This class name is the name of the callback handler implementation class used to plug-in a security token framework. The specified callback handler class must implement the javax.security.auth.callback.CallbackHandler interface and must provide a constructor using the following syntax:
MyCallbackHandler(String username, char[] password, java.util.Map properties)

Where:

username

User name that is passed into the configuration.

password

Password that is passed into the configuration.

properties

Specifies the other configuration properties that are passed into the configuration.

This constructor is required if the callback handler needs a user name and a password. However, if the callback handler does not need a user name and a password, such as X509CallbackHandler, use a constructor with the following syntax:
MyCallbackHandler(java.util.Map properties)

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. If we use this implementation, you must provide a basic authentication user ID and password on this panel.

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. We can use this callback handler when the web service is acting as a client. If we use this implementation, provide a basic authentication user ID and password on this panel.

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, 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. If we use this implementation, you must provide a basic authentication user ID and password on this panel.

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. IBM recommends that we do not use this callback handler on a Java EE application client. If we use this implementation, provide a basic authentication user ID and password on this panel.

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. If we use this implementation, provide a key store password, path, and type on this panel.

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. We 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 we use this implementation, provide a key store password, path, and type on this panel.

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. If we use this implementation, you must provide a key store password, path, and type on this panel.

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.TokenGeneratorComponent interface.

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 username token generator. For an X.509 token generator, the application server sends the original signer certification only.

Optional: Select the Use RunAs identity option. Select this option if we have identity assertion defined in the IBM extended deployment descriptor and to use the Run As identity instead of the initial caller identity for identity assertion in a downstream call. This option is valid only if we have configured Username TokenGenerator as a token generator.

Optional: Specify the basic authentication user ID in the Basic authentication user ID field. This entry specifies the user name that is passed to the constructors of the callback handler implementation. The basic authentication user name and password are used if specified one of the following default callback handler implementations in the Callback handler class name field:

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

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

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

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

Optional: Specify the basic authentication password in the Basic authentication password field. This entry specifies the password that is passed to the constructors of the callback handler implementation.

Optional: Specify the key store password in the Key store password field. This entry specifies the password used to access the key store file. The key store and its configuration are used if you select on of the following default callback handler implementations provided by WebSphere Application Server:

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

The keystore is used to build the X.509 certificate with the certificate path.

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

The keystore is used to build the X.509 certificate with the certificate path.

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

The keystore is used to retrieve the X.509 certificate.

Optional: Specify the key store path in the Path field. IBM recommends that you use the ${USER_INSTALL_ROOT} in the path name as this variable expands to the WAS path on the machine. To change the path used by this variable, click Environment > WebSphere variables, and click USER_INSTALL_ROOT. This field is required when you use the com.ibm.wsspi.wssecurity.auth.callback.PKCS7CallbackHandler, com.ibm.wsspi.wssecurity.auth.callback.PkiPathCallbackHandler, or com.ibm.wsspi.wssecurity.auth.callback.X509CallbackHandler callback handler implementations.

Optional: Select the key store type in the Type field. This selection indicates the format used by the keystore file. We can select one of the following values for this field:

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

PKCS12KS (PKCS12)

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

Click OK and then click Save to save the configuration.

Click the name of the token generator configuration.

Under Additional properties, click Callback handler > Keys.

Specify the key name, key alias, and the key password.

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 in the Key name field. For digital signatures, the key name is used by the request generator or response generator 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. For example, CN=Bob,O=IBM,C=US.

Specify the key alias in the Key alias field. The key alias is used by the key locator to find the key within the keystore file.

Specify the key password in the Key password field. This password is needed to access the key object within the keystore file.

Click OK and Save to save the configuration.

Results
You have configured the token generator for the application level.

What to do next
Specify a similar token consumer configuration for the application level.

Subtopics

Request generator (sender) binding configuration settings
Use this page to specify the binding configuration for the request generator.

Response generator (sender) binding configuration settings
Use this page to specify the binding configuration for the response generator or response sender.

Callback handler configuration settings for JAX-RPC
Use this page to specify how to acquire the security token that is inserted in the Web Services Security header for JAX-RPC 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.

Key collection
Use this page to view a list of logical names that is mapped to a key alias in the keystore file.

Key configuration settings
Use this page to define the mapping of a logical name to a key alias in a keystore file.

Web services: Client security bindings collection
Use this page to view a list of application-level, client-side binding configurations for Web Services Security. These bindings are used when a web service is a client to another web service.

Web services: Server security bindings collection
Use this page to view a list of server-side binding configurations for Web Services Security.

Related concepts

Overview of standards and programming models for web services message-level security

Related tasks

Configure the collection certificate store for the generator binding on the application level
Configure token generators using JAX-RPC to protect message authenticity at the application level

Property name	Default value	Explanation
com.ibm.ws.wssecurity.config.token. BasicAuth.Nonce.cacheTimeout	600 seconds	Timeout value, in seconds, for the nonce value that is cached on the server.
com.ibm.ws.wssecurity.config.token. BasicAuth.Nonce.clockSkew	0 seconds	Time, in seconds, before the nonce time stamp expires.
com.ibm.ws.wssecurity.config.token. BasicAuth.Nonce.maxAge	300 seconds	Clock skew value, in seconds, to consider when WebSphere Application Server checks the timeliness of the message.