Oak Documentation

Token Creation

The creation of a new token is triggered by valid and supported Credentials passed to the login module chain that contain an additional, empty .token attribute.

The TokenLoginModule will obtain these Credentials from the shared state during the commit phase (i.e. phase 2 of the JAAS authentication) and will pass them to the configured TokenProvider implementation the following sequence:

Credentials shared = getSharedCredentials();
if (shared != null && tokenProvider.doCreateToken(shared)) {
    [...]
    TokenInfo ti = tokenProvider.createToken(shared);
    [...]
}

In case of success these steps will have generated a new token and stored it's hash along with all mandatory and informative attributes to the new content node representing the token.

Token Validation

Once a token has been created it can be used for subsequent repository logins with TokenCredentials. This time the TokenLoginModule will attempt to perform the login phase (i.e. phase 1 of the JAAS authentication).

This includes resolving the login token (TokenProvider.getTokenInfo) and asserting it's validity in case it exists. The validation consists of following steps:

• check that the token has not expired (TokenInfo.isExpired)
• verify that all mandatory attributes are present and match the expectations (TokenInfo.matches)

Only if these steps have been successfully completed the login of the TokenLoginModule will succeed.

Token Removal

A given login token (and the node associated with it) will be removed if the authentication fails due to an expired token or with an explicit API call i.e. TokenInfo.remove.

Resetting Expiration Time

The default TokenProvider implementation will automatically reset the expiration time of a given token upon successful authentication.

This behavior can be disabled by setting the tokenRefresh configuration parameter to false (see PARAM_TOKEN_REFRESH below). In this case expiration time will not be reset and an attempt to do so using the API (e.g. calling TokenInfo.resetExpiration(long loginTime)) will return false indicating that the expiration time has not been reset. The token will consequently expire and the user will need to login again using the configured login mechanism (e.g. using the credentials support for token creation).

Token Cleanup

Automatic token cleanup can be enabled by setting the tokenCleanupThreshold parameter to a value larger than 0 (0 means disabled). This will trigger a cleanup call if the number of tokens under a user exceeds this value. (As an implementation detail a throttling method was introduced to only allow the call to go through 1/8 times).

This is available with Oak 1.7.12 on, see also [OAK-6818]for additional information.

Content Structure

The login tokens issued for a given user are all located underneath a node named .tokens that will be created by the TokenProvider once the first token is created. The default implementation creates a distinct node for each login token as described below

testUser {
    "jcr:primaryType": "rep:User",
    ...
    ".tokens" {
        "jcr:primaryType": "rep:Unstructured",
        "2014-04-10T16.09.07.159+02.00" {
            "jcr:primaryType": "rep:Token",
            ...
        "2014-05-07T12.08.57.683+02.00" {
            "jcr:primaryType": "rep:Token",
            ...
        }
        "2014-06-25T16.00.13.018+02.00" {
            "jcr:primaryType": "rep:Token",
            ...
        }
    }
}

Token Nodes

As of Oak 1.0 the login token are represented in the repository as follows:

• the token node is referenceable with the dedicated node type rep:Token (used to be unstructured in Jackrabbit 2.x)
• expiration and key properties are defined to be mandatory and protected
• expiration time is obtained from PARAM_TOKEN_EXPIRATION specified in the login attributes and falls back to the configuration parameter with the same name as specified in the configuration options of the TokenConfiguration.

The definition of the new built-in node type rep:Token:

[rep:Token] > mix:referenceable
- rep:token.key (STRING) protected mandatory
- rep:token.exp (DATE) protected mandatory
- * (UNDEFINED) protected
- * (UNDEFINED) multiple protected

The following example illustrates the token nodes resulting from this node type definition:

testUser {
        "jcr:primaryType": "rep:User",
        ...
        ".tokens" {
            "2014-04-10T16.09.07.159+02.00" {
                "jcr:primaryType": "rep:Token",
                "jcr:uuid": "30c1f361-35a2-421a-9ebc-c781eb8a08f0",
                "rep:token.key": "{SHA-256}afaf64dba5d862f9-1000-3e2d4e58ac16189b9f2ac95d8d5b692e61cb06db437bcd9be5c10bdf3792356a",
                "rep:token.exp": "2014-04-11T04:09:07.159+02:00",
                ".token.ip": "0:0:0:0:0:0:0:1%0"
                ".token.otherMandatoryProperty": "expectedValue",
                "referer": "http://localhost:4502/crx/explorer/login.jsp"
                "otherInformalProperty": "somevalue"
            },
            "2014-05-07T12.08.57.683+02.00" {
                "jcr:primaryType": "rep:Token",
                "jcr:uuid": "c95c91e2-2e08-48ab-93db-6e7c8cdd6469",
                "rep:token.key": "{SHA-256}b1d268c55abda258-1000-62e4c368972260576d37e6ba14a10f9f02897e42992624890e22c522220f7e54",
                "rep:token.exp": "2014-05-08T00:08:57.683+02:00"
            },
            ...
        }
    }
}

Configuration Parameters