Token Managers

A Token Manager is responsible for generating and verifying authentication tokens. When a request is authenticated through any configured method, such as Basic Authentication, the response includes the Auth-Token header. The value of this token is generated by the Token Manager. Subsequent requests can utilize this authentication token in lieu of actual credentials.

Note	The Token Manager works in conjunction with the Authentication Mechanism `tokenBasicAuthMechanism`. This mechanism handles the token and delegates its verification to the configured token manager.

Implementation

The Token Manager implementation class must implement the org.restheart.plugins.security.TokenManager interface.

Tip	For an example implementation check the code of RndTokenManager, which generates random tokens.

Note that TokenManager extends Authenticator for token verification methods.

public interface TokenManager extends Authenticator, ConfigurablePlugin {
    public static final HttpString AUTH_TOKEN_HEADER = HttpString.tryFromString("Auth-Token");
    public static final HttpString AUTH_TOKEN_VALID_HEADER = HttpString.tryFromString("Auth-Token-Valid-Until");
    public static final HttpString AUTH_TOKEN_LOCATION_HEADER = HttpString.tryFromString("Auth-Token-Location");
    public static final HttpString ACCESS_CONTROL_EXPOSE_HEADERS = HttpString.tryFromString("Access-Control-Expose-Headers");

    /**
     * retrieves or generates a token valid for the account
     *
     * @param account
     * @return the token for the account
     */
    public PasswordCredential get(final Account account);

    /**
     * invalidates the token bound to the account
     *
     * @param account
     */
    public void invalidate(final Account account);

    /**
     * updates the account bound to a token
     *
     * @param account
     */
    public void update(final Account account);

    /**
     * injects the token headers in the response
     *
     * @param exchange
     * @param token
     */
    public void injectTokenHeaders(final HttpServerExchange exchange, final PasswordCredential token);
}

Registering

The Token Manager class must be annotated with @RegisterPlugin:

@RegisterPlugin(name="myTokenManager", description = "my custom token manager")
public class MyTokenManager implements TokenManager {

}

Note	Only one token manager can be used. If more than one token manager is defined and enabled, only the first one will be used.

Configuration

The Token Manager can receive parameters from the configuration file using the @Inject("config") annotation:

@Inject("config")
private Map<String, Object> config;

@OnInit
public void init() throws ConfigurationException {
    // get configuration arguments
    int number  = argValue(this.config, "number");
    String string = argValue(this.config, "string");
}

The parameters are defined in the configuration using the name of the token manager as defined by the @RegisterPlugins annotation:

myTokenManager:
    number: 10
    string: a string