Supporting Custom Token Types

AM supports token transformations to and from a variety of token types, including username, SAML v2.0, OpenID Connect, and X.509. In addition to these supported token types, REST STS instances can use custom token types as the input or output token, or both, in a token transformation. When you configure a REST STS instance to support a token transformation that takes a custom token type, you can also configure a custom validator and provider class for the custom token type. AM uses custom validator classes to validate custom tokens and custom provider classes to produce custom tokens.

Tip

For information on downloading and building AM sample source code, see How do I access and build the sample code provided for AM (All versions)? in the Knowledge Base.

You can find the STS code examples under /path/to/openam-samples-external/sts-example-code.

Specify custom token validator and provider classes in the AM console by configuring the Custom Token Validators and Custom Token Providers properties under Realms > Realm Name > STS > REST STS Instance Name.

A custom validator class can be used in transformations that produce standard STS output tokens, such as SAML v2.0 tokens or OpenID Connect tokens, and in transformations that produce custom output token types.

A custom provider class can be used in token transformations that take standard STS input tokens, such as username tokens or AM SSO tokens, and in transformations that take custom input token types.

Before a REST STS instance can use a custom token type validator or provider class, you must bundle the class into the AM .war file and restart AM.

AM invokes a single instance of a validator or provider class to run all concurrently dispatched token transformations that use the custom token type. Because there is only a single instance of the class, you must code custom validator and provider classes to be thread-safe.

Developing Custom Token Type Validator Classes

To create a custom token type validator class, implement the org.forgerock.openam.sts.rest.token.validator.RestTokenTransformValidator class.

Custom token type validator classes implement the validateToken method. This method takes a RestTokenValidatorParameters object as input. Note that the generic type of RestTokenValidatorParameters is org.forgerock.json.fluent.JsonValue. As a result of using this type, custom validator classes can access the JSON representation of the input token passed to the REST STS instance in the input_token_state JSON key.

The validateToken method returns an org.forgerock.openam.sts.rest.token.validator.RestTokenTransformValidatorResult object. At a minimum, this object contains the AM SSO token corresponding to the validated principal. It can also contain additional information specified as a JSON value, allowing a custom validator to pass extra state to a custom provider in a token transformation.

Developing Custom Token Type Provider Classes

To create a custom token type provider class, implement the org.forgerock.openam.sts.rest.token.provider.RestTokenProvider class.

Custom token type provider classes implement the createToken method. This method takes an org.forgerock.openam.sts.rest.token.provider.CustomRestTokenProviderParameters object as input. This object gives the custom provider access to the following information:

The principal returned by the RestTokenTransformValidator
The AM SSO token corresponding to the validated principal
Any additional state returned in the RestTokenValidatorResult object
The type of input token validated by the RestTokenTransformValidator in the token transformation
The JsonValue corresponding to this validated token, as specified by the input_token_state object in the transformation request
The JsonValue corresponding to the token_output_state object specified in the token transformation request (which can provide additional information pertinent to the creation of the output token)

The createToken method returns a string representation of the custom token in a format that can be transmitted across HTTP in JSON. It should be base64-encoded if binary.

Using Custom Token Type Validators and Providers

This section provides an example of how to use custom token type validators and providers.

The example assumes that you already configured a token transformation by completing the following tasks:

Implementing the RestTokenTransformValidator interface to create a custom token type validator
Implementing the RestTokenProvider interface to create a custom token type provider
Bundling the two classes into the AM .war file
Restarting AM
Publishing a REST STS instance with a custom token type named CUSTOM, specifying the custom validator and provider classes in the instance's configuration

To transform a CUSTOM token to an OpenID Connect token, you might specify a JSON payload similar to the following:

{
    "input_token_state":
        {
            "token_type": "CUSTOM",
            "extra_stuff": "very_useful_state"
        },
    "output_token_state":
        {
            "token_type": "OPENIDCONNECT",
            "nonce": "1234",
            "allow_access": true
        }
}

With the preceding JSON payload, AM passes a JsonValue instance to the validateToken method of the custom token type validator class as follows:

{
    "token_type": "CUSTOM",
    "extra_stuff": "very_useful_state"
}

To transform a username token to a CUSTOM token, you might specify a JSON payload similar to the following:

{
    "input_token_state":
        {
            "token_type": "USERNAME",
            "username": "unt_user17458687",
            "password": "password"
        },
    "output_token_state":
        {
            "token_type": "CUSTOM",
            "extra_stuff_for_custom": "some_useful_information"
        }
}

With the preceding JSON payload, AM passes the following information to the createToken method of the custom token type provider:

The principal returned by the USERNAME token validator: unt_user17458687.
The AM SSO token corresponding to this authenticated principal.
Additional state returned by the token validator, if any. Because the USERNAME token validator does not return any additional state, the additional state for this example would be null.
The input token type: CUSTOM

A JsonValue representation of the following:

{
    "token_type": "USERNAME",
    "username": "unt_user17458687",
    "password": "password"
}

A JsonValue representation of the following:

{
    "token_type": "CUSTOM",
    "extra_stuff_for_custom": "some_useful_information"
}

To transform a CUSTOM token to a CUSTOM token, you might specify a JSON payload similar to the following:

{
    "input_token_state":
        {
            "token_type": "CUSTOM",
            "extra_stuff": "very_useful_state"
        },
    "output_token_state":
        {
            "token_type": "CUSTOM",
            "extra_stuff_for_custom": "some_useful_information"
        }
}

The input to the custom validator and provider would be similar to the preceding examples, with the possible addition of any additional state that the custom validator returned from the validateToken method.