Azure AI Gateway Labs
Documentation Open portal
Security & identity ยท Lab 11

Go keyless with Microsoft Entra ID and RBAC

Replace shared gateway API keys with Microsoft Entra ID tokens. Grant users, groups, apps, and managed identities an AI Gateway runtime role on all assets, a model alias, or an MCP server, call models from the playground, curl, Python, TypeScript, and C# with no secret in code, and grant management access separately with the control-plane roles.

Intermediate 45 min PortalCLIBicepCodeTerraformNotebook Updated
Notebook Source Edit

What you'll do

  • Choose between AI Gateway User, AI Gateway Models User, and AI Gateway Tools User, and pick the narrowest scope
  • Assign a runtime role in the portal, with az role assignment create, or with Bicep or Terraform
  • Acquire a token for the https://ai.gateway.azure.com resource and send it as a bearer token
  • Call a model from Python, TypeScript, and C# with DefaultAzureCredential and no API key
  • Grant management access with AI Gateway Developer, AI Gateway Contributor, or Contributor, separately from runtime access
  • Tell a 401 from a 403 and fix each one

Before you start

Tracks: Portal, Azure CLI, Bicep + azd, Code, Terraform, Notebook

A security review of your AI platform found runtime API keys in .env files, CI logs, and a shared notebook. Every key grants every model and tool on the gateway, nobody can say which person is behind a key, and rotation means chasing every team. The platform team wants callers to use their own Microsoft Entra identity instead: access granted by Azure RBAC, scoped to one model alias or MCP server when needed, and removed automatically when someone leaves a group. In this lab you grant a runtime role, call a model with an Entra token from the playground, the command line, and code, give a platform engineer management access without runtime access, and see what the gateway answers when a role is missing.

Before you begin

One-time setupThe Setup guide tasks that this lab uses. Mark each one done once, and the labs stop listing it.

Tip

On the Bicep + azd and Terraform tracks, azd up or terraform apply creates its own gateway and model and grants you the role, so you can skip this section. You need only the one-time setup above.

  • Complete Publish a Foundry model and make your first call. You need a gateway with at least one model alias.
  • Your Azure CLI sign-in in the tenant that holds the gateway.
  • Permission to create role assignments on the gateway: Owner, User Access Administrator, or Role Based Access Control Administrator. Contributor can manage the gateway but can't grant roles. If you don't have one of these, ask an administrator to run the role assignment steps for you.
  • For Grant control-plane access on the Azure CLI track, permission to register an application in Microsoft Entra ID, which most tenants give every user. Otherwise, grant the role to a teammate or a group in the portal.
  • For the Code track, one of: Python 3.9 or later, Node.js 22.18 or later, or the .NET 8 SDK or later.
  • Run the scripts and samples from the lab's folder, ~/aigateway/labs/11-entra-rbac.

You don't need an API key in this lab. Set these variables once. Every track and the Verify section reuse them.

# Name your gateway from lab 02, its model provider, and the backend model under that provider
export RG="<resource-group>"
export GATEWAY="<gateway>"
export PROVIDER="<provider-name>"          # for example foundry-models
export MODEL="<model-name>"                # the backend model name under that provider

# Read the gateway's resource ID, which role assignments use as their scope, and its runtime URL
export GATEWAY_ID="$(az aigateway show -g "$RG" -n "$GATEWAY" --query id -o tsv)"
export AI_GATEWAY_URL="https://$(az aigateway show -g "$RG" -n "$GATEWAY" --query properties.frontend.defaultHostname -o tsv)"
echo "๐Ÿ†” Gateway ID: $GATEWAY_ID"
echo "๐ŸŒ Runtime URL: $AI_GATEWAY_URL"

# Read the alias that apps send in the model field: for Foundry imports, it matches the deployment's model name
export AI_GATEWAY_MODEL="$(az aigateway model show -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" \
  -n "$MODEL" --query properties.deployment.modelName -o tsv)"
echo "๐Ÿ”– Model alias: $AI_GATEWAY_MODEL"

# Read your object ID in Microsoft Entra ID, so that you can grant yourself a role
export MY_OBJECT_ID="$(az ad signed-in-user show --query id -o tsv)"
echo "๐Ÿ‘ค Your object ID: $MY_OBJECT_ID"

# Remove any API key from your shell, to prove that nothing in this lab uses one
unset AI_GATEWAY_API_KEY
echo "๐Ÿ”‘ AI_GATEWAY_API_KEY is unset, so every call in this lab is keyless"

How it works

Access to AI Gateway crosses two trust boundaries. Inbound, your app authenticates to the gateway endpoint. Outbound, the gateway authenticates to each model or tool with its own credential, which you set up in Call backends with managed identities.

For inbound Entra access, the caller gets an access token for AI Gateway's resource, https://ai.gateway.azure.com, and sends it in the Authorization: Bearer <token> header. The gateway validates the token at its edge, then checks the caller's Azure RBAC role assignments for the model alias or MCP server in the request. Without a matching runtime role, it answers 403 before any policy or backend runs. Runtime roles grant invocation only, not gateway management. Broad assignments use the gateway's default workspace, <gateway resource ID>/workspaces/default, which the portal calls All assets.

Runtime roleRole IDGrantsAssignable at
AI Gateway Usercaad7a21-134e-43f4-a550-c5ffc17e051cList and invoke models, list and call MCP toolsDefault workspace, model alias, or MCP server
AI Gateway Models Usera6b68e3d-a1f0-4c60-8678-237c050cf4eaList and invoke modelsDefault workspace or model alias
AI Gateway Tools Userdce03f8d-857f-4e40-a90d-67770fa6ecd2List and call tools within MCP serversDefault workspace or MCP server

Managing the gateway is a separate permission, granted by the control-plane roles in Grant control-plane access: AI Gateway Developer, AI Gateway Contributor, and Contributor. None of them lets an identity invoke models or tools.

CallerToken typeScope to request
App that signs users in with MSALDelegated (on behalf of the user)https://ai.gateway.azure.com/Data.All
Service principal, managed identity, or agent identityApp-onlyhttps://ai.gateway.azure.com/.default
You, signed in to the Azure CLIDelegatedaz account get-access-token --scope https://ai.gateway.azure.com/Data.All

Policies that count by Caller identity, such as the token limits and budgets in labs 06 and 07, keep working: for Entra callers, the gateway combines the token's tenant ID (tid) and object ID (oid), so each principal gets its own counter.

Grant a runtime role

Grant yourself AI Gateway Models User on all of the gateway's assets, its default workspace. Do this once, whichever track you follow to call the gateway afterward. Role scopes are Azure resource IDs:

ScopeResource ID
All assets (default workspace)<gateway resource ID>/workspaces/default, where the gateway's resource ID is /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/aigateways/<gateway>
Model alias<gateway resource ID>/workspaces/default/aliases/<alias>
MCP server<gateway resource ID>/workspaces/default/toolServers/<mcp-server-name>

An assignment on the gateway's resource ID also works, because Azure RBAC assignments apply to the child resources.

Choose your track
1

Start a role assignment

Open the AI Gateway portal, select your gateway, and select AccessEntra IDAdd role assignment. The Add role assignments wizard has four steps: Identities, Access, Scope, and Review.

2

Select identities

On Select identities, the Users, groups, and apps tab finds users, groups, and service principals. In Search by name, email, or object ID, enter your name, your email, or your object ID, the MY_OBJECT_ID value from Before you begin. Check your account, and select Next. In production, prefer an Entra group so membership controls access. To grant an app running in Azure, open the Managed identities tab and pick its identity, filtered by Subscription and Resource type.

3

Choose access

On Choose access, What do these identities need to do? offers four options. The first three are management tasks, which you meet in Grant control-plane access:

  • Manage the gateway, Manage gateway assets, and Build with gateway assets let the identities view or change the gateway's configuration. Each has a check box that adds runtime access, AI Gateway User.
  • Invoke gateway assets only ("No control plane access.") grants a runtime role and nothing else.

Select Invoke gateway assets only, then Next.

4

Choose scope

On Choose scope, Where should this access apply? picks the runtime role. The Azure roles to assign panel shows the result:

  • All models and tools grants AI Gateway User on all assets, the default workspace.
  • All models grants AI Gateway Models User on all assets.
  • All tools grants AI Gateway Tools User on all assets.
  • Specific assets lists the model aliases and MCP servers under Resources, with each one's Authorization scope. Select one or more: an MCP server alone grants AI Gateway Tools User on that server.

Select All models, then Next.

Invoke gateway assets only, with the All models scope, assigns AI Gateway Models User.
5

Review and assign

On Review, Role assignments to create lists the identity, its type, the role, and the scope, All assets. Select Assign.

Checkpoint

Your account appears in AccessEntra ID with the AI Gateway Models User role, All assets as the resource scope, and Models as the access.

Important

Role assignments can take several minutes to apply. Until then, Entra calls return 403. Wait a few minutes and retry before you change anything else.

Call the gateway with a token

Choose your track
1

Open the playground with Entra ID

Select Catalog and pick your model. In the playground's Authentication section, set Method to Microsoft Entra ID, your signed-in identity. The other method, API key, adds an API key list with your runtime keys. The portal checks your permissions through the control plane, so you also need Microsoft.Authorization/permissions/read on the gateway, which Reader and higher roles include.

If your role doesn't apply yet, the playground says "You don't have permission to invoke this model with Entra ID. Grant access in Access > Entra ID, or ask your administrator." and disables the prompt. Wait for the role to apply and refresh the page.

2

Send a prompt

With Microsoft Entra ID selected, send In one sentence, why use Microsoft Entra ID instead of API keys?. The playground's code examples follow the authentication method you select.

Checkpoint

The model answers, and Method shows Microsoft Entra ID, not a key.

Grant control-plane access

Runtime roles let an identity call models and tools. Viewing or changing the gateway's configuration is a separate permission, which a control-plane role grants through Azure Resource Manager. Give a platform engineer or a deployment pipeline only the management role it needs, and add a runtime role only if it also calls models:

Control-plane roleRole IDGrantsAssign at
AI Gateway Developere71899cc-9858-44a9-a0e3-7b95f671540fRead the configuration of model aliases and MCP serversDefault workspace, or one model alias or MCP server
AI Gateway Contributor7c27cbcc-1723-4201-8fbc-50f2e2c24ee5Create, change, and delete model providers, models, aliases, and MCP servers, with their routing and limitsDefault workspace
Contributorb24988ac-6180-42a0-ab88-20f7382dd24cManage the gateway itself: settings, networking, identities, runtime API keys, gateway-wide policies, and exportersGateway

None of these roles lets the identity invoke models or tools, and none of them can create role assignments: that still takes Owner, User Access Administrator, or Role Based Access Control Administrator. AI Gateway Contributor can't read the gateway resource or change the gateway-wide policies on Policies, which need Contributor on the gateway.

In this section, you give a test identity, aigw-lab11-ops, AI Gateway Contributor on all assets, and check what it can and can't do.

Choose your track
1

Pick the identity

Select AccessEntra ID, then Add role assignment. On Select identities, pick who manages the gateway's assets: a teammate, an Entra group, or the aigw-lab11-ops app from the Azure CLI track. Then select Next.

2

Choose the management task

On Choose access, select Manage gateway assets ("Configure models and tools, including policies, routing, and limits, and optionally invoke them."). Azure roles to assign shows AI Gateway Contributor. Under Runtime access, leave Allow these identities to invoke models and tools cleared, so the identity can manage the assets but not call them, and select Next.

Manage gateway assets assigns AI Gateway Contributor. Leave Runtime access cleared for management only.

The other management tasks map to the other roles:

  • Manage the gateway grants Contributor on the gateway. Its check box, Also allow these identities to invoke models and tools directly, adds AI Gateway User on all assets.
  • Build with gateway assets grants AI Gateway Developer, and adds a scope step: all gateway assets, or specific model aliases and MCP servers.
3

Review and assign

On Review, Role assignments to create lists one row: the identity, AI Gateway Contributor, and the scope All assets, /workspaces/default. Select Assign. If the page then says it couldn't be loaded, select Retry.

Each row is one Azure role assignment. All assets is the gateway's default workspace.
Checkpoint

AccessEntra ID lists the identity with AI Gateway Contributor, All assets as the resource scope, and No runtime access.

The Access column shows No runtime access for control-plane roles.

Verify

Prove that access now follows the role assignment, not a key.

1

Confirm the keyless call succeeds

Run the curl call or a code sample from the previous section. It returns 200 with a reply.

2

Send a token for the wrong audience

A token for Azure Resource Manager is valid, but not for AI Gateway:

Bash
# Call the model with a token for Azure Resource Manager, the CLI's default audience, and print the status code
echo "๐Ÿšฆ Expect 401 Unauthorized, because the token is for the wrong audience:"
curl -sS -o /dev/null -w "%{http_code}\n" "${AI_GATEWAY_URL%/}/default/models/openai/v1/chat/completions" \
  -H "Authorization: Bearer $(az account get-access-token --query accessToken -o tsv)" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$AI_GATEWAY_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}]}"

The gateway answers 401: authentication failed, so the role was never checked.

3

Remove the role and try again

Remove your assignment. In the portal, select AccessEntra ID, select More actions on your row, then Remove role assignment, and confirm with Remove. With the Azure CLI, delete it wherever it is on the gateway, so it works whichever track created it:

Bash
# Delete your AI Gateway Models User role assignments (a6b68e3d-โ€ฆ) on the gateway and its assets
ROLE_IDS="$(az role assignment list --all --assignee "$MY_OBJECT_ID" \
  --role "a6b68e3d-a1f0-4c60-8678-237c050cf4ea" \
  --query "[?ends_with(scope, '/aigateways/$GATEWAY') || contains(scope, '/aigateways/$GATEWAY/')].id" -o tsv)"
# xargs passes one ID per line, the same way in Bash and zsh
echo "$ROLE_IDS" | xargs az role assignment delete --ids &&
  echo "๐Ÿšฎ Your AI Gateway Models User role assignment on $GATEWAY is deleted"

Then wait a few minutes, get a fresh token, and repeat the curl call.

The gateway now answers 403: you're authenticated, but no role allows you to invoke the model. In the playground, sending a prompt shows Request failed (403). with the same Access denied message, and View details opens the error's JSON.

4

Restore access

Assign the role again (portal, az role assignment create, or ./infra/assign-roles.sh models), wait for it to apply, and confirm the call returns 200. On the Bicep + azd track, run azd provision --no-state: azd skips a deployment when the templates and parameters haven't changed, and --no-state forces it, so the template re-creates the assignment. On the Terraform track, run terraform plan -out tfplan && terraform apply tfplan in the terraform folder: the plan notes that the assignment was deleted outside of Terraform and creates it again (Plan: 1 to add, 0 to change, 0 to destroy.).

Checkpoint

You called a model with no API key, got 401 for a token with the wrong audience, and 403 while your identity had no role.

Go further

  • Narrow the scope. Replace the assignment on all assets with AI Gateway Models User on a single alias (./infra/assign-roles.sh models "alias:<alias>"). Calls to other aliases now return 403.
  • Grant tools only. Give an agent AI Gateway Tools User on one MCP server from Federate MCP tools, so it can list and call those tools but not invoke models.
  • Run without a user. Deploy the Python sample to an Azure service with a managed identity, assign the role to that identity's principal ID, and the same code runs with app-only tokens for the .default scope. Agent identities work the same way.
  • Budget per person. Add a cost limit with Caller identity as the counter dimension and an override for one Entra identity in Enforce cost budgets. Each tid and oid pair gets its own budget.
  • See who called. In MonitoringSettings, Token claim attributes exports claims such as tid, oid, appid, and azp as azure.ai_gateway.identity.claims.<claim> attributes on logs, traces, and metrics. See Monitor usage, cost, and traces.

Clean up

Role assignments don't cost anything. Keep yours if you'll continue with Entra-based labs. Otherwise remove it, and revoke any runtime keys you no longer need in AccessAPI keys. Always remove the AI Gateway Contributor assignment and the aigw-lab11-ops app from Grant control-plane access.

Choose your track
1

Remove the role assignments

Select AccessEntra ID, and find your row with the AI Gateway Models User role. Select More actions, then Remove role assignment, and confirm with Remove. Do the same for the AI Gateway Contributor row of the identity from Grant control-plane access. If you created the aigw-lab11-ops app, delete it with the Azure CLI track.

azd down and terraform destroy don't touch your gateway from lab 02 or its role assignments, because the Bicep + azd and Terraform tracks created their own gateway. They don't delete the aigw-lab11-ops app either: delete it as in the Azure CLI track.

Next steps

Finished the lab?

Mark it complete to track your progress across paths. It's saved only in this browser.