CXF WS-Security runtime token caching - 6.5

Talend ESB STS User Guide

Talend Data Fabric
Talend Data Services Platform
Talend ESB
Talend MDM Platform
Talend Open Studio for ESB
Talend Real-Time Big Data Platform
Talend ESB
Design and Development
Installation and Upgrade

CXF caches tokens in the security runtime in the following circumstances:

  • When the IssuedTokenInterceptorProvider is invoked to obtain an Issued token from an STS.

  • When the STSTokenValidator is used to validate a received UsernameToken, BinarySecurityToken or SAML Assertion to an STS.

  • When the SecureConversation protocol is used.

  • When the WS-Trust SPNEGO protocol is used.

  • When tokens are obtained from a Kerberos KDC.

In each of these use-cases, the retrieved token is cached to prevent repeated remote calls to obtain the desired security token. There is no built-in support as yet to cache tokens in the WS-Security layer to prevent repeat validation. Of course this could be easily done by wrapping the existing validators with a custom caching solution.


CXF defines a SecurityToken class which encapsulates all relevant information about a successful authentication event in the security runtime (as defined above). In particular, it contains the following items (among others):

  • A String identifier of the token. This could be a SAML Assertion Id, the Identifier element of a SecurityContextToken, or the wsu:Id of a UsernameToken, etc.

  • The DOM Element that represents that security token.

  • Attached and Unattached reference elements for that token that might have been retrieved from an STS.

  • A byte[] secret associated with the token.

  • An expiration date after which the token is not valid.

  • A String TokenType that categorizes the token.

  • An X.509 Certificate associated with the token.

  • The principal associated with the token.

  • A hashcode that represents the security token (normally the hashcode of the underlying WSS4J object).

  • An identifier of another SecurityToken that represents a transformed version of this token.


CXF defines a TokenStore interface for caching SecurityTokens in the WS-Security runtime module. Prior to CXF 2.6, a simple default HashMap based approach was used to cache security tokens. In CXF 2.6, Ehcache is used to provide a suitable default TokenStore implementation to cache security tokens. Tokens are stored until the expiry date of the token if it exists, provided it does not exceed the maximum storage time of 12 hours. If it exceeds this, or if there is no expiry date provided in the security token, it is cached for the default storage time of 1 hour. If the token is expired then it is not cached. This default storage time is configurable. Note that while Ehcache is a compile time dependency of the WS-Security module in CXF, it can be safely excluded in which case CXF will fall back to use the simple HashMap based cache, unless the user specifically wants to implement an alternative TokenStore implementation and configure this instead.

Apache CXF 2.6 provides support for configuring caching via the following JAX-WS properties:

  • "" - The TokenStore instance to use to cache security tokens. By default this uses the EHCacheTokenStore if Ehcache is available. Otherwise it uses the MemoryTokenStore.

  • "ws-security.cache.config.file" - Set this property to point to a configuration file for the underlying caching implementation. By default the cxf-ehcache.xml file in the CXF rt-ws-security module is used.