Introduction
PicketLink supports the concept of Token Registry to store tokens using any store such databases, filesystem or memory.
They are useful for auditing and to track the tokens that were issued or revocated by the Identity Provider or the Security Token Service.
When running PicketLink in a clustered environment, consider using Token Registries with databases. That way changes to the token table are visible to all nodes.
of-box Token Registries
The table bellow shows all implementations provided by PicketLink:
|
Name
|
Description
|
Version
|
|
org.picketlink.identity.federation.core.sts.registry.DefaultTokenRegistry
|
In-memory based registry. Used by default if no configuration is provided
|
2.x.x
|
|
org.picketlink.identity.federation.core.sts.registry.FileBasedTokenRegistry
|
Filesystem based registry
|
2.x.x
|
|
org.picketlink.identity.federation.core.sts.registry.JPABasedTokenRegistry
|
Database/JPA based registry
|
2.1.3
|
Currently, the PicketLink module.xml does not configure dependencies for JPA. If you want to use the JPA-based token registry, please read this JIRA
https://issues.jboss.org/browse/PLINK2-97
We're working to provide those dependencies out-of-box for next versions of EAP.
Configuration
Token Registries are configured through the PicketLinkSTS (Security Token Service configuration) element in the WEB-INF/picketlink.xml file:
<PicketLinkSTS xmlns="urn:picketlink:identity-federation:config:1.0" TokenTimeout="5000" ClockSkew="0">
<TokenProviders>
<TokenProvider
ProviderClass="org.picketlink.identity.federation.core.saml.v2.providers.SAML20AssertionTokenProvider"
TokenType="urn:oasis:names:tc:SAML:2.0:assertion"
TokenElement="Assertion" TokenElementNS="urn:oasis:names:tc:SAML:2.0:assertion">
<Property Key="TokenRegistry" Value="org.picketlink.identity.federation.core.sts.registry.JPABasedTokenRegistry" />
</TokenProvider>
</TokenProviders>
</PicketLinkSTS>
The example above uses a SAML v2 Token Provider configured with the
org.picketlink.identity.federation.core.sts.registry.JPABasedTokenRegistry implementation. This is done by the
TokenRegistry property.
org.picketlink.identity.federation.core.sts.registry.FileBasedTokenRegistry
<TokenProvider
ProviderClass="org.picketlink.identity.federation.core.saml.v2.providers.SAML20AssertionTokenProvider"
TokenType="urn:oasis:names:tc:SAML:2.0:assertion"
TokenElement="Assertion" TokenElementNS="urn:oasis:names:tc:SAML:2.0:assertion">
<Property Key="TokenRegistry" Value="FILE" />
<Property Key="TokenRegistryFile" Value="/some/dir/token.registry" />
</TokenProvider>
Use the TokenRegistryFile to specify a file where the tokens should be persisted.
org.picketlink.identity.federation.core.sts.registry.JPABasedTokenRegistry
<TokenProvider
ProviderClass="org.picketlink.identity.federation.core.saml.v2.providers.SAML20AssertionTokenProvider"
TokenType="urn:oasis:names:tc:SAML:2.0:assertion"
TokenElement="Assertion" TokenElementNS="urn:oasis:names:tc:SAML:2.0:assertion">
<Property Key="TokenRegistry" Value="org.picketlink.identity.federation.core.sts.registry.JPABasedTokenRegistry" />
</TokenProvider>
This implementation requires that you have a valid JPA Persistence Unit named
picketlink-sts.
Custom Token Registry
If none of the built-in implementations are useful for you, PicketLink allows you to create your own implementation. To do that, just create a class that implements the org.picketlink.identity.federation.core.sts.registry.SecurityTokenRegistry interface.
We recommend that you take a look first at one of the provided implementation before building your own.
Bellow is an skeleton for a custom Token Registry implementation:
public class CustomSecurityTokenRegistry implements SecurityTokenRegistry {
@Override
public void addToken(String tokenID, Object token) throws IOException {
// TODO: logic to add a token to the registry
}
@Override
public void removeToken(String tokenID) throws IOException {
// TODO: logic to remove a token to the registry
}
@Override
public Object getToken(String tokenID) {
// TODO: logic to get a token from the registry
return null;
}
}