When you specify the token generators at the application level,
the information is used on the generator side to generate the security token.
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
Complete
the following steps to configure the token generator on the application level:
Procedure
- Locate the token generator panel in the administrative console.
- Click Applications > Enterprise applications > application_name .
- 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 Applications > Enterprise applications > application_name.
- Under Related Items, click EJB Modules or Web Modules
> URI_name.
- 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 cell and server levels,
you can specify these additional properties for a nonce on the Default bindings
for Web services security panel within the administrative console.
- For the cell level, click Security > Web services.
- For the server level, click Servers > Application servers > server_name.
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. If you use this implementation, you
must 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 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 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. 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 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. 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.