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.
- Choose where to run commandsEvery track except the portal
- Sign in to AzureOn your own machine. Cloud Shell is already signed in.
- Install the
aigatewayextensionThe Azure CLI tracks and the Verify steps - Clone the labs repoThe Bicep + azd and Terraform tracks, the notebooks, and the code samples
You've done the one-time setup that this lab uses.
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"# Name your gateway from lab 02, its model provider, and the backend model under that provider
$RG = "<resource-group>"
$GATEWAY = "<gateway>"
$PROVIDER = "<provider-name>" # for example foundry-models
$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
$GATEWAY_ID = az aigateway show -g $RG -n $GATEWAY --query id -o tsv
$env:AI_GATEWAY_URL = "https://$(az aigateway show -g $RG -n $GATEWAY --query properties.frontend.defaultHostname -o tsv)"
Write-Host "๐ Gateway ID: $GATEWAY_ID"
Write-Host "๐ Runtime URL: $env:AI_GATEWAY_URL"
# Read the alias that apps send in the model field: for Foundry imports, it matches the deployment's model name
$env:AI_GATEWAY_MODEL = az aigateway model show -g $RG --gateway-name $GATEWAY --provider-name $PROVIDER `
-n $MODEL --query properties.deployment.modelName -o tsv
Write-Host "๐ Model alias: $env:AI_GATEWAY_MODEL"
# Read your object ID in Microsoft Entra ID, so that you can grant yourself a role
$MY_OBJECT_ID = az ad signed-in-user show --query id -o tsv
Write-Host "๐ค Your object ID: $MY_OBJECT_ID"
# Remove any API key from your session, to prove that nothing in this lab uses one
Remove-Item Env:AI_GATEWAY_API_KEY -ErrorAction SilentlyContinue
Write-Host "๐ AI_GATEWAY_API_KEY is removed, 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 role | Role ID | Grants | Assignable at |
|---|---|---|---|
| AI Gateway User | caad7a21-134e-43f4-a550-c5ffc17e051c | List and invoke models, list and call MCP tools | Default workspace, model alias, or MCP server |
| AI Gateway Models User | a6b68e3d-a1f0-4c60-8678-237c050cf4ea | List and invoke models | Default workspace or model alias |
| AI Gateway Tools User | dce03f8d-857f-4e40-a90d-67770fa6ecd2 | List and call tools within MCP servers | Default 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.
| Caller | Token type | Scope to request |
|---|---|---|
| App that signs users in with MSAL | Delegated (on behalf of the user) | https://ai.gateway.azure.com/Data.All |
| Service principal, managed identity, or agent identity | App-only | https://ai.gateway.azure.com/.default |
| You, signed in to the Azure CLI | Delegated | az 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:
| Scope | Resource 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.
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.
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.
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.
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.
Review and assign
On Review, Role assignments to create lists the identity, its type, the role, and the scope, All assets. Select Assign.
Your account appears in AccessEntra ID with the AI Gateway Models User role, All assets as the resource scope, and Models as the access.
Create the role assignment
az role assignment create needs the principal's object ID, the role ID, and the full scope:
# Give yourself the AI Gateway Models User role (a6b68e3d-โฆ) on all assets, the default workspace, to call every model
az role assignment create \
--assignee-object-id "$MY_OBJECT_ID" \
--assignee-principal-type User \
--role "a6b68e3d-a1f0-4c60-8678-237c050cf4ea" \
--scope "$GATEWAY_ID/workspaces/default" --output none &&
echo "๐ You have the AI Gateway Models User role on all assets of $GATEWAY"# Give yourself the AI Gateway Models User role (a6b68e3d-โฆ) on all assets, the default workspace, to call every model
az role assignment create `
--assignee-object-id $MY_OBJECT_ID `
--assignee-principal-type User `
--role "a6b68e3d-a1f0-4c60-8678-237c050cf4ea" `
--scope "$GATEWAY_ID/workspaces/default" --output none
if ($?) { Write-Host "๐ You have the AI Gateway Models User role on all assets of $GATEWAY" }Use the helper for other roles and scopes
The lab's helper script maps user, models, and tools to the role IDs, builds the scope for all assets (the
default workspace), the gateway, a model alias, or an MCP server, and defaults to the signed-in user:
# Give yourself the AI Gateway Models User role on all assets, the default workspace
./infra/assign-roles.sh models &&
echo "๐ You have the AI Gateway Models User role on all assets of $GATEWAY"
# Or grant the same role on one model alias only, so that calls to other aliases return 403
./infra/assign-roles.sh models "alias:$AI_GATEWAY_MODEL" &&
echo "๐ You have the AI Gateway Models User role on the alias $AI_GATEWAY_MODEL"
# Or grant AI Gateway Tools User on one MCP server, which lets you list and call its tools, but not models
./infra/assign-roles.sh tools "mcp:<mcp-server-name>" &&
echo "๐ You have the AI Gateway Tools User role on the MCP server"
# Or give an Entra group AI Gateway User (models and tools) on all assets, so that membership controls access
./infra/assign-roles.sh user workspace <group-object-id> Group &&
echo "๐ The group has the AI Gateway User role on all assets of $GATEWAY"# Give yourself the AI Gateway Models User role on all assets, the default workspace
./infra/assign-roles.ps1 -Role models
if ($?) { Write-Host "๐ You have the AI Gateway Models User role on all assets of $GATEWAY" }
# Or grant the same role on one model alias only, so that calls to other aliases return 403
./infra/assign-roles.ps1 -Role models -Scope "alias:$env:AI_GATEWAY_MODEL"
if ($?) { Write-Host "๐ You have the AI Gateway Models User role on the alias $env:AI_GATEWAY_MODEL" }
# Or grant AI Gateway Tools User on one MCP server, which lets you list and call its tools, but not models
./infra/assign-roles.ps1 -Role tools -Scope "mcp:<mcp-server-name>"
if ($?) { Write-Host "๐ You have the AI Gateway Tools User role on the MCP server" }
# Or give an Entra group AI Gateway User (models and tools) on all assets, so that membership controls access
./infra/assign-roles.ps1 -Role user -PrincipalId <group-object-id> -PrincipalType Group
if ($?) { Write-Host "๐ The group has the AI Gateway User role on all assets of $GATEWAY" }#!/usr/bin/env bash
# Grants an AI Gateway runtime role to a Microsoft Entra identity on all assets, a model alias, or an MCP server.
#
# Usage: ./assign-roles.sh <role> [scope] [principal-object-id] [principal-type]
# role user | models | tools
# user = AI Gateway User (models and tools)
# models = AI Gateway Models User (models only)
# tools = AI Gateway Tools User (tools only)
# scope workspace (default: all assets, the default workspace) | gateway | alias:<alias-name>
# | mcp:<mcp-server-name>
# principal-object-id defaults to the signed-in user
# principal-type User (default) | Group | ServicePrincipal
#
# Requires RG and GATEWAY, the Azure CLI with the aigateway extension, and permission to create role assignments
# (Owner, User Access Administrator, or Role Based Access Control Administrator). Contributor isn't enough.
set -euo pipefail
: "${RG:?Set RG to the resource group of the gateway}"
: "${GATEWAY:?Set GATEWAY to the gateway name}"
ROLE="${1:?Usage: ./assign-roles.sh <user|models|tools> [workspace|gateway|alias:<name>|mcp:<name>] [principal-object-id] [principal-type]}"
TARGET="${2:-workspace}"
PRINCIPAL_ID="${3:-}"
PRINCIPAL_TYPE="${4:-User}"
case "$ROLE" in
user) ROLE_ID="caad7a21-134e-43f4-a550-c5ffc17e051c"; ROLE_NAME="AI Gateway User" ;;
models) ROLE_ID="a6b68e3d-a1f0-4c60-8678-237c050cf4ea"; ROLE_NAME="AI Gateway Models User" ;;
tools) ROLE_ID="dce03f8d-857f-4e40-a90d-67770fa6ecd2"; ROLE_NAME="AI Gateway Tools User" ;;
*) echo "Unknown role '$ROLE'. Use user, models, or tools." >&2; exit 2 ;;
esac
GATEWAY_ID="$(az aigateway show -g "$RG" -n "$GATEWAY" --query id -o tsv)"
case "$TARGET" in
workspace) SCOPE="$GATEWAY_ID/workspaces/default" ;;
gateway) SCOPE="$GATEWAY_ID" ;;
alias:?*)
[[ "$ROLE" != "tools" ]] || { echo "AI Gateway Tools User can't be assigned on a model alias." >&2; exit 2; }
SCOPE="$GATEWAY_ID/workspaces/default/aliases/${TARGET#alias:}" ;;
mcp:?*)
[[ "$ROLE" != "models" ]] || { echo "AI Gateway Models User can't be assigned on an MCP server." >&2; exit 2; }
SCOPE="$GATEWAY_ID/workspaces/default/toolServers/${TARGET#mcp:}" ;;
*) echo "Unknown scope '$TARGET'. Use workspace, gateway, alias:<name>, or mcp:<name>." >&2; exit 2 ;;
esac
if [[ -z "$PRINCIPAL_ID" ]]; then
PRINCIPAL_ID="$(az ad signed-in-user show --query id -o tsv)"
PRINCIPAL_TYPE="User"
fi
echo "Role: $ROLE_NAME ($ROLE_ID)"
echo "Principal: $PRINCIPAL_ID ($PRINCIPAL_TYPE)"
echo "Scope: $SCOPE"
az role assignment create \
--assignee-object-id "$PRINCIPAL_ID" \
--assignee-principal-type "$PRINCIPAL_TYPE" \
--role "$ROLE_ID" \
--scope "$SCOPE" \
--output none
az role assignment list --scope "$SCOPE" \
--query "[?principalId=='$PRINCIPAL_ID'].{Role:roleDefinitionName, PrincipalType:principalType, Scope:scope}" \
--output table
echo "Role assignments can take several minutes to apply. Until then, calls return 403."On GitHub, open assign-roles.sh or assign-roles.ps1.
For a managed identity, pass its principal (object) ID with the type ServicePrincipal, for example
from az identity show -g <resource-group> -n <identity-name> --query principalId -o tsv.
Confirm the assignment
# List your role assignments on the gateway and its assets, with each role's name and scope
# Match the gateway by name: Bicep stores some scopes with resourcegroups in lower case
echo "๐ Your role assignments on $GATEWAY:"
az role assignment list --all --assignee "$MY_OBJECT_ID" \
--query "[?ends_with(scope, '/aigateways/$GATEWAY') || contains(scope, '/aigateways/$GATEWAY/')].{Role:roleDefinitionName, Scope:scope}" -o table# List your role assignments on the gateway and its assets, with each role's name and scope
# Match the gateway by name: Bicep stores some scopes with resourcegroups in lower case
Write-Host "๐ Your role assignments on ${GATEWAY}:"
az role assignment list --all --assignee $MY_OBJECT_ID `
--query "[?ends_with(scope, '/aigateways/$GATEWAY') || contains(scope, '/aigateways/$GATEWAY/')].{Role:roleDefinitionName, Scope:scope}" -o tableThe list shows AI Gateway Models User with the gateway's resource ID followed by /workspaces/default as
the scope, the same scope that the portal's All assets uses.
What you need: only the one-time setup from Before you begin. This track doesn't use your gateway from lab 02:
azd up creates a new one, so it works on its own.
Choose what to declare
The template grants one AI Gateway runtime role to one principal on all assets (the default workspace, like the
portal), the gateway, a model alias, or an MCP server. It names the assignment with guid() of the scope, principal, and role, so redeploying it changes nothing. azd
passes your signed-in identity as the principal: it sets AZURE_PRINCIPAL_ID to your object ID before every
deployment.
Review the templates
infra/main.bicep creates the resource group rg-<environment name> and calls the quick start's
resources.bicep for the gateway, the Foundry model, its default alias, and the
app-first-call key, which this lab doesn't use. Then it calls infra/role-assignment.bicep with your object ID:
// Lab 11 with azd: "azd up" creates the resource group rg-<environment name>, the quick start's gateway, Foundry
// model, default alias, and runtime API key, then grants you an AI Gateway runtime role so that you can call the
// model with a Microsoft Entra token instead of a key. The runtime API key is never an output.
targetScope = 'subscription'
@description('azd environment name. The resource group is rg-<environmentName>.')
@minLength(1)
@maxLength(60)
param environmentName string
@description('Region for every resource. Pick one where AI Gateway and the lab\'s Foundry models are available. List them with az provider show --namespace Microsoft.ApiManagement (Setup guide, Find the available regions).')
@metadata({ azd: { type: 'location' } })
param location string
@description('Object ID of the identity to grant. azd sets AZURE_PRINCIPAL_ID to the signed-in user or service principal.')
param principalId string
@description('Type of that identity. azd reads it from AZURE_PRINCIPAL_TYPE, User by default.')
@allowed([ 'User', 'Group', 'ServicePrincipal' ])
param principalType string = 'User'
@description('Role to grant: user (AI Gateway User), models (AI Gateway Models User), or tools (AI Gateway Tools User). azd reads it from DATA_PLANE_ROLE.')
@allowed([ 'user', 'models', 'tools' ])
param role string = 'models'
@description('Where to grant it: all assets (the default workspace), the whole gateway, or only the model alias. azd reads it from DATA_PLANE_ROLE_SCOPE.')
@allowed([ 'workspace', 'gateway', 'alias' ])
param roleScope string = 'workspace'
var suffix = take(uniqueString(subscription().id, environmentName, location), 6)
var tags = { 'azd-env-name': environmentName }
resource rg 'Microsoft.Resources/resourceGroups@2024-03-01' = {
name: 'rg-${environmentName}'
location: location
tags: tags
}
// The quick start's template: a gateway, a Foundry model behind the default alias, and the app-first-call key.
module base '../../quickstart/infra/resources.bicep' = {
name: 'aigw-base'
scope: rg
params: {
location: location
tags: tags
gatewayName: 'aigw-${suffix}'
foundryName: 'aigw${suffix}'
}
}
module roleAssignment 'role-assignment.bicep' = {
name: 'aigw-role-assignment'
scope: rg
params: {
gatewayName: base.outputs.gatewayName
principalId: principalId
principalType: principalType
role: role
scope: roleScope
scopeName: roleScope == 'alias' ? base.outputs.aliasName : ''
}
}
output AZURE_RESOURCE_GROUP string = rg.name
output AI_GATEWAY_NAME string = base.outputs.gatewayName
output AI_GATEWAY_ID string = base.outputs.gatewayId
output AI_GATEWAY_URL string = base.outputs.gatewayUrl
output AI_GATEWAY_PROVIDER string = base.outputs.providerName
output AI_GATEWAY_BACKEND_MODEL string = base.outputs.modelName
output AI_GATEWAY_MODEL string = base.outputs.aliasName
output FOUNDRY_ACCOUNT_NAME string = base.outputs.foundryName
output AI_GATEWAY_ROLE_ASSIGNMENT_ID string = roleAssignment.outputs.roleAssignmentId
output AI_GATEWAY_ROLE_SCOPE_ID string = roleAssignment.outputs.scopeIdinfra/role-assignment.bicep creates the assignment. It only references the gateway, so you can also deploy it
on its own to your gateway from lab 02, with az deployment group create -g <resource-group> --template-file infra/role-assignment.bicep --parameters gatewayName=<gateway> principalId=<object-id>:
// Grants an AI Gateway runtime role to a Microsoft Entra identity on all assets (the default workspace), the gateway,
// a model alias, or an MCP server. Runtime roles let callers invoke models and call tools. They don't grant gateway
// management.
// The assignment name is derived from the scope, principal, and role, so redeploying the template is safe.
@description('Name of the existing AI Gateway (Microsoft.ApiManagement/aigateways).')
param gatewayName string
@description('Object ID of the user, group, service principal, or managed identity to grant.')
param principalId string
@description('Type of the principal. Use ServicePrincipal for apps and managed identities.')
@allowed([ 'User', 'Group', 'ServicePrincipal' ])
param principalType string = 'User'
@description('Role to grant: user (AI Gateway User, models and tools), models (AI Gateway Models User), or tools (AI Gateway Tools User).')
@allowed([ 'user', 'models', 'tools' ])
param role string = 'models'
@description('Where to grant it: all assets (the default workspace, like the portal), the gateway, one model alias, or one MCP server.')
@allowed([ 'workspace', 'gateway', 'alias', 'mcp' ])
param scope string = 'workspace'
@description('Alias name when scope is alias, or MCP server name when scope is mcp.')
param scopeName string = ''
var roleIds = {
user: 'caad7a21-134e-43f4-a550-c5ffc17e051c'
models: 'a6b68e3d-a1f0-4c60-8678-237c050cf4ea'
tools: 'dce03f8d-857f-4e40-a90d-67770fa6ecd2'
}
var roleDefinitionId = subscriptionResourceId('Microsoft.Authorization/roleDefinitions', roleIds[role])
var childName = empty(scopeName) ? 'unused' : scopeName
#disable-next-line BCP081
resource gateway 'Microsoft.ApiManagement/aigateways@2026-11-01' existing = {
name: gatewayName
}
#disable-next-line BCP081
resource workspace 'Microsoft.ApiManagement/aigateways/workspaces@2026-11-01' existing = {
parent: gateway
name: 'default'
}
#disable-next-line BCP081
resource alias 'Microsoft.ApiManagement/aigateways/workspaces/aliases@2026-11-01' existing = {
parent: workspace
name: childName
}
#disable-next-line BCP081
resource toolServer 'Microsoft.ApiManagement/aigateways/workspaces/toolServers@2026-11-01' existing = {
parent: workspace
name: childName
}
resource onGateway 'Microsoft.Authorization/roleAssignments@2022-04-01' = if (scope == 'gateway') {
scope: gateway
name: guid(gateway.id, principalId, roleDefinitionId)
properties: {
principalId: principalId
principalType: principalType
roleDefinitionId: roleDefinitionId
}
}
resource onWorkspace 'Microsoft.Authorization/roleAssignments@2022-04-01' = if (scope == 'workspace') {
scope: workspace
name: guid(workspace.id, principalId, roleDefinitionId)
properties: {
principalId: principalId
principalType: principalType
roleDefinitionId: roleDefinitionId
}
}
resource onAlias 'Microsoft.Authorization/roleAssignments@2022-04-01' = if (scope == 'alias') {
scope: alias
name: guid(alias.id, principalId, roleDefinitionId)
properties: {
principalId: principalId
principalType: principalType
roleDefinitionId: roleDefinitionId
}
}
resource onToolServer 'Microsoft.Authorization/roleAssignments@2022-04-01' = if (scope == 'mcp') {
scope: toolServer
name: guid(toolServer.id, principalId, roleDefinitionId)
properties: {
principalId: principalId
principalType: principalType
roleDefinitionId: roleDefinitionId
}
}
output roleAssignmentId string = scope == 'workspace'
? onWorkspace.id
: (scope == 'gateway' ? onGateway.id : (scope == 'alias' ? onAlias.id : onToolServer.id))
output scopeId string = scope == 'workspace'
? workspace.id
: (scope == 'gateway' ? gateway.id : (scope == 'alias' ? alias.id : toolServer.id))For a group or managed identity, pass its object ID with principalType=Group or principalType=ServicePrincipal.
If you already hold the role at the same scope, that deployment fails with RoleAssignmentExists, because the
existing assignment has a different name. You have the access you need, so carry on.
Deploy with azd up
Move into the lab's folder, create an azd environment named aigw-lab11 in your current subscription, then provision
everything. It takes about three minutes.
# Move into the lab's folder, which holds the azd project
cd ~/aigateway/labs/11-entra-rbac &&
echo "๐ Lab folder: $(pwd)"
# Create an azd environment in your current subscription, so that azd doesn't prompt you
azd env new aigw-lab11 --location eastus2 --subscription "$(az account show --query id --output tsv)" &&
echo "๐ azd environment aigw-lab11 deploys to eastus2"
# Provision the gateway, the Foundry model and its alias, and your AI Gateway runtime role on all its assets
azd up &&
echo "๐ Gateway deployed: $(azd env get-value AI_GATEWAY_URL)"# Move into the lab's folder, which holds the azd project
Set-Location ~/aigateway/labs/11-entra-rbac
if ($?) { Write-Host "๐ Lab folder: $(Get-Location)" }
# Create an azd environment in your current subscription, so that azd doesn't prompt you
azd env new aigw-lab11 --location eastus2 --subscription (az account show --query id --output tsv)
if ($?) { Write-Host "๐ azd environment aigw-lab11 deploys to eastus2" }
# Provision the gateway, the Foundry model and its alias, and your AI Gateway runtime role on all its assets
azd up
if ($?) { Write-Host "๐ Gateway deployed: $(azd env get-value AI_GATEWAY_URL)" }For another region, pick one where AI Gateway and the gpt-5-mini model are available, as in Find the available
regions.
Read the outputs
Set the variables that the next sections and Verify use from azd's environment values. This lab is keyless, so you don't read the key. The last command lists your role assignments on the gateway.
# Read the gateway's names, resource ID, runtime URL, and alias from azd's environment values
export RG="$(azd env get-value AZURE_RESOURCE_GROUP)"
export GATEWAY="$(azd env get-value AI_GATEWAY_NAME)"
export PROVIDER="$(azd env get-value AI_GATEWAY_PROVIDER)"
export MODEL="$(azd env get-value AI_GATEWAY_BACKEND_MODEL)"
export GATEWAY_ID="$(azd env get-value AI_GATEWAY_ID)"
export AI_GATEWAY_URL="$(azd env get-value AI_GATEWAY_URL)"
export AI_GATEWAY_MODEL="$(azd env get-value AI_GATEWAY_MODEL)"
echo "๐ Gateway $GATEWAY in $RG"
echo "๐ Runtime URL: $AI_GATEWAY_URL"
echo "๐ Model alias: $AI_GATEWAY_MODEL"
# Read your object ID in Microsoft Entra ID
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"
# List your role assignments on the gateway and its assets, including the one that azd up created
# Match the gateway by name: Bicep stores some scopes with resourcegroups in lower case
echo "๐ Your role assignments on $GATEWAY:"
az role assignment list --all --assignee "$MY_OBJECT_ID" \
--query "[?ends_with(scope, '/aigateways/$GATEWAY') || contains(scope, '/aigateways/$GATEWAY/')].{Role:roleDefinitionName, Scope:scope}" -o table# Read the gateway's names, resource ID, runtime URL, and alias from azd's environment values
$RG = azd env get-value AZURE_RESOURCE_GROUP
$GATEWAY = azd env get-value AI_GATEWAY_NAME
$PROVIDER = azd env get-value AI_GATEWAY_PROVIDER
$MODEL = azd env get-value AI_GATEWAY_BACKEND_MODEL
$GATEWAY_ID = azd env get-value AI_GATEWAY_ID
$env:AI_GATEWAY_URL = azd env get-value AI_GATEWAY_URL
$env:AI_GATEWAY_MODEL = azd env get-value AI_GATEWAY_MODEL
Write-Host "๐ Gateway $GATEWAY in $RG"
Write-Host "๐ Runtime URL: $env:AI_GATEWAY_URL"
Write-Host "๐ Model alias: $env:AI_GATEWAY_MODEL"
# Read your object ID in Microsoft Entra ID
$MY_OBJECT_ID = az ad signed-in-user show --query id -o tsv
Write-Host "๐ค Your object ID: $MY_OBJECT_ID"
# Remove any API key from your session, to prove that nothing in this lab uses one
Remove-Item Env:AI_GATEWAY_API_KEY -ErrorAction SilentlyContinue
Write-Host "๐ AI_GATEWAY_API_KEY is removed, so every call in this lab is keyless"
# List your role assignments on the gateway and its assets, including the one that azd up created
# Match the gateway by name: Bicep stores some scopes with resourcegroups in lower case
Write-Host "๐ Your role assignments on ${GATEWAY}:"
az role assignment list --all --assignee $MY_OBJECT_ID `
--query "[?ends_with(scope, '/aigateways/$GATEWAY') || contains(scope, '/aigateways/$GATEWAY/')].{Role:roleDefinitionName, Scope:scope}" -o tableazd up ended with SUCCESS, and the list shows AI Gateway Models User with a scope that ends with
/aigateways/<gateway>/workspaces/default. In the portal, AccessEntra ID lists you with that role.
Change the role or the scope
The parameters come from azd environment values, with the defaults in infra/main.parameters.json.
DATA_PLANE_ROLE picks the role (user, models, or tools), and DATA_PLANE_ROLE_SCOPE picks where to grant
it (workspace for all assets, gateway, or alias for the default alias only). To grant only the alias, set the
scope and provision again:
# Grant the role on the default alias instead of all assets
azd env set DATA_PLANE_ROLE_SCOPE alias &&
echo "๐ DATA_PLANE_ROLE_SCOPE is alias"
# Deploy the templates again, which adds the role assignment on the alias
azd provision &&
echo "๐ You also have the role on the alias $AI_GATEWAY_MODEL"# Grant the role on the default alias instead of all assets
azd env set DATA_PLANE_ROLE_SCOPE alias
if ($?) { Write-Host "๐ DATA_PLANE_ROLE_SCOPE is alias" }
# Deploy the templates again, which adds the role assignment on the alias
azd provision
if ($?) { Write-Host "๐ You also have the role on the alias $env:AI_GATEWAY_MODEL" }A Bicep deployment only adds or updates resources, so you now hold the role on all assets and on the alias.
To test the narrower scope, remove only the assignment on all assets with az role assignment delete --assignee "$MY_OBJECT_ID" --role a6b68e3d-a1f0-4c60-8678-237c050cf4ea --scope "$GATEWAY_ID/workspaces/default": calls to the
alias still return 200. Set DATA_PLANE_ROLE_SCOPE back to workspace and run azd provision --no-state before
Verify, which re-creates the assignment on all assets. For an MCP server, deploy
infra/role-assignment.bicep on its own with role=tools scope=mcp scopeName=<mcp-server-name>.
What you need: only the one-time setup from Before you begin, plus Terraform 1.9 or later, as in
Deploy a lab with Terraform. This track doesn't use your gateway from
lab 02: terraform apply creates a new one, so it works on its own.
Choose what to declare
Like the Bicep template, the configuration grants one AI Gateway runtime role to one principal on all assets (the
default workspace, like the portal), the gateway, or the default alias. It names the assignment with uuidv5() of
the scope, principal, and role, so applying it again changes nothing. The principal is you, unless you pass another
one: the configuration reads your object ID from your Azure CLI sign-in.
Review the configuration
terraform/main.tf creates the resource group rg-<environment_name> and calls the quick start's
resources module for the gateway, the Foundry model, its default alias, and the
app-first-call key, which this lab doesn't use:
# Lab 11 with Terraform: creates the resource group rg-<environment_name>, the quick start's gateway, Foundry model,
# default alias, and runtime API key, then grants you an AI Gateway runtime role (role-assignment.tf), so that you can
# call the model with a Microsoft Entra token instead of a key. The runtime API key is never an output.
data "azapi_client_config" "current" {}
locals {
suffix = substr(sha1("${data.azapi_client_config.current.subscription_id}/${var.environment_name}/${var.location}"), 0, 6)
tags = { "environment-name" = var.environment_name }
}
resource "azurerm_resource_group" "rg" {
name = "rg-${var.environment_name}"
location = var.location
tags = local.tags
}
# The quick start's module: a gateway, a Foundry model behind the default alias, and the app-first-call key.
module "base" {
source = "../../quickstart/terraform/resources"
subscription_id = data.azapi_client_config.current.subscription_id
resource_group_name = azurerm_resource_group.rg.name
resource_group_id = azurerm_resource_group.rg.id
location = var.location
tags = local.tags
gateway_name = "aigw-${local.suffix}"
foundry_name = "aigw${local.suffix}"
}terraform/role-assignment.tf creates the role assignment with the azurerm provider. terraform/variables.tf
declares the role, the scope, and the principal, with the same defaults as the Bicep template:
# Grants an AI Gateway runtime role to a Microsoft Entra identity, the signed-in user by default, on all assets (the
# default workspace), the gateway, or the default alias. Runtime roles let callers invoke models and call tools. They
# don't grant gateway management. One assignment at a time: changing role_scope replaces it.
locals {
role_ids = {
user = "caad7a21-134e-43f4-a550-c5ffc17e051c" # AI Gateway User: models and tools
models = "a6b68e3d-a1f0-4c60-8678-237c050cf4ea" # AI Gateway Models User: models only
tools = "dce03f8d-857f-4e40-a90d-67770fa6ecd2" # AI Gateway Tools User: tools only
}
role_definition_id = "/subscriptions/${data.azapi_client_config.current.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/${local.role_ids[var.role]}"
principal_id = var.principal_id != "" ? var.principal_id : data.azapi_client_config.current.object_id
role_scope_ids = {
workspace = module.base.workspace_id
gateway = module.base.gateway_id
alias = "${module.base.workspace_id}/aliases/${module.base.alias_name}"
}
role_scope_id = local.role_scope_ids[var.role_scope]
}
resource "azurerm_role_assignment" "runtime" {
name = uuidv5("url", "${local.role_scope_id}/${local.principal_id}/${local.role_definition_id}")
scope = local.role_scope_id
role_definition_id = local.role_definition_id
principal_id = local.principal_id
principal_type = var.principal_type
skip_service_principal_aad_check = var.principal_type == "ServicePrincipal"
}For a group or managed identity, pass its object ID with -var principal_id=<object-id> and
-var principal_type=Group or -var principal_type=ServicePrincipal.
Deploy with terraform apply
Move into the lab's Terraform folder, select your current subscription, then plan and apply the configuration. It takes about four minutes, most of it while the new gateway activates.
# Move into the lab's Terraform folder
cd ~/aigateway/labs/11-entra-rbac/terraform &&
echo "๐ Terraform folder: $(pwd)"
# Deploy to the Azure CLI's current subscription
export ARM_SUBSCRIPTION_ID="$(az account show --query id --output tsv)" &&
echo "๐ Subscription: $ARM_SUBSCRIPTION_ID"
# Download the providers, then plan and apply the gateway, the Foundry model and its alias, and your AI Gateway
# runtime role on all its assets
terraform init &&
terraform plan -out tfplan &&
terraform apply tfplan &&
echo "๐ Gateway deployed: $(terraform output -raw ai_gateway_url)"# Move into the lab's Terraform folder
Set-Location ~/aigateway/labs/11-entra-rbac/terraform
if ($?) { Write-Host "๐ Terraform folder: $(Get-Location)" }
# Deploy to the Azure CLI's current subscription
$env:ARM_SUBSCRIPTION_ID = az account show --query id --output tsv
if ($?) { Write-Host "๐ Subscription: $env:ARM_SUBSCRIPTION_ID" }
# Download the providers, then plan and apply the gateway, the Foundry model and its alias, and your AI Gateway
# runtime role on all its assets
terraform init
if ($?) { terraform plan -out tfplan }
if ($?) { terraform apply tfplan }
if ($?) { Write-Host "๐ Gateway deployed: $(terraform output -raw ai_gateway_url)" }The configuration deploys to eastus2. For another region where AI Gateway and the gpt-5-mini model are
available, as in Find the available regions, run
export TF_VAR_location=<region> (PowerShell: $env:TF_VAR_location = "<region>") before terraform plan.
Read the outputs
Set the variables that the next sections and Verify use from the Terraform outputs. This lab is keyless, so you don't read the key. The last command lists your role assignments on the gateway.
# Read the gateway's names, resource ID, runtime URL, and alias from the configuration's outputs
export RG="$(terraform output -raw azure_resource_group)"
export GATEWAY="$(terraform output -raw ai_gateway_name)"
export PROVIDER="$(terraform output -raw ai_gateway_provider)"
export MODEL="$(terraform output -raw ai_gateway_backend_model)"
export GATEWAY_ID="$(terraform output -raw ai_gateway_id)"
export AI_GATEWAY_URL="$(terraform output -raw ai_gateway_url)"
export AI_GATEWAY_MODEL="$(terraform output -raw ai_gateway_model)"
echo "๐ Gateway $GATEWAY in $RG"
echo "๐ Runtime URL: $AI_GATEWAY_URL"
echo "๐ Model alias: $AI_GATEWAY_MODEL"
# Read your object ID in Microsoft Entra ID
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"
# List your role assignments on the gateway and its assets, including the one that terraform apply created
echo "๐ Your role assignments on $GATEWAY:"
az role assignment list --all --assignee "$MY_OBJECT_ID" \
--query "[?ends_with(scope, '/aigateways/$GATEWAY') || contains(scope, '/aigateways/$GATEWAY/')].{Role:roleDefinitionName, Scope:scope}" -o table# Read the gateway's names, resource ID, runtime URL, and alias from the configuration's outputs
$RG = terraform output -raw azure_resource_group
$GATEWAY = terraform output -raw ai_gateway_name
$PROVIDER = terraform output -raw ai_gateway_provider
$MODEL = terraform output -raw ai_gateway_backend_model
$GATEWAY_ID = terraform output -raw ai_gateway_id
$env:AI_GATEWAY_URL = terraform output -raw ai_gateway_url
$env:AI_GATEWAY_MODEL = terraform output -raw ai_gateway_model
Write-Host "๐ Gateway $GATEWAY in $RG"
Write-Host "๐ Runtime URL: $env:AI_GATEWAY_URL"
Write-Host "๐ Model alias: $env:AI_GATEWAY_MODEL"
# Read your object ID in Microsoft Entra ID
$MY_OBJECT_ID = az ad signed-in-user show --query id -o tsv
Write-Host "๐ค Your object ID: $MY_OBJECT_ID"
# Remove any API key from your session, to prove that nothing in this lab uses one
Remove-Item Env:AI_GATEWAY_API_KEY -ErrorAction SilentlyContinue
Write-Host "๐ AI_GATEWAY_API_KEY is removed, so every call in this lab is keyless"
# List your role assignments on the gateway and its assets, including the one that terraform apply created
Write-Host "๐ Your role assignments on ${GATEWAY}:"
az role assignment list --all --assignee $MY_OBJECT_ID `
--query "[?ends_with(scope, '/aigateways/$GATEWAY') || contains(scope, '/aigateways/$GATEWAY/')].{Role:roleDefinitionName, Scope:scope}" -o tableterraform apply ended with Apply complete! Resources: 10 added, 0 changed, 0 destroyed., and the list shows
AI Gateway Models User with a scope that ends with /aigateways/<gateway>/workspaces/default. In the portal,
AccessEntra ID lists you with that role.
Change the role or the scope
The settings are Terraform variables, with the defaults in terraform/variables.tf. role picks the role (user,
models, or tools), and role_scope picks where to grant it (workspace for all assets, gateway, or alias
for the default alias only). To grant only the alias, pass the scope to terraform plan and apply the plan:
# Plan the change: grant the role on the default alias instead of all assets
terraform plan -var role_scope=alias -out tfplan &&
echo "๐ The plan moves the role assignment to the alias"
# Apply the plan
terraform apply tfplan &&
echo "๐ You have the role on the alias $AI_GATEWAY_MODEL only"# Plan the change: grant the role on the default alias instead of all assets
terraform plan -var role_scope=alias -out tfplan
if ($?) { Write-Host "๐ The plan moves the role assignment to the alias" }
# Apply the plan
terraform apply tfplan
if ($?) { Write-Host "๐ You have the role on the alias $env:AI_GATEWAY_MODEL only" }The plan ended with Plan: 1 to add, 0 to change, 1 to destroy.: azurerm_role_assignment.runtime must be
replaced, because its scope changes.
Unlike a Bicep deployment, Terraform replaces the assignment, so you now hold the role on the alias only, and calls
to the alias still return 200. -var role=tools -var role_scope=alias fails at plan time: AI Gateway Tools
User can't be assigned on a model alias. Before Verify, plan and apply again without -var, which moves the
assignment back to all assets.
The next sections run the samples from the lab's folder, so move up to it: cd .. (PowerShell: Set-Location ..).
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
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.
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.
The model answers, and Method shows Microsoft Entra ID, not a key.
Get a token
The Azure CLI can issue a token for the AI Gateway audience with your sign-in:
# Get an access token for the AI Gateway audience, with your Azure CLI sign-in
export AI_GATEWAY_TOKEN="$(az account get-access-token \
--scope https://ai.gateway.azure.com/Data.All --query accessToken -o tsv)"
echo "๐ค Token acquired: in AI_GATEWAY_TOKEN (${#AI_GATEWAY_TOKEN} characters, not shown)"# Get an access token for the AI Gateway audience, with your Azure CLI sign-in
$env:AI_GATEWAY_TOKEN = az account get-access-token `
--scope https://ai.gateway.azure.com/Data.All --query accessToken -o tsv
Write-Host "๐ค Token acquired: in AI_GATEWAY_TOKEN ($($env:AI_GATEWAY_TOKEN.Length) characters, not shown)"Access tokens are short-lived, typically about an hour. Run the command again when you get a 401.
Look inside the token
Decode the token's payload (the middle segment) to see what the gateway checks:
# Decode the token's payload, its middle segment, and show the claims that the gateway checks
echo "๐ค Token claims:"
jq -R 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson
| {aud, tid, oid, scp, azp}' <<< "$AI_GATEWAY_TOKEN"# Take the token's payload, its middle segment, and turn its base64url text into padded base64
$payload = ($env:AI_GATEWAY_TOKEN -split '\.')[1].Replace('-', '+').Replace('_', '/')
$payload = $payload.PadRight($payload.Length + (4 - $payload.Length % 4) % 4, '=')
# Decode the payload, and show the claims that the gateway checks
Write-Host "๐ค Token claims:"
[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($payload)) |
ConvertFrom-Json | Select-Object aud, tid, oid, scp, azpaud is 18550318-e177-4205-a743-6816d6fcdc3f, AI Gateway's app ID. scp is Data.All because the CLI gets a
delegated token for you, azp is the Azure CLI's client ID, and tid plus oid identify you to per-caller
policies.
Call the model with the bearer token
# Call the model with your token in the Authorization header, where a key would go
curl -sS "${AI_GATEWAY_URL%/}/default/models/openai/v1/chat/completions" \
-H "Authorization: Bearer $AI_GATEWAY_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"model\":\"$AI_GATEWAY_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"Say hello in five words.\"}]}" \
| jq -r 'if .choices then "๐ค \(.choices[0].message.content)" else "๐จ \(.error.message // .)" end'# Build the request: the alias in model, and one user message
$body = @{
model = $env:AI_GATEWAY_MODEL
messages = @(@{ role = "user"; content = "Say hello in five words." })
} | ConvertTo-Json -Depth 5
# Call the model with your token in the Authorization header, where a key would go
$response = Invoke-RestMethod -Method Post `
-Uri "$($env:AI_GATEWAY_URL.TrimEnd('/'))/default/models/openai/v1/chat/completions" `
-Headers @{ Authorization = "Bearer $env:AI_GATEWAY_TOKEN" } `
-ContentType "application/json" -Body $body
if ($?) { Write-Host "๐ค $($response.choices[0].message.content)" }A token takes the key's place in the same Authorization header. Remove any api-key header that older code
adds: a request with both gets 400.
The model replies, and no runtime key was sent.
Install the packages
Each sample uses DefaultAzureCredential, which uses your Azure CLI or IDE sign-in on a laptop and a managed
identity or workload identity when the code runs in Azure. No key or secret appears in code or config.
# Move into the folder that holds the samples
cd infra
echo "๐ Sample folder: infra"
# Create a virtual environment for the packages, and activate it
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
echo "๐ฆ The virtual environment .venv is active"
# Install the OpenAI and Azure Identity packages that the sample uses
pip install -r requirements.txt
echo "๐ฆ The OpenAI and Azure Identity packages are installed"# Move into the folder that holds the samples
cd infra
echo "๐ Sample folder: infra"
# Install the OpenAI and Azure Identity packages that the sample uses
npm install
echo "๐ฆ The OpenAI and Azure Identity packages are installed"# Move into the folder that holds the samples
cd infra
echo "๐ Sample folder: infra"
# Restore the Azure Identity package that the sample uses
dotnet restore
echo "๐ฆ The Azure Identity package is restored"Review the sample
The only change from an API-key client is where the credential comes from:
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import OpenAI
token_provider = get_bearer_token_provider(
DefaultAzureCredential(), "https://ai.gateway.azure.com/.default")
client = OpenAI(
base_url=f"{gateway_url}/default/models/openai/v1",
api_key=token_provider, # called before each request, sent as Authorization: Bearer <token>
)import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
import OpenAI from "openai";
const getToken = getBearerTokenProvider(
new DefaultAzureCredential(), "https://ai.gateway.azure.com/.default");
const client = new OpenAI({
baseURL: `${gatewayUrl}/default/models/openai/v1`,
apiKey: getToken, // called before each request, sent as Authorization: Bearer <token>
});var credential = new DefaultAzureCredential();
AccessToken token = await credential.GetTokenAsync(
new TokenRequestContext(new[] { "https://ai.gateway.azure.com/.default" }));
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token.Token);The OpenAI SDKs for Python (1.106 or later) and TypeScript (5.18 or later) accept a function as the API key.
They call it before each request and send the result as Authorization: Bearer <token>, and the Azure
Identity token provider refreshes the token before it expires. The C# sample calls the REST endpoint with
HttpClient and asks the credential for a token before each call, which also returns a cached token until
it's close to expiry. Don't use an AzureOpenAI client here: the gateway exposes the OpenAI v1 API at
/default/models/openai/v1.
The complete samples add input checks and print the reply and token usage:
"""Calls a model through AI Gateway with a Microsoft Entra ID access token instead of an API key.
DefaultAzureCredential picks up your Azure CLI or Visual Studio Code sign-in on a laptop, and a managed
identity or workload identity when the code runs in Azure. The token provider returns a cached token and
refreshes it before it expires. The OpenAI SDK (1.106 or later) calls the provider before every request and
sends the result as `Authorization: Bearer <token>`.
Usage:
pip install -r requirements.txt
az login
export AI_GATEWAY_URL="<gateway-url>"
export AI_GATEWAY_MODEL="<model-name>"
python call_with_entra.py
"""
import os
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import OpenAI
# App-only and managed identity callers must use /.default. It also works for an Azure CLI sign-in.
AI_GATEWAY_SCOPE = "https://ai.gateway.azure.com/.default"
gateway_url = os.environ["AI_GATEWAY_URL"].rstrip("/")
model = os.environ["AI_GATEWAY_MODEL"]
token_provider = get_bearer_token_provider(DefaultAzureCredential(), AI_GATEWAY_SCOPE)
client = OpenAI(
base_url=f"{gateway_url}/default/models/openai/v1",
api_key=token_provider,
)
completion = client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": "In one sentence, why use Microsoft Entra ID instead of API keys?"}],
)
print(f"Model reply: {completion.choices[0].message.content}")
print(f"Tokens used: {completion.usage.total_tokens if completion.usage else 'n/a'}")// Calls a model through AI Gateway with a Microsoft Entra ID access token instead of an API key.
//
// DefaultAzureCredential picks up your Azure CLI or Visual Studio Code sign-in on a laptop, and a managed
// identity or workload identity when the code runs in Azure. getBearerTokenProvider returns a cached token
// and refreshes it before it expires. The OpenAI package (5.18 or later) calls the provider before every
// request and sends the result as `Authorization: Bearer <token>`.
//
// Usage (Node.js 22.18 or later runs TypeScript directly; on older versions use `npx tsx call-with-entra.ts`):
// npm install
// az login
// export AI_GATEWAY_URL="<gateway-url>"
// export AI_GATEWAY_MODEL="<model-name>"
// node call-with-entra.ts
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
import OpenAI from "openai";
// App-only and managed identity callers must use /.default. It also works for an Azure CLI sign-in.
const AI_GATEWAY_SCOPE = "https://ai.gateway.azure.com/.default";
function required(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`Set ${name} before running this sample.`);
return value;
}
const gatewayUrl: string = required("AI_GATEWAY_URL").replace(/\/+$/, "");
const model: string = required("AI_GATEWAY_MODEL");
const getToken = getBearerTokenProvider(new DefaultAzureCredential(), AI_GATEWAY_SCOPE);
const client = new OpenAI({
baseURL: `${gatewayUrl}/default/models/openai/v1`,
apiKey: getToken,
});
const completion = await client.chat.completions.create({
model,
messages: [{ role: "user", content: "In one sentence, why use Microsoft Entra ID instead of API keys?" }],
});
console.log(`Model reply: ${completion.choices[0].message.content}`);
console.log(`Tokens used: ${completion.usage?.total_tokens ?? "n/a"}`);// Calls a model through AI Gateway with a Microsoft Entra ID access token instead of an API key.
//
// DefaultAzureCredential picks up your Azure CLI or Visual Studio sign-in on a laptop, and a managed identity
// or workload identity when the code runs in Azure. Request a new token for each call: the credential caches
// tokens and refreshes them before they expire.
//
// Usage:
// az login
// export AI_GATEWAY_URL="<gateway-url>"
// export AI_GATEWAY_MODEL="<model-name>"
// dotnet run
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
using Azure.Core;
using Azure.Identity;
// App-only and managed identity callers must use /.default. It also works for an Azure CLI sign-in.
const string AiGatewayScope = "https://ai.gateway.azure.com/.default";
static string Required(string name) =>
Environment.GetEnvironmentVariable(name) is { Length: > 0 } value
? value
: throw new InvalidOperationException($"Set {name} before running this sample.");
var gatewayUrl = Required("AI_GATEWAY_URL").TrimEnd('/');
var model = Required("AI_GATEWAY_MODEL");
var credential = new DefaultAzureCredential();
AccessToken token = await credential.GetTokenAsync(new TokenRequestContext(new[] { AiGatewayScope }));
using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, $"{gatewayUrl}/default/models/openai/v1/chat/completions")
{
Content = JsonContent.Create(new
{
model,
messages = new[] { new { role = "user", content = "In one sentence, why use Microsoft Entra ID instead of API keys?" } },
}),
};
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token.Token);
using var response = await http.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
{
Console.Error.WriteLine($"{(int)response.StatusCode} {response.ReasonPhrase}: {body}");
return 1;
}
using var json = JsonDocument.Parse(body);
var reply = json.RootElement.GetProperty("choices")[0].GetProperty("message").GetProperty("content").GetString();
Console.WriteLine($"Model reply: {reply}");
var tokensUsed = json.RootElement.TryGetProperty("usage", out var usage) ? usage.GetProperty("total_tokens").ToString() : "n/a";
Console.WriteLine($"Tokens used: {tokensUsed}");
return 0;On GitHub, open call_with_entra.py, call-with-entra.ts, and CallWithEntra.cs with CallWithEntra.csproj.
Run it
# Run the sample, which calls the model with an Entra ID token and prints the reply and the tokens used
echo "๐ค Calling the model with your Entra ID token, and no API key:"
python call_with_entra.py# Run the sample, which calls the model with an Entra ID token and prints the reply and the tokens used
echo "๐ค Calling the model with your Entra ID token, and no API key:"
node call-with-entra.ts# Build and run the sample, which calls the model with an Entra ID token and prints the reply and the tokens used
echo "๐ค Calling the model with your Entra ID token, and no API key:"
dotnet runThe sample prints the model's reply and the tokens used, with AI_GATEWAY_API_KEY unset.
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 role | Role ID | Grants | Assign at |
|---|---|---|---|
| AI Gateway Developer | e71899cc-9858-44a9-a0e3-7b95f671540f | Read the configuration of model aliases and MCP servers | Default workspace, or one model alias or MCP server |
| AI Gateway Contributor | 7c27cbcc-1723-4201-8fbc-50f2e2c24ee5 | Create, change, and delete model providers, models, aliases, and MCP servers, with their routing and limits | Default workspace |
| Contributor | b24988ac-6180-42a0-ab88-20f7382dd24c | Manage the gateway itself: settings, networking, identities, runtime API keys, gateway-wide policies, and exporters | Gateway |
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.
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.
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.
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.
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.
AccessEntra ID lists the identity with AI Gateway Contributor, All assets as the resource scope, and No runtime access.
This track also works after the Bicep + azd or Terraform track: it uses the variables from Read the outputs.
Check the role definitions
# List the built-in AI Gateway roles with their IDs: three runtime roles and two control-plane roles
echo "๐ AI Gateway roles in Azure RBAC:"
az role definition list --query "[?starts_with(roleName, 'AI Gateway')].{Role:roleName, Id:name}" -o table# List the built-in AI Gateway roles with their IDs: three runtime roles and two control-plane roles
Write-Host "๐ AI Gateway roles in Azure RBAC:"
az role definition list --query "[?starts_with(roleName, 'AI Gateway')].{Role:roleName, Id:name}" -o tableCreate a test identity
Register an app named aigw-lab11-ops, create its service principal, and give it a client secret that expires
tomorrow. The secret stays in your shell and is never shown. If you run the commands again, they reuse the app and
its service principal, and replace the secret.
# Register the app aigw-lab11-ops, and create its service principal, the identity that you grant the role to
export OPS_APP_ID="$(az ad app create --display-name aigw-lab11-ops --query appId -o tsv)"
export OPS_OBJECT_ID="$(az ad sp show --id "$OPS_APP_ID" --query id -o tsv 2>/dev/null ||
az ad sp create --id "$OPS_APP_ID" --query id -o tsv)"
echo "๐ค Service principal aigw-lab11-ops: $OPS_OBJECT_ID"
# Give the app a client secret that expires tomorrow, and keep it only in this shell
OPS_SECRET="$(az ad app credential reset --id "$OPS_APP_ID" --only-show-errors \
--end-date "$(date -u -d tomorrow +%F 2>/dev/null || date -u -v+1d +%F)" --query password -o tsv)"
echo "๐ Client secret: in OPS_SECRET (${#OPS_SECRET} characters, not shown), expires tomorrow"# Register the app aigw-lab11-ops, and create its service principal, the identity that you grant the role to
$OPS_APP_ID = az ad app create --display-name aigw-lab11-ops --query appId -o tsv
$OPS_OBJECT_ID = az ad sp show --id $OPS_APP_ID --query id -o tsv 2>$null
if (-not $OPS_OBJECT_ID) { $OPS_OBJECT_ID = az ad sp create --id $OPS_APP_ID --query id -o tsv }
Write-Host "๐ค Service principal aigw-lab11-ops: $OPS_OBJECT_ID"
# Give the app a client secret that expires tomorrow, and keep it only in this session
$OPS_SECRET = az ad app credential reset --id $OPS_APP_ID --only-show-errors `
--end-date (Get-Date).ToUniversalTime().AddDays(1).ToString("yyyy-MM-dd") --query password -o tsv
Write-Host "๐ Client secret: in OPS_SECRET ($($OPS_SECRET.Length) characters, not shown), expires tomorrow"az ad sp create-for-rbac does the same in one command, but its default one-year secret fails in tenants whose
policy limits credential lifetimes. If you can't register apps at all, use the Portal track with a teammate or a
group instead.
Grant AI Gateway Contributor
Assign the role on all assets, the default workspace, as the portal's Manage gateway assets does:
# Give aigw-lab11-ops the AI Gateway Contributor role (7c27cbcc-โฆ) on all assets, the default workspace
az role assignment create \
--assignee-object-id "$OPS_OBJECT_ID" \
--assignee-principal-type ServicePrincipal \
--role "7c27cbcc-1723-4201-8fbc-50f2e2c24ee5" \
--scope "$GATEWAY_ID/workspaces/default" --output none &&
echo "๐ aigw-lab11-ops has the AI Gateway Contributor role on all assets of $GATEWAY"# Give aigw-lab11-ops the AI Gateway Contributor role (7c27cbcc-โฆ) on all assets, the default workspace
az role assignment create `
--assignee-object-id $OPS_OBJECT_ID `
--assignee-principal-type ServicePrincipal `
--role "7c27cbcc-1723-4201-8fbc-50f2e2c24ee5" `
--scope "$GATEWAY_ID/workspaces/default" --output none
if ($?) { Write-Host "๐ aigw-lab11-ops has the AI Gateway Contributor role on all assets of $GATEWAY" }For read-only access, use AI Gateway Developer (e71899cc-9858-44a9-a0e3-7b95f671540f) at the same scope, or on
one alias or MCP server. To manage the gateway itself, use Contributor (b24988ac-6180-42a0-ab88-20f7382dd24c) with
--scope "$GATEWAY_ID".
Sign in as the identity
Sign in as aigw-lab11-ops in a separate Azure CLI profile, so your own sign-in stays as it is. AZURE_CONFIG_DIR
picks the folder where the Azure CLI keeps its sign-in, and the ops helper runs one command with that profile:
# Keep the identity's sign-in in its own Azure CLI profile, and run commands with it through the ops helper
export OPS_CONFIG_DIR="$HOME/.azure-aigw-lab11-ops"
ops() { AZURE_CONFIG_DIR="$OPS_CONFIG_DIR" az "$@"; }
# Sign in as aigw-lab11-ops with its client secret, then remove the secret from your shell
ops login --service-principal --username "$OPS_APP_ID" --password="$OPS_SECRET" \
--tenant "$(az account show --query tenantId -o tsv)" --allow-no-subscriptions --output none &&
echo "๐ Signed in as aigw-lab11-ops in a separate Azure CLI profile" && unset OPS_SECRET# Keep the identity's sign-in in its own Azure CLI profile, and run commands with it through the ops helper
$OPS_CONFIG_DIR = Join-Path $HOME ".azure-aigw-lab11-ops"
function ops {
$saved = $env:AZURE_CONFIG_DIR
$env:AZURE_CONFIG_DIR = $OPS_CONFIG_DIR
try { az @args } finally { $env:AZURE_CONFIG_DIR = $saved }
}
# Sign in as aigw-lab11-ops with its client secret, then remove the secret from your session
ops login --service-principal --username $OPS_APP_ID --password=$OPS_SECRET `
--tenant (az account show --query tenantId -o tsv) --allow-no-subscriptions --output none
if ($LASTEXITCODE -eq 0) {
Write-Host "๐ Signed in as aigw-lab11-ops in a separate Azure CLI profile"
Remove-Variable OPS_SECRET
}A new client secret can take a minute to apply. If the sign-in fails with AADSTS7000215: Invalid client secret provided, wait a minute and run the sign-in again: the secret stays in your shell until the sign-in succeeds.
Check what the identity can do
The az aigateway commands read the gateway resource before they act on its assets, and AI Gateway Contributor
doesn't include reading the gateway. So call the management API, version 2026-11-01, with az rest. First,
refresh the identity's subscriptions: it sees yours only once the role assignment applies, and az rest needs it to
call the URL. Then manage an alias, try to create a runtime API key, and call the model:
# Refresh the identity's subscriptions: yours appears once the role assignment applies
ops account list --refresh --query "[].name" -o tsv
# The management API of the gateway's default workspace
export WS_API="https://management.azure.com$GATEWAY_ID/workspaces/default"
# Read the model aliases: allowed
ops rest --method get --url "$WS_API/aliases?api-version=2026-11-01" --query "value[].name" -o tsv &&
echo "โ
aigw-lab11-ops can read the model aliases"
# Create an alias for your model, then delete it: allowed
ops rest --method put --url "$WS_API/aliases/ops-test?api-version=2026-11-01" --output none \
--body "{\"properties\":{\"backendModels\":[{\"resourceId\":\"$GATEWAY_ID/workspaces/default/modelProviders/$PROVIDER/models/$MODEL\"}]}}" &&
echo "โ
aigw-lab11-ops created the alias ops-test"
ops rest --method delete --url "$WS_API/aliases/ops-test?api-version=2026-11-01" &&
echo "๐ฎ aigw-lab11-ops deleted the alias ops-test"
# Create a runtime API key: denied, because keys belong to the gateway, which needs Contributor
ops rest --method put --url "https://management.azure.com$GATEWAY_ID/apiKeys/ops-test?api-version=2026-11-01" \
--body '{"properties":{"displayName":"ops-test"}}' --output none ||
echo "๐ฆ aigw-lab11-ops can't create runtime API keys"
# Call the model with an app token: denied, because management roles don't grant runtime access
echo "๐ฆ Expect 403 Forbidden:"
curl -sS -w "\n%{http_code}\n" "${AI_GATEWAY_URL%/}/default/models/openai/v1/chat/completions" \
-H "Authorization: Bearer $(ops account get-access-token --scope https://ai.gateway.azure.com/.default --query accessToken -o tsv)" \
-H "Content-Type: application/json" \
-d "{\"model\":\"$AI_GATEWAY_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}]}"# Refresh the identity's subscriptions: yours appears once the role assignment applies
ops account list --refresh --query "[].name" -o tsv
# The management API of the gateway's default workspace
$WS_API = "https://management.azure.com$GATEWAY_ID/workspaces/default"
# Read the model aliases: allowed
ops rest --method get --url "$WS_API/aliases?api-version=2026-11-01" --query "value[].name" -o tsv
if ($LASTEXITCODE -eq 0) { Write-Host "โ
aigw-lab11-ops can read the model aliases" }
# Create an alias for your model, then delete it: allowed
# Write the request body to a file, which --body reads with the @ prefix, so that its quotes reach az intact
@{ properties = @{ backendModels = @(@{ resourceId = "$GATEWAY_ID/workspaces/default/modelProviders/$PROVIDER/models/$MODEL" }) } } |
ConvertTo-Json -Depth 5 -Compress | Set-Content -Path alias.json
ops rest --method put --url "$WS_API/aliases/ops-test?api-version=2026-11-01" --output none --body '@alias.json'
if ($LASTEXITCODE -eq 0) { Write-Host "โ
aigw-lab11-ops created the alias ops-test" }
ops rest --method delete --url "$WS_API/aliases/ops-test?api-version=2026-11-01"
if ($LASTEXITCODE -eq 0) { Write-Host "๐ฎ aigw-lab11-ops deleted the alias ops-test" }
# Create a runtime API key: denied, because keys belong to the gateway, which needs Contributor
'{"properties":{"displayName":"ops-test"}}' | Set-Content -Path key.json
ops rest --method put --url "https://management.azure.com$GATEWAY_ID/apiKeys/ops-test?api-version=2026-11-01" `
--body '@key.json' --output none
if ($LASTEXITCODE -ne 0) { Write-Host "๐ฆ aigw-lab11-ops can't create runtime API keys" }
Remove-Item alias.json, key.json
# Call the model with an app token: denied, because management roles don't grant runtime access
Write-Host "๐ฆ Expect 403 Forbidden:"
$opsToken = ops account get-access-token --scope https://ai.gateway.azure.com/.default --query accessToken -o tsv
$body = @{ model = $env:AI_GATEWAY_MODEL; messages = @(@{ role = "user"; content = "ping" }) } | ConvertTo-Json -Depth 5
try {
Invoke-RestMethod -Method Post -Uri "$($env:AI_GATEWAY_URL.TrimEnd('/'))/default/models/openai/v1/chat/completions" `
-Headers @{ Authorization = "Bearer $opsToken" } -ContentType "application/json" -Body $body
} catch { Write-Host "$([int]$_.Exception.Response.StatusCode) $($_.ErrorDetails.Message)" }Your subscription and the alias list print, ops-test is created and deleted, the key fails with
AuthorizationFailed for Microsoft.ApiManagement/aigateways/apiKeys/write, and the model call returns 403
with Access denied. If the refresh prints nothing, az rest fails with Subscription '<id>' not found, or
reading the aliases fails with AuthorizationFailed, the role hasn't applied yet: new control-plane assignments
can take several minutes, so wait and run the block again.
Verify
Prove that access now follows the role assignment, not a key.
Confirm the keyless call succeeds
Run the curl call or a code sample from the previous section. It returns 200 with a reply.
Send a token for the wrong audience
A token for Azure Resource Manager is valid, but not for AI Gateway:
# 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.
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:
# 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.
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.).
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 return403. - 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
.defaultscope. 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
tidandoidpair gets its own budget. - See who called. In MonitoringSettings, Token claim attributes exports claims such as
tid,oid,appid, andazpasazure.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.
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.
Remove the role assignment
# Delete your AI Gateway Models User role assignments (a6b68e3d-โฆ) on the gateway and its assets, unless Verify already removed them
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)"
if [ -n "$ROLE_IDS" ]; then
# 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"
else
echo "โ
You have no AI Gateway Models User role assignment on $GATEWAY to delete"
fi# Delete your AI Gateway Models User role assignments (a6b68e3d-โฆ) on the gateway and its assets, unless Verify already removed them
$roleIds = @(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)
if ($roleIds) {
az role assignment delete --ids @roleIds
if ($?) { Write-Host "๐ฎ Your AI Gateway Models User role assignment on $GATEWAY is deleted" }
} else {
Write-Host "โ
You have no AI Gateway Models User role assignment on $GATEWAY to delete"
}Delete the test identity
Delete the role assignments of aigw-lab11-ops on the gateway, then the app, which also deletes its service
principal, and its Azure CLI profile:
# Delete the role assignments of aigw-lab11-ops on the gateway and its assets
# xargs passes one ID per line, the same way in Bash and zsh
OPS_ROLE_IDS="$(az role assignment list --all --assignee "$OPS_OBJECT_ID" \
--query "[?ends_with(scope, '/aigateways/$GATEWAY') || contains(scope, '/aigateways/$GATEWAY/')].id" -o tsv)"
[ -z "$OPS_ROLE_IDS" ] || echo "$OPS_ROLE_IDS" | xargs az role assignment delete --ids
# Delete the app and its service principal, then the identity's Azure CLI profile
az ad app delete --id "$OPS_APP_ID" && rm -rf "$OPS_CONFIG_DIR" &&
echo "๐ฎ aigw-lab11-ops, its role assignments, and its Azure CLI profile are deleted"# Delete the role assignments of aigw-lab11-ops on the gateway and its assets
$opsRoleIds = @(az role assignment list --all --assignee $OPS_OBJECT_ID `
--query "[?ends_with(scope, '/aigateways/$GATEWAY') || contains(scope, '/aigateways/$GATEWAY/')].id" -o tsv)
if ($opsRoleIds) { az role assignment delete --ids @opsRoleIds }
# Delete the app and its service principal, then the identity's Azure CLI profile
az ad app delete --id $OPS_APP_ID
if ($?) {
Remove-Item -Recurse -Force $OPS_CONFIG_DIR -ErrorAction SilentlyContinue
Write-Host "๐ฎ aigw-lab11-ops, its role assignments, and its Azure CLI profile are deleted"
}Remove local files
Delete infra/.venv, infra/node_modules, or infra/bin and infra/obj. Then remove the role assignment
with the Portal or Azure CLI track.
Delete everything azd created
In the aigateway/labs/11-entra-rbac folder, delete the resource group with the gateway, the Foundry account, and
your role assignment. --purge also purges the soft-deleted Foundry account.
It takes a few minutes.
# Delete everything that azd up created, and purge the Foundry account
azd down --purge --force &&
echo "๐ฎ Everything that azd up created is deleted"Delete everything Terraform created
In the aigateway/labs/11-entra-rbac/terraform folder, delete the resource group with the gateway, the Foundry
account, and your role assignment. The azurerm provider also purges
the soft-deleted Foundry account. It takes a few minutes. If you ran the Code track, also remove its local files
as in that tab.
# Delete everything that terraform apply created, and purge the soft-deleted Foundry account
cd ~/aigateway/labs/11-entra-rbac/terraform &&
terraform destroy -auto-approve &&
echo "๐ฎ Everything that terraform apply created is deleted"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
- Call backends with managed identities: secure the outbound boundary.
- Enforce cost budgets with per-caller overrides: budget each Entra identity.
- Monitor usage, cost, and traces: attribute usage to
tid,oid, and app claims. - Docs: Security and identity, Authenticate with Entra ID, Grant control-plane access, and Agent frameworks and SDKs.