PingOne Advanced Identity Cloud

Configure an "on behalf of" authentication flow for AI agents

The "on behalf of" flow allows an AI agent to perform actions on behalf of an end user, which is useful for securing the actions of digital assistants.

Task 1: Configure the OAuth 2.0 provider service

Configure the OAuth 2.0 provider service to support the grant types needed for the "on behalf of" authentication flow:

  1. In the Advanced Identity Cloud admin console, go to Native Consoles > Access Management > Services.

  2. Click the OAuth2 Provider service, then click the Advanced tab:

    • In the Grant Types field, select the Resource Owner Password Credentials and Token Exchange grant types, if they aren’t already selected.

  3. Click Save Changes.

Task 2: Create and configure a custom OAuth 2.0 application

Create and configure a custom OAuth 2.0 application with a confidential client type to act as a resource that the AI agent can access on behalf of end users.

Task 2.1: Create a custom OAuth 2.0 application

  1. In the Advanced Identity Cloud admin console, go to apps Applications, then click add Custom Application.

  2. In the Add a Custom Application modal:

    1. Click OIDC - OpenId Connect, then click Next.

    2. Click Web, then click Next.

  3. In the Application Details modal:

    1. Enter a name for the application. For example, Digital Assistant Web App.

    2. Select one or more application Owners.

    3. Click Next.

  4. In the Web Settings modal:

    1. Enter a Client ID for the application using only alphanumeric characters, dashes, or underscores. For example, digital-assistant-web-app.

    2. Enter a Client Secret and make a note of it, as you won’t be able to view it again after creating the application.

    3. Click Create Application.

  5. Follow the instructions in Configure a custom OAuth 2.0 application to configure the application you created.

Task 2.2: Configure a custom OAuth 2.0 application

  1. In the Advanced Identity Cloud admin console, go to apps Applications.

  2. Review the Applications page to find the application you want to configure.

  3. Click the applications’s ellipsis icon (more_horiz), then click edit Edit.

  4. Click the Sign On tab to configure the application’s OAuth 2.0 client:

    1. In the Grant Types field, select Resource Owner Password Credentials to add it to the existing grant types.

    2. In the Scopes field, enter the scopes that the application needs to access resources. For example, openid, read-data, write-data, and admin-action.

    3. Click Show Advanced Settings to display a vertical tab menu, then click the Authentication vertical tab.

    4. In the Token Endpoint Authentication Method field, select client_secret_post.

    5. Click Save.

Task 3: Create and configure an AI agent

Create and configure an AI agent that can access the custom OAuth 2.0 application on behalf of end users using the token exchange grant type.

Task 3.1: Create an AI agent

  1. Follow the instructions in Create an AI agent. An example name for the AI agent is Digital Assistant AI Agent, and an example client ID is digital-assistant-ai-agent. These example values are used for illustrative purposes in the following sections.

  2. Follow the instructions in Configure an AI agent to configure the AI agent you created.

Task 3.2: Configure an AI agent

  1. In the Advanced Identity Cloud admin console, go to smart_toy AI Agents.

  2. Review the AI Agents page to find the AI agent you want to configure.

  3. Click the AI agent’s ellipsis icon (more_horiz), then click edit Edit.

  4. Click the Access tab to configure the agent’s OAuth 2.0 client:

    1. Click Show Advanced Settings to display a vertical tab menu, then click the Advanced vertical tab:

    2. In the Grant Types field, enter urn:ietf:params:oauth:grant-type:token-exchange.

    3. In the Token Endpoint Authentication Method field, select client_secret_post.

    4. Click the OAuth Provider Overrides tab.

    5. Select the Enable OAuth2 Provider Overrides checkbox.

    6. Select the Use Client-Side Access & Refresh Tokens checkbox.

    7. Select the Accept Audience Parameters in Token Exchange Requests checkbox.

  5. Click the Applications tab:

    1. Click add Add Application.

    2. In the Resource field, select the custom OAuth 2.0 application you created in the previous task.

    3. Click Save.

    4. In the Subjects field, select users that the AI agent will act on behalf of or in the Subject Groups field, select groups of users that the AI agent will act on behalf of.

    5. In the Permissions field, choose one of the following approaches:

      • To limit the scopes the AI agent can request, select specific scopes. For example, read-data. This approach is recommended for "on behalf of" operations where the AI agent only needs access to a limited set of permissions.

      • To allow the AI agent to request any or all of the scopes that are assigned to the custom OAuth 2.0 application, select all scopes in this field or leave it empty. This approach might be suitable for "human-in-the-loop" workflows, where end users are required to explicitly approve high-risk or sensitive operations.

      You can also enter custom scope values that aren’t in the drop-down list by typing them into the field.

    6. Click Save.

Task 4: Test the authentication flow

Run a series of commands to get an access token for an end user and then exchange it for a new access token that represents an AI agent acting on behalf of the end user.

Task 4.1: Get an end user access token

  1. Create a user account for the end user that the AI agent will act on behalf of, if one doesn’t already exist.

  2. Get an access token for the end user using the Resource Owner Password Credentials grant type:

    $ curl \
--request POST 'https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/access_token' \(1)
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \(2)
--data-urlencode 'username=<end-user-username>' \(3)
--data-urlencode 'password=<end-user-password>' \(4)
--data-urlencode 'client_id=<oauth2-app-client-id>' \(5)
--data-urlencode 'client_secret=<oauth2-app-client-secret>' \(6)
--data-urlencode 'scope=<application-scopes>'(7)
    Show request guidance
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 The grant_type for this request is password, which represents the Resource Owner Password Credentials grant type.
    3 Replace <end-user-username> with the username of the end user that the AI agent will act on behalf of. For example, barbara.jensen.
    4 Replace <end-user-password> with the password of the end user.
    5 Replace <oauth2-app-client-id> with client ID of the custom OAuth 2.0 application you created in task 2. For example, digital-assistant-web-app.
    6 Replace <oauth2-app-client-secret> with the client secret of the custom OAuth 2.0 application.
    7 Replace <application-scopes> with some or all of the scopes you assigned to the custom OAuth 2.0 application. For example, openid. 
    {
    "access_token": "eyJ0eXAiOi...nbCv_gODEw", (1)
    "refresh_token": "eyJ0eXAiOi...1HXGCc8z0s",
    "scope": "openid",
    "token_type": "Bearer",
    "expires_in": 3599
}
    Show response guidance
    1 The access_token value in the response is the end user’s access token.

  3. Introspect the end user’s access token to verify that the sub claim represents the end user and the token contains the expected scopes:

    $ curl \
--request POST 'https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/introspect' \(1)
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=<end-user-access-token>' \(2)
--data-urlencode 'client_id=<oauth2-app-client-id>' \(3)
--data-urlencode 'client_secret=<oauth2-app-client-secret>' \(4)
    Show request guidance
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <end-user-access-token> with the end-user’s access token from the response in step 2.
    3 Replace <oauth2-app-client-id> with client ID of the custom OAuth 2.0 application. For example, digital-assistant-ai-agent.
    4 Replace <oauth2-app-client-secret> with the client secret of the custom OAuth 2.0 application. 
    {
    "active": true,
    "scope": "openid", (1)
    "realm": "/alpha",
    "client_id": "digital-assistant-web-app",
    "user_id": "2199ef22-7927-4ecf-8345-ee58df8f6328",
    "username": "2199ef22-7927-4ecf-8345-ee58df8f6328",
    "token_type": "Bearer",
    "exp": 1775741840,
    "sub": "2199ef22-7927-4ecf-8345-ee58df8f6328", (2)
    "iss": "https://<tenant-env-fqdn>:443/am/oauth2/realms/root/realms/alpha",
    "subname": "2199ef22-7927-4ecf-8345-ee58df8f6328",
    "auth_level": 0,
    "authGrantId": "zCUFAdfohd5ul06NsTienRQrCrk",
    "auditTrackingId": "c1665344-1da9-4804-b95a-de0a4013d026-550633",
    "expires_in": 3578
}
    Show response guidance
    1 The scope claim contains the application scopes that the end user can access.
    2 The sub claim contains the end user’s UUID, which indicates that the token represents the end user.

Task 4.2: Get an AI agent access token

  1. Use the Token Exchange grant type to exchange the end user’s access token for a new AI agent access token that the AI agent can use to access the custom OAuth 2.0 application on behalf of the end user:

    $ curl \
--request POST 'https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/access_token' \(1)
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \(2)
--data-urlencode 'subject_token=<end-user-access-token>' \(3)
--data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:access_token' \
--data-urlencode 'client_id=<ai-agent-client-id>' \(4)
--data-urlencode 'client_secret=<ai-agent-client-secret>' \(5)
--data-urlencode 'audience=<oauth2-app-client-id>' \(6)
--data-urlencode 'scope=<ai-agent-scopes>'(7)
    Show request guidance
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 The grant_type for this request is urn:ietf:params:oauth:grant-type:token-exchange, which represents the Token Exchange grant type.
    3 Replace <end-user-access-token> with the end user’s access token.
    4 Replace <ai-agent-client-id> with client ID of the AI agent you created in task 3. For example, digital-assistant-ai-agent.
    5 Replace <ai-agent-client-secret> with the client secret of the AI agent.
    6 Replace <oauth2-app-client-id> with the client ID of the custom OAuth 2.0 application. For example, digital-assistant-web-app. Setting this as the audience indicates that the AI agent intends to access the custom OAuth 2.0 application on behalf of the end user.
    7 Replace <ai-agent-scopes> with some or all of the scopes that you assigned to the AI agent in task 3.2, step 5e. For example, read-data. 
    {
    "access_token": "eyJ0eXAiOi...7-SnU_UoYg", (1)
    "refresh_token": null,
    "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "scope": "read-data",
    "token_type": "Bearer",
    "expires_in": 3599
}
    Show response guidance
    1 The access_token value in the response is can be used by the AI agent to access the custom OAuth 2.0 application on behalf of the end user.

  2. Introspect the AI agent’s access token to verify that the sub claim represents the end user and the act claim contains the AI agent’s client ID:

    $ curl \
--request POST 'https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/introspect' \(1)
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=<ai-agent-access-token>' \(2)
--data-urlencode 'client_id=<ai-agent-client-id>' \(3)
--data-urlencode 'client_secret=<ai-agent-client-secret>' \(4)
    Show request guidance
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <ai-agent-access-token> with the ai-agent’s access token from the response in step 1.
    3 Replace <ai-agent-client-id> with client ID of the AI agent. For example, digital-assistant-ai-agent.
    4 Replace <ai-agent-client-secret> with the client secret of the AI agent. 
    {
    "active": true,
    "scope": "read-data", (1)
    "realm": "/alpha",
    "client_id": "digital-assistant-ai-agent",
    "user_id": "2199ef22-7927-4ecf-8345-ee58df8f6328",
    "username": "2199ef22-7927-4ecf-8345-ee58df8f6328",
    "token_type": "Bearer",
    "exp": 1775741873,
    "sub": "2199ef22-7927-4ecf-8345-ee58df8f6328", (2)
    "iss": "https://<tenant-env-fqdn>:443/am/oauth2/realms/root/realms/alpha",
    "subname": "2199ef22-7927-4ecf-8345-ee58df8f6328",
    "auth_level": 0,
    "authGrantId": "e3ktYI6ggph39IdDz59pnIjZjeM",
    "act": {
        "sub": "digital-assistant-ai-agent" (3)
    },
    "auditTrackingId": "c1665344-1da9-4804-b95a-de0a4013d026-550848",
    "expires_in": 3543
}
    Show response guidance
    1 The scope claim contains the scopes that the AI agent can access.
    2 The sub claim contains the end user’s UUID, which indicates that the token represents the end user.
    3 The act claim contains a sub claim with the AI agent’s client ID, which indicates that the AI agent is acting on behalf of the end user.