Agent endpoint authorization in Microsoft Foundry

Agent endpoint authorization determines whether a caller can interact with an agent at runtime in Foundry Agent Service. Management access instead controls who can create, configure, update, or delete agents and other resources in the Foundry project. A principal can be allowed to call an individual agent without receiving permission to manage that agent or its project. For Foundry management access, see Authentication and authorization in Microsoft Foundry and role-based access control in Foundry.

Use this article to choose how callers authenticate and gain access to an agent endpoint. To apply these settings, see Configure agent endpoint authorization. To understand how endpoint access relates to the identities an agent uses for tools and resources, see Identity and access in Agent Service.

Endpoint access boundary

An agent endpoint is the stable URL that clients and channels use to call an agent. The endpoint can expose multiple protocols, but its authorization configuration applies at the caller-to-agent boundary.

Authorization at this boundary answers two questions:

What identity or trusted channel does the request represent?
What permission allows that identity or channel to call the agent?

Compare endpoint authorization schemes

An endpoint authorization scheme defines how Foundry validates an incoming request and decides whether the caller can interact with the agent. You can configure multiple schemes on an endpoint. For example, an endpoint can accept both Azure RBAC-authorized direct clients and agent blueprint-authorized direct clients, together with a Bot Service scheme for Microsoft Teams or Microsoft 365.

Scheme	How access is decided	Typical use
`AzureRbac` or its `Entra` alias¹	The caller presents a token for the Foundry resource, and Azure RBAC determines whether the represented principal can access the agent.	Applications, SDKs, REST clients, developer tools, and workload callers that use Foundry access.
`AgentBlueprint` (preview)	The caller presents a token for the agent's agent blueprint, and the endpoint applies the scheme's token-validation rules.	Applications that need individual agent access without granting the caller Foundry RBAC permissions.
`BotServiceRbac`²	Azure Bot Service validates the channel request, and Azure RBAC determines whether the signed-in user has access.	Microsoft Teams and Microsoft 365 channels where each user needs the applicable Azure permission.
`BotServiceTenant`²	Azure Bot Service validates the channel request and limits access to signed-in users in the configured tenant.	Microsoft Teams and Microsoft 365 channels intended for tenant-wide access.
`BotService`²	Azure Bot Service validates the channel request without an additional user authorization rule.	Legacy compatibility only. For new agents, use `BotServiceRbac` or `BotServiceTenant`.

¹ AzureRbac is the current name for the existing Entra authorization scheme. The new name distinguishes its Azure RBAC authorization behavior from other schemes that also use Microsoft Entra authentication. Existing configurations that use Entra remain supported, but don't configure both aliases on the same endpoint.

² You can configure only one of BotService, BotServiceRbac, and BotServiceTenant at a time.

API keys aren't supported for agent endpoints. Configure the authorization schemes on the agent endpoint and assign any required Azure roles at project or agent scope.

Microsoft Entra endpoint access

Both AzureRbac and AgentBlueprint use Microsoft Entra to authenticate the caller. They differ in which resource the token targets and how the endpoint authorizes access after authentication. A Microsoft Entra access token contains an audience (aud) claim that identifies the resource for which the token was issued. Each scheme accepts a different token audience and applies a different authorization rule:

AzureRbac accepts tokens issued for the Foundry resource (https://ai.azure.com) and applies Azure RBAC.
AgentBlueprint accepts tokens issued for the individual agent's agent blueprint and applies token-validation rules configured on that scheme.

You can configure both schemes on the same endpoint. The request token's audience determines which configured scheme can authorize the request.

Azure RBAC scheme

The AzureRbac scheme is the default for an agent endpoint. The client requests a token for the Foundry resource, which is identified by https://ai.azure.com. The caller must also have the Microsoft.CognitiveServices/accounts/AIServices/endpoints/interact/action permission at the Foundry project or individual agent scope. Foundry Agent Consumer is the recommended least-privilege built-in role for this permission. Foundry User also includes the permission but grants additional privileges to create and manage agents in the project.

Important

The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

Use an agent-scope assignment when a principal should call one agent without receiving broader project access. Agent-scope role assignments are evaluated for agent endpoint access and don't grant broader control-plane or management permissions.

The previous Entra scheme name has the same runtime behavior as AzureRbac. Use AzureRbac for new configurations, and retain Entra only when you need compatibility with an existing configuration or client library.

Agent blueprint scheme (preview)

The AgentBlueprint scheme accepts a token issued for the individual agent's agent blueprint instead of the shared Foundry resource. It authorizes direct runtime access without requiring the consuming principal to have a Foundry role.

A delegated client signs in the user and requests a permission exposed by the agent blueprint application registration. By default, the fully qualified delegated scope is:

api://<agent-blueprint-client-id>/access_agent

The api://<agent-blueprint-client-id> resource URI and access_agent permission name are defaults, not fixed values. If you customize either value on the agent blueprint application registration, the client requests the configured fully qualified scope.

The resulting token represents the signed-in user, identifies the client application, and targets the agent blueprint. Foundry preauthorizes supported first-party clients, such as the Foundry portal, CLI, and Visual Studio Code experiences, when it creates or updates the agent. For a customer-owned client, configure preauthorization or obtain user or administrator consent.

A confidential application can instead request an app-only token for the agent blueprint audience by using /.default. For app-only tokens, the AgentBlueprint scheme currently requires a nonempty token_validation_rules.allowed_clients list that contains the caller's application ID. If the rule is omitted or doesn't contain the caller, authorization is denied. This client allow list is the currently supported app-only authorization mechanism and doesn't require an app role.

Authorization to acquire an agent blueprint token is separate from endpoint authorization. The request must still satisfy the endpoint's token-validation rules.

Token validation rules

After Microsoft Entra validates the token, the AgentBlueprint scheme can restrict accepted audiences, tenants, client applications, principals, and delegated permissions. The service supplies audience, tenant, and delegated-permission defaults for the backing agent blueprint, while explicit rules let you narrow access for a particular agent.

For delegated tokens, preauthorization or consent controls whether the client can acquire the token, while token-validation rules control whether the endpoint accepts it. You can omit allowed_clients for delegated tokens when you don't need an additional delegated-client restriction. For app-only tokens, the required nonempty client allow list controls which applications can call the agent after token validation.

For the configuration properties, defaults, and empty-list behavior, see Configure token validation rules.

Development access to create, configure, or test agents doesn't automatically establish end-user agent blueprint access. Conversely, authorizing a client for the agent blueprint doesn't grant that client management access to the Foundry project.

Routine authorization

Routine dispatch uses a token for the Foundry audience and doesn't support the preview AgentBlueprint scheme. Keep AzureRbac or its Entra alias configured for an endpoint that a routine calls.

Bot Service channel authorization

Agents published to Microsoft Teams or Microsoft 365 use the Activity Protocol and an Azure Bot Service authorization scheme. The publishing flow normally configures the appropriate scheme. BotServiceRbac and BotServiceTenant present a sign-in prompt in the conversation so that the user can authenticate before interacting with the agent.

Use BotServiceRbac when each user needs the applicable Azure permission.
Use BotServiceTenant when users in the configured tenant can access the agent without individual Foundry RBAC assignments.
Use BotService only for legacy compatibility. It doesn't apply an additional user authorization rule.

When Azure RBAC applies

The AzureRbac and BotServiceRbac schemes apply Azure RBAC. Other schemes use a different authorization rule.

Configuration	Is Azure RBAC required?	Authorization rule
`AzureRbac` or its `Entra` alias	Yes	Delegated clients must be authorized to request the applicable Foundry permission. The caller then presents a token for the Foundry audience and must have an Azure role that permits access to the agent.
`AgentBlueprint`	No	Delegated clients must be authorized to request the configured permission. The caller then presents a token for the agent blueprint audience, which must satisfy the scheme's validation rules.
`BotServiceRbac`	Yes	The signed-in user must have an Azure role that permits access to the agent.
`BotServiceTenant`	No	The signed-in user must be in the configured tenant. This rule is a fixed tenant rule rather than a customizable rule.
`BotService`	No	No additional user authorization rule is applied after Azure Bot Service validates the channel request.

Feedback

Was this page helpful?

Last updated on 2026-10-23