PingOne

Managing AI agents

Use the AI Agents page to add and edit artificial intelligence (AI) agents to be managed by PingOne. Learn more in AI Agents.

Adding an AI agent

Add an AI agent to register the agent with a unique identity and manage its authentication settings and access to resources.

Steps

  1. In the PingOne admin console, go to AI Agents and click the icon.

  2. Enter the following:

    • Name: A unique identifier for the AI agent.

    • Description (optional): A brief description of the agent, such as Retail Chatbot or Workforce Assistant.

    • Icon (optional): A graphic representation of the AI agent. Use a file up to 1 MB in JPG, JPEG, GIF, or PNG format.

  3. Click Save.

Next steps

Complete the configuration steps in Editing an AI agent.

Editing an AI agent

Edit an AI agent to configure its authentication settings and access to resources.

Steps

  1. In the PingOne admin console, go to AI Agents and browse or search for the AI agent you want to edit.

  2. Click the AI agent entry to open the details panel.

  3. On the Overview tab, click the Pencil icon () and enter or edit the following:

    Field Description

    Name

    The name for the AI agent.

    Description

    A brief description of the AI agent.

    Icon

    A graphic representation of the AI agent. Use a file up to 1 MB in JPG, JPEG, GIF, or PNG format.

  4. Click Save.

  5. On the Configuration tab, click and enter or edit the following:

    Field Description

    Response Type

    Select Code, Access Token, or ID Token for the response type.

    Grant Type

    Select Authorization Code, Implicit, Client Credentials, CIBA, Device Authorization, Refresh Token, or Token Exchange for the grant type.

    Learn more in Grant types.

    PKCE Enforcement

    Select a value for PKCE code challenge enforcement. This value determines how the AI agent creates the code challenge from the code verifier.

    Learn more in PKCE enforcement.

    Refresh Token configuration

    Select this option to enable the Refresh Token grant type. You can specify the following:

    Refresh Token Format

    The type of refresh token PingOne issues for the AI agent in exchange for an expired access token:

    • Opaque Token: Contains a unique, unreadable string and doesn’t require a digital signature. This will be the only refresh token type issued after March 1, 2027.

    • JSON Web Token: Contains claims and information about the user’s authentication status, and requires a digital signature. This option is only available until March 1, 2027, after which it will be deprecated.

    Learn more about the timeline for JWT deprecation in Refresh tokens.

    Refresh Token Duration

    The lifetime of the refresh tokens. The default value is 30 days. Valid values are between 60 seconds and 1826 days (for Opaque Token).

    Refresh Token Rolling Duration

    How long the AI agent can use the refresh token grant type to obtain a new access token and a new refresh token after the most recent user authentication event. The default value is 180 days. Valid values are between 60 seconds and 1826 days (for Opaque Token).

    Refresh Token Rolling Duration must be longer than or equal to the Refresh Token Duration.
    Refresh Token Rolling Grace Period

    The amount of time that a rolled refresh token remains valid if the client failed to receive an updated one during a roll. Valid values are between 0 and 86,400 seconds (24 hours). A value of 0 means that a refresh token becomes invalid after it’s rolled.

    Redirect URIs

    The address to which PingOne forwards the OIDC response after authentication.

    The Redirect URI can’t contain a fragment component, such as #somedata. Learn more in Redirection endpoint in the IETF documentation.

    Allow Redirect URI Patterns

    Use a wildcard for flexibility in managing redirect URIs. Learn more in Redirect URIs.

    Token Endpoint Authentication Method

    Select one of the following:

    • None

    • Client Secret Basic

    • Client Secret Post

    • Client Secret JWT

    • Private Key JWT

    Learn more in Token endpoint authentication methods.

    Require Pushed Authorization Request

    Require the AI agent to send its authorization requests directly to PingOne without going through the browser. Requiring this can safeguard sensitive information from end-user devices. If Require Pushed Authorization Request isn’t selected, the AI agent can send plain authorization requests or pushed authorization requests. Learn more in Pushed authorization requests.

    Pushed Authorization Request Reference Timeout

    Specify how long the pushed authorization request should be valid. The default value is 60 seconds.

    Additional Refresh Token Replay Protection

    Outside of the optional rolling grace period, refresh tokens are intended for one-time use. For increased security, enable this option so that PingOne can invalidate both access and refresh tokens when a refresh token is reused. Learn more in Refresh token rotation.

    Initiate Login URI

    The AI agent’s login initiation endpoint for third parties to begin the sign-on process.

    If provided, PingOne redirects users to this URI to initiate sign-on (SSO) to PingOne. The AI agent is responsible for implementing the relevant OIDC flow when the Initiate Login URI is requested.

    Learn more in Initiating Login from a Third Party in the OIDC specification. This URI is required if you want the AI agent to show in the PingOne application portal. Learn more in Application portal.

    Target Link URI

    The URI for the AI agent. If provided, PingOne redirects AI agent users to this URI after the user is authenticated.

    Signoff URLs

    The URLs to which the browser can be redirected after user signs off from the AI agent.

    If you include a post_logout_redirect_uri query parameter in the /signoff request, with the same value that was set in the AI agent, the browser will redirect the user to the matching URL.

    Request Parameter Signature Requirement

    Specify how the AI agent sends the optional request parameter in its authorization requests.

    Click Compare Options for a description of the different settings.

    • Default: Allow the AI agent to send authorization requests with or without the request parameter. If using the request parameter, the AI agent must include a digital signature.

    • Require signed request parameters: Requires the AI agent to use the request parameter and include a digital signature of it in its authorization requests.

    • Allow unsigned request parameters: Allows the AI agent to send authorization requests with or without the request parameter. If using the request parameter, including a digital signature is optional for the AI agent.

    Learn more in Request Parameter Signature Requirement.

    Token Header Options

    Select Include the x5t parameter in the header of access tokens, ID tokens, and JWT-based refresh tokens if the AI agent, custom resource, or both require the x5t parameter in the digital signature verification process. The x5t parameter acts as a fingerprint for the X.509 certificate and provides increased security by identifying the specific key used to sign the token.

    ID Token Duration

    The lifetime of the ID token. A duration of 1 hour or less is recommended.

    PingOne API Access Token Duration

    The lifetime of the PingOne API access token. A duration of 1 hour or less is recommended. This setting is applicable only if this AI agent is allowed to request PingOne API scopes.

    OpenID Connect Session Management

    Facilitate OIDC session management by allowing AI agents in the same browsing mode, such as private or normal browsing mode, to monitor the PingOne user session. Only AI agents running in the same browsing mode can monitor the PingOne user session.

    To use this option, your PingOne environment must be configured with a custom domain, such as sso.example.com, and the AI agents must be accessible under that domain. For example, apps.example.com/app1 and apps.example.com/app2 or app1.example.com and app2.example.com. Learn more in Setting up a custom domain.

    When enabled, the session_state parameter is included in the PingOne authorization response with the session status, such as unchanged, changed, or error. Learn more in OIDC session management in the PingOne API documentation and Best practices: Session management.

    • The default idle timeout is 30 days. To set a shorter idle timeout of fewer than 30 days:

      1. Build a PingOne DaVinci flow that includes the Return Success Response (Redirect Flows) node from the PingOne Authentication connector.

      2. In the Return Success Response (Redirect Flows) node, set the Idle Timeout value to the desired amount of time, such as 5 minutes.

      3. Assign the flow to the applicable AI agents.

    • If a user session is deleted because of a PingOne session API request or is purged by the system, it doesn’t trigger a changed response.

    Request scopes to access multiple resources

    Enable this option to allow the AI agent to request scopes from multiple custom resources in a single request.

    To use this option, any custom resources that the AI agent requests access to must have the following configurations across all requested custom resources:

    • Overview tab: Access token time to live must be set to the same value.

    • Attributes tab: The mapping configuration of the sub attribute must be the same.

    • Attributes tab: Any other attribute using the same name in multiple custom resources must have the same mapping configurations.

    • Scopes tab: The scope names must be unique so that PingOne can determine which custom resource and associated scope that the AI agent is attempting to access.

    • Permissions tab: For environments with PingOne Authorize, permissions names must be unique if Include user permissions in access tokens is enabled.

    If any of these configurations aren’t consistent across the requested custom resources, the request results in an error.

    Terminate User Session by ID Token

    Enable this option to allow the AI agent to send requests for PingOne to terminate end-user sessions at the /idpSignoff endpoint using only the ID token.

    The audience claim value in the ID token must match the client ID of the AI agent so that PingOne can identify the session to be terminated. The AI agent isn’t required to have access to the session token cookie.

    Learn more in the PingOne API documentation.

    CORS Settings

    Specifies the CORS options for the AI agent. Learn more in Cross-origin resource sharing.

    • Allow any CORS-safe origin (default): Allows the AI agent to access resources from a domain that is CORS-safelisted, according to the Fetch specification.

    • Allow specific origins: Allows the AI agent to access resources from a specific domain.

      • Allowed origins: Specifies the allowed origin domains for CORS. You can specify a domain pattern or a valid IPv4 address. If you use a domain pattern, you can specify one wildcard to match incoming requests.

        You can’t use the wildcard on the domain name.

        For example, the following search patterns are valid:

        • https://*.test.com

        • https://www.app*.test.com

        The following patterns are not valid:

        • https://test*.com

        • https://www.app.test*.com

    • Disallow all origins: Don’t allow the AI agent to access resources from a cross-origin domain.

    After you make changes to the CORS Settings, it can take several minutes for the new settings to take effect, due to time-to-live configuration on the resource.

  6. On the Resources tab, click and select the checkboxes to add appropriate OAuth scopes for the AI agent. Click the Selected scopes tab to see the scopes that are currently selected for the AI agent.

    The OAuth scopes determine the resources that the AI agent can access. If you add OIDC scopes here, the AI agent inherits the attributes associated with that scope.

    If the AI agent uses the refresh token grant type, add the offline_access scope to enable the AI agent to request a refresh token from PingOne on a per-request basis. For example, when the AI agent needs a refresh token, it includes the offline_access scope in its request, and PingOne includes a refresh token in its token response. However, when the AI agent doesn’t need a refresh token, it doesn’t include the scope in the request, and PingOne therefore doesn’t include a refresh token in its token response.

    If the offline_access scope is not added to an AI agent that uses the refresh token grant type, PingOne always includes a refresh token in its token response, whether the AI agent needs a refresh token or not.

    To customize the lifetime of access tokens for AI agents, you must configure a custom resource, set the desired access token lifetime, and then add those scopes to the AI agent. Learn more in Customizing access token lifetime.

  7. On the Policies tab, click and select the authentication policies for the AI agent.

    If you have a DaVinci license, you can select PingOne policies or DaVinci flow policies, but not both. If you don’t have a DaVinci license, you’ll see PingOne policies only.

    To add one or more PingOne authentication policies, click the PingOne Policies tab. If the AI agent was previously configured with one or more DaVinci flow policies, click Deselect all other Policies to remove them from the AI agent, then select the PingOne authentication policies you want to apply to the AI agent. PingOne authentication policies are applied in the order in which they appear in the list. Click the Selected PingOne Policies tab, reorder the policies as needed, then click Save.

    To add one or more DaVinci flow policies, click the DaVinci Policies tab. If the AI agent was previously configured with one or more PingOne authentication policies, click Deselect all other Policies to remove them from the AI agent, then select the DaVinci flow policies you want to apply to the AI agent. PingOne applies the first DaVinci flow policy in the list. Click the Selected DaVinci Policies tab, reorder the policies as needed, then click Save.

    For OAuth-based AI agents, you can specify another policy in the acr_values parameter in the authorization request. The acr_values parameter specifies the sign-on policies that PingOne should use for authentication. You can include any policies assigned to the AI agent. Specify either a single DaVinci policy by flow policy ID or one or more PingOne policies by name, separated by spaces or the encoded space character %20. For example, acr_values=d1210a6b0b2665dbaa5b652221badba2 or acr_values=Single_Factor%20Multi_Factor.

    Learn more in Authentication policies for applications.

  8. Click Save.

  9. On the Attribute Mappings tab, click , select a PingOne user attribute, and map it to an attribute in the AI agent that you’re adding.

    Learn more in Customizing OIDC attributes for an application.

    1. Enter an AI agent attribute and then select the corresponding PingOne attribute in the list.

    2. Click the Gear icon () to use the expression builder to build an attribute mapping.

      Learn more in Using the expression builder.

  10. Click Save.

  11. On the Access tab, click and enter or edit the following:

    Field Description

    Application Portal Display

    Determines whether an AI agent icon appears in the application portal, even if the user would see the AI agent in the application portal based on the group membership policy. Learn more in Application access control.

    Admin Only Access

    Specifies that a user with an administrator role is required to access the application. The user must have one of the following roles:

    • Organization Admin

    • Environment Admin

    • Identity Data Admin

    • Client Application Developer

    Group Membership Policy

    Select the group membership policy for the AI agent. Learn more in Groups.

  12. Click Save.

  13. (Optional) For workforce MFA use cases, to connect the AI agent to your PingFederate instance, download the AI agent properties file and upload it to the relevant PingID adapter instance in PingFederate.

    Learn more in Configuring a PingID adapter instance.

  14. Click Save.

  15. To enable the AI agent, click the toggle at the top of the details panel to the right (blue).

    You can disable the AI agent by clicking the toggle to the left (gray).

    If you selected Response Type = Code and Grant Type = Authorization Code, there is also an Integrate tab that you can use to test your configuration. Generate code snippets from this tab and copy them into a web application so that you can ensure that the authorization and authentication configuration is working as intended.

    Learn more in Integrate PingOne with a Node.js Express app and Integrate Ping SDK for JavaScript with PingOne.