+

Search Tips   |   Advanced Search

Callback handler settings for JAX-WS

Configure callback handler settings for JAX-WS, which determine how security tokens are acquired from messages headers.

We can configure callback handler settings when we are editing a general cell-level or server-level binding. We can also configure application specific bindings for tokens and message parts required by the policy set.

Before we specify values for the Keystore and Key properties on this page, we must understand that the keystore/alias information that we provide for the generator, and the keystore/alias information that we provide for the consumer are used for different purposes. The main difference applies to the alias for an X.509 callback handler:.

Generator

When used in association with an encryption generator, the alias supplied for the generator is used to retrieve the public key to encrypt the message. A password is not required. The alias that is entered on a callback handler associated with an encryption generator must be accessible without a password. This means that the alias must not have private key information associated with it in the keystore. When used in association with a signature generator, the alias supplied for the generator is used to retrieve the private key to sign the message. A password is required.

Since an alias used to sign a message requires a password, and an alias used to encrypt a message requires there be no password, we cannot use the same alias for both a signature generator and an encryption generator.

Consumer

When used in association with an encryption consumer, the alias supplied for the consumer is used retrieve the private key to decrypt the message. A password is required.

When used in associated with a signature consumer, the alias supplied for the consumer is used strictly to retrieve the public key used to resolve an X.509 certificate that is not passed in the SOAP security header as a BinarySecurityToken. A password is not required.

The alias that is entered on a callback handler associated with an signature consumer must be accessible without a password. This means that the alias must not have private key information associated with it in the keystore.

When an X.509 certificate that is not passed in the SOAP security header as a BinarySecurityToken, a SecurityTokenReference will appear in the KeyInfo element within the Signature element in the SOAP security header that will be used to resolve the X.509 certificate. The methods that can be used are Key identifier, X.509 issuer name and issuer serial, and Thumbprint. The consumer will accept any of these three methods for resolving an X.509 certificate outside the message when a keystore/alias is configured for an X.509 token consumer associated with a signature consumer. The X.509 token consumer does not dynamically resolve certificates that appear outside the message to entries in a keystore. The certificates that will be used must be known at configuration time and hardcoded in the X.509 token consumer callback handler.

When an X.509 certificate is to be resolved outside the message, we can resolve multiple certificates when using general bindings, but only one when using application specific bindings. Only one certificate can be resolved outside the message when application specific bindings are used because, in application specific bindings, there is only one X.509 token consumer availble to use. Since there is only one X.509 token consumer to use, there is only one alias to use, therefore, only one certificate can be resolved. For example, if the X.509 token consumer is configured for certificate A, if client A sends the keyIdentifier for certificate A, the certificate can be retrieved. However, if client B sends the keyIdentifier for certificate B, the certificate cannot be retrieved and the message will be rejected.

When general bindings are used, multiple X.509 token consumers can be created that each have different certificates configured on them (keystore/alias). All of the X.509 token consumers associated with the certificates that you wish to resolve would be assigned to the Signing key information of our signed part configuration in the bindings.

When an X.509 certificate is sent in the SOAP security header as a BinarySecurityToken, if there is a keystore/alias configured on the X.509 token consumer associated with a signature consumer, the certificate configured on the consumer will be compared against the one that is passed in the message. If they do not match, the message will be rejected. This behavior is different than JAX-RPC. The certificate associated with the alias configured on the X.509 token consumer is not used to evaluate trust on the inbound certificate. Only the trust store and cert stores are used for that purpose.

If we want the certificate configured on the X.509 token consumer associated with a signature consumer to be available for KeyInfo resolution, but not reject X.509 certificates passed in the message that do not match, we can add the following custom property to the X.509 token consumer callback handler: 

com.ibm.wsspi.wssecurity.consumer.callbackHandlerKeystoreLimitsAccess=false

Since an alias used to decrypt a message requires a password, and an alias used to verify a signature requires there be no password, we cannot use the same alias for both a signature consumer and an encryption consumer.

Checking your keys

We can check that the alias to configure for an X.509 token consumer or generator callback handler is the correct type using the keytool application.

The keytool application is installed with the application server in the (wasHome)/bin directory. If we run 'keytool' without parameters, it diplays the syntax. An example invocation of the keytool application is: 

keytool -list -v -keystore myKeystore.p12 -storepass myPassword -storetype PKCS12

Use the keytool application to show the contents of our keystore, then check to see if the entry type of our alias is consistent with its intended use. If we are configuring an entry that requires a private key, the entry type must be keyEntry. If we are configuring an entry that requires a public key, the entry type must be trustedCertEntry.

To view this administrative console page when we are editing a general cell-level binding, complete the following actions:

  1. Click Services > Policy sets > Default policy set bindings. The bindings panel indicates which binding is set as the default binding, for example, the Provider sample binding.

  2. To edit this default binding, click Services > Policy sets > General provider policy set bindings.

  3. Click the name of the default binding as determined in the first step. For example, Provider sample.

  4. Click the WS-Security policy in the Policies table.

  5. Click the Authentication and protection link in the Main message security policy bindings section.

  6. Click the name_of_token link in the Protection tokens section or the Authentication tokens section.

  7. Click the Callback handler link.

To view this administrative console page when we are configuring application specific bindings for tokens and message parts required by the policy set:

  1. Click Applications > Application Types > WebSphere enterprise applications.

  2. Select an application containing web services. The application must contain a service provider or a service client.

  3. Click the Service provider policy sets and bindings link or the Service client policy sets and bindings in the Web Services Properties section.

  4. Select a binding. We must have previously attached a policy set and assigned an application specific binding.

  5. Click the WS-Security policy in the Policies table.

  6. Click the Authentication and protection link in the Main message security policy bindings section.

  7. Click the name_of_token link in the Protection tokens section or the Authentication tokens section.

  8. Click the Callback handler link.

This administrative console page applies only to JAX-WS applications.

The Callback Handler displays fields differently for different tokens being configured. Depending on whether we are configuring generator or consumer tokens for protection or we are configuring inbound or outbound tokens for authentication, the sections and fields on this panel display some or all of the fields explained in this topic, as noted in the description of each field.


Class name

The fields in the Class name section are available for all types of token configuration.

Select the class name to use for the callback handler. Select the Use built-in default option for normal operation. Use the Use custom option only if we are using a custom token type.

For the Kerberos custom token type, use the class name, com.ibm.websphere.wssecurity.callbackhandler.KRBTokenGenerateCallbackHandler, for token generator configuration. Use com.ibm.websphere.wssecurity.callbackhandler.KRBTokenConsumeCallbackHandler for token consumer configuration.


Use built-in default

That the default value is used for the class name. Use the default value (shown in the field) for the class name when we select this radio button. This name is based on the token type and whether the callback handler is for a token generator or a token consumer. This option is mutually exclusive to the Use custom option.


Use custom

That a custom value is used for the class name. Select this radio button and enter the name in the field to use a custom class name.

No default value is available for this entry field. Use the information in the following table to determine this value:

Token Type Consumer or Generator Callback Handler Class Name
UsernameToken consumer com.ibm.websphere.wssecurity.callbackhandler.UNTConsumeCallbackHandler
UsernameToken generator com.ibm.websphere.wssecurity.callbackhandler.UNTGenerateCallbackHandler
X509Token consumer com.ibm.websphere.wssecurity.callbackhandler.X509ConsumeCallbackHandler
X509Token generator com.ibm.websphere.wssecurity.callbackhandler.X509GenerateCallbackHandler
LTPAToken/LTPAPropagationToken consumer com.ibm.websphere.wssecurity.callbackhandler.LTPAConsumeCallbackHandler
LTPAToken/LTPAPropagationToken generator com.ibm.websphere.wssecurity.callbackhandler.LTPAGenerateCallbackHandler
SecureConversationToken consumer com.ibm.ws.wssecurity.impl.auth.callback.SCTConsumeCallbackHandler
SecureConversationToken generator com.ibm.ws.wssecurity.impl.auth.callback.WSTrustCallbackHandler

This button is mutually exclusive to the Use built-in default option.


Certificates (generator)

The fields in the Certificates section are available if we are configuring a protection token. For a generator token, we can click to select a certificate store from the listing, or click the New button to add a certificate store.


Certificates (consumer)

The fields in the Certificates section are available if we are configuring a protection token. For a consumer token, we can use the Trust any certificate option, or the Certificate store option, to configure the certificate store.


Certificates - Trust any certificate (consumer)

This option is applicable only to the token consumer. This option indicates the system will trust all certificates, and does not define a specific certificate store. This option is mutually exclusive to the Certificate store option.


Certificates - Certificate store (consumer)

This option is applicable only the to the token consumer. Specify a certificate store collection containing intermediate certificates, which can include certificate revocation lists (CRLs). Select this option to trust the certificate store or stores specified in the entry field. This option is mutually exclusive to the Trust any certificate option. When we select the Certificate store option, the New button is enabled so that we can configure a new certificate store and trusted anchor store.

We can set the value of the certificate store field to the default value, which is None. However, the trusted anchor store value must be set to a specific value. There is no default value. The trusted anchor is required if the Trust any certificate option is not selected.


Basic authentication

The fields in the Basic authentication section are available if we are configuring an authentication token that is not an LTPA propagation token.

For the Kerberos custom token type, complete the Basic Authentication section for the Kerberos login.


User name

User name to authenticate.


Password

Password to be authenticated. Enter a password to authenticate in this entry field.


Confirm password

Password to confirm.


Keystore

The keystore fields are not available when the run times determines that they are not needed.

In the Keystore name list, we can click Custom to define a custom keystore, click one of the externally defined keystore names, or click None if no keystore is required.


Keystore - Name

Name of the keystore to use.

Click the name of a keystore name from this menu or select one of the following values:

None

To not use a keystore.

Custom

To use a user-defined keystore. Click the Custom keystore configuration link to configure custom keystore and key settings.


Key

Attributes of the key to be retrieved from the configured key store. Some fields in the Key section are not available when the run times determines that they are not needed.

When a centrally managed keystore is selected for the Keystore, the fields in the Key section are available.


Name

Name of the key to use. The list is populated with the keys available in the selected centrally managed keystore. Select the name of the key to use, or '(none)' if no key is to be used.


Alias

Display the alias of the key name selected


Password

Password for the key to use. This field will only be available when the run time determines that it is needed.

We cannot set a password for public keys for asymmetric encryption generator or asymmetric signature consumer. Please refer to 'avoid trouble' at the beginning of the article.


Confirm password

Confirmation of the password for the key to use. This field will only be available when the run time determines that it is needed.

Do not provide a key confirm password for public keys for asymmetric outbound encryption or inbound signature.


Keystore - Custom keystore configuration

Link to create a custom keystore. Click this link to open a panel where we can configure a custom keystore.


Key store password

Password used to access the keystore file.


Key store path

Location of the keystore file.

Use ${USER_INSTALL_ROOT} in the path name because this variable expands to the product path on the machine. To change the path used by this variable, click Environment > WebSphere variables and click USER_INSTALL_ROOT.


Key store type

Type of keystore file format

Choose 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 the application server. This option provides stronger protection for stored private keys using Triple DES encryption.

(ZOS) JCERACFKS

(ZOS) Use JCERACFKS if the certificates are stored in a SAF key ring (z/OS only).

PKCS12KS (PKCS12)

Use this option if your keystore file uses the PKCS#12 file format.


Custom properties

The fields in the Custom properties section are available for all types of token configuration.

We can add custom properties needed by the callback handler using name-value pairs.

To implement signer certificate encryption when using JAX-WS, add the custom property com.ibm.wsspi.wssecurity.token.cert.useRequestorCert with the value true on the callback handler of the encryption token generator. This implementation uses the certificate of the signer of the SOAP request to encrypt the SOAP response. This custom property is used by the response generator.

For a Kerberos custom token based on OASIS Web Services Security Specification for Kerberos Token Profile V1.1, specify the following property for token generation: com.ibm.wsspi.wssecurity.krbtoken.clientRealm. Name of the Kerberos realm associated with the client and allows the Kerberos client realm to initiate the Kerberos login. If not specified, the default Kerberos realm name is used. This property is optional for a single Kerberos realm environment.

The Kerberos custom property, com.ibm.wsspi.wssecurity.krbtoken.loginPrompt, enables the Kerberos login when the value is true. The default is false. This property is optional.

When configuring a username token for JAX-WS, to protect against replay attacks it is strongly recommended that we add the following custom properties to the callback handler configuration. These custom properties enable and verify the nonce and timestamp for message authentication.

Property name (generator) Property value
com.ibm.wsspi.wssecurity.token.username.addNonce true
com.ibm.wsspi.wssecurity.token.username.addTimestamp true

Property name (consumer) Property value
com.ibm.wsspi.wssecurity.token.username.verifyNonce true
com.ibm.wsspi.wssecurity.token.username.verifyTimestamp true


Name

Name of the custom property to use.

Custom properties are not initially displayed in this column. Click one of the following actions for custom properties:

Button Resulting action
New Creates a new custom property entry. To add a custom property, enter the name and value.
Delete Removes the selected custom property.


Value

Value of the custom property to use. With the Value entry field, we can enter or delete the value for a custom property.

  • Define and manage policy set bindings
  • Manage policy sets
  • WS-Security authentication and protection
  • Protection token settings (generator or consumer)
  • Application policy sets collection
  • Application policy set settings
  • Search attached applications collection
  • Policy set bindings settings
  • Key information settings