---
title: TokenTransformationFilter
description: Transforms a token issued by AM to another token type.
component: pinggateway
version: 2026
page_id: pinggateway:reference:TokenTransformationFilter
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/TokenTransformationFilter.html
revdate: 2026-01-12
section_ids:
  TokenTransformationFilter-usage: Usage
  TokenTransformationFilter-properties: Properties
  TokenTransformationFilter-example: Example
  TokenTransformationFilter-moreinfo: More information
---

# TokenTransformationFilter

Transforms a token issued by AM to another token type.

The TokenTransformationFilter makes the result of the token transformation available to downstream handlers in the `sts` context. Learn more in [StsContext](StsContext.html).

The current implementation uses REST Security Token Service (STS) APIs to transform an OpenID Connect ID Token (`id_token`) into a SAML 2.0 assertion. The subject confirmation method is Bearer, as described in [Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0](https://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf).

The TokenTransformationFilter makes the result of the token transformation available to downstream handlers in the `issuedToken` property of the `${contexts.sts}` context.

The TokenTransformationFilter configuration references a REST STS instance that must be set up in AM before the TokenTransformationFilter can be used. The REST STS instance exposes a preconfigured transformation under a specific REST endpoint.

Errors that occur during the token transformation cause a error response to be returned to the client and an error message to be logged for the PingGateway administrator.

## Usage

```json
{
    "name": "string",
    "type": "TokenTransformationFilter",
    "config": {
        "amService": AmService reference,
        "idToken": runtime expression<string>,
        "instance": configuration expression<string>,
        "username": configuration expression<string>, //deprecated
        "password": configuration expression<string>  //deprecated
    }
}
```

## Properties

* `"amService"`: *AmService [reference](preface.html#definition-reference), required*

  The [AmService](AmService.html) heap object to use for the following properties:

  * `agent`, the credentials of the PingGateway agent in AM, to authenticate PingGateway as an AM REST STS client, and to communicate WebSocket notifications from AM to PingGateway. This credentials are evaluated when the route is initialized

  * `url`, the URL of an AM service to use for session token validation and authentication. Authentication and REST STS requests are made to this service.

  * `realm`, the AM realm containing the following information:

    * The AM application that can make the REST STS request and whose credentials are the username and password.

    * The STS instance described by the instance field.

  * `ssoTokenHeader`, the name of the HTTP header that provides the SSO token for the REST STS client subject.

  * `amHandler`, the handler to use for authentication and STS requests to AM.

* `"idToken"`: *runtime expression<[string](preface.html#definition-string)>, required*

  The value of the OpenID Connect ID token. The expected value is a string that is the JWT encoded `id_token`.

* `"instance"`: *configuration expression<[string](preface.html#definition-string)>, required*

  An expression evaluating to the name of the REST STS instance.

  This expression is evaluated when the route is initialized, so the expression cannot refer to `request` or `contexts`.

* `"username"`: *string, required*

  |   |                                                                                     |
  | - | ----------------------------------------------------------------------------------- |
  |   | The use of this property is deprecated. Use the AmService property `agent` instead. |

  The username to authenticate PingGateway as an AM REST STS client.

* `"password"`: *expression, required*

  |   |                                                                                     |
  | - | ----------------------------------------------------------------------------------- |
  |   | The use of this property is deprecated. Use the AmService property `agent` instead. |

  The password to authenticate PingGateway as an AM REST STS client.

## Example

The following example shows a configuration for a TokenTransformationFilter:

```json
{
  "type": "TokenTransformationFilter",
  "config": {
    "amService": "MyAmService",
    "idToken": "${contexts.oauth2Info.idToken}",
    "instance": "openig"
  }
}
```

You can find an example of how to set up and test the TokenTransformationFilter in [OIDC ID tokens to SAML assertions with PingAM](../gateway-guide/ttf.html).

## More information

[org.forgerock.openig.openam.TokenTransformationFilter](../_attachments/apidocs/org/forgerock/openig/openam/TokenTransformationFilter.html)

[org.forgerock.openig.openam.StsContext](../_attachments/apidocs/org/forgerock/openig/openam/StsContext.html)

[StsContext](StsContext.html)