Recall that the TokenValidator interface has a method that takes a realm parameter:
-
boolean canHandleToken(ReceivedToken validateTarget, String realm)- Whether this TokenValidator implementation can validate the given token in the given realm
Realms are handled in a slightly different way in TokenValidators compared to TokenProviders. Recall that for TokenProviders, the implementation is essentially asked whether it can provide a token in a given realm. For the SCTProvider, the realm is ignored in this method. However, when creating a token, the SCTProvider will store the given realm as a property associated with that token in the cache. The SAMLTokenProvider checks to see if the given realm is null, and if it is not null then the realmMap must contain a key which matches the given realm.
There is a subtle distinction between the realm passed to "canHandleToken" for TokenValidators and the realm returned after a token is validated as part of the TokenValidatorResponse object. The realm passed to "canHandleToken" is the realm to validate the token in. So for example, you could have two TokenValidator instances registered to validate the same token, but in different realms. All of the TokenValidator implementations that ship with the STS ignore the realm as part of this method. However, the method signature gives the user the option to validate tokens in different realms in a more flexible manner.
The realm that is returned as part of the TokenValidatorResponse is the realm that the validated token is in (if any). This can be different to the realm the token was validated in. The X509TokenValidator ignores this parameter altogether. The SCTValidator checks to see whether the SecurityToken that was stored in the cache has a realm property, and if so sets this on the TokenValidatorResonse. The UsernameTokenValidator and SAMLTokenValidator handle realms in a more sophisticated manner. Recall that the UsernameTokenValidator has the following method:
-
void setUsernameTokenRealmCodec(UsernameTokenRealmCodec uTRC)- Set the UsernameTokenRealmCodec instance to use to return a realm from a validated token.
The UsernameTokenRealmCodec has a single method:
-
String getRealmFromToken(UsernameToken usernameToken)- Get the realm associated with the UsernameToken parameter.
No UsernameTokenRealmCodec implementation is set by default on the UsernameTokenValidator, hence no realm is
returned in TokenValidatorResponse. If an implemention is specified, then the UsernameTokenValidator will
retrieve a realm from the UsernameTokenRealmCodec implementation corresponding to the validated UsernameToken.
If a cache is configured, and the UsernameToken was already stored in the cache, then the realm is compared
to the realm of the cached token, stored under the tag org.apache.cxf.sts.token.realm.
If they do not match then validation fails.