PingOne

Machine-to-machine interaction

Machine-to-machine interaction is one of the use cases supported by OAuth 2.0 token exchange in PingOne. Learn more about how it works and the supported use cases in Configuring OAuth 2.0 token exchange.

Use machine-to-machine interaction for token exchange to enable server-to-server communication to exchange an existing token for a new token without any user interaction. In machine-to-machine interaction, the application obtains a subject token representing the user who authenticates and authorizes the request

The application obtains a subject token representing the user who authenticates and authorizes the request and exchanges it for a new token to access a protected resource. When minting the new access tokens, PingOne doesn’t include the sub claim because no user (subject) is involved.

Example scenario

A backend system, Zillion Deals, generates the top 10 deals of the week for an online retail store. To complete this task:

  1. Zillion Deals needs to retrieve flyers from across the country from a resource server, e-Flyers.

  2. e-Flyers must retrieve the best deals from another resource server, Zing.

What you’ll do

To set up the example scenario for impersonation, you’ll add:

  • Zillion Deals application: This backend application initiates the flow.

  • e-Flyers custom resource: This resource has the information needed by the Zillion Deals application.

  • e-Flyers Token Exchange application: This application processes the token exchange request.

  • Zing custom resource: This resource has additional information the Zillion Deals application retrieves data from without user interaction.

Example tasks

Adding e-Flyers as a custom resource

As a PingOne administrator, add a custom resource in PingOne for the e-Flyers resource server.

Steps

  1. In the PingOne admin console, go to Applications > Resources and click the icon.

  2. In the Create Resource Profile step:

    1. For Resource Name, enter e-Flyers.

    2. For Audience, enter the audience for resource in the format of https://api.example.com/e.

    3. (Optional) For Description, enter a brief description of the resource.

    4. For Access token time to live, leave the default or optionally edit the maximum time that the access token will be valid for use in the application, in seconds.

    5. Click Next.

  3. In the Attributes step:

    1. Leave the default mapping of sub to User ID.

    2. Click Add.

    3. Enter an Attribute representing the flyers, such as e.attr and then click the Gear icon () next to the attribute to open the Advanced Expressions modal.

    4. In the modal, enter an expression to map the flyers to the attribute, such as 'Eee', and click Save.

    5. Click Next.

  4. In the Scopes step:

    1. Click Add Scope.

    2. For Scope Name, enter a name, such as e.crud.

    3. (Optional) Enter a Description for the scope.

    4. Click Save.

Adding Zillion Deals as an application

Add an application in PingOne for Zillion Deals and assign the scope from the e-Flyers custom resource. Zillion Deals must use the client credentials grant type to obtain access tokens from PingOne to send API requests to e-Flyers to retrieve flyers from across the country.

The access tokens contain a subject (sub). The subject is the user who authenticates and authorizes the application request from Zillion Deals. When minting these access tokens, PingOne populates the attribute claim with the mapped value you provide (e.attr = Eee) and doesn’t include the sub claim because no user is involved (User ID is null).

Steps

  1. Go to Applications > Applications and click the icon.

  2. In the Add Application panel:

    1. For Application Name, enter Zillion Deals.

    2. (Optional) Enter a Description for the application.

    3. Select an OIDC-based application type and click Save.

  3. On the Configuration tab:

    1. Click the Pencil icon ().

    2. For Grant Type, select Client Credentials.

      The client credentials grant type is used for machine-to-machine interactions.

    3. Leave all other default settings.

    4. Click Save.

  4. On the Resources tab:

    1. Click .

    2. Assign the resource you created in Adding e-Flyers as a custom resource.

    3. Click Save.

Adding Zing as a custom resource

Add a custom resource in PingOne for the Zing resource server.

Steps

  1. Go to Applications > Resources and click the icon.

  2. In the Create Resource Profile step:

    1. For Resource Name, enter Zing.

    2. For Audience, enter the audience for resource in the format of https://api.example.com/z.

    3. (Optional) For Description, enter a brief description of the resource.

    4. For Access token time to live, leave the default or optionally edit the maximum time that the access token will be valid for use in the application, in seconds.

    5. Click Next.

  3. In the Attributes step:

    1. Leave the default mapping of sub to User ID.

    2. Click Add to add another attribute.

    3. Enter an Attribute representing the deals, such as z.attr and click next to the attribute to open the Advanced Expressions modal.

    4. In the modal, enter an expression to map the deals to the attribute, such as 'Zee', and click Save.

    5. Click Next.

  4. In the Scopes step:

    1. Click Add Scope.

    2. For Scope Name, enter a name, such as z.read.

    3. (Optional) Enter a Description for the scope.

    4. Click Save.

Adding the e-Flyers Token Exchange application

Create an application to handle the token exchange requests and obtain access tokens from PingOne to send API requests to Zing. The e-Flyers Token Exchange application must use:

  • The token exchange grant type to obtain access tokens from PingOne to send API requests to Zing to retrieve the best deals

  • The application credentials in its token request because only applications can send token requests to PingOne, and custom resources can’t.

When minting these access tokens, PingOne populates the attribute claim with the value you provide (z.attr = Zee) and doesn’t include the sub claim because no user is involved (User ID is null).

Steps

  1. Go to Applications > Applications and click the icon.

  2. In the Add Application panel:

    1. For Application Name, enter e-Flyers Token Exchange.

    2. (Optional) Enter a Description for the application.

    3. Select an OIDC-based application type and click Save.

  3. On the Configuration tab:

    1. Click .

    2. For Grant Type, select Token Exchange.

    3. Leave all other default settings.

    4. Click Save.

  4. On the Resources tab:

    1. Click .

    2. Assign the resource you created in Adding Zing as a custom resource.

    3. Click Save.

  5. Provide the application credentials and custom resource credentials to your organization’s developers for the applications and custom resources, respectively.

Required configurations

The following table lists the required configurations for the applications and custom resources and includes example client IDs that correspond to the Runtime process overview:

Applications Custom resources

Zillion Deals

  • Client ID: 4076de38

  • Grant type: Client credentials

  • Scopes:

    • openid (default)

    • e.crud

e-Flyers

  • Client ID: bc82af8d

  • Audience: https://api.example.com/e

  • Scopes: e.crud

  • Attributes:

    • sub: User ID (default)

    • e.attr: Eee

e-Flyers Token Exchange

  • Client ID: b03ae60a

  • Grant type: Token exchange

  • Scopes:

    • openid (default)

    • z.read

Zing

  • Client ID: bf53b521

  • Audience: https://api.example.com/z

  • Scopes: z.read

  • Attributes:

    • sub: User ID (default)

    • z.attr: Zee

Runtime process overview

The following diagram shows a high-level overview of the example machine-to-machine interaction flow:

A diagram of the example impersonation token exchange flow.

  1. Zillion Deals sends a token request to PingOne using the client credentials grant type.

    • For client identification and authentication, Zillion Deals uses the client ID and secret defined in PingOne for Zillion Deals (client_id=4076de38).

    • Zillion Deals includes scope=e.crud in the token request.

  2. PingOne returns an access token to Zillion Deals based on the attribute mappings defined in PingOne for e-Flyers.

    The payload is decoded as follows:

    {
  "client_id": "4076de38-d226-49c8-8b47-5f8df21ef3a2", # the client ID of Zillion Deals
  "iss": "https://auth.pingone.com/6991589d-87eb-47f4-9131-284cebe106b3/as",
  "jti": "98dccaf3-44d9-47a3-ba56-9f2db0888fca",
  "iat": 1770161254,
  "exp": 1770164854,
  "aud": [
    "https://api.example.com/e" # the audience is e-Flyers
  ],
  "scope": "e.crud", # the scope of the access token
  "e.attr": "Eee",
  "env": "6991589d-87eb-47f4-9131-284cebe106b3",
  "org": "d4229c38-0f5e-4bf7-9292-9d3b0df7294c",
  "p1.rid": "98dccaf3-44d9-47a3-ba56-9f2db0888fca"
}

  3. Zillion Deals sends an API request to e-Flyers. For authorization, Zillion Deals includes the access token (from step 2) as the Authorization HTTP request header value in the API request.

  4. e-Flyers evaluates the access token and determines that:

    • The issuer of the access token is PingOne.

    • The application that requested the token is Zillion Deals.

    • The audience of the access token includes itself, e-Flyers.

  5. e-Flyers sends an introspection request to PingOne to validate the access token.

    For client identification and authentication, e-Flyers uses the client ID and secret defined in PingOne for e-Flyers (client_id=bc82af8d).

  6. e-Flyers sends a token request using the token exchange grant type to PingOne.

    • For client identification and authentication, e-Flyers uses the client ID and secret defined in PingOne for the e-Flyers Token Exchange application (client_id=b03ae60a)).

    • e-Flyers includes the following parameters in the token request:

      • scope=z.read

      • subject_token=<access token from step 3>

      • subject_token_type=urn:ietf:params:oauth:token-type:access_token

      • requested_token_type=urn:ietf:params:oauth:token-type:access_token

  7. PingOne validates the subject token for the following:

    • The subject token is a valid JWT.

    • The issuer of the subject token matches the issuer of the current PingOne environment.

  8. PingOne mints an access token based on the attribute mappings defined in PingOne for Zing.

  9. PingOne returns a token response containing an access token to e-Flyers.

    The following is the token response:

    {
    "access_token": "eyJ…", # the access token as a result of the token exchange token request
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "z.read",
    "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

    The access token is decoded as follows:

    {
  "client_id": "b03ae60a-e4f9-4e9e-ae3d-52592e61d939", # the client ID of e-Flyers Token Exchange App
  "iss": "https://auth.pingone.com/6991589d-87eb-47f4-9131-284cebe106b3/as",
  "jti": "03965dbd-6db1-40a9-92ae-7267faf7808a",
  "iat": 1770161259,
  "exp": 1770164859,
  "aud": [
    "https://api.example.com/z" # the audience is Zing
  ],
  "scope": "z.read", # the scope of the access token
  "z.attr": "Zee",
  "env": "6991589d-87eb-47f4-9131-284cebe106b3",
  "org": "d4229c38-0f5e-4bf7-9292-9d3b0df7294c",
  "p1.rid": "03965dbd-6db1-40a9-92ae-7267faf7808a"
}

  10. e-Flyers sends an API request to Zing. For authorization, e-Flyers includes the access token (from step 9) as the Authorization HTTP request header value in the API request.

  11. Zing evaluates the access token and determines that:

    • The issuer of the access token is PingOne.

    • The application requesting the token is the e-Flyers Token Exchange application.

    • The audience of the access token includes itself, Zing.

  12. Zing sends an introspection request to PingOne to validate the access token.

  13. Zing returns an API response to e-Flyers. At this point, e-Flyers as a resource server can fulfill the API request from Zillion Deals (in step 3).

  14. e-Flyers returns an API response to Zillion Deals.