PingAM

AI agents

AI agents are specialized OAuth 2.0 identities that securely perform tasks on behalf of end users through a delegated token exchange process, ensuring distinct accountability and granular access control.

You can use AI agents to securely build digital assistants that operate on behalf of end users, such as a chatbot on a retail website helping a user navigate products, or an internal workforce assistant acting on behalf of an employee to access enterprise tools like Salesforce.

Token delegation

Using OAuth 2.0 token exchange, an AI agent can swap an existing access token for a new, constrained, delegation token that encodes both the original subject and the acting agent. The AI agent can then complete tasks on behalf of a user or another agent, with scopes and audiences controlled by the authorization server.

Common use cases

  • Automated operations: Use an AI agent to handle routine high-volume tasks, such as triaging tickets or provisioning access.

  • Digital assistants: Use AI agents to search products, manage preferences, or place orders.

How to use an AI agent

To use an AI agent, you must first complete these steps:

Once registered, you can use the AI agent like an OAuth 2.0 machine identity. For example:

Enable AI agents

In AM, AI agents are switched off by default.

To enable AI agents:

  1. In the AM admin UI, set the advanced property org.forgerock.am.oauth2.aiagents.enabled to true, and save your changes.

  2. Enable AI agents in the OAuth 2.0 provider.

    1. In the AM admin UI, go to Realms > realm name > Services.

    2. Create an OAuth 2.0 provider service if one doesn’t exist already.

    3. On the OAuth 2.0 provider page, select the AI Agents tab, and select Enable AI Agents.

    4. Save your changes.

    5. Refresh the UI for the changes to apply.

  3. Go to Applications > OAuth 2.0 and verify that AI Agents appears as the last item in the menu.

Register an AI agent in the UI

Use the AI agents UI to onboard an AI agent, configure its standard OAuth 2.0 properties as a specialized OAuth 2.0 client, update, or delete an agent.

To create an AI agent:

  1. Go to Applications > OAuth 2.0 > AI Agents and click + Add AI Agent.

  2. Provide values for Client ID, Client secret, Redirection URIs, Scope(s), and Default Scope(s), and click Create.

  3. Configure the AI agent properties as required and save your changes.

    Find out more about standard OAuth 2.0 client properties in Client application registration.

Register an AI agent dynamically

Use dynamic client registration (DCR) when you want to use automation or agents to onboard themselves.

  1. Enable DCR in the provider:

    1. In the AM admin UI, go to Realms > realm name > Services > OAuth2 Provider.

    2. On the Client Dynamic Registration tab, enable Allow Open Dynamic Client Registration.

    3. Save your changes.

  2. Configure your webserver to map the DCR endpoint to appear under the authorization server metadata. This complies with RFC 8414.

    For example, for an Apache Tomcat deployment:

    1. Edit the server.xml to add the mapping:

      <Valve className="org.apache.catalina.valves.rewrite.RewriteValve" /> to /Server/Service/Engine/Host

    2. Create a file called rewrite.config and place it under CATALINA_HOME/conf/Catalina/localhost/.

    3. Add the following mapping to rewrite.config:

      RewriteRule ^/\.well-known/oauth-authorization-server$ /am/oauth2/realms/root/.well-known/oauth-authorization-server/aiagent [L]

    4. Save your changes.

    5. Restart Tomcat.

    You can verify the AI agent registration URL by calling the well-known authorization server endpoint and reading the registration_endpoint value, for example:

    $ curl https://am.example.com:8443/am/oauth2/realms/root/.well-known/oauth-authorization-server/aiagent
{
  "…​": "…​",
  "registration_endpoint": "https://am.example.com:8443/am/oauth2/aiagent/register",
  "…​": "…​"
}

  3. To register an agent, you can now post a DCR request to the AI agent endpoint:

    For example:

    $ curl \
--request POST \
--header "Content-Type: application/json" \
--data "grant_type=client_credentials" \
--data "client_id=My AI Agent" \
--data "client_secret=client_secret" \
--data "scope=read" \
'https://am.example.com:8443/am/oauth2/realms/root/aiagent/register'
    You can use DCR scripting to run extra checks and processes before and after the agent registration.