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 WebSphere® Application Server 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, you 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, make sure that the STS communicates
the token expiration time outside the encrypted token, and that the
SAML token does not include the OneTimeUse assertion.
When you do not want to reuse the same SAMLToken for subsequent
requests, you 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 |