Edit

Share via

Agent OAuth flows: On behalf of flow

Agents (agent identity blueprints) operating on behalf of regular, signed-in users use the standard OAuth 2.0 protocol with all its capabilities. User delegation enables agent identities to operate on behalf of signed-in users using standard OAuth 2.0 On-Behalf-Of flows with agent-specific impersonation. The agent identity is assigned the necessary delegated permissions needed for OBO access. It requires consent from users to access their data.

Agents have the capabilities of Microsoft Entra ID resource (API) applications and support the API attributes required for the (OAuth2Permissions, AppURI). Agents can’t use any OBO flows. Redirect URIs aren't supported.

Warning

Microsoft recommends using the approved SDKs like Microsoft.Identity.Web and Microsoft Agent ID SDK libraries to implement these protocols. Manual implementation of these protocols is complex and error-prone, and using the SDKs helps ensure security and compliance with best practices.

Managed identities integration

Managed identities are the preferred credential type. In this configuration, the managed identity token serves as the credential for the parent agent identity blueprint, while standard MSI protocols apply for credential acquisition. This integration allows the agent ID to receive the full benefits of MSI security and management, including automatic credential rotation and secure storage.

Protocol steps

Agents aren't supported for OBO (/authorize) flows. Supported grant types are client_credential, jwt_bearer, and refresh_token. The flow involves the agent identity blueprint, agent identity, and a client credential. The client credential can be a client secret, a client certificate, or a managed identity used as Federated Identity Credential (FIC).

Diagram showing the illustration of on-behalf-of token acquisition flow for agents.

  1. The user authenticates with the client and obtains a user access token (client token, Tc).

  2. Client sends the user access token (Tc) to the agent identity blueprint to act on behalf of the user. It's the token that is used for the OBO exchange for the agent identity blueprint.

  3. The agent identity blueprint requests an exchange token by presenting its client credential (secret, certificate, or managed identity token (TUAMI)). In this example, we use a managed identity as FIC. Microsoft Entra ID returns token T1 to the agent.

    Warning

    Client secrets shouldn't be used as client credentials in production environments for agent identity blueprints due to security risks. Instead, use more secure authentication methods such as federated identity credentials (FIC) with managed identities or client certificates. These methods provide enhanced security by eliminating the need to store sensitive secrets directly within your application configuration.

    POST /oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=AgentBlueprint
&scope=api://AzureADTokenExchange/.default
&fmi_path=AgentIdentity
&client_assertion=TUAMI
&grant_type=client_credentials

    Where TUAMI is the managed identity token for user assigned managed identity (UAMI). This step returns T1.

  4. The agent identity, a child of the agent identity blueprint, sends an OBO token exchange request. This request includes both T1 and the user access token Tc.

    POST /oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=AgentIdentity
&scope=https://resource.example.com/scope1
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={T1}
&grant_type=urn:ietf:params:oauth:grant-type:jwt_bearer
&assertion={Tc(aud=AgentIdentity Blueprint, oid=User)}
&requested_token_use=on_behalf_of

  5. Microsoft Entra ID returns the resource token after validating both the T1 and Tc. The OBO protocol requires token audience to match the client ID:

    • T1 (aud) == Agent identity Parent app == Agent identity blueprint client ID
    • Tc (aud) == Agent identity blueprint client ID

Sequence diagram

The following sequence diagram shows the OBO flow

Diagram showing the token sequence of on-behalf-of token acquisition flow for agents.

Refresh token support

Refresh token can be used for asynchronous scenarios and background processes:

POST /oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=AgentIdentity
&scope=https://resource.example.com/scope1
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion={T1}
&grant_type=refresh_token
&refresh_token={AgentIdentityRefreshToken}

Permission inheritance

Agent identities can inherit delegated permissions from their parent agent identity blueprint when the InheritDelegatedPermissions property is enabled. This inheritance mechanism reduces consent complexity for multi-instance scenarios by allowing agent identities to use permissions already granted to their parent application. The inheritance functionality applies specifically when FIC impersonation is used and enables efficient permission management across multiple instances. However, inheritance works only within tenant boundaries, ensuring that permission scope remains contained within appropriate organizational limits.

Related content

  • Last updated on