Web services client token cache for SAML

When a SAML token is initially requested, the web services runtime environment automatically caches the SAMLToken. As a result of this automatic client token caching function, subsequent web services requests can use the SAMLToken from the previous request.

The web services client token cache for SAML enables web services clients to reuse SAML tokens when accessing business services. Reusing valid SAML tokens reduces traffic to the Security Token Service (STS) and also reduces the performance impact of sending WS-Trust request messages. There are several requirements for a token to be considered valid and therefore available for caching and reuse.

In order for a SAML token to be reused, the expiration time of the token must be equivalent to, or greater than, the current time. A cache cushion is added to the current time when comparing the token expiration time with the current time so that the token does not expire immediately after it is sent.

In addition, a token is valid only if it is sent again to the same business service. The SAML function in WAS does not verify the AudienceRestriction condition for the SAML token. Therefore, a practical way to ensure that the SAML token is reused for the right audience is to reuse the token only for the same web service that originally used the token. If an assertion contains the OneTimeUse assertion, the SAML token is not cached.

To take advantage of the SAMLToken cache, the application and SAMLToken must meet the following requirements:

• The SAMLToken must have a relatively long expiration time, with at least 5 minutes remaining in the token lifetime after the first request is completed. The WS-Security runtime environment validates the cached SAMLToken expiration time against a predefined cache cushion. The cached token is valid only if the remaining token lifetime is greater than the cushion value. The default cushion value is 5 minutes. This value can be configured using the custom property, cacheCushion. To override the default cache cushion, edit the CallbackHandler custom property for the SAMLToken generator. Add the cacheCushion property and set the cache cushion value in milliseconds. If the cached SAMLToken lifetime is within the cache cushion limit, a new SAMLToken is requested. For example, we can change the cache cushion to 3 minutes or 180000 milliseconds.

  Custom property name	Value
  cacheCushion	180000

• The SAML token cannot contain the OneTimeUse assertion.

• If the SAML token is encrypted, verify the STS communicates the token expiration time outside the encrypted token, and that the SAML token does not include the OneTimeUse assertion.

When we do not want to reuse the same SAMLToken for subsequent requests, we can disable the client side SAMLToken cache with the cacheToken custom property. To disable the client side SAMLToken cache, modify the custom property in the CallbackHandler for the SAMLToken generator. Add the cacheToken property and set the value to false.

Custom property name	Value
cacheToken	false