Web services security generic security token login module custom properties

Web services security generic security token login module custom properties

When you 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 that we can use to set internal system configuration properties. We can use these configuration properties, along with the options provided in the console, to control how the token is generated or consumed.
To configure these custom properties for the callback handler in the console...

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.
Supported configurations: We can 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 that can be used to configure both token generator and token consumer bindings.

handler custom properties for both token generator and token consumer bindings.. This table contains the custom property name,
Name Values Description

clockSkew

This custom property does not have a 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:

The new NotBefore time setting equals the initial NotBefore time setting, minus the amount of time specified for the clockSkew custom property.

The new NotAfter time setting equals the initial NotAfter time setting, plus the amount of time specified for the clockSkew custom property.

stsURI
This custom property does not have a 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
This custom property does not have a default value.

Specify the binding name for the WS-Trust client.
wstrustClientBindingScope We can specify an application or domain value. Specify the type of bindings used for the WS-Trust client.
The following conditions apply:

If we specify the domain value, general bindings are used.

If we specify the application value, custom bindings are used.

If we do not specify a value and application bindings exist, those application bindings are used.

If we do not specify a value and general bindings exist, those general bindings are used.

If neither application or general bindings exist, the default bindings are used.

This custom property is optional.
wstrustClientOnBehalfOfCallbackHandler

This custom property does not have a 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, etc.
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
This custom property does not have a 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:

Trust Version 1.3 (Default)

Specify 1.3 to use Trust Version 1.3 (Default). http://docs.oasis-open.org/ws-sx/ws-trust/200512

Trust Version 1.2

Specify 1.2 to use Trust Version 1.2. http://schemas.xmlsoap.org/ws/2005/02/trust

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
We can use any string value.

Issuer for the request token.
This custom property is optional.
wstrustValidateTargetOption
The default value 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:

If we do not specify a value for this custom property, the token is wrapped in the Base element extension within the RequestedSecurityToken element.

If we specify the token value, the token is wrapped in the ValidateTarget element within the RequestedSecurityToken element.
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.

handler custom properties for token generator bindings only.. This table contains the custom property name, its values, and
Name Value Description
(WAS v8.5.0.1)
passThroughToken

We can use a True or False value. The default value is False.
The value for this custom property is not case sensitive.

Use this custom property to 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 this property is set to True, the inbound token will be obtained in this order:

From the sharedState from a stacked JAAS login module

From the com.ibm.wsspi.wssecurity.token.tokenHolder list on the message context

From the inbound SecurityTokens

For more information, see the 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.

com.ibm.wsspi.wssecurity.token.tokenHolder

com.ibm.wsspi.wssecurity.token.enableCaptureTokenContext

com.ibm.wsspi.wssecurity.token.enableCaptureTokenInboundMsg

useRunAsSubject
We can use a True or False value. The default value 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:

If we set this custom property to a false value, the generic security token login module does not use WS-Trust Validate to exchange the token for the outbound request. Instead, it uses WS-Trust Issue to request a token.

If we do not specify this custom property, the generic security token login module attempts to use a token from the RunAs Subject and WS-Trust Validate to exchange the token.

If a token does not exist in the RunAs Subject, the generic security token login module uses WS-Trust Issue and is protected by the trust client policy sets.

useRunAsSubjectOnly
We can use a True or False value. The default value is False.
The value for this custom property is not case sensitive.

Use this custom property to 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
We can use any string value of the ValueType value for the security token.

When you 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
We can use a True or False value. The default value 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
We can use a True or False value. The default value 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 modules 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.

handler custom properties for token consumer bindings only.. This table contains the custom property name, its values, and
Name Value Description
(WAS v8.5.0.1)
alwaysGeneric

We can use a True or False value. The default value 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 that is 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.
(WAS v8.5.0.1)
passThroughToken

We can use a True or False value. The default value 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 this property is set to True, the inbound token is not sent to the STS, and it passes through the consumer. When this property is 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.

Related tasks

Configure custom properties to secure web services
Configure a generic security token login module for an authentication token: Token generator
Configure a generic security token login module for an authentication token: Token consumer
Enable or disable single sign-on interoperability mode for the LTPA token

Inbound and outbound custom properties
Web services security custom properties

Related information:

http://www.w3.org/TR/xml-exc-c14n/

Name	Value	Description
(WAS v8.5.0.1) passThroughToken	We can use a True or False value. The default value is False. The value for this custom property is not case sensitive.	Use this custom property to 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 this property is set to True, the inbound token will be obtained in this order: From the sharedState from a stacked JAAS login module From the com.ibm.wsspi.wssecurity.token.tokenHolder list on the message context From the inbound SecurityTokens For more information, see the 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. com.ibm.wsspi.wssecurity.token.tokenHolder com.ibm.wsspi.wssecurity.token.enableCaptureTokenContext com.ibm.wsspi.wssecurity.token.enableCaptureTokenInboundMsg
useRunAsSubject	We can use a True or False value. The default value 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: If we set this custom property to a false value, the generic security token login module does not use WS-Trust Validate to exchange the token for the outbound request. Instead, it uses WS-Trust Issue to request a token. If we do not specify this custom property, the generic security token login module attempts to use a token from the RunAs Subject and WS-Trust Validate to exchange the token. If a token does not exist in the RunAs Subject, the generic security token login module uses WS-Trust Issue and is protected by the trust client policy sets.
useRunAsSubjectOnly	We can use a True or False value. The default value is False. The value for this custom property is not case sensitive.	Use this custom property to 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	We can use any string value of the ValueType value for the security token.	When you 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	We can use a True or False value. The default value 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	We can use a True or False value. The default value 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 modules includes the requested token type in the WS-Trust RequestedSecurityToken token. This custom property is optional.

Name	Values	Description
clockSkew	This custom property does not have a 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: The new NotBefore time setting equals the initial NotBefore time setting, minus the amount of time specified for the clockSkew custom property. The new NotAfter time setting equals the initial NotAfter time setting, plus the amount of time specified for the clockSkew custom property.
stsURI	This custom property does not have a 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	This custom property does not have a default value.	Specify the binding name for the WS-Trust client.
wstrustClientBindingScope	We can specify an application or domain value.	Specify the type of bindings used for the WS-Trust client. The following conditions apply: If we specify the domain value, general bindings are used. If we specify the application value, custom bindings are used. If we do not specify a value and application bindings exist, those application bindings are used. If we do not specify a value and general bindings exist, those general bindings are used. If neither application or general bindings exist, the default bindings are used. This custom property is optional.
wstrustClientOnBehalfOfCallbackHandler	This custom property does not have a 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, etc. 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	This custom property does not have a 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: Trust Version 1.3 (Default) Specify 1.3 to use Trust Version 1.3 (Default). http://docs.oasis-open.org/ws-sx/ws-trust/200512 Trust Version 1.2 Specify 1.2 to use Trust Version 1.2. http://schemas.xmlsoap.org/ws/2005/02/trust	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	We can use any string value.	Issuer for the request token. This custom property is optional.
wstrustValidateTargetOption	The default value 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: If we do not specify a value for this custom property, the token is wrapped in the Base element extension within the RequestedSecurityToken element. If we specify the token value, the token is wrapped in the ValidateTarget element within the RequestedSecurityToken element.