1) The TokenRenewer interface
Security tokens are renewed in the STS via the TokenRenewer interface. It has the following methods:
- void setVerifyProofOfPossession(boolean verifyProofOfPossession) - A boolean switch to enable or disable the proof of possession requirement.
- void setAllowRenewalAfterExpiry(boolean allowRenewalAfterExpiry) - A switch to enable or disable the ability to renew tokens after they have expired.
- boolean canHandleToken(ReceivedToken renewTarget) - Whether this TokenRenewer implementation can renew the given token.
- boolean canHandleToken(ReceivedToken renewTarget, String realm) - Whether this TokenRenewer implementation can renew the given token in the given realm.
- TokenRenewerResponse renewToken(TokenRenewerParameters tokenParameters) - Renew the token using the given parameters
After the successful validation of a token, the state of the token is checked. If the state is not valid or expired, then an exception is thrown. The STS then iterates through the configured list of TokenRenewer implementations to see which can renew the given (validated) token. The token is then renewed and returned to the client.
The TokenRenewerParameters class is nothing more than a collection of configuration properties to use in renewing the token, which are populated by the STS operations using information collated from the request, or static configuration, etc. The TokenRenewerResponse class holds the results from the (successful) token renewal, including the DOM representation of the renewed token, the token Id, the new lifetime of the renewed token, and references to the renewed token.
2) The SAMLTokenRenewer
The SAMLTokenRenewer can renew valid or expired SAML 1.1 and SAML 2.0 tokens. The following properties can be configured on the SAMLTokenRenewer directly:
- boolean signToken - Whether to sign the renewed token or not. The default is true.
- ConditionsProvider conditionsProvider - An object used to add a Conditions statement to the token.
- Map<String, SAMLRealm> realmMap - A map of realms to SAMLRealm objects. See here for an explanation of realms in the SAMLTokenProvider.
- long maxExpiry - how long a token is allowed to be expired (in seconds) before renewal. The default is 30 minutes.
2.1) Token validation
Before the received SAML token can be renewed, a number of validation steps (that are specific to renewing SAML tokens) takes place. Two boolean properties are retrieved from the properties of the cached token:
- org.apache.cxf.sts.token.renewing.allow - Whether the token is allowed to be renewed or not.
- org.apache.cxf.sts.token.renewing.allow.after.expiry - Whether the token is allowed to be renewed or not after it has expired.
If the state of the token is expired, and if the token is allowed to be renewed after expiry, a final check is done against the boolean set via the "setAllowRenewalAfterExpiry" method of TokenRenewer. If this is set to false (the default), then an exception is thrown. So to support token renewal after expiry, you must explicitly define this behaviour on the TokenRenewer implementation. Finally, a check is done on how long ago the SAML Token expired. If it is greater than the value configured in the "maxExpiry" property (30 minutes by default), then an exception is thrown.
The next validation step is to check proof of possession, if this is enabled (true by default). The Subject KeyInfo of the Assertion must contain a PublicKey or X509Certificate that corresponds to either the client certificate if TLS is used, or to the private key that was used to sign some part of the request. Finally, if an "AppliesTo" URI is sent as part of the request, the SAMLTokenRenewer checks that the received Assertion contains at least one AudienceRestrictionURI that matches that address, otherwise it throws an Exception.
2.2) Renewing the SAML Assertion
After the validation steps outlined above have passed, the token is renewed in the following way:
- A new ID is generated for the token.
- A new "IssueInstant" is set on the token.
- A new Conditions Element replaces the old Conditions Element of the token, using the configured ConditionsProvider.
- The Assertion is (re)-signed if the "signToken" property is true.
3) SAML Token Renewal in action
Finally, let's take a look at a system test in CXF that shows how to renew a SAML Token issued by an STS. The wsdl of the service provider defines a number of endpoints which use the transport binding, with a (endorsing) supporting token requirement which has an IssuedToken policy that requires a SAML token. In other words, the client must request a SAML token from an STS and send it to the service provider over TLS, and optionally use the secret associated with the SAML token to sign the message Timestamp (if an EndorsingSupportingToken policy is specified in the wsdl).
The STS spring configuration is available here. The SAMLTokenRenewer is configured with proof-of-possession enabled, and tokens are allowed to be renewed after they have expired. Let's look at the test code and client configuration. All of the tests follow the same pattern. The client requests a SAML Token from the STS (as per the IssuedToken policy), with a TTL (time-to-live) value of 8 seconds. The client then uses this issued token to make a successful request to the service provider. The test code then sleeps for 8 seconds to expire the token, and tries to invoke on the service provider again. The IssuedTokenInterceptorProvider in the WS-Security runtime in CXF recognises that the token has expired, and sends it to the STS for renewal. The returned (renewed) token is then sent to the service provider.