Product names changed when ForgeRock became part of Ping Identity.

The following name changes have been in effect since early 2024:

Learn more about the name changes in New names for ForgeRock products in the Knowledge Base.

The STS supports the following features:

STS token transformations validate input tokens before generating output tokens. The STS uses authentication trees to perform token validation. When deploying STS, you must configure an appropriate authentication tree to validate input tokens.

This section describes authentication configuration requirements for username, X.509, and OIDC tokens. No special authentication configuration is required when using AM session tokens as the input tokens in token transformations.

Because STS instances aren’t part of a secure framework like WS-Trust, this section also discusses security considerations when sending tokens across a network to an STS instance.

In addition to configuring AM authentication to support input token validation, you must identify the authentication tree that will validate each input token type. To do so, configure the Authentication Target Mappings property in the STS instance configuration. Learn more in the STS configuration properties.

To configure an STS instance using the AM admin UI, go to Realms > Realm Name > STS, and click Add Rest STS.

Read STS configuration properties for detailed information about STS configuration properties.

To publish an STS instance programmatically, use the Publish service. This service is a collection of endpoints you can use to publish instances instead of accessing the AM admin UI.

Learn more in The Publish service.

An STS instance endpoint is composed of the following:

For example, an STS instance configured in the alpha realm with the deployment URL element username-transformer exposes the endpoint /rest-sts/alpha/username-transformer.

Token transformations are represented in JSON as follows:

The STS supports the following token types and properties:

The following are examples of JSON payloads that define STS token transformations:

Find more examples of JSON payloads you can send to STS instances in the comments in the Java example sample code.

You can use the curl command to check that a published STS instance is working as expected.

For example, if you publish a REST instance with a deployment URL element username-transformer that supports username to SAML v2.0 bearer assertion token transformation, you can send an HTTP POST request to the /rest-sts/username-transformer endpoint, setting the _action parameter to translate as follows:

The iPlanetDirectoryPro header is required and should contain the SSO token of an administrative user, such as amAdmin, who has access to perform the operation.

The RestSTSConsumer.java sample code provides an example of how to consume a published STS instance programmatically. Tailor this example as required to provide programmatic consumption of your own STS instances.

The sts-tokengen endpoint provides administrators with the ability to query and cancel tokens issued using REST API calls.

When using the sts-tokengen endpoint, make sure you provide the token ID for an AM administrator, such as amAdmin, as the value of a header whose name is the name of the SSO token cookie, by default iPlanetDirectoryPro.

STS users can validate and cancel tokens by making an HTTP POST call to an STS instance’s endpoint.

To validate a token, use the validate action. The following example validates an OIDC token previously issued by the username-transformer STS instance:

To cancel a token, use the cancel action. The following example cancels an OIDC token previously issued by the username-transformer STS instance:

The sample code referenced in this section provides an example of how to programmatically publish STS instance. The code isn’t intended to be a working example. Instead, it is a starting point that you can modify to satisfy your organization’s specific requirements.

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?.

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

After publishing an STS instance programmatically, you can view the instance’s configuration in the AM admin UI. The instance is ready for consumption.

Sample code is available for the following classes:

The following are general configuration properties for STS instances:

The following are deployment configuration properties for STS instances:

The following are SAML v2.0 token configuration properties for STS instances:

The properties fall into two categories:

The following are OIDC token configuration properties for STS instances:

The properties fall into two categories:

An STS instance configured to issue OIDC tokens models the relationship between an OIDC token provider and relying party. In other words, an STS instance issues tokens for a particular OAuth 2.0 client. The tokens contain aud and azp claims for the OAuth 2.0 client, and signing key state corresponding to a token provider.

In this model, when users call an STS instance to generate an OIDC ID token, the process is analogous to the exchange between an OAuth 2.0 authorization server and resource owner following the initial redirection from an OAuth 2.0 client initiating the implicit flow. The STS instance returns the OIDC ID token that corresponds to the authorization server’s authentication of the resource owner.

AM authenticates the token specified as the input_token_state for the token transformation

Implicit in this model is the notion that an OIDC ID token has value outside of an OAuth 2.0 flow, and that an OAuth 2.0 client, as a relying party, could be generalized as a SAML v2.0 service provider. The ID token isn’t simply an an entity-provided verifiable authorized access to a specific resource, but rather a generic service provider that consumes an OIDC ID token to authenticate and authorize the subject asserted by the token.

Therefore, the configuration of an STS instance that issues OIDC ID tokens contains information that defines the token provider and relying party.

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.

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

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:

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

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

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

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

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

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.