Migrating the server-side bindings file

This article provides general information about migrating the server-side bindings configuration for a Java™ 2 Platform, Enterprise Edition (J2EE) Version 1.3 application to a J2EE Version 1.4 application. The steps are based on typical scenarios, but the steps are not all-inclusive.

The following table lists the mappings of the top-level sections under the server-side Binding Configurations tab from a J2EE Version 1.3 application to a J2EE Version 1.4 application.

Table 1. The mapping of the configuration sections
J2EE Version 1.3 Binding Configurations	J2EE Version 1.4 Binding Configurations
Request Receiver Binding Configuration Details	Request Consumer Service Binding Configuration Details
Response Sender Binding Configuration Details	Response Generator Binding Configuration Details

Consider the following steps to migrate the server-side bindings from J2EE Version 1.3 to J2EE Version 1.4. These steps are dependent upon your specific configuration.

Migrate the configuration information under the Request Receiver Binding Configuration Details section of a J2EE Version 1.3 application.
1. Migrate any trust anchor information that is specified in the J2EE Version 1.3 application to J2EE Version 1.4 using the Trust Anchor dialog.
2. Migrate the information under the certificate store list that is specified in the J2EE Version 1.3 application to J2EE Version 1.4 by configuring the Certificate Store List section in the J2EE Version 1.4 application.
3. Configure the key locator and token consumer information that is referenced from the Key Information dialog window. The configuration of the key locator and the token consumer depends upon the key information type. For example, if an X.509 certificate that is embedded in the <wsse:Security> security header is used for digital signature, complete the following steps:
  1. For configuring the key locator, specify the com.ibm.wsspi.wssecurity.keyinfo.X509TokenKeyLocator class as the key locator class and do not specify a key store.
  2. For configuring the token consumer, select the com.ibm.wsspi.wssecurity.token.509TokenConsumer class, specify X509 certificate token for the value type Uniform Resource Identifier (URI), and specify system.wssecurity.X509BST in the jaas.config.name field. Also, you must specify the certificate path settings (the trust anchor reference and the certificate store reference) as part of the token consumer configuration.
4. Explicitly specify the key information type in the Key Information Dialog window. In a J2EE Version 1.3 application, the key information type, such as the security token reference and the key identifier, is not explicitly specified. The key information type is implied by the configuration. In a J2EE Version 1.4 application, you must specify the key information type explicitly using the Key Information Dialog when you have digital signature or encryption information in the binding file. Before you configure the key information, make sure that you have configured the key locator and token consumer information that is referenced from the Key Information dialog.
  When you configure the key information for either digital signature or encryption, you need to specify the correct key information type. The value of the key information type depends upon the type of mechanism that is used to reference the security token that is used for digitally signing or encrypting. The following information describes the Security token reference (or Direct reference) and the Key identifier, which are the most common, recommended key information types that are used for digitally signing and encrypting:
  Security token reference (or Direct reference)
  The security token is directly referenced using the Uniform Resource Identifiers (URIs). The following <KeyInfo> element is generated in the Simple Object Access Protocol (SOAP) message for this key information type:
  <ds:KeyInfo> <wsse:SecurityTokenReference> <wsse:Reference URI="#mytoken" /> </wsse:SecurityTokenReference> </ds:KeyInfo>
  Key identifier
  The security token is referenced using an opaque value that uniquely identifies the token. The algorithm that is used for generating the KeyIdentifier value depends upon the token type. For example, a hash of the important elements of the security token is used for generating the KeyIdentifier value. The following <KeyInfo> element is generated in the SOAP message for this key information type:
  <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <wsse:SecurityTokenReference> <wsse:KeyIdentifier ValueType="wsse:X509v3">/62wXO...</wsse:KeyIdentifier> </wsse:SecurityTokenReference> </ds:KeyInfo>
  In the Key Information Dialog window, specify the names of the key locator and the token consumer that you configured previously. The Key name field is optional for the consumer side.
5. Migrate the information in the Signing Information section by configuring the Signing Information, Part References, and Transforms sections.
  - Specify the Signature method and Canonicalization method algorithms in the Signing Information Dialog window.
  - Specify the Digest method algorithm in the Part Reference Dialog window.
6. Migrate the information under the Encryption Information section. In the Encryption Information Dialog window, select the name of the Key Information element that is configured for encryption, and specify the RequiredConfidentiality part. Verify that the value for the selected RequiredConfidentiality part is the same name as the Required Confidentiality part that is configured in the extension file.
  The Login Mapping section in the J2EE Version 1.3 application maps to the Token Consumer configuration for the type of token that is specified by the authentication method. For example, to migrate a Login Mappings configuration that uses the BasicAuth authentication method, configure a token consumer for the username token. To configure a token consumer for a username token, complete the following steps:
  1. Select the com.ibm.wsspi.wssecurity.UsernameTokenConsumer token consumer class.
  2. Specify the name of the Required Security Token configuration from the Extensions within in the Security Token field.
  3. Select Username Token for value type.
  4. Specify the system.wssecurity.UsernameToken value in the jaas.config.name field.
Migrate the configuration information in the Response Sender Binding Configuration Details section of the J2EE Version 1.3 bindings file to the Response Generator Binding Configuration Details section of the J2EE Version 1.4 application. Configuring the Response Generator section is very similar to configuring the Request Consumer section.
1. Migrate the information from the Key Locators section by using the Key Locator Dialog window in an assembly tool.
2. Configure a token generator, which is referenced in the Key Information Dialog window. You must configure a token generator for every security token that is generated in the SOAP message. If the token generator is for an X.509 certificate that is used for digital signature or encryption, complete the following steps:
  1. For configuring the key locator, specify the com.ibm.wsspi.wssecurity.keyinfo.X509TokenKeyLocator class as the key locator class and do not specify a key store.
  2. For configuring the token generator, select the com.ibm.wsspi.wssecurity.X509TokenGenerator class and specify X509 certificate token for the value type Uniform Resource Identifier (URI). The key store information that is specified for the token generator is the same information that is used for configuring the key locator. Therefore, the keystore information from the Key Locators configuration in a J2EE Version 1.3 application is used to configure the key locator and the token generator in a J2EE Version 1.4 application.
  3. In the Token Generator Dialog window, specify the key store information that is required by the callback handler to obtain the key information that is required for generating the token.
  4. For the callback handler, select the com.ibm.wsspi.wssecurity.auth.callback.X509CallbackHandler class.
3. Specify the names of the key locator and the token generator in the Key Information Dialog window that you configured previously. The Key name is required for the generator side. The key that is specified in the Key Information Dialog window must exist in the list of keys that is specified in the key locator configuration. Also, migrating the Signing Information and the Encryption Information configurations is similar to migrating the Signing Information and the Encryption Information configurations for the Request Receiver Binding Configuration section. Configuring the key information for the response generator section is similar to configuring the key information for the request consumer section.

This set of steps describse the types of information that you need to migrate the server-side bindings configuration for a J2EE Version 1.3 application to a J2EE Version 1.4 application.

Migrate the client-side binding configuration for a J2EE Version 1.3 application to a J2EE Version 1.4 application. For more information, see Migrating the client-side bindings file.