Configuring token consumer on the application level

This task describes the steps that are needed to specify the token consumer on the application level. The information is used on the consumer side to incorporate the security token.

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

  1. Locate the token consumer panel in the WebSphere® Application Server administrative console.
    1. Click Applications > Enterprise applications > application_name.
    2. Under Related Items, click EJB Modules or Web Modules > URI_name.
    3. Under Additional properties you can access the token consumer for the following bindings:
      • For the request consumer (receiver) binding, click Web services: Server security bindings. Under Request consumer (receiver) binding, click Edit custom.
      • For the response consumer (receiver) binding, click Web services: Client security bindings. Under Response consumer (receiver) binding, click Edit custom.
    4. Under Required properties, click Token consumer.
    5. Click New to create a token consumer configuration, click Delete to delete an existing configuration, or click the name of an existing token consumer configuration to edit its settings. If you are creating a new configuration, enter a unique name in the Token consumer name field. For example, you might specify con_signtgen.
  2. Specify a class name in the Token consumer class name field. The token consumer class must implement the com.ibm.wsspi.wssecurity.token.TokenConsumerComponent interface. The token consumer class name for the request consumer and the response consumer must be similar to the token generator class name for the request generator and the response generator. For example, if your application requires a user name token consumer, you can specify the com.ibm.wsspi.wssecurity.token.UsernameTokenGenerator class name on the Token generator panel for application level and the com.ibm.wsspi.wssecurity.token.UsernameTokenConsumer class name in this field.
  3. 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. For example, if you receive a username token in your request message, you might want to reference the token in the username token consumer.
    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_tcon in your deployment descriptor, user_tcon is displayed as an option in the Part reference field.
  4. Optional: In the certificate path section of the panel, select a certificate store type and indicate the trust anchor and certificate store name, if necessary. These options and fields are necessary when you specify com.ibm.wsspi.wssecurity.token.X509TokenConsumer as the token consumer class name. The names of the trust anchor and the collection certificate store are created in the certificate path under your token consumer. You can select one of the following options:
    None
    If you select this option, the certificate path is not specified.
    Trust any
    If you select this option, any certificate is trusted. When the received token is consumed, the Application Server does not validate the certificate path.
    Dedicated signing information
    If you select this option, you can select a trust anchor and a certificate store configuration. When you select the trust anchor or the certificate store of a trusted certificate, you must configure the trust anchor and the certificate store before setting the certificate path.
    Trust anchor
    A trust anchor specifies a list of key store configurations that contain trusted root certificates. These configurations are used to validate the certificate path of incoming X.509-formatted security tokens. Keystore objects within trust anchors contain trusted root certificates that are used by the CertPath API to validate the trustworthiness of a certificate chain. You must create the keystore file using the key tool utility, which is located in the install_dir/java/jre/bin/keytool file.
    You can configure trust anchors for the application level by completing the following steps:
    1. Click Applications > Enterprise applications > application_name.
    2. Under Related Items, click EJB Modules or Web Modules > URI_name.
    3. Access the token consumer from the following bindings:
      • For the request consumer (receiver) binding, click Web services: Server security bindings. Under Request consumer (receiver) binding, click Edit custom.
      • For the response consumer (receiver) binding, click Web services: Client security bindings. Under Response consumer (receiver) binding, click Edit custom.
    4. Under Additional properties, click Trust anchors.
    Collection certificate store
    A collection certificate store includes a list of untrusted, intermediary certificates and certificate revocation lists (CRLs). The collection certificate store is used to validate the certificate path of the incoming X.509-formatted security tokens. You can configure the collection certificate store for the application level by completing the following steps:
    1. Click Applications > Enterprise applications > application_name.
    2. Under Related Items, click EJB Modules or Web Modules > URI_name.
    3. Access the token consumer from the following bindings:
      • For the request consumer (receiver) binding, click Web services: Server security bindings. Under Request consumer (receiver) binding, click Edit custom.
      • For the response consumer (receiver) binding, click Web services: Client security bindings. Under Response consumer (receiver) binding, click Edit custom.
    4. Under Additional properties, click Collection certificate store.
  5. Optional: Specify a trusted ID evaluator. The trusted ID evaluator is used to determine whether to trust the received ID. You can select one of the following options:
    None
    If you select this option, the trusted ID evaluator is not specified.
    Existing evaluator definition
    If you select this option, you can select one of the configured trusted ID evaluators. For example, you can select the SampleTrustedIDEvaluator, which is provided by WebSphere Application Server as an example.
    Binding evaluator definition
    If you select this option, you can configure a new trusted ID evaluator by specifying a trusted ID evaluator name and class name.
    Trusted ID evaluator name
    Specifies the name that is used by the application binding to refer to a trusted identity (ID) evaluator that is defined in the default bindings.
    Trusted ID evaluator class name
    Specifies the class name of the trusted ID evaluator. The specified trusted ID evaluator class name must implement the com.ibm.wsspi.wssecurity.id.TrustedIDEvaluator interface. The default TrustedIDEvaluator class is com.ibm.wsspi.wssecurity.id.TrustedIDEvaluatorImpl. When you use this default TrustedIDEvaluator class, you must specify the name and value properties for the default trusted ID evaluator to create the trusted ID list for evaluation. To specify the name and value properties, complete the following steps:
    1. Under Additional properties, click Properties > New.
    2. Specify the trusted ID evaluator name in the Property field. You must specify the name in the the form, trustedId_n where _n is an integer from 0 to n.
    3. Specify the trusted ID in the Value field.
    For example:
    property name="trustedId_0", value="CN=Bob,O=ACME,C=US"
property name="trustedId_1, value="user1"

    If the distinguished name (DN) is used, the space is removed for comparison. See the programming model information in the documentation for an explanation of how to implement the com.ibm.wsspi.wssecurity.id.TrustedIDEvaluator interface. For more information, see Default implementations of the Web services security service provider programming interfaces.

    Note: Define the trusted ID evaluator on the server level instead of the application level. To define the trusted ID evaluator on the server level, complete the following steps:
    1. Click Servers > Application servers > server_name.
    2. Under Security, click Web services: Default bindings for Web services security.
    3. Under Additional properties, click Trusted ID evaluators.
    4. Click New to define a new trusted ID evaluator.

    The trusted ID evaluator configuration is available only for the token consumer on the server-side application level.

  6. Optional: Select the Verify nonce option. This option indicates whether to verify a nonce in the user name token if it is specified for the token consumer. Nonce is a unique, cryptographic number that is embedded in a message to help stop repeat, unauthorized attacks of user name tokens. The Verify nonce option is valid only when the incorporated token type is a user name token.
  7. Optional: Select the Verify timestamp option. This option indicates whether to verify a time stamp in the user name token. The Verify nonce option is valid only when the incorporated token type is a user name token.
  8. Specify the value type local name in the Local name field. This field specifies the local name of the value type for the consumed token. 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.
    LTPA
    This local name specifies a Lightweight Third Party Authentication (LTPA) token.
    Important: When you specify LTPA for the value type local name, you do not need to specify the value type Uniform Resource Identifier (URI), which is http://www.ibm.com/websphere/appserver/tokentype/5.0.2.
  9. Optional: Specify the value type URI in the URI field. This entry specifies the namespace URI of the value type for the consumed token.
    Remember: If you specify the token consumer for a username token or an X.509 certificate security token, you do not need to specify a value type URI.

    If you want to specify another token, you must specify both the local name and the URI. For example, if you have an implementation of your own custom token, you can specify CustomToken in the Local name field and http://www.ibm.com/custom

  10. Click OK and Save to save the configuration.
  11. Click the name of your token consumer configuration.
  12. Under Additional properties, click JAAS configuration. The Java™ Authentication and Authorization Service (JAAS) configuration specifies the name of the JAAS configuration that is defined in the JAAS login panel. The JAAS configuration specifies how the token logs in on the consumer side.
  13. Select a JAAS configuration from the JAAS configuration name field. The field specifies the name of the JAAS system application login configuration. You can specify additional JAAS system and application configurations by clicking Security > Global security. Under Authentication, click JAAS configuration and either Application logins > New or System logins > New. Do not remove the predefined system or application login configurations. However, within these configurations, you can add module class names and specify the order in which WebSphere Application Server loads each module. WebSphere Application Server provides the following predefined JAAS configurations:
    ClientContainer
    This selection specifies the login configuration that is used by the client container applications. The configuration uses the CallbackHandler application programming interface (API) that is defined in the deployment descriptor for the client container. To modify this configuration, see the JAAS configuration panel for application logins.
    WSLogin
    This selection specifies whether all of the applications can use the WSLogin configuration to perform authentication for the security run time. To modify this configuration, see the JAAS configuration panel for application logins.
    DefaultPrincipalMapping
    This selection specifies the login configuration that is used by Java 2 Connectors (J2C) to map users to principals that are defined in the J2C authentication data entries. To modify this configuration, see the JAAS configuration panel for application logins.
    system.wssecurity.IDAssertion
    This selection enables a Version 5.x application to use identity assertion to map a user name to a WebSphere Application Server credential principal. To modify this configuration, see the JAAS configuration panel for system logins.
    system.wssecurity.Signature
    This selection enables a Version 5.x application to map a distinguished name (DN) in a signed certificate to a WebSphere Application Server credential principal. To modify this configuration, see the JAAS configuration panel for system logins.
    system.LTPA_WEB
    This selection processes login requests that are used by the Web container such as servlets and JavaServer Pages (JSPs) files. To modify this configuration, see the JAAS configuration panel for system logins.
    system.WEB_INBOUND
    This selection handles login requests for Web applications, which include servlets and JavaServer Pages (JSP) files. This login configuration is used by WebSphere Application Server Version 5.1.1. To modify this configuration, see the JAAS configuration panel for system logins.
    system.RMI_INBOUND
    This selection handles logins for inbound Remote Method Invocation (RMI) requests. This login configuration is used by WebSphere Application Server Version 5.1.1. To modify this configuration, see the JAAS configuration panel for system logins.
    system.DEFAULT
    This selection handles the logins for inbound requests that are made by internal authentications and most of the other protocols except Web applications and RMI requests. This login configuration is used by WebSphere Application Server Version 5.1.1. To modify this configuration, see the JAAS configuration panel for system logins.
    system.RMI_OUTBOUND
    This selection processes RMI requests that are sent outbound to another server when either the com.ibm.CSI.rmiOutboundLoginEnabled or the com.ibm.CSIOutboundPropagationEnabled properties are true. These properties are set in the CSIv2 authentication panel.

    To access the panel, click Security > Global security. Under Authentication, click Authentication protocol > CSIv2 outbound authentication. To set the com.ibm.CSI.rmiOutboundLoginEnabled property, select the Custom outbound mapping option. To set the com.ibm.CSIOutboundPropagationEnabled property, select the Security attribute propagation option. To modify this JAAS login configuration, see the JAAS configuration panel for system logins.

    system.wssecurity.X509BST
    This selection verifies an X.509 binary security token (BST) by checking the validity of the certificate and the certificate path. To modify this configuration, see the JAAS configuration panel for system logins.
    system.wssecurity.PKCS7
    This selection verifies an X.509 certificate within a PKCS7 object that might include a certificate chain, a certificate revocation list, or both. To modify this configuration, see the JAAS configuration panel for system logins.
    system.wssecurity.PkiPath
    This section verifies an X.509 certificate with a public key infrastructure (PKI) path. To modify this configuration, see the JAAS configuration panel for system logins.
    system.wssecurity.UsernameToken
    This selection verifies the basic authentication (user name and password) data. To modify this configuration, see the JAAS configuration panel for system logins.
    system.wssecurity.IDAssertionUsernameToken
    This selection supports the use of identity assertion in Version 6 applications to map a user name to a WebSphere Application Server credential principal. To modify this configuration, see the JAAS configuration panel for system logins.
    None
    With this selection, you do not specify a JAAS login configuration.
  14. Click OK and then click Save to save the configuration.
You have configured the token consumer for the application level.
You must specify a similar token generator configuration for the application level.
Parent topic: Securing JAX-RPC Web services manually based on WS-Security
Related concepts
Default implementations of the Web services security service provider programming interfaces
Related tasks
Configuring the collection certificate store for the consumer binding on the application level
Configuring token consumer on the application level
Feedback