---
title: Custom token types
description: AM supports token transformations to and from a variety of token types, including username, SAML 2.0, OIDC, and X.509. In addition to these core token types, STS instances can use custom token types as the input or output token, or both, in a token transformation. When you configure an 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.
component: pingam
version: 8.1
page_id: pingam:sts:sts-custom-token-types
canonical_url: https://docs.pingidentity.com/pingam/8.1/sts/sts-custom-token-types.html
page_aliases: ["sts-guide:sts-custom-token-types.adoc"]
section_ids:
  sts-consume-rest-custom-validator: Develop custom token type validator classes
  sts-consume-rest-custom-provider: Develop custom token type provider classes
  sts-consume-rest-custom-using: Use custom token type validators and providers
---

# Custom token types

AM supports token transformations to and from a variety of token types, including username, SAML 2.0, OIDC, and X.509. In addition to these core token types, STS instances can use custom token types as the input or output token, or both, in a token transformation. When you configure an 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.

|   |                                                                                                                                                                                                                                                                                                                                                                                    |
| - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | Learn about downloading and building PingAM sample source code in the following *Knowledge Base* article: [How do I access and build the sample code provided for PingAM?](https://support.pingidentity.com/s/article/How-do-I-access-and-build-the-sample-code-provided-for-PingAM).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 admin UI by configuring the Custom Token Validators and Custom Token Providers properties under Realms > *realm name* > STS > *STS instance*.

A custom validator class can be used in transformations that produce standard STS output tokens, such as SAML 2.0 tokens or OIDC 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 an 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.

## Develop 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 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.

## Develop 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.

## Use 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 an 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 OIDC token, you might specify a JSON payload similar to the following:

```json
{
    "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:

```json
{
    "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:

```json
{
    "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 doesn't return any additional state, the additional state for this example would be null.

* The input token type: `CUSTOM`

* A `JsonValue` representation of the following:

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

* A `JsonValue` representation of the following:

  ```json
  {
      "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:

```json
{
    "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.