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.
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
newfeat Best practice: The WebSphere® Application Server Version 6.1
Feature Pack for Web Services extends the capabilities of this product
to introduce support for the Java API for XML-Based Web Services (JAX-WS) 2.0 programming model.
JAX-WS is the next generation Web services programming model complimenting
the foundation provided by the Java API for XML-based RPC (JAX-RPC) programming model. Using the strategic
JAX-WS programming model, development of Web services and clients
is simplified through support of a standards-based annotations model.
Although the JAX-RPC programming model and applications are still
supported, take advantage of the easy-to-implement JAX-WS programming
model to develop new Web services applications and clients. bprac
WebSphere
Application Server provides default values for bindings. You must
modify the defaults for a production environment.
You 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.
Procedure
- Access the default bindings for the server level.
- Click .
- Under Security, click Web services: Default
bindings for Web services security.
- Click to access the default bindings on the cell level.
- Under Default generator bindings, click Token
generators.
- 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. If you are creating 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.
- Specify a class name in the Token generator
class name field. The Java Authentication and Authorization
Service (JAAS) Login Module implementation is used to create the security
token on the generator side. The token generator class name must
be similar to the token consumer class name. For example, if your
application requires an X.509 certificate token consumer, you 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 Lightweight Third Party Authentication
(LTPA) token.
- 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. You 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 Configuring the collection certificate on the server or cell level.
- Select the Add nonce option to include
a nonce 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 available if you specify a user name token
for the token generator.
- Select the Add timestamp option
to include a time stamp in the user name token for the token generator.
- 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 that is 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 Configuring the key information for the generator binding 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 you enter LTPA for
the local name, you must 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_PROPAGATION
- For LTPA token propagation, the value type local name is LTPA_PROPAGATION.
If you enter LTPA_PROPAGATION for the local
name, you must 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,
you can use http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3 for
the local name.
- Specify the value type URI in the URI field.
This entry specifies the namespace URI of the value type for
a security token that is 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, you do not
need to specify the namespace URI. If another token is specified,
you must specify the namespace URI of the value type.
- Click OK and then Save to
save the configuration.
- Click the name of your token generator configuration.
- 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 Java Authentication and Authorization Service (JAAS) javax.security.auth.callback.CallbackHandler
interface for acquiring the security token.
- Specify a callback handler class implementation in the Callback
handler class name field. This attribute specifies
the name of the Callback handler class implementation that is 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 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.
- 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. 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 in the basic authentication section of 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.
- 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. 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 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. 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. For more information on configuring the collection
certificate store, see Configuring 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.
- Optional: Select the Use identity
assertion option. Select this option if you
have identity assertion that is 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.
- 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.
- 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 you specify one of
the following default callback handler implementations that are 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
- 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 that are 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, you must specify the keystore
password, the keystore path, and the keystore type.
- 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 your keystore file uses the Java Keystore (JKS) format.
- JCEKS
- Use this option if you are using Java Cryptography Extensions.
- JCERACFKS
- Use JCERACFKS if the certificates are stored in a SAF key
ring (z/OS only).
- PKCS11KS (PKCS11)
- Use this format if your 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 your keystore file uses the PKCS#12 file format.
- Click OK and then Save to
save the configuration.
- Click the name of your token generator configuration.
- Under Additional properties, click .
- 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
for the key configuration in the Key name field.
This name refers to the name of the key object that is stored within
the keystore file.
- 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.
- Specify the password that is associated with the key in
the Key password field.
- 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
You must specify a similar token consumer configuration.