Web services security SAML token custom properties

WAS v8.5 > Reference > Custom properties
Web services security SAML token custom properties

When you configure a web services security SAML token, we can configure name-value pairs of data, where the name is a property key and the value is a string value used to set internal system configuration properties. We can use these configuration properties, along with the options provided in the dmgr console, to control how the SAML token is generated or consumed.

To configure these SAML custom properties, in the dmgr console, either:

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.
You 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. You 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.
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.

The following sections list the custom properties and indicate how each custom property is used.

SAML token generator custom properties
SAML token consumer custom properties
SAML token custom properties for both token generator and token consumer
Trust client custom properties

SAML token generator custom properties

The following table lists the callback handler custom properties that can only be used to configure SAML token generator bindings.
SAML token callback handler custom properties for token generator bindings only. This table contains the custom property name, its values, and a short description.

Name Values Description
appliesTo This custom property does not have a default value. Specify the AppliesTo for the requested SAML token when a WSS API is used.
com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath This custom property does not have a default value. Specify the required configuration data when generating a self-issued SAML token.
cacheCushion Default is 5 minutes. Specify the amount of time, in minutes, before a SAML token's expiration time that a new token should be issued. For example, if the cacheCushion is set to 5 minutes and the SAML token will expire in 2 minutes, it will not be re-used; a new SAML token will be issued. When the runtime is in the process of caching a SAML token, a token that is beyond the cache cushion will not be cached.
cacheToken Valid values are true and false. The default behavior is true, which allows SAML token caching for reuse. Specify whether a SAML token can be cached for reuse.
com.ibm.wsspi.wssecurity.saml.client.SamlTokenCacheEntries Default is 250. Use this JVM custom property to specify the maximum number of cache entries that can be maintained.
com.ibm.wsspi.wssecurity.saml.client.SamlTokenCacheTimeout Default is 60 minutes. This property is used only for SAML tokens for which the expiration time is unknown (tokens that are encrypted or an expiration is not included with the token in the response from the STS). For SAML tokens for which the expiration time is unknown, the SamlTokenCacheTimeout is used to substitute for the expiration time. For a new SAML token that will enter the cache under this criteria, its expiration time will be (current_time)+SamlTokenCacheTimeout.
The conditions described for the cacheCushion property will still apply, so keep the cacheCushion value in mind when altering the value for the SamlTokenCacheTimeout.
confirmationMethod Valid values include bearer, holder-of-key, and sender-vouches. This custom property does not have a default value. Specify a SAML token subject ConfirmationMethod.
com.ibm.wsspi.wssecurity.saml.get.SamlToken This custom property does not have a default value. Use this custom property to get the SAML token to RequestContext.
com.ibm.wsspi.wssecurity.saml.put.SamlToken This custom property does not have a default value. Set the SAML token to RequestContext.
failOverToTokenRequest Valid values are true or false. Default is true, which means the web services security runtime always issues a new SAML token if the input token is invalid. Specify whether the web services security runtime should use the attached policy set to issue a new SAML token if the input SAML token in the RequestContext is invalid.
com.ibm.wsspi.wssecurity.saml.config.issuer.IssuerURI This custom property does not have a default value. Specify the issuer URL in the custom properties.
com.ibm.wsspi.wssecurity.saml.config.issuer.KeyStoreRef This custom property does not have a default value. Specify a reference to a centrally managed keystore in the custom properties.
com.ibm.wsspi.wssecurity.saml.config.issuer.TimeToLiveMilliseconds Default is 3600000 (60 minutes). Specify, in milliseconds, the amount of time that can elapse before a token expires in the custom properties.
recipientAlias This custom property does not have a default value. Specify a target service alias for a certificate.
signToken This custom property does not have a default value. Specify whether a SAML token should be signed with an application message.
sslConfigAlias If a value is not specified for this property, the default SSL alias defined in the system's SSL configuration is used.
This property is optional.
Specify the alias to an SSL configuration that a WS-Trust client uses to request a SAML token.
stsURI This custom property does not have a default value. Specify the SecurityTokenService (STS) address.
keySize This custom property does not have a default value. Specify the KeySize when requesting a SecretKey from STS.
tokenRequest Valid values include issue, propagation, and issueByWSPrincipal. Default is issue. Specify the SAMLToken request method.
tokenType This custom property does not have a default value. Set the required token type to SAMLGenerateCallback
usekeyType This custom property is optional. The valid values are KeyValue, X509Certificate, and X509IssuerSerial. Specify the Usekey type, which tells the client to generate a specific type of key Information.
WSSConsumingContext This custom property does not have a default value. Specify the WSSConsumingContext object the WS-Trust client uses to request a SAML token.
WSSGenerationContext This custom property does not have a default value. Specify the WSSGenerationContext object the WS-Trust client uses to request a SAML token.

SAML token consumer custom properties

The following table lists the callback handler custom properties that can only be used to configure SAML token consumer bindings.
SAML token callback handler custom properties for token consumer bindings only. This table contains the custom property name, its values, and a short description.

Name Values Description
allowUnencKeyInHok Valid values are true or false. Default is true, which means that unencrypted keys are allowed. Use this property to direct the SAML token consumer to accept an unencrypted key in a SAML holder-of-key token.
com.ibm.wsspi.wssecurity.saml.signature.SignatureCacheEntries An integer. Default is 1000. Specify how many signature cache entries can be maintained. for a SAML consumer token.
com.ibm.wsspi.wssecurity.saml.signature.SignatureCacheTimeout An integer. Default is 60 minutes. Specify how many minutes a SAML token is to be cached. A signature validation does not need to be repeated while the SAML token is cached.
keyAlias This custom property does not have a default value. Specify the key alias for a SAML consumer token.
keyName This custom property does not have a default value. Specify the key name for a SAML consumer token.
keyPassword This custom property does not have a default value. Specify the key password for a SAML consumer token.
keyStorePassword This custom property does not have a default value. Specify the keystore password for a SAML consumer token
keyStorePath This custom property does not have a default value. Specify the keystore file path for a SAML consumer token.
keyStoreRef This custom property does not have a default value. Specify the keystore reference for a SAML consumer token.
keyStoreType This custom property does not have a default value. Specify the keystore type for a SAML consumer token.
signatureRequired Default is true. Specify whether a signature is required on a SAML assertion.
trustAnySigner Default is false. Specify whether a recipient can trust any certificate that signs a SAML assertion.
trustedAlias This custom property does not have a default value. Specify the trusted STS certificate's alias for a SAML consumer token.
trustedIssuer_ The name is specified as trustedIssuer_n where n is an integer. This custom property does not have a default value. Specify the name of a trusted issuer.
trustedSubjectDN_ The value specified must be in the format trustedSubjectDN_n, where n is an integer. This custom property does not have a default value. Specify the X509Certificate's SubjectDN name for the trusted issuer.
trustStorePassword This custom property does not have a default value. Specify the truststore password for a SAML consumer token.
trustStorePath This custom property does not have a default value. Specify the truststore file path for a SAML consumer token.
trustStoreRef This custom property does not have a default value. Specify the truststore reference for a SAML consumer token.
trustStoreType This custom property does not have a default value. Specify the truststore type name for a SAML consumer token
validateAudienceRestriction Valid values are true or false. Default is false which means that an AudienceRestriction assertion validation is not required. Use this custom property specify whether an AudienceRestriction assertion must be validated.
validateOneTimeUse Valid values are true or false. Default is true, which means that OneTimeUse assertion validation is required. Specify whether a OneTimeUse assertion in SAML 2.0, or a DoNotCacheCondition in SAML 1.1 must be validated.
CRLPATH This custom property does not have a default value. Specify the file path to the list of revoked certificates for a SAML consumer token.
X509PATH This custom property does not have a default value. Specify the intermediate X509 certificate file path for a SAML consumer token.
CRLPATH_ The value specified must be in the format trustedSubjectDN_n, where n is an integer. This custom property does not have a default value. Specify the file path to the list of revoked X509 certificates for a SAML consumer token.
X509PATH_ The value specified must be in the format X509_path_n, where n is an integer. This custom property does not have a default value. Specify the file path for the intermediate X509 certificate for a SAML consumer token.

SAML token custom properties for both token generator and token consumer

The following table lists the callback handler custom properties that can be used to configure both SAML token generator and SAML token consumer bindings.
SAML token callback handler custom properties for token generator and token consumer bindings. This table contains the custom property name, its values, and a short description.

Name Values Description
clockSkew Default is 5 minutes. Specify, in minutes, an adjustment to the times in the self-issued SAML token 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 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.

clientLabel This custom property does not have a default value. Specify, in bytes, the client label to use for the derived keys whenever a WSS API is used with the requested SAML token.
serviceLabel This custom property does not have a default value. Specify, in bytes, the service label to use for the derived keys whenever a WSS API is used with the requested SAML token.
keylength This custom property does not have a default value. Specify, in bytes, the derived key length to use for the derived keys whenever a WSS API is used with the requested SAML token.
nonceLength Default is 128. Specify, in bytes, the derived nonce length to use for the derived keys whenever a WSS API is used with the requested SAML token.
requireDKT Default is false. Specify an option for the derived keys whenever a WSS API is used with the requested SAML token.
useImpliedDKT Default is false. Specify an option used with Implied derived keys whenever a WSS API is used with the requested SAML token.

Trust client custom properties

The following table lists the callback handler custom properties that can be used to configure trust client generator bindings.
Callback handler custom properties for the trust client generator bindings. This table contains the custom property name, its values, and a short description.

Name Values Description
com.ibm.wsspi.wssecurity.trust.client.TrustServiceCacheEntries Default is 1000. Specify the maximum number of STS service instance cache entries that can be maintained.
com.ibm.wsspi.wssecurity.trust.client.TrustServiceCacheTimeout Default is 60 minutes. Specify, in minutes, the length of time an STS service instance can be kept in a client side cache.
keyType The following keyTypes can be specified for WS-Trust 1.2:

com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.WST12#KEYTYPE_PUBLICKEY
com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.WST12#KEYTYPE_SYMMETRICKEY

The following keyTypes can be specified for WS-Trust 1.3:

com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.WST13#KEYTYPE_PUBLICKEY
com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.WST13#KEYTYPE_SYMMETRICKEY
com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.WST13#KEYTYPE_BEARER

Specify the keyType when making a WS-Trust request to STS.
wstrustClientBinding This custom property does not have a default value. Specify a binding name for the WS-trust client.
wstrustClientBindingScope This custom property does not have a default value. Specify the binding scope for the policy set that is attached to the WS-Trust client.
wstrustClientCollectionRequest Valid values are true or false. Default is false which means that a RequestSecurityToken is used instead of a RequestSecurityTokenCollection. Specify whether a RequestSecurityTokenCollection is required in a WS-Trust request.
wstrustClientPolicy This custom property does not have a default value. Specify the policy set name for a WS-Trust client.
wstrustClientSoapVersion Valid values are 1.1 and 1.2. If no value is specified, the SOAP version defaults to SOAP version the application client is using. Specify the SOAP version in a WS-Trust request.
wstrustClientWSTNamespace Default is trust 13. Valid values are trust12 and trust 13. Specify the WS-Trust namespace for a WS-Trust request.

Related

Configure custom properties to secure web services

Reference:

Inbound and outbound custom properties
Web services security custom properties

+
Search Tips | Advanced Search

Name	Values	Description
appliesTo	This custom property does not have a default value.	Specify the AppliesTo for the requested SAML token when a WSS API is used.
com.ibm.webservices.wssecurity.platform.SAMLIssuerConfigDataPath	This custom property does not have a default value.	Specify the required configuration data when generating a self-issued SAML token.
cacheCushion	Default is 5 minutes.	Specify the amount of time, in minutes, before a SAML token's expiration time that a new token should be issued. For example, if the cacheCushion is set to 5 minutes and the SAML token will expire in 2 minutes, it will not be re-used; a new SAML token will be issued. When the runtime is in the process of caching a SAML token, a token that is beyond the cache cushion will not be cached.
cacheToken	Valid values are true and false. The default behavior is true, which allows SAML token caching for reuse.	Specify whether a SAML token can be cached for reuse.
com.ibm.wsspi.wssecurity.saml.client.SamlTokenCacheEntries	Default is 250.	Use this JVM custom property to specify the maximum number of cache entries that can be maintained.
com.ibm.wsspi.wssecurity.saml.client.SamlTokenCacheTimeout	Default is 60 minutes.	This property is used only for SAML tokens for which the expiration time is unknown (tokens that are encrypted or an expiration is not included with the token in the response from the STS). For SAML tokens for which the expiration time is unknown, the SamlTokenCacheTimeout is used to substitute for the expiration time. For a new SAML token that will enter the cache under this criteria, its expiration time will be (current_time)+SamlTokenCacheTimeout. The conditions described for the cacheCushion property will still apply, so keep the cacheCushion value in mind when altering the value for the SamlTokenCacheTimeout.
confirmationMethod	Valid values include bearer, holder-of-key, and sender-vouches. This custom property does not have a default value.	Specify a SAML token subject ConfirmationMethod.
com.ibm.wsspi.wssecurity.saml.get.SamlToken	This custom property does not have a default value.	Use this custom property to get the SAML token to RequestContext.
com.ibm.wsspi.wssecurity.saml.put.SamlToken	This custom property does not have a default value.	Set the SAML token to RequestContext.
failOverToTokenRequest	Valid values are true or false. Default is true, which means the web services security runtime always issues a new SAML token if the input token is invalid.	Specify whether the web services security runtime should use the attached policy set to issue a new SAML token if the input SAML token in the RequestContext is invalid.
com.ibm.wsspi.wssecurity.saml.config.issuer.IssuerURI	This custom property does not have a default value.	Specify the issuer URL in the custom properties.
com.ibm.wsspi.wssecurity.saml.config.issuer.KeyStoreRef	This custom property does not have a default value.	Specify a reference to a centrally managed keystore in the custom properties.
com.ibm.wsspi.wssecurity.saml.config.issuer.TimeToLiveMilliseconds	Default is 3600000 (60 minutes).	Specify, in milliseconds, the amount of time that can elapse before a token expires in the custom properties.
recipientAlias	This custom property does not have a default value.	Specify a target service alias for a certificate.
signToken	This custom property does not have a default value.	Specify whether a SAML token should be signed with an application message.
sslConfigAlias	If a value is not specified for this property, the default SSL alias defined in the system's SSL configuration is used. This property is optional.	Specify the alias to an SSL configuration that a WS-Trust client uses to request a SAML token.
stsURI	This custom property does not have a default value.	Specify the SecurityTokenService (STS) address.
keySize	This custom property does not have a default value.	Specify the KeySize when requesting a SecretKey from STS.
tokenRequest	Valid values include issue, propagation, and issueByWSPrincipal. Default is issue.	Specify the SAMLToken request method.
tokenType	This custom property does not have a default value.	Set the required token type to SAMLGenerateCallback
usekeyType	This custom property is optional. The valid values are KeyValue, X509Certificate, and X509IssuerSerial.	Specify the Usekey type, which tells the client to generate a specific type of key Information.
WSSConsumingContext	This custom property does not have a default value.	Specify the WSSConsumingContext object the WS-Trust client uses to request a SAML token.
WSSGenerationContext	This custom property does not have a default value.	Specify the WSSGenerationContext object the WS-Trust client uses to request a SAML token.

Name	Values	Description
allowUnencKeyInHok	Valid values are true or false. Default is true, which means that unencrypted keys are allowed.	Use this property to direct the SAML token consumer to accept an unencrypted key in a SAML holder-of-key token.
com.ibm.wsspi.wssecurity.saml.signature.SignatureCacheEntries	An integer. Default is 1000.	Specify how many signature cache entries can be maintained. for a SAML consumer token.
com.ibm.wsspi.wssecurity.saml.signature.SignatureCacheTimeout	An integer. Default is 60 minutes.	Specify how many minutes a SAML token is to be cached. A signature validation does not need to be repeated while the SAML token is cached.
keyAlias	This custom property does not have a default value.	Specify the key alias for a SAML consumer token.
keyName	This custom property does not have a default value.	Specify the key name for a SAML consumer token.
keyPassword	This custom property does not have a default value.	Specify the key password for a SAML consumer token.
keyStorePassword	This custom property does not have a default value.	Specify the keystore password for a SAML consumer token
keyStorePath	This custom property does not have a default value.	Specify the keystore file path for a SAML consumer token.
keyStoreRef	This custom property does not have a default value.	Specify the keystore reference for a SAML consumer token.
keyStoreType	This custom property does not have a default value.	Specify the keystore type for a SAML consumer token.
signatureRequired	Default is true.	Specify whether a signature is required on a SAML assertion.
trustAnySigner	Default is false.	Specify whether a recipient can trust any certificate that signs a SAML assertion.
trustedAlias	This custom property does not have a default value.	Specify the trusted STS certificate's alias for a SAML consumer token.
trustedIssuer_	The name is specified as trustedIssuer_n where n is an integer. This custom property does not have a default value.	Specify the name of a trusted issuer.
trustedSubjectDN_	The value specified must be in the format trustedSubjectDN_n, where n is an integer. This custom property does not have a default value.	Specify the X509Certificate's SubjectDN name for the trusted issuer.
trustStorePassword	This custom property does not have a default value.	Specify the truststore password for a SAML consumer token.
trustStorePath	This custom property does not have a default value.	Specify the truststore file path for a SAML consumer token.
trustStoreRef	This custom property does not have a default value.	Specify the truststore reference for a SAML consumer token.
trustStoreType	This custom property does not have a default value.	Specify the truststore type name for a SAML consumer token
validateAudienceRestriction	Valid values are true or false. Default is false which means that an AudienceRestriction assertion validation is not required.	Use this custom property specify whether an AudienceRestriction assertion must be validated.
validateOneTimeUse	Valid values are true or false. Default is true, which means that OneTimeUse assertion validation is required.	Specify whether a OneTimeUse assertion in SAML 2.0, or a DoNotCacheCondition in SAML 1.1 must be validated.
CRLPATH	This custom property does not have a default value.	Specify the file path to the list of revoked certificates for a SAML consumer token.
X509PATH	This custom property does not have a default value.	Specify the intermediate X509 certificate file path for a SAML consumer token.
CRLPATH_	The value specified must be in the format trustedSubjectDN_n, where n is an integer. This custom property does not have a default value.	Specify the file path to the list of revoked X509 certificates for a SAML consumer token.
X509PATH_	The value specified must be in the format X509_path_n, where n is an integer. This custom property does not have a default value.	Specify the file path for the intermediate X509 certificate for a SAML consumer token.

Name	Values	Description
clockSkew	Default is 5 minutes.	Specify, in minutes, an adjustment to the times in the self-issued SAML token 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 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.
clientLabel	This custom property does not have a default value.	Specify, in bytes, the client label to use for the derived keys whenever a WSS API is used with the requested SAML token.
serviceLabel	This custom property does not have a default value.	Specify, in bytes, the service label to use for the derived keys whenever a WSS API is used with the requested SAML token.
keylength	This custom property does not have a default value.	Specify, in bytes, the derived key length to use for the derived keys whenever a WSS API is used with the requested SAML token.
nonceLength	Default is 128.	Specify, in bytes, the derived nonce length to use for the derived keys whenever a WSS API is used with the requested SAML token.
requireDKT	Default is false.	Specify an option for the derived keys whenever a WSS API is used with the requested SAML token.
useImpliedDKT	Default is false.	Specify an option used with Implied derived keys whenever a WSS API is used with the requested SAML token.

Name	Values	Description
com.ibm.wsspi.wssecurity.trust.client.TrustServiceCacheEntries	Default is 1000.	Specify the maximum number of STS service instance cache entries that can be maintained.
com.ibm.wsspi.wssecurity.trust.client.TrustServiceCacheTimeout	Default is 60 minutes.	Specify, in minutes, the length of time an STS service instance can be kept in a client side cache.
keyType	The following keyTypes can be specified for WS-Trust 1.2: com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.WST12#KEYTYPE_PUBLICKEY com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.WST12#KEYTYPE_SYMMETRICKEY The following keyTypes can be specified for WS-Trust 1.3: com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.WST13#KEYTYPE_PUBLICKEY com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.WST13#KEYTYPE_SYMMETRICKEY com.ibm.wsspi.wssecurity.core.token.config.WSSConstants.WST13#KEYTYPE_BEARER	Specify the keyType when making a WS-Trust request to STS.
wstrustClientBinding	This custom property does not have a default value.	Specify a binding name for the WS-trust client.
wstrustClientBindingScope	This custom property does not have a default value.	Specify the binding scope for the policy set that is attached to the WS-Trust client.
wstrustClientCollectionRequest	Valid values are true or false. Default is false which means that a RequestSecurityToken is used instead of a RequestSecurityTokenCollection.	Specify whether a RequestSecurityTokenCollection is required in a WS-Trust request.
wstrustClientPolicy	This custom property does not have a default value.	Specify the policy set name for a WS-Trust client.
wstrustClientSoapVersion	Valid values are 1.1 and 1.2. If no value is specified, the SOAP version defaults to SOAP version the application client is using.	Specify the SOAP version in a WS-Trust request.
wstrustClientWSTNamespace	Default is trust 13. Valid values are trust12 and trust 13.	Specify the WS-Trust namespace for a WS-Trust request.