Configure agent endpoint authorization in Microsoft Foundry

Configure authorization for direct clients and Azure Bot Service channels that call a Foundry Agent Service endpoint. For direct clients, configure AzureRbac, AgentBlueprint, or both. For Microsoft Teams and Microsoft 365 channels, configure the applicable Bot Service authorization through the publishing flow.

Both direct-client schemes use Microsoft Entra authentication. AzureRbac accepts tokens for the Foundry resource and applies Azure RBAC. AgentBlueprint accepts tokens for the individual agent's agent blueprint and applies token-validation rules.

For a comparison of all endpoint authorization schemes, see Agent endpoint authorization.

Prerequisites

  • A Foundry project with an existing agent.

  • The Foundry User role or another role that permits you to update the agent.

    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.

  • The project endpoint and agent name.

  • If you configure direct access for a custom client, permission to create or configure a client application registration.

  • If you configure agent blueprint access, permission to configure the agent blueprint. Being an owner on the client application registration and on the agent blueprint is one way to satisfy both permission requirements.

  • Familiarity with Agent identity concepts and Microsoft Entra endpoint access.

  • For the runtime client examples, install the packages for your language:

    • Python 3.9 or later: pip install openai azure-identity. Use openai 1.106.0 or later. The examples were tested with openai 2.46.0 and azure-identity 1.25.3.
    • .NET 8: dotnet add package OpenAI and dotnet add package Azure.Identity. The examples were tested with OpenAI 2.12.0 and Azure.Identity 1.21.0.
    • Node.js 20 or later: npm install openai @azure/identity. Use openai 5.18.0 or later. The examples were tested with openai 6.46.0 and @azure/identity 4.13.1.

Inspect the current endpoint configuration

Before you update authorization, read the complete agent configuration and save its current authorization_schemes array. An update replaces the entire array, so include every scheme you want the endpoint to retain.

  1. Send a management request for the agent:

    GET {{project_endpoint}}/agents/{{agent_name}}?api-version=v1
Authorization: ******

  2. Save the current agent_endpoint.authorization_schemes value.

  3. Record the agent's OpenAI-compatible base URL for use by the runtime client.

  4. Record any Bot Service scheme that must remain configured.

Use a token for the Foundry resource for this management request, even when the runtime endpoint accepts only the AgentBlueprint scheme.

Configure direct Microsoft Entra authorization

Configure Microsoft Entra authorization for clients that call an endpoint protocol directly. The following procedures configure the endpoint and client application for one or both supported schemes.

Configure authorization schemes

Use the following scheme or combination of schemes:

Scheme Use when Authorization requirement
AzureRbac A caller uses a token for the shared Foundry resource. The client is authorized to request the Foundry token, and the represented principal has the endpoint interaction permission through Azure RBAC.
AgentBlueprint (preview) A client uses a delegated or app-only token for the individual agent's agent blueprint. The client is authorized to request the applicable token, and the token satisfies the scheme's token-validation rules.
Both schemes You use agent blueprint access during preview or transition existing clients from Foundry access. Each direct request is authorized by the scheme that accepts the audience in its token.

Important

The AgentBlueprint scheme currently changes authorization only for direct runtime clients. Foundry development clients, routine dispatch, and Azure Bot Service integrations continue to use Foundry access. Keep AzureRbac or its Entra alias configured for any endpoint these clients use.

The endpoint URL doesn't change when you change schemes. The client changes the resource and permission for which it acquires a token.

The Entra type remains a supported alias for AzureRbac. Use AzureRbac for new configurations, retain Entra when compatibility requires it, and don't configure both aliases on the same endpoint.

Prepare the client application

A direct client needs a client application registration to acquire an access token. Prepare the client before you configure its scheme-specific permission and token request. For a transition, use the existing client application registration.

  1. Create or select a client application registration.
  2. Configure the application type, supported account types, and any redirect URI required by your application architecture.
  3. Record the tenant ID and client ID.
  4. For a confidential client, configure a certificate or federated credential. Don't store a client secret in source code.

For registration guidance, see Register an application with the Microsoft identity platform.

Configure Azure RBAC access

AzureRbac is the default authorization scheme. It applies Azure RBAC, so the represented principal needs the Microsoft.CognitiveServices/accounts/AIServices/endpoints/interact/action permission at project or individual agent scope. The Entra alias has the same runtime behavior. For more information, see Azure RBAC scheme.

Configure the endpoint

  1. Configure the AzureRbac scheme. Include any other authorization schemes that the endpoint must retain.

    PATCH {{project_endpoint}}/agents/{{agent_name}}?api-version=v1
Authorization: ******
Content-Type: application/merge-patch+json

{
  "agent_endpoint": {
    "authorization_schemes": [
      {
        "type": "AzureRbac",
        "isolation_key_source": {
          "kind": "Entra"
        }
      }
    ]
  }
}

  2. Read the agent again and confirm that the AzureRbac scheme is configured.

Authorize the client to request a Foundry token

Configure the client application to request tokens for the Foundry resource.

  1. For delegated user access, add the Foundry resource's user_impersonation delegated permission to the client application's configured API permissions.
  2. Grant consent for user_impersonation. A user can grant consent only when tenant policy permits it. Otherwise, a tenant administrator must grant consent.

Consent authorizes a delegated client to request a Foundry token for the signed-in user. An app-only client instead authenticates by using its application credential. Neither path grants the represented user or service principal access to the agent endpoint.

For client permission and consent guidance, see Configure a client application to access a web API and Application consent experience.

Call the agent with a Foundry token

Configure the OpenAI client with the agent's OpenAI-compatible base URL and a refreshable token provider for the https://ai.azure.com/.default scope. The following examples configure an interactive public client and send a request to an agent that has the Responses protocol enabled. The redirect URI must match one configured on the client application registration.

from azure.identity import (
    InteractiveBrowserCredential,
    get_bearer_token_provider,
)
from openai import OpenAI

scope = "https://ai.azure.com/.default"

credential = InteractiveBrowserCredential(
    tenant_id="<tenant-id>",
    client_id="<client-application-id>",
    redirect_uri="http://localhost",
)

token_provider = get_bearer_token_provider(
    credential,
    scope,
)

client = OpenAI(
    base_url="<agent-openai-base-url>",
    api_key=token_provider,
)

response = client.responses.create(
    input="Hello! What can you do?",
)
print(response.output_text)

Reference: InteractiveBrowserCredential, get_bearer_token_provider, and the OpenAI client.

The token provider and authentication policy acquire and refresh the token instead of storing a token in the OpenAI client's API-key configuration. For a confidential client, use a credential that supports your configured certificate or federated credential instead of an interactive credential. Don't log or persist the bearer token.

Authorize the represented principal

Assign the user or service principal represented by the token the Microsoft.CognitiveServices/accounts/AIServices/endpoints/interact/action permission at the project or individual agent scope. Use Foundry Agent Consumer as the least-privilege built-in role for callers that only interact with agent endpoints. Use Foundry User only when the principal also needs agent development or management privileges.

Configure agent blueprint access (preview)

Important

The AgentBlueprint scheme is in preview.

Configure the AgentBlueprint scheme and its token-validation rules in one endpoint update. Then authorize the client to request an agent blueprint token.

Configure the endpoint

  1. Add the AgentBlueprint scheme.

  2. Add a token_validation_rules object when you need to override or restrict the defaults. See the token validation rule reference after this procedure.

  3. Include any other authorization schemes that the endpoint must retain.

    PATCH {{project_endpoint}}/agents/{{agent_name}}?api-version=v1
Authorization: ******
Content-Type: application/merge-patch+json

{
  "agent_endpoint": {
    "authorization_schemes": [
      {
        "type": "AgentBlueprint",
        "isolation_key_source": {
          "kind": "Entra"
        },
        "token_validation_rules": {
          "allowed_audiences": [
            "<agent-blueprint-audience>"
          ],
          "allowed_tenants": [
            "<tenant-id>"
          ],
          "allowed_clients": [
            "<client-application-id>"
          ],
          "allowed_principals": [
            "<principal-object-id>"
          ],
          "required_scopes": [
            "access_agent"
          ]
        }
      }
    ]
  }
}

  4. Read the agent again.

  5. Confirm that the AgentBlueprint scheme and effective rule values are configured.

  6. Record blueprint.client_id from the agent response. This value identifies the agent blueprint.

If you omit token_validation_rules, Foundry applies the default audience and tenant values for the backing agent blueprint and requires the default access_agent delegated permission.

Token-validation rules

Each token-validation rule accepts up to 10 values. Use permission names, not fully qualified scope values, in required_scopes.

Rule Use it to Omitted or null Empty array
allowed_audiences Restrict accepted token audiences. Uses the backing agent blueprint audience. Blocks all requests.
allowed_tenants Restrict accepted tenants and issuers. Uses the backing agent blueprint tenant. Blocks all requests.
allowed_clients Restrict client application IDs. Delegated tokens have no client restriction. App-only authorization is denied because app-only tokens currently require a nonempty list. Blocks all requests.
allowed_principals Restrict user or service principal IDs. No principal restriction. Blocks all requests.
required_scopes Require delegated permission names in scp. Requires access_agent. Invalid configuration.

allowed_audiences is a runtime validation allow list. It doesn't define which resource the client requests when it acquires a token.

For delegated tokens, omit allowed_clients when you don't need an additional client restriction. When you configure the rule, a delegated client is rejected if its client ID isn't in the list. Don't use an empty list unless you intend to block all requests.

For app-only tokens, configure a nonempty allowed_clients list that contains the caller's application ID. If the rule is omitted, empty, or doesn't contain the caller, authorization is denied. This list is the currently supported app-only authorization mechanism.

Authorize the client to request an agent blueprint token

The client needs authorization to request a token for the agent blueprint. Endpoint token validation is a separate requirement.

For delegated access:

  1. Locate the agent blueprint by using blueprint.client_id from the agent endpoint configuration.

  2. Identify its resource URI and delegated permission. The generated defaults are:

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

    The resource URI and permission name can be customized. Use the values configured on the agent blueprint.

  3. Add the agent blueprint delegated permission to the client application's API permissions.

  4. Complete one of the following authorization paths for the delegated permission:

    • Preauthorize the client application on the agent blueprint. Users aren't prompted to consent.
    • Allow the user to grant consent when the client first requests the permission. This option is available only when tenant policy permits user consent.
    • Have a tenant administrator grant consent for the organization.

  5. If you use an allowed_clients rule, confirm that it includes the client application ID.

Client authorization to acquire the token and permission to call the endpoint are independent requirements. When allowed_clients is configured, an authorized client is rejected if its client ID isn't in the list. Adding a client to the list doesn't authorize it to acquire a delegated token.

For the underlying Microsoft Entra configuration, see Expose scopes in a protected web API, Application consent experience, and Grant tenant-wide admin consent.

For app-only access:

  1. Configure the confidential client with a certificate or federated credential.
  2. Configure a nonempty token_validation_rules.allowed_clients list that contains the client application ID.
  3. Request an app-only token for <agent-blueprint-audience>/.default.

The currently supported app-only authorization mechanism uses this client allow list and doesn't require an app role.

Call the agent with an agent blueprint token

Use the same OpenAI-compatible client and endpoint as the Foundry-audience path, but configure the token provider to request the fully qualified agent blueprint permission. The following examples use the generated default permission api://<agent-blueprint-client-id>/access_agent. If you customize the resource URI or permission name, use the value you configured.

from azure.identity import (
    InteractiveBrowserCredential,
    get_bearer_token_provider,
)
from openai import OpenAI

scope = "api://<agent-blueprint-client-id>/access_agent"

credential = InteractiveBrowserCredential(
    tenant_id="<tenant-id>",
    client_id="<client-application-id>",
    redirect_uri="http://localhost",
)

token_provider = get_bearer_token_provider(
    credential,
    scope,
)

client = OpenAI(
    base_url="<agent-openai-base-url>",
    api_key=token_provider,
)

response = client.responses.create(
    input="Hello! What can you do?",
)
print(response.output_text)

Reference: InteractiveBrowserCredential, get_bearer_token_provider, and the OpenAI client.

The token provider and authentication policy acquire and refresh the delegated token. For app-only access, use a credential that supports your configured certificate or federated credential and request <agent-blueprint-audience>/.default. Don't log or persist the bearer token.

Configure header-based isolation for hosted agents

This configuration applies only when a trusted middle tier calls a hosted agent and supplies an end-user identifier through the x-ms-user-identity header. For the hosted-agent isolation model and the Foundry RBAC permission required to send this header, see Isolate hosted agent sessions per user.

Set isolation_key_source.kind to Header on the scheme that authorizes the request. Authorization to supply the header depends on the scheme:

The app-only token can be issued through client credentials or managed identity. A delegated user token can't supply a header-based isolation key, even when its client application ID is listed.

The following agent_endpoint object configures a confidential middle-tier client to use header-based isolation with the AgentBlueprint scheme. Set MIDDLE_TIER_CLIENT_ID to the application ID of the caller. The same value must appear in both allow lists because each list authorizes a separate part of the request.

{
  "agent_endpoint": {
    "authorization_schemes": [
      {
        "type": "AgentBlueprint",
        "isolation_key_source": {
          "kind": "Header",
          "allowed_clients": [
            "${MIDDLE_TIER_CLIENT_ID}"
          ]
        },
        "token_validation_rules": {
          "allowed_clients": [
            "${MIDDLE_TIER_CLIENT_ID}"
          ]
        }
      }
    ]
  }
}

Transition from Azure RBAC to agent blueprint access

During the transition, configure both direct-client schemes on the endpoint: add AgentBlueprint while retaining the Azure RBAC path through AzureRbac or its Entra alias. Update each client application to request agent blueprint tokens instead of Foundry-audience tokens, and retain both schemes until every client has moved. Inspect the endpoint and inventory the client applications before you begin.

  1. Retain AzureRbac or its Entra alias and add AgentBlueprint. Configure the intended token-validation rules in the same request, and include any other authorization schemes that the endpoint must retain.

    PATCH {{project_endpoint}}/agents/{{agent_name}}?api-version=v1
Authorization: ******
Content-Type: application/merge-patch+json

{
  "agent_endpoint": {
    "authorization_schemes": [
      {
        "type": "AzureRbac",
        "isolation_key_source": {
          "kind": "Entra"
        }
      },
      {
        "type": "AgentBlueprint",
        "isolation_key_source": {
          "kind": "Entra"
        },
        "token_validation_rules": {
          "allowed_clients": [
            "<client-application-id>"
          ]
        }
      }
    ]
  }
}

  2. Read the agent and confirm both schemes, the effective validation rules, and blueprint.client_id.

  3. Follow Authorize the client to request an agent blueprint token for the existing client application.

  4. Follow Call the agent with an agent blueprint token to configure the existing client for the new token path, but don't deploy the client change yet.

  5. Verify that the existing Foundry token and the new agent blueprint token are both accepted.

  6. Update each deployed client to use the agent blueprint token.

  7. Monitor the transition until no client depends on Foundry-audience runtime access.

The endpoint remains in the dual-scheme state at the recommended stopping point for the preview. When the AgentBlueprint scheme is no longer in preview and the client rollout is complete:

  1. Update the endpoint to remove AzureRbac or its Entra alias while preserving AgentBlueprint, its validation rules, and any other authorization scheme.
  2. Verify agent blueprint access again after removing the Azure RBAC scheme.

Changing runtime schemes doesn't change the token required for agent management operations. Continue to use Foundry management access to read or update the agent.

AzureRbac or its Entra alias and AgentBlueprint can coexist with one Bot Service scheme during a transition.

Verify direct-client access

Verify the client authorization, token, and endpoint decision for each configured scheme.

  1. Acquire a token by using the configured client application:
    • For the Foundry audience, request the https://ai.azure.com/.default scope.
    • For delegated agent blueprint access, sign in a user and request the configured fully qualified permission.
  2. Call an enabled protocol on the stable agent endpoint.
  3. Confirm that the endpoint accepts the intended client and principal.
  4. Run a negative check for each explicit authorization restriction and confirm a token that doesn't match is rejected.

Configure Bot Service authorization

Publish the agent

The Microsoft Teams and Microsoft 365 publishing flow configures the Activity Protocol and the Bot Service authorization scheme that corresponds to the selected publishing scope. You can configure only one of BotService, BotServiceRbac, and BotServiceTenant at a time.

  1. Choose the publishing scope:
    • Just you in the Foundry portal, or Shared in the REST API, configures BotServiceRbac. Each signed-in user needs the applicable Azure permission.
    • People in your organization in the Foundry portal, or Tenant in the REST API, configures BotServiceTenant. The publishing request requires administrator approval in the Microsoft 365 admin center.
  2. Publish the agent by following Publish agents to Microsoft Copilot and Microsoft Teams.
  3. Read the agent again and confirm that the Activity Protocol and the expected Bot Service scheme are configured.
  4. Confirm that any AzureRbac, Entra, or AgentBlueprint scheme required for direct clients remains in authorization_schemes.
  5. For BotServiceRbac, assign each user the Azure permission required to interact with the agent. Foundry Agent Consumer is the least-privilege built-in role for users who don't need development or management access.

Publishing can replace a different Bot Service scheme. Republish with the intended scope when you need to change between BotServiceRbac and BotServiceTenant. Use BotService only for legacy compatibility.

Verify Bot Service channel access

  1. Open the published agent in Microsoft Teams or Microsoft 365.
  2. Send a message and complete the in-conversation sign-in when prompted.
  3. For BotServiceRbac, verify access with a user who has the required Azure permission and confirm that a user without the permission is rejected.
  4. For BotServiceTenant, verify access with a user in the configured tenant and confirm that a user outside the tenant is rejected.

Related content

  • Last updated on