+

Search Tips   |   Advanced Search

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 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 SAML token is generated or consumed.

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

  1. Expand Services.

  2. Select Service provider or Service client

  3. Click on the appropriate application in the Name column.

  4. Click on the appropriate binding in the Binding column.

    We must have previously attached a policy set and assigned a binding.

or

  1. Expand Applications > Application Types and click WebSphere enterprise applications.

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

  3. Under the Web Services Properties heading, click Service provider policy sets and bindings or Service client policy sets and bindings.

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

Then complete the following steps:

  1. Click WS-Security in the Policies table.

  2. Under the Main Message Security Policy Bindings heading, click Authentication and protection.

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

  4. Under the Additional Bindings heading, click Callback handler.

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

The following table lists the callback handler custom properties that can only be used to configure SAML token generator bindings.

callback handler custom properties for token generator bindings only. This table contains the custom property name, its values, and
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.
(V8502) audienceRestriction Valid values are true and false. The default behavior is true, which includes AudienceRestrictionCondition in the SAML token. This property applies only to self-issued SAML tokens. Specify whether the AudienceRestrictionCondition element is included in the SAML token.
(V8502) authenticationMethod This custom property does not have a default value. This property applies only to self-issued SAML tokens. Specify the value for the AuthenticationMethod attribute on the AuthenticationStatement element in the SAML token. When this custom property is specified, the Subject will be contained in an AuthenticationStatement instead of an AttributeStatement.
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 The default value is 5 minutes. Specify the amount of time, in minutes, before the expiration time of a SAML token expires and a new token must 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 The default value 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 The default value 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. 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. The default value is true, which means that 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.
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,issueByWSCredential, and issueByWSPrincipal. The default value is issue. Specify the SAMLToken request method. For more information about the values that can be specified for this property, see the topic Propagating SAML tokens
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 that the WS-Trust client uses to request a SAML token.
WSSGenerationContext This custom property does not have a default value. Specify the WSSGenerationContext object that 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.

handler custom properties for token consumer bindings only. This
Name Values Description
(WAS v8.5.0.1)

allowUnencKeyInHok

Valid values are true or false. The default value is true, which means that unencrypted keys are allowed. 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. The default value 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. The default value 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.

Sample: name=myKeyStoreRef managementScope=(cell):myCell:(node):myNode

keyStoreType This custom property does not have a default value. Specify the keystore type for a SAML consumer token.
signatureRequired The default value is true. Specify whether a signature is required on a SAML assertion.
trustAnySigner The default value 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.

Sample: name=myTrustStoreRef managementScope=(cell):myCell:(node):myNode

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. The default value 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. The default value 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. 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.

handler custom properties for token generator and token consumer bindings. This table contains the custom property name, its values, and
Name Values Description
clockSkew The default value is 3 minutes. 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.

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 The default value 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 The default value is false. Specify an option for the derived keys whenever a WSS API is used with the requested SAML token.
useImpliedDKT The default value 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 custom properties that can be used to configure trust client. When used in conjunction with a SAML token generator, these custom properties are added to the SAML token generator callback handler.

properties for the trust client.. This table contains
Name Values Description
com.ibm.wsspi.wssecurity.trust.client.TrustServiceCacheEntries The default value is 1000. Specify the maximum number of STS service instance cache entries that can be maintained.
com.ibm.wsspi.wssecurity.trust.client.TrustServiceCacheTimeout The default value 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:

  • http://schemas.xmlsoap.org/ws/2005/02/trust/PublicKey

  • http://schemas.xmlsoap.org/ws/2005/02/trust/SymmetricKey

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

  • http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey

  • ttp://docs.oasis-open.org/ws-sx/ws-trust/200512/SymmetricKey

  • http://docs.oasis-open.org/ws-sx/ws-trust/200512/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. The default value is false which means that a RequestSecurityToken is used instead of a RequestSecurityTokenCollection. Specify whether a RequestSecurityTokenCollection is required in a WS-Trust request.
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 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 that the application client is using. Specify the SOAP version in a WS-Trust request.
wstrustClientWSTNamespace The default value is trust13. Valid values are trust12 and trust13. Specify the WS-Trust namespace for a WS-Trust request.


Related tasks

  • Configure custom properties to secure web services

  • Inbound and outbound custom properties
  • Web services security custom properties
  • Propagating SAML tokens