PingOne

Configuring token exchange with trusted issuers

PingOne accepts signed JSON Web Tokens (JWTs) from trusted external authorization servers as inputs during OAuth 2.0 token exchange. Trusted issuers can include another PingOne environment, another Ping Identity product, or a third-party solution.

You can provide these JWTs as the subject token, actor token, or both, and exchange them for an access token to access a custom resource. To accept third-party JWTs, PingOne validates the token’s digital signature using the trusted issuer’s configured JSON Web Key Set (JWKS) and applies the issuer’s token validation settings.

For each incoming token issued by a trusted issuer, PingOne ignores the p1.userId claim and doesn’t use the token to locate a user. The corresponding subjectTokenUser or actorTokenUser value is null. This applies even to tokens issued by another PingOne environment.

What you’ll do

To set up token exchange with external trusted issuers in PingOne, you’ll:

  1. Add a trusted issuer to represent external JWT issuers.

  2. Assign the trusted issuer to an application that handles token exchange requests.

  3. Define custom resource attribute mappings to determine the claims in the resulting access tokens.

Before you begin

For this use case, you’ll need:

  • The Environment Admin role or a custom role with equivalent permissions to manage trusted issuers and trusted issuer assignments. Learn more in Administrator Roles.

  • An OpenID Connect (OIDC)-based application configured with the token exchange grant type. Worker applications aren’t supported. Learn more in Adding an application.

  • A custom resource as the intended audience of the access tokens during token exchange. Learn more in Adding a custom resource.

Steps

  1. Add a Trusted Issuer by completing the steps in Adding a trusted issuer.

  2. Assign the Trusted Issuer to an application that will handle token exchange:

    1. Go to Applications > Applications and click the OIDC-based application to which you want to assign a trusted issuer.

    2. On the Trusted Issuers tab, click the Pencil icon ().

    3. Select the checkboxes for the Trusted Issuers you want to assign.

    4. Click Save.

  3. Define attribute mappings in the custom resources that are the intended audiences of the access tokens for the token exchange requests.

    In the following example, you’ll map the actor token’s sub claim to the act claim in the resulting access token.

    1. Go to Applications > Resources and browse or search for the applicable custom resource.

    2. On the Attributes tab, click and click Add.

    3. Enter act for the attribute name.

    4. Click the Gear icon () to open the Advanced Expressions modal.

    5. Enter the following expression:

      {"sub": #root.context.requestData.actorToken.sub}

      This expression sets the resulting access token’s act claim to a JSON object whose sub property contains the actor token’s sub claim.

    6. Click Save.

    7. On the Attributes tab, click Save.

Runtime process overview

In the previous example attribute mapping, the custom resource attribute mapping adds an act claim to the resulting token and sets its value to the sub claim from the trusted issuer’s actor token.

The process flow for exchanging a token from a trusted issuer is as follows:

  1. The application uses the authorization code grant type to obtain an access token from PingOne.

  2. The application uses the client credentials grant type to obtain an access token from the trusted issuer.

  3. The application sends a token exchange request to PingOne using the token exchange grant type.

    • If the subject token is a signed JWT from an assigned trusted issuer, the request specifies urn:ietf:params:oauth:token-type:jwt as the value of the subject_token_type parameter.

    • If the actor token is such a JWT, the request specifies the same value for the actor_token_type parameter.

    • If both tokens are such JWTs, the request specifies the value for both parameters.

  4. PingOne returns an access token that includes an act claim.

    The claim’s value comes from the actor token’s sub claim based on the custom resource attribute mapping.

Next steps

Run a PingOne Audit report or create a webhook to view events related to trusted issuers. Learn more in Running an audit report. You can find a complete list of events logged in PingOne in Audit Reporting Events in the PingOne API documentation.