Generic security token login module for the token generator

When a web service request is made, the application server calls the generic security login module for the token generator as part of the Web Service Security authentication process.

The login module delegates the token generation process to a Security Token Service (STS) through a WS-Trust Issue or WS-Trust Validate request. The STS processes the request and returns a RequestSecurityTokenResponse message to the login module. The login module includes the token from the STS response message in the security header of the web service request message. If a token is not returned or an error occurs from the STS call, then the login module produces a LoginException message and an error is returned to the web services client.

The login module, and its use of the Security Token Service, permits the following actions:

• An exchange of security tokens when the incoming or outgoing security tokens are different token types

• An exchange of security tokens when mapping one identity to another identity

• The evaluation of authorization checks to ensure that the authenticated users are permitted to invoke the target web service

• The token exchange is invoked from the RunAs Subject or generated by the Web Services Security runtime environment. The exchange is based on the policy set and bindings configured for the trust request.

To use the generic security token login module for the token generator, the token generator in the Web Services Security policy set bindings must:

• Proper JAAS login configuration name

• Specify the callback handler class name

The JAAS login configuration name is wss.generate.issuedToken, and the callback handler class name is com.ibm.websphere.wssecurity.callbackhandler.GenericIssuedTokenGenerateCallbackHandler. See documentation about configuring a generic login module for an authentication token on the token generator side of the Web Services Security process.

Supported token types

• We can specify any token type whose ValueType value can be processed by the designated STS. Depending on which STS we use, the token types might include:
  • SAML 2.0
  • SAML 1.1

  • Username
  • PassTicket
  • Kerberos
  • LTPA
  • Security Access Manager credential

• The requested token sent in the SOAP message to the service provider is the token specified in the policy.

• We can use this token for authentication only. We cannot use this token as a protection token. For SAML v2.0, 1.1, and 1.0, only bearer and send voucher confirmation methods are supported.

We can configure the generic security token login module for the token generator to use either a WS-Trust Issue or WS-Trust Validate request to exchange or validate the security token. These two options are described in subsequent sections.

WS-Trust Issue

We can configure the login module for the token generator to use WS-Trust Issue to request a security token. In this scenario, the trust client sends an authentication security token to an STS in the SOAP security header. This authentication token originates from one of the following locations:

• The RunAs Subject in the current security context

• The callback handler configured within the bindings for the trust client policy sets

Upon successful processing of the STS request, the STS authenticates the token and issues the requested token.

WS-Trust Validate

We can optionally configure the login module for the token generator to use WS-Trust Validate to request a security token. In this scenario, the login module searches for the authentication security token from the RunAs Subject based on the configured token ValueType value. The login module sends the token in the trust request by embedding it inside the RequestedSecurityToken element as a child element. This token might be wrapped inside either the ValidateTarget element or the Base extension element. The STS validates the embedded token inside the RequestedSecurityToken element and returns a new security token or a validation status code. If only a validation status code is returned, the token generator uses the original security token. Although the returned token can have any ValueType value, as previously described in the WS-Trust Issue usage scenario, the token to be validated must be one of the following token types:

• SAML 2.0
• SAML 1.1

• Username
• PassTicket
• Kerberos
• LTPA
• LTPA v2

Use WS-Trust Issue or WS-Trust Validate

The generic login module uses WS-Trust Validate to validate the token from the RunAs Subject if the following conditions are both true:

• A RunAs Subject exists in the current security context

• Only one security token exists whose value type matches the ValueType value for the requested token

If WS-Trust Validate returns a valid status code and a security token, the returned token is the requested token. If WS-Trust Validate returns a valid status code only, the existing token from the RunAs Subject is the requested token.

Also, we can select a token from the RunAs Subject for validation and exchange it for the requested token. The selected token can have a different ValueType value from the requested token. See documentation about configuring a generic security token login module for an authentication token on the token generator side of the Web Services Security process.

If the ValueType value for the requested token is an LTPA or LTPA v2 type, the generic security token login module automatically extracts a WSCredential. It generates a Web Service Security LTPA or LTPA v2 token for validation and exchange, if the following conditions are true:

• An LTPA or LTPA v2 security token does not exist in the RunAs Subject.

• An WSCredential exists in the RunAs Subject.

When there is only one security token in RunAs Subject that matches the ValueType of the requested token, we can configure the login module to not invoke a WS-Trust Validate request to validate the matching token. Instead, the login module sends the matching token to the downstream service provider without validation.

The generic security token login module automatically uses WS-Trust Issue to request the token, if the following conditions are true:

• A RunAs Subject does not exist
• A matching token ValueType value does not exist in the RunAs Subject

• The login module cannot validate the token from the RunAs Subject

A configuration option enforces the use of either the WS-Trust Issue in the generic login module or the WS-Trust Validate. For more information, see the documentation about configuring a generic login module for an authentication token on the token generator side of the Web Services Security process.

Policy sets

The implementation of the generic security token login module does not involve a new token type in a policy set. For example, if we plan to use a generic login module to generate a user name token, we can create a policy set that specifies a user name token as an authentication token. Some custom token types are not supported by the existing default system login modules. However, we can implement these token types using custom login modules. These custom token types are supported by generic security token login modules if they are supported by the designated STS.

Bindings

When we configure bindings for an authentication token, we have the following options:

• Use a generic login module.

• Use an existing system default login module.

• Create our own custom login module.

For example, if we configure a user name token, we can use the wss.generate.unt JAAS login configuration and maintain the existing behavior. However, we can configure the wss.generate.issuedToken JAAS login to use the generic security token login module.

Related:

Generic security token login modules

Generic security token login module for the token consumer

Configure a generic security token login module for an authentication token: Token generator