Web services security generic security token login module custom properties
When we configure a generic security token login module, we can configure name-value pairs of data, where the name is a property key and the value is a string value we can use to set internal system configuration properties. Use these configuration properties, along with the options provided in the administrative console, to control how the token is generated or consumed.
To configure these custom properties for the callback handler in the administrative console, complete the following steps:
- Expand Services.
- Select Service provider or Service client
- Click on the appropriate application in the Name column.
- Click on the appropriate binding in the Binding column.
We must have previously attached a policy set and assigned a binding.
or
- Expand Applications > Application Types and click WebSphere enterprise applications.
- Select an application containing Web services. The application must contain a service provider or a service client.
- Under the Web Services Properties heading, click Service provider policy sets and bindings or Service client policy sets and bindings.
- Select a binding. We must have previously attached a policy set and assigned an application-specific binding.
Then complete the following steps:
- Click WS-Security in the Policies table.
- Under the Main Message Security Policy Bindings heading, click Authentication and protection.
- Under the Authentication tokens heading, click the name of the authentication token.
Use the token, which is processed by the generic security token login module, for authentication only. We cannot use the token as a protection token.
- Under the Additional Bindings heading, click Callback handler.
- Under the Custom Properties heading, enter the name and value pairs.
- Callback handler custom properties for both token generator and token consumer bindings
- Callback handler custom properties for token generator bindings
- Callback handler custom properties for token consumer bindings
Callback handler custom properties for both token generator and token consumer bindings
The following table lists the callback handler custom properties used to configure both token generator and token consumer bindings.
| Name | Values | Description |
|---|---|---|
| clockSkew | No default value. | Specify, in minutes, an adjustment to the times in the self-issued
SAML token that the SAMLGenerateLoginModule creates.
The clockSkew custom property is set on the Callback handler of the SAML token generator that uses the SAMLGenerateLoginModule class. The value specified for this custom property must be numeric and is specified in minutes. When a value is specified for this custom property, the following time adjustments are made in the self-issued SAML token that the SAMLGenerateLoginModule creates:
|
| stsURI | No default value. | Specify the Security Token Service (STS) address.
This custom property is required for the token consumer. However, this custom property is optional for the token generator if the requested token exists in the RunAs Subject and its verification is not required. |
| wstrustClientBinding | No default value. | Specify the binding name for the WS-Trust client. |
| wstrustClientBindingScope | We can specify an application or domain value. | Type of bindings used for the WS-Trust client.
The following conditions apply:
This custom property is optional. |
|
| No default value. Example value: com.acme.myOnBehalfOfCallbackHandler |
Specify a custom callback handler to obtain the XML for the OnBehalfOf element for the trust request. This option is used when the OnBehalfOf setting is not static for the configuration and must change on a per-request basis. The custom callback handler will use a com.ibm.websphere.wssecurity.callbackhandler.PropertyCallback and must do the following to pass the XML string back to the runtime: Map wssContext = ((PropertyCallback)callback).getProperties();
wssContext.put("wstrustClientOnBehalfOf", xmlString);
The wssContext that is obtained from the PropertyCallback can be used with methods in the com.ibm.websphere.wssecurity.wssapi.WSSUtilFactory class if the custom callback handler needs access to the MessageContext, HTTP headers, and so on. If the OnBehalfOf setting is static for the configuration, instead of using wstrustClientOnBehalfOfCallbackHandler, set the wstrustClientOnBehalfOf property to the desired XML in the callback handler custom properties. |
| wstrustClientPolicy | No default value. | Specify the policy set name for the WS-Trust client. |
| wstrustClientSoapVersion | We can specify a 1.1 or 1.2 value. | Specify the SOAP message version that the trust client uses to generate the SOAP message. The SOAP message is sent to the Security Token Service (STS). If we do not define this custom property, the generic security token login module uses the SOAP version of
the application when it generates the SOAP message for the trust client request.
The default value corresponds to the SOAP version used by the application client. This custom property is optional. |
| wstrustClientWSTNamespace |
Specify one of the following values:
| Specify which trust client namespace the generic security token login modules uses when it makes the WS-Trust request. |
| wstrustValidateClientBinding | By default, the value for this custom property is the same value specified for the wstrustClientBinding custom property. | Specify the bindings used by the WS-Trust
Validate request.
If we do not specify this custom property, the WS-Trust Validate request uses the same bindings used by WS-Trust Issue, which are defined by the wstrustClientBinding custom property. |
| wstrustValidateClientPolicy | By default, the value for this custom property is the same value specified for the wstrustClientPolicy custom property. | Specify the policy sets to use with the WS-Trust
Validate request.
If we do not specify a value for this custom property, WS-Trust Validate uses the same policy set as WS-Trust Issue, which is defined by the required wstrustClientPolicy custom property. |
| wstrustIssuer | Use any string value. | Specify the issuer for the request token.
This custom property is optional. |
| wstrustValidateTargetOption | The default is the WS-Trust
Base element extension.
We can specify a token value or a base value, which is also the default value. | Specify whether the WS-Trust client passes
the validation token to the WS-Trust Security Token Service using the ValidateTarget or the Base element extension.
The following conditions apply:
|
wstrustClientOnBehalfOfCallbackHandler
Callback handler custom properties for token generator bindings
The following table lists the callback handler custom properties that can only be used to configure token generator bindings.
| Name | Value | Description |
|---|---|---|
| passThroughToken | Use a True or False value. The default is False.
The value for this custom property is not case sensitive. |
Direct whether the outbound token should be obtained from the STS or not. The default behavior is to always obtain the token from the STS. When set to True, the inbound token will be obtained in this order:
See following constants in the com.ibm.wsspi.wssecurity.core.Constants Java API documentation. This documentation is available under Reference > Programming interfaces > APIs in the Information Center navigation.
|
| useRunAsSubject | Use a True or False value. The default is True.
The value for this custom property is not case sensitive. | Specify whether the generic security token login modules use the token from the RunAs Subject for the outgoing request. By default, the login module uses the validated tokens in the RunAs Subject first.
The following conditions apply:
|
| useRunAsSubjectOnly | Use a True or False value. The default is False.
The value for this custom property is not case sensitive. | Disable or enable WS-Trust Issue in the generic security token login module. If we set this custom property to a true value, the generic security token login module uses the token from the RunAs Subject and WS-Trust Validate to exchange the tokens. The generic security token login module does not use WS-Trust Issue to request a token even if WS-Trust Validate fails or it does not find a matching token in the RunAs Subject. |
| useToken | Use any string value of the ValueType value for the security token. | When we use a security token in a RunAs Subject to validate and exchange
tokens for an outbound request, we can use this custom property to specify which token ValueType value in the RunAs Subject to validate and exchange for the requested token.
For example, we might have a token with a ValueType value of Token_1 in the RunAs Subject. However, the ValueType value of Token_2 is the required token. We can set this custom property to Token_1 . If we do not define this custom property, the validation token is the token from the RunAs Subject that has the same ValueType value as the required token. This custom property is optional. |
| validateUseToken | Use a True or False value. The default is True.
The value for this custom property is not case sensitive. | Specify whether the token generator uses WS-Trust Validate
to validate the token from the RunAs Subject.
By default, the generic security token login module validates a token from the RunAs Subject against the Security Token Service (STS) before sending the token in the SOAP message to the service provider. If we set this custom property value to false and the generic security token login module finds a matching token from the RunAs Subject, the login module does not invoke WS-Trust Validate to validate the matching token. Instead, it sends the matching token to the downstream service provider without validation. |
| wstrustIncludeTokenType | Use a True or False value. The default is True.
The value for this custom property is not case sensitive. | Specify whether the WS-Trust
RequestedSecurityToken token includes the requested token ValueType value.
If we do not specify this custom property, the generic security token login module includes the requested token type in the WS-Trust RequestedSecurityToken token. This custom property is optional. |
Callback handler custom properties for token consumer bindings
The following table lists the callback handler custom properties that can only be used to configure token consumer bindings.
| Name | Value | Description |
|---|---|---|
| alwaysGeneric | Use a True or False value. The default is False.
The value for this custom property is not case sensitive. | Specify whether the login module creates a GenericSecurityToken.
If passThroughToken and this property are both set to True, the login module always creates a GenericSecurityToken instead of a built-in token type that corresponds to the valueType configured for the token. |
| exchangedTokenType | The valid value for this custom property is the string ValueType value for the token supported by the system default login modules. | Specify the new token with the defined ValueType value, which the trust service must return after successful validation.
If we do not specify a value for the custom property, the generic security token login module accepts whichever token the trust service returns. This custom property is optional. |
| passThroughToken | Use a True or False value. The default is False.
The value for this custom property is not case sensitive. | Specify whether the inbound token should be sent to the STS.
The default behavior is to always send the inbound token to the STS for validation, exchange, or both. When set to True, the inbound token is not sent to the STS, and it passes through the consumer. When set to True and a built-in token is used, the token is parsed and made available on the WS-Security context for later processing by a caller configuration JAAS login module. |