PingFederate Server

Configuring a refresh token-to-ID-JAG token exchange

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.

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

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.

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.

  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) is set to the Partner’s Entity ID value.

Learn more in Configuring SP connections for OAuth token exchange.

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.

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:

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:

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