When you specify the token generators at the application
level, the information is used on the generator side to generate the
security token.
Before you begin
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.
![[Updated in July 2011]](../../deltaend.gif)
jul2011
About this task
Complete
the following steps to configure the token generator on the application
level.
Procedure
- Locate the token generator panel in the administrative
console.
- Click .
- Under Manage modules, click URI_name.
- Under Web Services Security Properties
you 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. If
you are creating 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 your application requires a username token consumer, you 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 that is defined in the deployment descriptor.
Important: On the application level, if you do not specify a
security token in your deployment descriptor, the Part
reference field is not displayed. If you define a security
token called user_tgen in your deployment descriptor, user_tgen is
displayed as an option in the Part reference field.
You can specify a security token in the deployment descriptor when
you assemble your 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 you want 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, complete
the following steps:
- Click .
- Under Related Items, click EJB Modules or .
- Under Additional Properties you 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 that is 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 you select
the
Add nonce option, you can specify the following
properties under Additional properties. These properties are used
by the request consumer.
Table 1. Additional nonce properties
Property name |
Default value |
Explanation |
com.ibm.ws.wssecurity.config.token.
BasicAuth.Nonce.cacheTimeout
|
600 seconds |
Specifies the 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 |
Specifies the time, in seconds, before the nonce
time stamp expires. |
com.ibm.ws.wssecurity.config.token.
BasicAuth.Nonce.maxAge
|
300 seconds |
Specifies the clock skew value, in seconds,
to consider when WebSphere Application Server checks the timeliness
of the message. |
On the server level, you
can specify these additional properties for a nonce on the Default
bindings for Web services security panel within the administrative
console. To access the panel, click . Under Security, 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 you specify any of
the following local names, you 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#X509
- 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, you 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,
you 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 your 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 that is 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
- 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.
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 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.
Use this implementation for a Java 2 Platform, Enterprise Edition
(J2EE) application client only. If you 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. You can use
this callback handler when the Web service is acting as a client.
If you use this implementation, you must 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, WebSphere Application Server does not issue
a prompt, but returns the user name and password to the token generator.
Use this implementation for a Java 2 Platform, Enterprise Edition
(J2EE) application client only. If you 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. It is recommended that you do not use this
callback handler on a J2EE application client.
The LTPATokenCallbackHandler
is used to generate either a LTPA or a LTPA_PROPAGATION token. When
the LTPATokenCallbackHandler is used to generate a LTPA token, you
can supply basic authentication information to obtain the required
LTPA token. However, when LTPATokenCallbackHandler is used to generate
a LTPA_PROPAGATION token, basic authentication information can not
be used to generate the token, and therefore should not be supplied.
- 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 you use this implementation,
you must 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. 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 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 you 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 you
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 you
have identity assertion defined in the IBM extended deployment descriptor
and you want 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 you 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 you 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 that are 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. 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. To change the path used by this variable, click , 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.
You 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 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 encrypt keys that use cryptographic hardware to
ensure protection.
- PKCS12KS (PKCS12)
- Use this option if your keystore uses the PKCS#12 file format.
- Click OK and then click Save to
save the configuration.
- Click the name of your token generator configuration.
- Under Additional properties, click .
- 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.
If you are creating 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
You must specify a similar token consumer configuration for
the application level.