--- title: Configuring a refresh token-to-ID-JAG token exchange description: PingFederate can issue an Identity Assertion JWT Authorization Grant (ID-JAG) through OAuth token exchange when a client presents a refresh token as the subject token. Use this flow when PingFederate acts as the identity provider authorization server and must mint an ID-JAG for a downstream resource authorization server. component: pingfederate version: 13.1 page_id: pingfederate:administrators_reference_guide:pf_configuring_refresh_token_to_idjag_exchange canonical_url: https://docs.pingidentity.com/pingfederate/13.1/administrators_reference_guide/pf_configuring_refresh_token_to_idjag_exchange.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: July 21, 2026 section_ids: before-you-begin: Before you begin create-a-refresh-token-token-processor-instance: Create a Refresh Token Token Processor instance define-a-token-exchange-processor-policy: Define a token exchange processor policy configure-the-oauth-token-exchange-sp-connection: Configure the OAuth Token Exchange SP connection enable-token-exchange-in-the-oauth-client: Enable token exchange in the OAuth client verify-the-token-exchange-request: Verify the token exchange request example: Example: next-steps: Next steps --- # Configuring a refresh token-to-ID-JAG token exchange PingFederate can issue an Identity Assertion JWT Authorization Grant (ID-JAG) through OAuth *(tooltip: \
\

A standard framework that enables an application (OAuth client) to obtain access tokens from an OAuth authorization server for the purpose of retrieving protected resources on a resource server.\

\
)* token exchange *(tooltip: \
\

The process by which a security token is exchanged for another security token.\

\
)* when a client presents a refresh token *(tooltip: \
\

A long-lived token used by OAuth clients to obtain a new access token without having to obtain fresh authorization from the resource owner.\

\
)* as the subject token. Use this flow when PingFederate acts as the identity provider authorization server and must mint an ID-JAG for a downstream resource authorization server. In this flow, the token exchange processor policy validates the inbound refresh token and makes attributes available for mapping. The OAuth Token Exchange SP connection identifies the downstream resource authorization server and defines how PingFederate issues the outbound ID-JAG. ## Before you begin Before you configure this flow, make sure that: * PingFederate is already issuing refresh tokens for the client that will request the ID-JAG. * You know the identifier of the resource authorization server that will consume the ID-JAG. * You have an existing OAuth client *(tooltip: \
\

The application in an OAuth framework that requests access to resources. If the request is approved by the authorization server, the client is issued an access token for the resources.\

\
)* that will send the token exchange request. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This procedure uses a refresh token as the subject token because it represents an existing grant and is better suited for repeated or automated token exchanges without requiring reauthentication. Refresh tokens are also typically longer-lived than ID tokens. If your deployment uses an ID token as the subject token instead, use a JWT Token Processor 2.0 instance in the token exchange processor policy. Learn more in [Configuring a JWT Token Processor 2.0 instance](pf_configuring_jwt_token_processor_20_instance.html). | ## Create a Refresh Token Token Processor instance Use a Refresh Token Token Processor instance when the token exchange processor policy must accept a subject token of type `urn:ietf:params:oauth:token-type:refresh_token`. Learn more in [Configuring a Refresh Token Token Processor instance](pf_configuring_refresh_token_processor_instance.html). | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you expose grant attributes from the Refresh Token Token Processor, the extended contract attribute name must exactly match the persistent grant attribute name, including case. | 1. In the PingFederate admin console, go to **Authentication > Token Exchange > Token Processors**. 2. Click **Create New Instance**. 3. On the **Type** tab, enter an instance name and ID, and then select **OAuth Refresh Token Token Processor** as the type. 4. Go to the **Instance Configuration** tab. This plugin type has no individual configurable fields. Click **Next**. 5. On the **Extended Contract** tab, add any additional grant attributes you need to expose, and then click **Next**. 6. On the **Token Attributes** tab, optionally mask any attributes in log files, and then click **Next**. 7. Review the summary and click **Save**. ## Define a token exchange processor policy The token exchange processor policy controls how PingFederate validates the inbound refresh token and which attributes are passed to ID-JAG creation. Learn more in [Defining token exchange processor policies](pf_defining_token_exchange_processor_policies.html). 1. Go to **Applications > Token Exchange > Processor Policies**. 2. Click **Add Processor Policy**. 3. On the **Manage Processor Policy** tab, enter the policy ID and name. If requests for this use case require both a subject token and an actor token, select **Actor Token Required**. Otherwise, leave it cleared. Click **Next**. 4. On the **Attribute Contract** tab, add contract attributes as needed, and then click **Next**. 5. On the **Token Processor Mapping** tab, click **Map New Token Processor**. 6. On the **Token Types** tab, in the **Subject Token Processor** list, select the Refresh Token Token Processor instance. The **Subject Token Type** field populates with `urn:ietf:params:oauth:token-type:refresh_token`. If your use case requires an actor token, also select the actor token processor and enter the actor token type. Click **Next**. 7. On the **Attribute Sources & User Lookup** tab, add additional attribute sources if needed, and then click **Next**. 8. On the **Contract Fulfillment** tab, map each contract attribute to a source and value, and then click **Next**. 9. On the **Issuance Criteria** tab, define any conditions that must be satisfied before PingFederate exchanges the token, and then click **Next**. 10. Review the mapping summary, click **Done**, review the policy summary, and then click **Done**. 11. Click **Save**. 12. (Optional) Set the new policy as the default processor policy. ## Configure the OAuth Token Exchange SP connection Configure an OAuth Token Exchange SP connection to issue the ID-JAG to the downstream resource authorization server. 1. Go to **Applications > Integration > SP Connections**. 2. Click **Create Connection**. 3. On the **Connection Template** page, select **Do Not Use A Template For This Connection** or select a template. Click **Next**. 4. On the **Connection Type** page, select **OAuth Token Exchange**, and then click **Next**. 5. On the **General Info** page, configure the identifying information for the connection. Set **Partner's Entity ID** to the resource authorization server base URL. Click **Next**. 6. On the **OAuth Token Exchange** page, click **Configure OAuth Token Exchange**. 7. On the **Protocol Settings** page, if the client includes a `resource` parameter in the token exchange request, configure the corresponding resource URIs so PingFederate can select the correct OAuth Token Exchange SP connection. If the request targets multiple resources, add each applicable resource URI. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | In this flow, the `resource` parameter helps PingFederate select the SP connection for the token exchange request. Use the `audience` parameter to identify the intended audience for the issued ID-JAG. **Partner's Entity ID** becomes the default `aud` claim if no audience is provided. | 8. In **Allowed Requested Token Types**, select **Identity Assertion JWT (ID-JAG)**. 9. Click **Next**. 10. On the **Token Lifetime** page, optionally override the token lifetime settings, and then click **Next**. 11. Click **Configure Token Creation**. 12. On the **Attribute Contract** page, optionally extend the contract with any additional attributes that you need in the issued token, and then click **Next**. 13. On the **Processor Policy Mapping** page, click **Map Processor Policy Instance**. 14. In the **Processor Policy Instance** list, select the token exchange processor policy instance, and then click **Next**. 15. On the **Attribute Retrieval** page, choose whether to use only the attributes in the incoming token or to use the incoming token to look up additional information. 16. On the **Attribute Contract Fulfillment** page, map the contract attributes required for the ID-JAG. 17. (Optional) Define issuance criteria for the token exchange. 18. On the **Summary** tab, review the token creation summary, click **Done**, complete the remaining SP connection tasks, configure credentials, and then save the connection. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Issued ID-JAG tokens use the `typ` header value `oauth-id-jag+jwt`. By default, the `aud` claim in the issued JSON Web Token (JWT) *(tooltip: \
\

An IETF standard container format for a JSON object used for the secure exchange of content, such as identity or entitlement information. You can find the industry standard in \RFC 7519\.\

\
)* is set to the **Partner's Entity ID** value. | Learn more in [Configuring SP connections for OAuth token exchange](pf_configuring_sp_connections_oauth_token_exchange.html). ## Enable token exchange in the OAuth client Enable the token exchange grant in the OAuth client that will send the token exchange request. 1. Go to **Applications > OAuth > Clients**. 2. Open the client that will send the token exchange request. 3. In **Allowed Grant Types**, select **Token Exchange**. 4. In the **Token Exchange** section, select the token exchange processor policy. 5. Click **Save**. Learn more in [Enabling token exchange in OAuth clients](pf_enabl_token_exchang_oauth_client.html). ## Verify the token exchange request After you complete the configuration, the client can request an ID-JAG by sending a token exchange request to the token endpoint. ### Example: Example token exchange request: ```none POST /oauth2/token HTTP/1.1 Host: acme.idp.example Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:token-exchange &requested_token_type=urn:ietf:params:oauth:token-type:id-jag &audience=https://acme.chat.example/ &resource=https://api.chat.example/ &scope=chat.read+chat.history &subject_token=h4X9fK2mN1vP7zQ8wB3r... &subject_token_type=urn:ietf:params:oauth:token-type:refresh_token ``` If the request succeeds, PingFederate returns the ID-JAG in the `access_token` field and identifies the issued token type as `urn:ietf:params:oauth:token-type:id-jag`. Example token exchange response: ```json { "access_token": "eyJhbGciOiJIUzI1NiIsI...", "issued_token_type": "urn:ietf:params:oauth:token-type:id-jag", "token_type": "N_A", "expires_in": 300 } ``` ## Next steps If the client uses the issued ID-JAG to request an access token from a resource authorization server, configure that resource authorization server to accept the ID-JAG as a JWT bearer assertion. Learn more in [JWT Bearer Grant Processors](pf_jwt_bearer_grant_processors.html).