PingOne Advanced Identity Cloud

Configure an autonomous AI agent flow

The autonomous AI agent flow lets an AI agent act independently, without requiring an end user to be present. The agent obtains its own access token using the Client Credentials grant type and then exchanges it for a scoped token that it can use to access a specific application. This is useful for automated pipelines, background tasks, and other scenarios where an AI agent acts on its own behalf rather than on behalf of an end user.

The following instructions use an example scenario of an AI agent that analyzes a web server’s access logs for bot traffic. The AI agent needs to access the web server’s logs API autonomously, to read and search the logs for indicators of bot traffic.

Task 1: Configure the OAuth 2.0 provider service

Configure the OAuth 2.0 provider service to support the grant types needed for the autonomous agent 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 Client 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 autonomously.

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 Service, then click Next.

  3. In the Application Details modal:

    1. Enter a name for the application. For example, Web Server Logs API App.

    2. Select one or more application Owners.

    3. Click Next.

  4. In the Service Settings modal:

    1. Enter a Client ID for the application using only alphanumeric characters, dashes, or underscores. For example, web-server-logs-api-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, then click it.

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

    1. In the Scopes field, enter the scopes that the application needs to access resources. For example, logs-read and logs-search.

    2. Click Save.

Task 3: Create and configure an AI agent

Create and configure an AI agent that can autonomously access the custom OAuth 2.0 application.

Task 3.1: Create an AI agent

  1. Follow the instructions in Create an AI agent. An example name for the AI agent is Bot Traffic Analyzer Agent, and an example client ID is bot-traffic-analyzer-agent.

  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, then click it.

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

    1. Click Show Advanced Settings to display a vertical tab menu. The Core vertical tab is selected by default.

    2. In the Scopes field, enter the scopes the agent needs for basic operations. For example, monitor-system.

    3. Click the Advanced vertical tab:

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

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

    4. Click the OAuth Provider Overrides vertical tab:

      1. Select the Enable OAuth2 Provider Overrides checkbox.

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

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

  4. 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. Leave the Subjects and Subject Groups fields empty, because the AI agent acts autonomously rather than on behalf of a specific user.

    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, logs-read and logs-search. This approach is recommended when you want to apply least privilege to the agent’s access.

      • To allow the AI agent to request any or all of the scopes assigned to the custom OAuth 2.0 application, select all scopes or leave the field empty.

    6. Click Save.

Task 4: Test the authentication flow

Run a series of commands to get an access token for the AI agent and then exchange it for a scoped token the agent can use to access the custom OAuth 2.0 application autonomously.

Task 4.1: Get an AI agent access token

  1. Get an access token for the AI agent using the Client 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=client_credentials' \(2)
--data-urlencode 'client_id=<ai-agent-client-id>' \(3)
--data-urlencode 'client_secret=<ai-agent-client-secret>' \(4)
--data-urlencode 'scope=<ai-agent-scopes>'(5)
    Show request guidance
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 The grant_type for this request is client_credentials, which represents the Client Credentials grant type.
    3 Replace <ai-agent-client-id> with the client ID of the AI agent you created in task 3. For example, bot-traffic-analyzer-agent.
    4 Replace <ai-agent-client-secret> with the client secret of the AI agent.
    5 Replace <ai-agent-scopes> with one or more of the scopes you assigned to the AI agent. For example, monitor-system. 
    {
    "access_token": "eyJ0eXAiOi...jARmOdTatY", (1)
    "scope": "monitor-system",
    "token_type": "Bearer",
    "expires_in": 3599
}
    Show response guidance
    1 The access_token value in the response is the AI agent’s access token.

  2. Introspect the AI agent’s access token to verify the claims contain the expected values:

    $ curl -G \
--request GET 'https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/tokeninfo' \(1)
--data-urlencode 'access_token=<ai-agent-access-token>'(2)
    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. 
    {
    "sub": "bot-traffic-analyzer", (1)
    "cts": "OAUTH2_STATELESS_GRANT",
    "auditTrackingId": "a910ad63-6b82-48d9-935c-52e962266243-276314",
    "subname": "bot-traffic-analyzer",
    "iss": "https://<tenant-env-fqdn>:443/am/oauth2/realms/root/realms/alpha",
    "tokenName": "access_token",
    "token_type": "Bearer",
    "authGrantId": "C3ca_i8hU6...ODXFTX-cEc",
    "client_id": "bot-traffic-analyzer",
    "access_token": "eyJ0eXAiOi...jARmOdTatY",
    "aud": "bot-traffic-analyzer", (2)
    "nbf": 1778764699,
    "grant_type": "client_credentials",
    "scope": [
        "monitor-system" (3)
    ],
    ...
}
    Show response guidance
    1 The sub claim contains the AI agent’s client ID, which indicates that the token represents the agent.
    2 The aud claim contains the AI agent’s client ID, which indicates that the intended audience of this access token is the agent.
    3 The scope claim contains the scopes that the AI agent can access.

Task 4.2: Exchange the AI agent token for application access

  1. Use the Token Exchange grant type to exchange the AI agent’s access token for a new token scoped to the custom OAuth 2.0 application:

    $ 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=<ai-agent-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=<exchanged-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 <ai-agent-access-token> with the AI agent’s access token from task 4.1.
    4 Replace <ai-agent-client-id> with the client ID of the AI agent. For example, bot-traffic-analyzer-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, web-server-logs-api-app. Setting this as the audience indicates that the AI agent intends to use the exchanged access token to access the custom OAuth 2.0 application.
    7 Replace <exchanged-scopes> with the scopes that the AI agent needs to access the application. For example, logs-read logs-search. 
    {
    "access_token": "eyJ0eXAiOi...83ZuC6fSnw", (1)
    "refresh_token": null,
    "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "scope": "logs-read logs-search",
    "token_type": "Bearer",
    "expires_in": 3599
}
    Show response guidance
    1 The access_token value in the response is the scoped token that the AI agent can use to access the custom OAuth 2.0 application autonomously.

  2. Introspect the exchanged token to verify the claims contain expected values:

    $ curl -G \
--request GET 'https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/tokeninfo' \(1)
--data-urlencode 'access_token=<exchanged-access-token>'(2)
    Show request guidance
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <exchanged-access-token> with the exchanged access token from the response in step 1. 
    {
    "sub": "bot-traffic-analyzer", (1)
    "cts": "OAUTH2_STATELESS_GRANT",
    "auditTrackingId": "a910ad63-6b82-48d9-935c-52e962266243-285038",
    "subname": "bot-traffic-analyzer",
    "iss": "https://<tenant-env-fqdn>:443/am/oauth2/realms/root/realms/alpha",
    "tokenName": "access_token",
    "token_type": "Bearer",
    "authGrantId": "wnqUfLhio1...i38m44oycg",
    "client_id": "bot-traffic-analyzer",
    "access_token": "eyJ0eXAiOi...83ZuC6fSnw",
    "aud": [
        "bot-traffic-analyzer", (2)
        "access-log-api" (2)
    ],
    "nbf": 1778767385,
    "act": {
        "sub": "bot-traffic-analyzer" (3)
    },
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "scope": [
        "logs-search", (4)
        "logs-read" (4)
    ],
    ...
}
    Show response guidance
    1 The sub claim contains the AI agent’s client ID, which indicates that the token represents the agent acting autonomously.
    2 The aud claim contains the client ID of the AI agent and the custom OAuth 2.0 application, which indicates that the intended audience of this access token is both the agent and the application.
    3 The act claim also contains the AI agent’s client ID. In an autonomous flow, both sub and act are the agent’s identity, in contrast to the "on behalf of" flow where sub is the end user and act is the agent.
    4 The scope claim contains the scopes that the AI agent can access on the application.