Configure a pluggable token

This topic describes how to configure the request sender to create security tokens in the Simple Object Access Protocol (SOAP) message and how to configure the request receiver to validate the security tokens found in the incoming SOAP message. You can use the authentication method defined in the login bindings and login mappings to generate security tokens in the request sender and validate security tokens in the request receiver.

WebSphere Application Server - Express supports pluggable security tokens. See the following topics for more information:

Note: The pluggable token is required for the request sender and request receiver as they are a pair. The request sender and the request receiver must match for a request to be accepted by the receiver.

Prior to completing these steps, it is assumed that you have already created a Web services-enabled Java 2 Platform, Enterprise Edition (J2EE) with a Web Services for J2EE (JSR 109) enterprise application. If not, see Developing Web services to create Web services-enabled J2EE with a JSR 109 enterprise application.

Perform the folowing steps in the WebSphere Development Studio Client for iSeries to configure a pluggable token for your Web service client:

  1. Open the webservicesclient.xml file in the Web Services Client Editor of the WebSphere Development Studio Client for iSeries. For more information, see Configure your Web services application.

  2. Click the Security Extensions tab. The Web Service Client Security Extensions editor displays. Specify the following settings:

    1. Under Service References, select an existing service reference or click Add to create a new one.
    2. Under Port Qname Bindings, select an existing port-qualified name for the selected service reference or click Add to create a new port name binding.
    3. Under Request Sender Configuration: Login Config, select an exiting authentication method or type in a new one in the editable list box. When a Web servics acts as a client, LTPA is a supported token generation format.

  3. Click the Web Services Client Binding tab. The Web Services Client Binding editor displays. Specify the following settings:

    1. Under Port Qualified Name Binding, select an existing entry or click Add to add a new port name binding. The Web Services Client Binding editor displays for the selected port.

    2. Under Login Binding, click Edit or Enable. The Login Binding dialog displays. Specify the following settings:

      1. In the Authentication Method field, enter the authentication method. The authentication method that you enter in this field must match the authentication method defined on the Security Extension tab for the same Web service port. This field is mandatory.
      2. (Optional) Enter the token value type information in the URI and Local name fields. These fields are ignored for the BasicAuth, Signature, and IDAssertion authentication methods, but required for other authentication methods. The token value type information is inserted into the <wsse:BinarySecurityToken>@ValueType element for binary security token and is used as the namespace for the XML-based token.
      3. Enter an implementation of the Java Authentication and Authorization Service (JAAS) javax.security.auth.callback.CallbackHandler interface. See Generating a pluggable token for information on how to develop a CallbackHandler that can generate a security token in the request sender. This is a mandatory field.
      4. Enter the basic authentication information in the User ID and Password fields. The basic authentication information is passed to the constructor of the CallbackHandler implementation. The usage of the basic authentication information is up to the implementation of the CallbackHandler.
      5. In the Property field, add name and value pairs. These pairs are passed to the constructor of the CallbackHandler implementation as java.util.Map data types.
      6. Click OK.

  4. Save the file.

Perform the folowing steps in the WebSphere Development Studio Client for iSeries to configure a pluggable token for your Web services application:

  1. Open the webservices.xml deployment descriptor for your Web services application in the Web Services Editor of the WebSphere Development Studio Client for iSeries. For more information, see Configure your Web services application.

  2. Click the Security Extensions tab. Specify the following settings:

    1. Under Web Service Description Extension, select an existing service reference or click Add to create a new extension.
    2. Under Port Component Binding, select an existing port-qualified name of the selected service reference or click Add to create a new one.
    3. Under Request Receiver Service Configuration Details: Login Config, select an exiting authentication method or click Add and enter a new method in the Add AuthMethod field that displays. You can select multiple authentication methods for the request receiver. The security token of the incoming message is authenticated against the authentication methods in the order that they are specified in the list.

  3. Click the Bindings tab. The Web Services Bindings editor displays. Under Web Service Description Bindings, select an existing entry or click Add to add a new Web services descriptor.

  4. Click the Binding Configurations tab. The Web Services Binding Configurations editor displays for the selected Web services descriptor. Under Request Receiver Binding Configuration Details: Login Mapping, click Add to create a new login mapping or click Edit to edit existing selected login mapping.

    The Login mapping dialog displays. Specify the following settings:

    1. In the Authentication method field, enter the authentication method. The information entered in this field must match the authentication method defined on the Security Extensions tab for the same Web service port. This is a mandatory field.
    2. In the Configuration name field, enter a JAAS login configuration name. You must define the JAAS login configuration name in the WebSphere administrative console under Security --> JAAS Configuration --> Application Logins). This is a mandatory field. For more information, see Configure JAAS login in the Security topic.
    3. (Optional) Select Use Token value type and enter the token value type information in the URI and Local name fields. This information is optional for BasicAuth, Signature and IDAssertion authentication methods, but required for any other authentication method. The token value type is used to validate the <wsse:BinarySecurityToken>@ValueType element for binary security tokens and to validate the namespace of the XML-based token.
    4. Under Callback Handler Factory, enter an implementation of the com.ibm.wsspi.wssecurity.auth.callback.CallbackHandlerFactory interface in the Class name field. This field is mandatory. See Validating a pluggable token for instructions on how to develop a CallbackHandlerFactory and JAAS Login Configuration to validate the security token of the incoming message.
    5. Under Callback Handler Factory Property, click Add and enter the name and value pairs for the Callback Handler Factory Property. These name and value pairs are passed as a java.util.Map data type to the com.ibm.wsspi.wssecurity.auth.callback.CallbackHandlerFactory.init() method. The usage of these name and value pairs is determined by the CallbackHandlerFactory implementation chosen.
    6. Under Login Mapping Property, click Add and enter the name and value pairs for the Login Mapping Property. These name and value pairs are available to the JAAS Login Module or Modules through thecom.ibm.wsspi.wssecurity.auth.callback.PropertyCallback JAAS Callback interface. Click Remove to delete selected login mapping.
    7. Click OK.

  5. Save the file.

Configure pluggable tokens with WebSphere administrative console

Prior to completing these steps, it is assumed that you deployed a Web services-enabled enterprise application to the WebSphere Application Server - Express.

Perform the following steps in the administrative console:

  1. Click Applications --> Enterprise Applications --> enterprise_application, where enterprise_application is the name of your enterprise application.

  2. Under Related Items, click Web Modules --> Uri, where Uri is the URI of your Web services-enabled module.

  3. (Optional) If the Web service is acting as a client, configure the client bindings. Under Additional Properties, click Web Services: Client Security Bindings to edit the response sender binding information, if Web services is acting as client. Specify the following settings:

    1. Under Response Sender Binding, click Edit.

    2. Under Additional Properties, click Login Binding.

    3. Select Dedicated Login Binding to define a new login binding. Specify the following settings:

      1. Enter the authentication method, this must match the authentication method defined in the IBM extension deployment descriptor. The authentication method must be unique in the binding file.
      2. Enter the name of your JAAS javax.security.auth.callback.CallbackHandler implementation. For more information, see Generating a pluggable token.
      3. Enter the basic authentication information (User ID and Password). The basic authentication information is passed to the construct of the CallbackHandler implementation. The usage of the basic authentication information defined by the implementation of the CallbackHandler.
      4. Enter the token value type, it is optional for BasicAuth, Signature and IDAssertion authentication methods but required for any other authentication method. The token value type is inserted into the <wsse:BinarySecurityToken>@ValueType for binary security token and used as the namespace of the XML-based token.
      5. Click Properties. Define the property with name and value pairs. These pairs are passed to the construct of the CallbackHandler implementation as java.util.Map data types.

  4. Under Additional Properties, click Web Services: Server Security Bindings to edit the request receiver binding information. Specify the following settings:

    1. Under Request Receiver Binding, click Edit.

    2. Under Additional Properties, click Login Mappings. Click New to create new login mapping. Specify the following settings:

      1. Enter the authentication method, this must match the authentication method defined in the IBM extension deployment descriptor. The authentication method must be unique in the login mapping collection of the binding file.
      2. Enter a JAAS Login Configuration name. The JAAS Login Configuration must be defined in the Security --> JAAS Configuration --> Application Logins settings. For more information, see Configure JAAS login in the Security topic.
      3. Enter the name of your com.ibm.wsspi.wssecurity.auth.callback.CallbackHandlerFactory implementation. See Validating a pluggable token for more information. This is a mandatory field.
      4. Enter the token value type. This setting is optional for BasicAuth, Signature and IDAssertion authentication methods but required for any other authentication method. The token value type is used to validate against the <wsse:BinarySecurityToken>@ValueType for binary security token and against the namespace of the XML-based token.
      5. Enter the name and value pairs for the Login Mapping Property by clicking Properties. These name and value pairs are available to the JAAS login module or modules by the com.ibm.wsspi.wssecurity.auth.callback.PropertyCallback JAAS callback.
      6. Enter the name and value pairs for the Callback Handler Factory Property These name and value pairs are passed as java.util.Map data types to the om.ibm.wsspi.wssecurity.auth.callback.CallbackHandlerFactory.init() method. The usage of these name and value pairs is dependent on the CallbackHandlerFactory implementation.

  5. Save the configuration.

You can also define login mappings for the server-level and cell-level default binding configuration (ws-security.xml). To define the login mappings for the server-level default binding configuration, perform these steps in the administrative console:

  1. Click Servers --> Application Servers --> server_name, where server_name is the name of your application server.

  2. Under Related Items, click Web Services: Default bindings for Web Services Security and then follow the steps outlined previously for creating or editing login mappings for Web Services: Server Security Bindings.

  3. To define the login mappings for the cell-level default binding configuration, click Security --> Web Services and then follow the steps outlined previously for creating or editing login mappings for Web Services: Server Security Bindings.

  4. Save the configuration.