Configure the Kerberos token policy set for JAX-WS applications

Use this topic to enable the Kerberos token policy set for JAX-WS applications.

Prior to beginning this task, specify the Kerberos configuration information for IBM WebSphere Application Server. See Kerberos (KRB5) authentication mechanism support for security.

The configuration model for the Kerberos token enables us to choose from the following existing WAS frameworks:

• For JAX-RPC applications, the deployment descriptor and bindings are used in the configuration. JAX-RPC application includes the deployment descriptor for a Kerberos custom token, which is configured with authentication tokens.

• For JAX-WS applications, the configuration uses a policy set and bindings. The JAX-WS application is attached by a custom policy with the Kerberos token configured with authentication tokens, message protection tokens, or both.

Fix packs that include updates to the SDK might overwrite unrestricted policy files. Back up unrestricted policy files before applying a fix pack and reapply these files after the fix pack is applied.

Configure the Kerberos token policy set for JAX-WS applications using the administrative console for WAS. In these steps, the Main policy configuation panel references the administrative console panel that is available after completing the first five steps.

Tasks

1. Expand Services > Policy sets and click Application policy sets > New to create a new policy set.

2. Specify a name and a short description for the new policy set and click Apply.

3. From the Policies heading, click Add and then select the WS-Security security policy type.

4. Click OK and click Save to save the new configuration directly to the master configuration.

5. In the Policies field, click WS-Security and click Main policy on the WS-Security panel to configure the main policy for the Kerberos token policy set.

6. From the Key Symmetry heading, select Use symmetric tokens for message protection.
7. Click Symmetric signature and encryption policies to configure the Kerberos custom token type or clear the Message level protection check box if we are configuring an authentication token only.

   Important: We do not need to configure the request token policy if we are using the Kerberos token for message protection. If we are configuring the authentication token only, proceed to the next step. If we are not configuring the request token policy for the authentication token, skip the next step.

8. On the Main policy configuration panel, configure the policy for the request token if we are configuring the authentication token.

   1. From the Policy Details heading, click Request token policies.

   2. Click Add token type and select Custom.

   3. Specify the name of the custom token in the Custom token name field.

   4. Specify the local part value in the Local part field. For interoperability with other web services technologies, specify the following local part: http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#GSS_Kerberosv5_AP_REQ. If we are not concerned with interoperability issues, we can specify one of the following local name values:
      • http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#Kerberosv5_AP_REQ
      • http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#Kerberosv5_AP_REQ1510
      • http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#GSS_Kerberosv5_AP_REQ1510
      • http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#Kerberosv5_AP_REQ4120
      • http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#GSS_Kerberosv5_AP_REQ4120

      These alternative values depend on the specification level for the Kerberos AP-REQ token generated by the Key Distribution Center (KDC). For more information about when to use these values, see Token type settings.

   5. Do not specify a value for the Namespace URI field if we are generating a Kerberos token.

   6. Click OK and Save to save the configuration directly to the master configuration.

   This step completes the configuration process for configuring the request token policy for the authentication token. We do not need to complete the next two steps. Complete the next steps to configure encryption and symmetric signature policies.

9. Return to the main policy configuration panel for the application policy set and click Symmetric signature and encryption policies to configure the encryption and symmetric signature policies.

   1. From the Message Integrity heading, click the Action menu list for the Token type for signing and validating messages field and select Custom.

   2. From the Message Confidentiality heading, select the Use same token for confidentiality used for integrity option.

   3. Click OK and Save to save the configuration changes.

   4. From the Message Integrity heading, click the Action menu list for the Token type for signing and validating messages field and select Edit Selected Type Policy.

   5. Edit the custom token type for the signature and encryption by specifying the local part for the Kerberos custom token.

      For example, specify http://docs.oasis-open.org/wss/oasis-wss-kerberos-token-profile-1.1#GSS_Kerberosv5_AP_REQ for the local part value. Do not specify a Namespace URI value.

   6. Click OK and then click the Save link to save the configuration changes.

10. Return to the main policy configuration panel for the application policy set and click Algorithms for symmetric tokens to configure the symmetric token algorithm.

    1. Select the algorithm suite to use for the symmetric tokens from the Algorithm suite menu list. Select the AES algorithms for a Kerberos token that is compliant with RFC-4120.

       The symmetric key wrap, or private key cryptography, algorithms include:

       • Triple DES key wrap: http://www.w3.org/2001/04/xmlenc#kw-tripledes
       • AES key wrap (aes128): http://www.w3.org/2001/04/xmlenc#kw-aes128
       • AES key wrap (aes256): http://www.w3.org/2001/04/xmlenc#kw-aes256

       Restriction: To use the 256-bit AES encryption algorithm, we must apply the unlimited jurisdiction policy files. To remain in compliance, see Basic Security Profile compliance tips.

       (Dist) Before downloading these policy files, mount the product HFS as read/write. Back up the existing policy files prior to overwriting them, in case we want to restore the original files later. The existing policy files, which are the local_policy.jar and US_export_policy.jar files, are located in the WAS_HOME/java/jre/lib/security/ directory.

       (ZOS) Before downloading these policy files, mount the product HFS as read/write. Back up the existing policy files prior to overwriting them, in case we want to restore the original files later. The existing policy files, which are the local_policy.jar and US_export_policy.jar files, are located in the WAS_HOME/java/lib/security/ directory.

       Important: Your country of origin might have restrictions on the import, possession, use, or re-export to another country, of encryption software. Before downloading or using the unrestricted policy files, we must check the laws of our country, its regulations, and its policies concerning the import, possession, use, and re-export of encryption software, to determine if it is permitted. For application server platforms using IBM Developer Kit, Java Technology Edition, v5, we can obtain unlimited jurisdiction policy files by completing the following steps:

       1. Visit the IBM developerWorks: Security Information website.

       2. Click Java 5.

       3. Click IBM SDK Policy files.

          The Unrestricted JCE Policy files for SDK 5 website is displayed.

       4. Enter your user ID and password or register with IBM to download the policy files. The policy files are downloaded onto your workstation.
       5. Re-mount the product HFS as read/only.

       For more information on the algorithm suite components, see Algorithms settings.

    2. Select either the Exclusive canonicalization or Inclusive canonicalization value for the Canonicalization algorithm menu list. For more information, see XML digital signature.

    3. Specify the XPath 1.0 or XPathfilter 2.0 version to use from the XPath version menu list.

What to do next

Configure the bindings for message protection for Kerberos for JAX-WS applications. See Configure the bindings for message protection for Kerberos.

Related:

Kerberos (KRB5) authentication mechanism support for security

XML digital signature

Basic Security Profile compliance tips

Configure the bindings for message protection for Kerberos

Request or Response token policies collection

Token type settings

Symmetric signature and encryption policies settings

Algorithms settings

Encryption information configuration settings: Message parts

IBM developerWorks: Security Information website