Your platform team runs one gateway per region, and every gateway calls the same Foundry account. Today each gateway uses its own system-assigned identity, so every new gateway needs a fresh Foundry User grant, and recreating a gateway leaves a stale role assignment behind. The team wants one identity that it owns, grants once, and attaches to every gateway, with no backend key stored anywhere. In this lab you check the gateway's system-assigned identity, create a user-assigned identity, give it access to Foundry, and switch a model provider to it without changing a single client.
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, model, and
key, so you can skip this section. You need only the one-time setup above, and permission to create role
assignments, for example Owner on the subscription. To check the system-assigned identity first, run the track
in Create a user-assigned identity and give it access up to
Read the outputs and the key, which sets the variables, then come back.
- Complete Publish a Foundry model and make your first call. You need a gateway with a Foundry model provider that uses a managed identity, a model alias, and a runtime API key.
- Every track uses the Azure CLI at least once: the portal can't change the identity of a model provider that already exists.
- Permissions:
- Create a managed identity in the resource group, for example Contributor or Managed Identity Contributor.
- Attach the identity to the gateway: Contributor on the gateway and Managed Identity Operator on the identity. Contributor on a resource group that holds both covers this.
- Create role assignments on the Foundry account, for example Owner, User Access Administrator, or Role Based Access Control Administrator.
Managed identities are free. Nothing in this lab adds charges beyond the model calls you make.
Set these variables once. Every track and the Verify section reuse them.
# Set your gateway, its Foundry provider and Foundry account, and the name of the user-assigned identity to create
export RG="<resource-group>"
export GATEWAY="<gateway>"
export PROVIDER="<provider-name>" # the Foundry provider from lab 02, for example foundry-models
export FOUNDRY_RG="<foundry-resource-group>" # resource group of the Foundry account
export FOUNDRY_ACCOUNT="<foundry-account-name>" # the account name, not a project or deployment name
export IDENTITY="id-aigateway-backends" # the user-assigned identity to create
echo "๐ Gateway $GATEWAY in $RG, with provider $PROVIDER and Foundry account $FOUNDRY_ACCOUNT"
echo "๐ค Identity to create: $IDENTITY"
# Read the Foundry account's resource ID and the gateway's runtime URL, and set the alias that you call
export FOUNDRY_ID="$(az cognitiveservices account show -g "$FOUNDRY_RG" -n "$FOUNDRY_ACCOUNT" --query id -o tsv)"
export AI_GATEWAY_URL="https://$(az aigateway show -g "$RG" -n "$GATEWAY" --query properties.frontend.defaultHostname -o tsv)"
export AI_GATEWAY_MODEL="<model-name>" # the alias you called in lab 02
echo "๐ Foundry account: $FOUNDRY_ID"
echo "๐ Runtime URL: $AI_GATEWAY_URL"
echo "๐ Model alias: $AI_GATEWAY_MODEL"
# Paste the runtime key from lab 02 without showing it, and don't commit it or write it to a file
printf "AI Gateway API key: " && read -rs AI_GATEWAY_API_KEY && export AI_GATEWAY_API_KEY && echo
echo "๐ Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"# Set your gateway, its Foundry provider and Foundry account, and the name of the user-assigned identity to create
$RG = "<resource-group>"
$GATEWAY = "<gateway>"
$PROVIDER = "<provider-name>" # the Foundry provider from lab 02, for example foundry-models
$FOUNDRY_RG = "<foundry-resource-group>" # resource group of the Foundry account
$FOUNDRY_ACCOUNT = "<foundry-account-name>" # the account name, not a project or deployment name
$IDENTITY = "id-aigateway-backends" # the user-assigned identity to create
Write-Host "๐ Gateway $GATEWAY in $RG, with provider $PROVIDER and Foundry account $FOUNDRY_ACCOUNT"
Write-Host "๐ค Identity to create: $IDENTITY"
# Read the Foundry account's resource ID and the gateway's runtime URL, and set the alias that you call
$FOUNDRY_ID = az cognitiveservices account show -g $FOUNDRY_RG -n $FOUNDRY_ACCOUNT --query id -o tsv
$env:AI_GATEWAY_URL = "https://$(az aigateway show -g $RG -n $GATEWAY --query properties.frontend.defaultHostname -o tsv)"
$env:AI_GATEWAY_MODEL = "<model-name>" # the alias you called in lab 02
Write-Host "๐ Foundry account: $FOUNDRY_ID"
Write-Host "๐ Runtime URL: $env:AI_GATEWAY_URL"
Write-Host "๐ Model alias: $env:AI_GATEWAY_MODEL"
# Paste the runtime key from lab 02 without showing it, and don't commit it or write it to a file
$env:AI_GATEWAY_API_KEY = Read-Host "AI Gateway API key" -MaskInput
Write-Host "๐ Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"Don't remember the provider name? List the Foundry providers:
az aigateway model-provider list -g "$RG" --gateway-name "$GATEWAY" --query "[?properties.modelProviderType=='Foundry'].name" -o tsv.
How it works
Every call crosses two boundaries. Inbound, the caller proves who it is to the gateway with a runtime API key (lab 10) or a Microsoft Entra token (lab 11). Outbound, the gateway proves who it is to the backend. The caller never sends a backend credential: you configure it once on the asset, such as a model provider or an MCP server backend.
For Azure backends, use a managed identity. The gateway requests a Microsoft Entra token for the backend's
audience, https://cognitiveservices.azure.com/ for Foundry, and Azure RBAC on the backend decides what the
identity can do. For Foundry and Azure OpenAI, grant Foundry User on the account. Keep backend API keys for
backends that can't accept an Entra token.
| System-assigned identity | User-assigned identity | Stored backend key | |
|---|---|---|---|
| Created by | Azure, with the gateway. The portal enables it by default. | You, as its own Azure resource | The backend's owner |
| Lifecycle | Tied to the gateway. Deleting the gateway deletes it. | Independent. Attach it to many gateways and keep it when a gateway is recreated. | You store it in the gateway and rotate it |
| Best for | One gateway calling Azure backends | Sharing one identity and its role assignments across gateways | Third-party providers and tools without Entra support |
| Foundry provider setting | authentication.managedIdentity without clientId | authentication.managedIdentity.clientId set to the identity's client ID | authentication.headers, for example an api-key header |
Attaching an identity to the gateway doesn't change which identity an asset uses. Each asset names its identity, so you can move assets one at a time.
The table uses the field names of API version 2026-11-01, where authentication sits at the top level of the
provider's properties, next to foundry. The az aigateway output shows the same shape. Only its --foundry
argument still takes authentication as one of the Foundry settings, and the CLI writes it to the top level.
Check the system-assigned identity
Lab 02's provider calls Foundry with the gateway's system-assigned identity. See it before you change anything.
Look at the identity in the portal
- Open the AI Gateway portal and select your gateway.
- Select Managed identities. On Configure identities, the System-assigned identity card shows Enabled with a Principal ID and a Tenant ID.
- Select View access. Backend access lists the assets that authenticate with a managed identity. Your Foundry provider appears with System-assigned as its identity and Foundry User as its role.
Check it with the CLI
# Show the gateway's identities: the type, and the system-assigned identity's principal and tenant IDs
echo "๐ค Identities of $GATEWAY:"
az aigateway identity show -g "$RG" -n "$GATEWAY" -o json# Show the gateway's identities: the type, and the system-assigned identity's principal and tenant IDs
Write-Host "๐ค Identities of ${GATEWAY}:"
az aigateway identity show -g $RG -n $GATEWAY -o jsonThe output shows type, which includes SystemAssigned, and the system-assigned principalId and tenantId.
If the command reports that no identity is assigned to the gateway, enable the system-assigned identity and grant
the new principal Foundry User on the Foundry account. identity assign returns when the gateway is ready
again:
# Turn on the gateway's system-assigned identity, and wait until the gateway is ready again
az aigateway identity assign -g "$RG" -n "$GATEWAY" --system-assigned true -o none &&
echo "๐ค The system-assigned identity of $GATEWAY is on"
# Read the principal ID of the system-assigned identity
PRINCIPAL_ID="$(az aigateway show -g "$RG" -n "$GATEWAY" --query identity.principalId -o tsv)"
echo "๐ค Gateway identity: $PRINCIPAL_ID"
# Give the identity the Foundry User role on the Foundry account, so that the gateway can call its models
az role assignment create --assignee-object-id "$PRINCIPAL_ID" --assignee-principal-type ServicePrincipal \
--role "53ca6127-db72-4b80-b1b0-d745d6d5456d" --scope "$FOUNDRY_ID" -o none &&
echo "๐ The gateway's identity has the Foundry User role on the Foundry account"# Turn on the gateway's system-assigned identity, and wait until the gateway is ready again
az aigateway identity assign -g $RG -n $GATEWAY --system-assigned true -o none
if ($?) { Write-Host "๐ค The system-assigned identity of $GATEWAY is on" }
# Read the principal ID of the system-assigned identity
$PRINCIPAL_ID = az aigateway show -g $RG -n $GATEWAY --query identity.principalId -o tsv
Write-Host "๐ค Gateway identity: $PRINCIPAL_ID"
# Give the identity the Foundry User role on the Foundry account, so that the gateway can call its models
az role assignment create --assignee-object-id $PRINCIPAL_ID --assignee-principal-type ServicePrincipal `
--role "53ca6127-db72-4b80-b1b0-d745d6d5456d" --scope $FOUNDRY_ID -o none
if ($?) { Write-Host "๐ The gateway's identity has the Foundry User role on the Foundry account" }Don't turn off the system-assigned identity while assets use it. Disabling it recycles the service principal: every backend configured with it fails until you enable it again, and a re-enabled identity gets a new principal ID without the old role assignments.
Create a user-assigned identity and give it access
Pick one track. Each track creates the identity, attaches it to the gateway, and grants it Foundry User on the Foundry account.
Create and attach the identity
- In Managed identitiesConfigure identities, under User-assigned identities, select Add identity.
- Select Create new and, in Name, replace the default, the gateway's name, with the name from
$IDENTITY, for exampleid-aigateway-backends. The portal creates the identity in the gateway's subscription, resource group, and region, which it shows below the name. - Select Add identity. The new identity appears in the table with its Principal and Client ID.
To reuse an identity that already exists, select Use existing instead, then pick its Subscription and User-assigned managed identity.
Read the identity's IDs
You need the principal ID to grant access and the client ID to point the provider at the identity.
# Read the identity's IDs: the resource ID to attach it, the principal ID to grant it access, and the client ID
# to point the provider at it
export IDENTITY_ID="$(az identity show -g "$RG" -n "$IDENTITY" --query id -o tsv)"
export IDENTITY_CLIENT_ID="$(az identity show -g "$RG" -n "$IDENTITY" --query clientId -o tsv)"
export IDENTITY_PRINCIPAL_ID="$(az identity show -g "$RG" -n "$IDENTITY" --query principalId -o tsv)"
echo "๐ Identity: $IDENTITY_ID"
echo "๐ค Client ID: $IDENTITY_CLIENT_ID"
echo "๐ค Principal ID: $IDENTITY_PRINCIPAL_ID"# Read the identity's IDs: the resource ID to attach it, the principal ID to grant it access, and the client ID
# to point the provider at it
$IDENTITY_ID = az identity show -g $RG -n $IDENTITY --query id -o tsv
$IDENTITY_CLIENT_ID = az identity show -g $RG -n $IDENTITY --query clientId -o tsv
$IDENTITY_PRINCIPAL_ID = az identity show -g $RG -n $IDENTITY --query principalId -o tsv
Write-Host "๐ Identity: $IDENTITY_ID"
Write-Host "๐ค Client ID: $IDENTITY_CLIENT_ID"
Write-Host "๐ค Principal ID: $IDENTITY_PRINCIPAL_ID"Grant Foundry User on the Foundry account
Attaching an identity doesn't grant it any access. In the Azure portal, open the Foundry account and select Access control (IAM)AddAdd role assignment. Select Foundry User, assign access to Managed identity, select your identity as the member, then select Review + assign.
Or grant the role from the command line:
# Give your identity the Foundry User role on the Foundry account, so that it can call the account's models
az role assignment create --assignee-object-id "$IDENTITY_PRINCIPAL_ID" --assignee-principal-type ServicePrincipal \
--role "53ca6127-db72-4b80-b1b0-d745d6d5456d" --scope "$FOUNDRY_ID" -o none &&
echo "๐ Identity $IDENTITY has the Foundry User role on the Foundry account"# Give your identity the Foundry User role on the Foundry account, so that it can call the account's models
az role assignment create --assignee-object-id $IDENTITY_PRINCIPAL_ID --assignee-principal-type ServicePrincipal `
--role "53ca6127-db72-4b80-b1b0-d745d6d5456d" --scope $FOUNDRY_ID -o none
if ($?) { Write-Host "๐ Identity $IDENTITY has the Foundry User role on the Foundry account" }User-assigned identities lists your identity, and the Foundry account's Access control (IAM)Role assignments shows it with Foundry User.
Create the identity
# Create the user-assigned identity, in the resource group's region
az identity create -g "$RG" -n "$IDENTITY" -o none &&
echo "๐ค Identity $IDENTITY is ready"
# Read the identity's IDs: the resource ID to attach it, the principal ID to grant it access, and the client ID
# to point the provider at it
export IDENTITY_ID="$(az identity show -g "$RG" -n "$IDENTITY" --query id -o tsv)"
export IDENTITY_CLIENT_ID="$(az identity show -g "$RG" -n "$IDENTITY" --query clientId -o tsv)"
export IDENTITY_PRINCIPAL_ID="$(az identity show -g "$RG" -n "$IDENTITY" --query principalId -o tsv)"
echo "๐ Identity: $IDENTITY_ID"
echo "๐ค Client ID: $IDENTITY_CLIENT_ID"
echo "๐ค Principal ID: $IDENTITY_PRINCIPAL_ID"# Create the user-assigned identity, in the resource group's region
az identity create -g $RG -n $IDENTITY -o none
if ($?) { Write-Host "๐ค Identity $IDENTITY is ready" }
# Read the identity's IDs: the resource ID to attach it, the principal ID to grant it access, and the client ID
# to point the provider at it
$IDENTITY_ID = az identity show -g $RG -n $IDENTITY --query id -o tsv
$IDENTITY_CLIENT_ID = az identity show -g $RG -n $IDENTITY --query clientId -o tsv
$IDENTITY_PRINCIPAL_ID = az identity show -g $RG -n $IDENTITY --query principalId -o tsv
Write-Host "๐ Identity: $IDENTITY_ID"
Write-Host "๐ค Client ID: $IDENTITY_CLIENT_ID"
Write-Host "๐ค Principal ID: $IDENTITY_PRINCIPAL_ID"The identity is created in the resource group's region. It can live in any resource group or subscription in the gateway's tenant.
Attach it to the gateway
identity assign adds your identity and keeps the identities the gateway already has, including the
system-assigned one. It returns when the gateway is ready again.
# Attach your identity to the gateway, keep its other identities, and wait until the gateway is ready again
az aigateway identity assign -g "$RG" -n "$GATEWAY" --user-assigned "$IDENTITY_ID" -o none &&
echo "๐ค Identity $IDENTITY is attached to $GATEWAY"# Attach your identity to the gateway, keep its other identities, and wait until the gateway is ready again
az aigateway identity assign -g $RG -n $GATEWAY --user-assigned $IDENTITY_ID -o none
if ($?) { Write-Host "๐ค Identity $IDENTITY is attached to $GATEWAY" }Grant Foundry User on the Foundry account
# Give your identity the Foundry User role on the Foundry account, so that it can call the account's models
az role assignment create --assignee-object-id "$IDENTITY_PRINCIPAL_ID" --assignee-principal-type ServicePrincipal \
--role "53ca6127-db72-4b80-b1b0-d745d6d5456d" --scope "$FOUNDRY_ID" -o none &&
echo "๐ Identity $IDENTITY has the Foundry User role on the Foundry account"# Give your identity the Foundry User role on the Foundry account, so that it can call the account's models
az role assignment create --assignee-object-id $IDENTITY_PRINCIPAL_ID --assignee-principal-type ServicePrincipal `
--role "53ca6127-db72-4b80-b1b0-d745d6d5456d" --scope $FOUNDRY_ID -o none
if ($?) { Write-Host "๐ Identity $IDENTITY has the Foundry User role on the Foundry account" }Grant the role on the Foundry account itself, the resource that the provider calls.
az aigateway identity show -g "$RG" -n "$GATEWAY" --query userAssignedIdentities -o json lists your identity,
with its clientId and principalId, and
az role assignment list --assignee "$IDENTITY_PRINCIPAL_ID" --scope "$FOUNDRY_ID" --query "[].roleDefinitionName" -o tsv
prints Foundry User.
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 templates declare the identity, its Foundry User role on the Foundry account, and the gateway's identities.
A deployment that declares the gateway sets its whole identity block, and the gateway keeps only the identities that
the block lists. That's why the other tracks attach the identity with az aigateway identity assign, which keeps the
identities the gateway already has. Here azd owns the gateway, so a template can list both the system-assigned
identity and yours.
The Foundry provider keeps the system-assigned identity for now. You point it at your identity in the next section, which gives the role assignment time to take effect.
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. That provider calls Foundry with the gateway's system-assigned identity. Then main.bicep calls
the lab's templates for your identity:
// Lab 12 with azd: "azd up" creates the resource group rg-<environment name> and the quick start's gateway, Foundry
// model, default alias, and runtime API key. Then it creates a user-assigned identity, grants it Foundry User on
// the Foundry account, and attaches it to the gateway. Set USE_USER_ASSIGNED_IDENTITY to true and run
// "azd provision" to point the Foundry provider at the identity. 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('Name of the user-assigned managed identity. azd reads it from IDENTITY_NAME.')
param identityName string = 'id-aigateway-backends'
@description('Point the Foundry provider at the user-assigned identity. azd reads it from USE_USER_ASSIGNED_IDENTITY.')
param useUserAssignedIdentity bool = false
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. Its
// provider uses the gateway's system-assigned identity.
module base '../../quickstart/infra/resources.bicep' = {
name: 'aigw-base'
scope: rg
params: {
location: location
tags: tags
gatewayName: 'aigw-${suffix}'
foundryName: 'aigw${suffix}'
}
}
module identity 'backend-identity.bicep' = {
name: 'aigw-backend-identity'
scope: rg
params: {
identityName: identityName
location: location
foundryAccountId: base.outputs.foundryId
}
}
module gatewayIdentity 'gateway-identity.bicep' = {
name: 'aigw-gateway-identity'
scope: rg
params: {
gatewayName: base.outputs.gatewayName
location: location
tags: tags
identityId: identity.outputs.identityId
}
}
module provider 'provider.bicep' = if (useUserAssignedIdentity) {
name: 'aigw-provider-identity'
scope: rg
params: {
gatewayName: gatewayIdentity.outputs.gatewayName
providerName: base.outputs.providerName
foundryAccountId: base.outputs.foundryId
identityClientId: identity.outputs.clientId
}
}
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 FOUNDRY_ID string = base.outputs.foundryId
output IDENTITY_NAME string = identityName
output IDENTITY_ID string = identity.outputs.identityId
output IDENTITY_CLIENT_ID string = identity.outputs.clientId
output IDENTITY_PRINCIPAL_ID string = identity.outputs.principalId
output PROVIDER_IDENTITY string = useUserAssignedIdentity ? identity.outputs.clientId : 'system-assigned'infra/backend-identity.bicep creates the user-assigned identity and calls infra/foundry-user-role.bicep in the
Foundry account's resource group to grant it Foundry User. The account can be in another resource group or
subscription, so you can also deploy this template on its own with az deployment group create, passing
identityName and foundryAccountId:
// Creates a user-assigned managed identity for AI Gateway to call its backends with, and grants that identity
// the Foundry User role on an existing Foundry (Azure AI Services) or Azure OpenAI account.
// Attaching the identity to the gateway is a separate step, with az aigateway identity assign or
// gateway-identity.bicep: declaring the gateway here would redeploy the whole gateway resource. Point a model
// provider at the identity afterwards with provider.bicep or az aigateway model-provider update.
// infra/main.bicep calls this template, gateway-identity.bicep, and provider.bicep for azd.
targetScope = 'resourceGroup'
@description('Name of the user-assigned managed identity to create.')
param identityName string = 'id-aigateway-backends'
@description('Region of the identity. Defaults to the resource group region.')
param location string = resourceGroup().location
@description('Resource ID of the Foundry (Azure AI Services) or Azure OpenAI account. It can be in another resource group or subscription.')
param foundryAccountId string
var foundryAccountName = last(split(foundryAccountId, '/'))
var foundrySubscriptionId = split(foundryAccountId, '/')[2]
var foundryResourceGroup = split(foundryAccountId, '/')[4]
resource backendIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-01-31' = {
name: identityName
location: location
}
module foundryUserRole './foundry-user-role.bicep' = {
name: take('foundry-user-${uniqueString(backendIdentity.id, foundryAccountId)}', 64)
scope: resourceGroup(foundrySubscriptionId, foundryResourceGroup)
params: {
foundryAccountName: foundryAccountName
principalId: backendIdentity.properties.principalId
}
}
output identityId string = backendIdentity.id
output clientId string = backendIdentity.properties.clientId
output principalId string = backendIdentity.properties.principalId
output foundryUserRoleAssignmentName string = foundryUserRole.outputs.roleAssignmentName// Grants a managed identity the Foundry User role on a Foundry (Azure AI Services) or Azure OpenAI account, so
// AI Gateway can call the account's model deployments with that identity and no keys.
// Adapted from lab 02's foundry-user-role.bicep, which grants the same role to the gateway's system identity.
targetScope = 'resourceGroup'
@description('Name of the Foundry (Azure AI Services) or Azure OpenAI account.')
param foundryAccountName string
@description('Principal (object) ID of the managed identity that receives the role.')
param principalId string
var foundryUserRoleDefinitionId = '53ca6127-db72-4b80-b1b0-d745d6d5456d'
resource foundryAccount 'Microsoft.CognitiveServices/accounts@2025-04-01-preview' existing = {
name: foundryAccountName
}
resource foundryUserRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
scope: foundryAccount
name: guid(foundryAccount.id, principalId, foundryUserRoleDefinitionId)
properties: {
principalId: principalId
principalType: 'ServicePrincipal'
roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', foundryUserRoleDefinitionId)
}
}
output roleAssignmentName string = foundryUserRoleAssignment.nameinfra/gateway-identity.bicep deploys the gateway again with both identities. Every azd provision deploys the
quick start's gateway with only its system-assigned identity first, then attaches yours again here:
// Attaches a user-assigned managed identity to an AI Gateway and keeps its system-assigned identity.
// A deployment sets the gateway's whole identity block, so the gateway keeps only the identities listed here. The
// template redeclares the gateway with the region and tags of the quick start's template, which
// infra/main.bicep deploys first: every "azd provision" sets the system-assigned identity there, then attaches the
// user-assigned identity again here. On a gateway you created another way, attach the identity with
// az aigateway identity assign instead, which keeps the identities the gateway already has.
targetScope = 'resourceGroup'
@description('Name of the existing AI Gateway (Microsoft.ApiManagement/aigateways) in this resource group.')
param gatewayName string
@description('Region of the gateway.')
param location string = resourceGroup().location
@description('Tags of the gateway.')
param tags object = {}
@description('Resource ID of the user-assigned managed identity to attach.')
param identityId string
#disable-next-line BCP081
resource gateway 'Microsoft.ApiManagement/aigateways@2026-11-01' = {
name: gatewayName
location: location
tags: tags
identity: {
type: 'SystemAssigned, UserAssigned'
userAssignedIdentities: {
'${identityId}': {}
}
}
properties: {}
}
output gatewayName string = gateway.name
output principalId string = gateway.identity.principalIdDeploy with azd up
Move into the lab's folder, create an azd environment named aigw-lab12 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/12-backend-identity &&
echo "๐ Lab folder: $(pwd)"
# Create an azd environment in your current subscription, so that azd doesn't prompt you
azd env new aigw-lab12 --location eastus2 --subscription "$(az account show --query id --output tsv)" &&
echo "๐ azd environment aigw-lab12 deploys to eastus2"
# Provision the gateway, the Foundry model, the alias, the key, and your identity with its role
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/12-backend-identity
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-lab12 --location eastus2 --subscription (az account show --query id --output tsv)
if ($?) { Write-Host "๐ azd environment aigw-lab12 deploys to eastus2" }
# Provision the gateway, the Foundry model, the alias, the key, and your identity with its role
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 and the key
Set the variables that the next sections, Verify, and Clean up use from azd's environment values, and read the key from the gateway, so that it never shows on screen. The last command lists the user-assigned identities attached to the gateway.
# Read the template's outputs: the names, the runtime URL, the alias, and the identity's IDs
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 IDENTITY="$(azd env get-value IDENTITY_NAME)"
export FOUNDRY_ID="$(azd env get-value FOUNDRY_ID)"
export AI_GATEWAY_URL="$(azd env get-value AI_GATEWAY_URL)"
export AI_GATEWAY_MODEL="$(azd env get-value AI_GATEWAY_MODEL)"
export IDENTITY_ID="$(azd env get-value IDENTITY_ID)"
export IDENTITY_CLIENT_ID="$(azd env get-value IDENTITY_CLIENT_ID)"
export IDENTITY_PRINCIPAL_ID="$(azd env get-value IDENTITY_PRINCIPAL_ID)"
# Read the key from the gateway, so that it never lands in a file or a deployment log
export AI_GATEWAY_API_KEY="$(az aigateway api-key list-secrets --ids "$(azd env get-value AI_GATEWAY_ID)/apiKeys/app-first-call" \
--query primaryKey --output tsv)"
echo "๐ Gateway $GATEWAY in $RG, with provider $PROVIDER and identity $IDENTITY"
echo "๐ Runtime URL: $AI_GATEWAY_URL"
echo "๐ Model alias: $AI_GATEWAY_MODEL"
echo "๐ค Client ID: $IDENTITY_CLIENT_ID"
echo "๐ Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"
# List the user-assigned identities attached to the gateway
echo "๐ค User-assigned identities of $GATEWAY:"
az aigateway identity show -g "$RG" -n "$GATEWAY" --query userAssignedIdentities -o json# Read the template's outputs: the names, the runtime URL, the alias, and the identity's IDs
$RG = azd env get-value AZURE_RESOURCE_GROUP
$GATEWAY = azd env get-value AI_GATEWAY_NAME
$PROVIDER = azd env get-value AI_GATEWAY_PROVIDER
$IDENTITY = azd env get-value IDENTITY_NAME
$FOUNDRY_ID = azd env get-value FOUNDRY_ID
$env:AI_GATEWAY_URL = azd env get-value AI_GATEWAY_URL
$env:AI_GATEWAY_MODEL = azd env get-value AI_GATEWAY_MODEL
$IDENTITY_ID = azd env get-value IDENTITY_ID
$IDENTITY_CLIENT_ID = azd env get-value IDENTITY_CLIENT_ID
$IDENTITY_PRINCIPAL_ID = azd env get-value IDENTITY_PRINCIPAL_ID
# Read the key from the gateway, so that it never lands in a file or a deployment log
$env:AI_GATEWAY_API_KEY = az aigateway api-key list-secrets --ids "$(azd env get-value AI_GATEWAY_ID)/apiKeys/app-first-call" `
--query primaryKey --output tsv
Write-Host "๐ Gateway $GATEWAY in $RG, with provider $PROVIDER and identity $IDENTITY"
Write-Host "๐ Runtime URL: $env:AI_GATEWAY_URL"
Write-Host "๐ Model alias: $env:AI_GATEWAY_MODEL"
Write-Host "๐ค Client ID: $IDENTITY_CLIENT_ID"
Write-Host "๐ Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"
# List the user-assigned identities attached to the gateway
Write-Host "๐ค User-assigned identities of ${GATEWAY}:"
az aigateway identity show -g $RG -n $GATEWAY --query userAssignedIdentities -o jsonazd up ended with SUCCESS, and the list shows your identity, keyed by its resource ID, with its clientId and
principalId.
az role assignment list --assignee "$IDENTITY_PRINCIPAL_ID" --scope "$FOUNDRY_ID" --query "[].roleDefinitionName" -o tsv
prints Foundry User.
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
The configuration declares the identity, its Foundry User role on the Foundry account, and the gateway's
identities. The gateway's identity block lists every identity the gateway keeps, so the configuration lists both
the system-assigned identity and yours. Terraform owns the gateway here: if you attach another identity with
az aigateway identity assign, the next plan detaches it again.
For that reason, this lab doesn't call the quick start's resources module,
whose gateway lists only the system-assigned identity. terraform/main.tf declares the same resources itself: the
gateway, the Foundry model, its default alias, and the app-first-call key. The Foundry provider keeps the
system-assigned identity for now. You point it at your identity in the next section, which gives the role
assignment time to take effect.
Review the configuration
terraform/main.tf creates the resource group rg-<environment_name>, the gateway with both identities, and the
Foundry account with its model:
# Lab 12 with Terraform: creates the resource group rg-<environment_name>, the quick start's gateway, Foundry model,
# default alias, and runtime API key, then your user-assigned identity with Foundry User on the Foundry account
# (backend-identity.tf). Set use_user_assigned_identity to true to point the Foundry provider at the identity
# (model-provider.tf). The runtime API key is never an output.
#
# The quick start's module declares the gateway with only its system-assigned identity, and the gateway keeps only
# the identities that its identity block lists. So this lab declares the module's resources itself, with a gateway
# that lists both identities.
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 }
gateway_name = "aigw-${local.suffix}"
foundry_name = "aigw${local.suffix}"
model_name = "gpt-5-mini"
model_version = "2025-08-07"
foundry_user_role_id = "53ca6127-db72-4b80-b1b0-d745d6d5456d"
workspace_id = "${azapi_resource.gateway.id}/workspaces/default"
}
resource "azurerm_resource_group" "rg" {
name = "rg-${var.environment_name}"
location = var.location
tags = local.tags
}
# The gateway, with its system-assigned identity and your user-assigned identity. It omits sku, so it gets the
# default SKU.
resource "azapi_resource" "gateway" {
type = "Microsoft.ApiManagement/aigateways@2026-11-01"
name = local.gateway_name
parent_id = azurerm_resource_group.rg.id
location = var.location
tags = local.tags
identity {
type = "SystemAssigned, UserAssigned"
identity_ids = [azurerm_user_assigned_identity.backends.id]
}
body = {
properties = {}
}
schema_validation_enabled = false
response_export_values = ["properties.frontend.defaultHostname"]
# Activation can take longer than azapi's default 30 minutes in some regions.
timeouts {
create = "60m"
}
}
# A Foundry account with one model deployment. Local auth is off: only Entra identities can call it.
resource "azurerm_cognitive_account" "foundry" {
name = local.foundry_name
resource_group_name = azurerm_resource_group.rg.name
location = var.location
tags = local.tags
kind = "AIServices"
sku_name = "S0"
custom_subdomain_name = local.foundry_name
local_auth_enabled = false
}
resource "azurerm_cognitive_deployment" "model" {
name = local.model_name
cognitive_account_id = azurerm_cognitive_account.foundry.id
sku {
name = "GlobalStandard"
capacity = 10
}
model {
format = "OpenAI"
name = local.model_name
version = local.model_version
}
}
# The quick start's provider calls Foundry with the gateway's system-assigned identity, which needs Foundry User too.
resource "azurerm_role_assignment" "gateway_foundry_user" {
name = uuidv5("url", "${azurerm_cognitive_account.foundry.id}/${azapi_resource.gateway.id}/${local.foundry_user_role_id}")
scope = azurerm_cognitive_account.foundry.id
role_definition_id = "/subscriptions/${data.azapi_client_config.current.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/${local.foundry_user_role_id}"
principal_id = azapi_resource.gateway.identity[0].principal_id
principal_type = "ServicePrincipal"
skip_service_principal_aad_check = true
}
# The deployment as a backend model of the provider, and an alias that apps send in the "model" field.
resource "azapi_resource" "model" {
type = "Microsoft.ApiManagement/aigateways/workspaces/modelProviders/models@2026-11-01"
name = local.model_name
parent_id = azapi_resource.provider.id
body = {
properties = {
displayName = local.model_name
supportedEndpoints = [
"/openai/v1/chat/completions",
"/openai/v1/responses",
]
deployment = {
resourceId = azurerm_cognitive_deployment.model.id
modelName = local.model_name
modelVersion = local.model_version
}
}
}
schema_validation_enabled = false
}
resource "azapi_resource" "alias" {
type = "Microsoft.ApiManagement/aigateways/workspaces/aliases@2026-11-01"
name = local.model_name
parent_id = local.workspace_id
body = {
properties = {
aliasName = local.model_name
backendModels = [
{
resourceId = azapi_resource.model.id
},
]
}
}
schema_validation_enabled = false
}
# The app-first-call key. Read its value with az aigateway api-key list-secrets.
resource "azapi_resource" "api_key" {
type = "Microsoft.ApiManagement/aigateways/apiKeys@2026-11-01"
name = "app-first-call"
parent_id = azapi_resource.gateway.id
body = {
properties = {
displayName = "app-first-call"
}
}
schema_validation_enabled = false
}terraform/backend-identity.tf creates your identity and grants it Foundry User on the Foundry account. Set the
identity_name variable for another name:
# A user-assigned managed identity for the gateway to call its backends with, and the Foundry User role on the
# Foundry account, so that the identity can call the account's model deployments with no keys. main.tf attaches the
# identity to the gateway.
resource "azurerm_user_assigned_identity" "backends" {
name = var.identity_name
resource_group_name = azurerm_resource_group.rg.name
location = var.location
tags = local.tags
}
resource "azurerm_role_assignment" "identity_foundry_user" {
name = uuidv5("url", "${azurerm_cognitive_account.foundry.id}/${azurerm_user_assigned_identity.backends.id}/${local.foundry_user_role_id}")
scope = azurerm_cognitive_account.foundry.id
role_definition_id = "/subscriptions/${data.azapi_client_config.current.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/${local.foundry_user_role_id}"
principal_id = azurerm_user_assigned_identity.backends.principal_id
principal_type = "ServicePrincipal"
skip_service_principal_aad_check = true
}Deploy with terraform apply
Move into the lab's Terraform folder, select your current subscription, then plan and apply the configuration. It takes about three minutes, most of it while the new gateway activates.
# Move into the lab's Terraform folder
cd ~/aigateway/labs/12-backend-identity/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, the alias, the key, and your identity
# with its role
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/12-backend-identity/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, the alias, the key, and your identity
# with its role
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 and the key
Set the variables that the next sections, Verify, and Clean up use from the Terraform outputs, and read the key from the gateway, so that it never shows on screen. The last command lists the user-assigned identities attached to the gateway.
# Read the configuration's outputs: the names, the runtime URL, the alias, and the identity's IDs
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 IDENTITY="$(terraform output -raw identity_name)"
export FOUNDRY_ID="$(terraform output -raw foundry_id)"
export AI_GATEWAY_URL="$(terraform output -raw ai_gateway_url)"
export AI_GATEWAY_MODEL="$(terraform output -raw ai_gateway_model)"
export IDENTITY_ID="$(terraform output -raw identity_id)"
export IDENTITY_CLIENT_ID="$(terraform output -raw identity_client_id)"
export IDENTITY_PRINCIPAL_ID="$(terraform output -raw identity_principal_id)"
# Read the key from the gateway, so that it never lands in a file or the Terraform state's outputs
export AI_GATEWAY_API_KEY="$(az aigateway api-key list-secrets --ids "$(terraform output -raw ai_gateway_id)/apiKeys/app-first-call" \
--query primaryKey --output tsv)"
echo "๐ Gateway $GATEWAY in $RG, with provider $PROVIDER and identity $IDENTITY"
echo "๐ Runtime URL: $AI_GATEWAY_URL"
echo "๐ Model alias: $AI_GATEWAY_MODEL"
echo "๐ค Client ID: $IDENTITY_CLIENT_ID"
echo "๐ Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"
# List the user-assigned identities attached to the gateway
echo "๐ค User-assigned identities of $GATEWAY:"
az aigateway identity show -g "$RG" -n "$GATEWAY" --query userAssignedIdentities -o json# Read the configuration's outputs: the names, the runtime URL, the alias, and the identity's IDs
$RG = terraform output -raw azure_resource_group
$GATEWAY = terraform output -raw ai_gateway_name
$PROVIDER = terraform output -raw ai_gateway_provider
$IDENTITY = terraform output -raw identity_name
$FOUNDRY_ID = terraform output -raw foundry_id
$env:AI_GATEWAY_URL = terraform output -raw ai_gateway_url
$env:AI_GATEWAY_MODEL = terraform output -raw ai_gateway_model
$IDENTITY_ID = terraform output -raw identity_id
$IDENTITY_CLIENT_ID = terraform output -raw identity_client_id
$IDENTITY_PRINCIPAL_ID = terraform output -raw identity_principal_id
# Read the key from the gateway, so that it never lands in a file or the Terraform state's outputs
$env:AI_GATEWAY_API_KEY = az aigateway api-key list-secrets --ids "$(terraform output -raw ai_gateway_id)/apiKeys/app-first-call" `
--query primaryKey --output tsv
Write-Host "๐ Gateway $GATEWAY in $RG, with provider $PROVIDER and identity $IDENTITY"
Write-Host "๐ Runtime URL: $env:AI_GATEWAY_URL"
Write-Host "๐ Model alias: $env:AI_GATEWAY_MODEL"
Write-Host "๐ค Client ID: $IDENTITY_CLIENT_ID"
Write-Host "๐ Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"
# List the user-assigned identities attached to the gateway
Write-Host "๐ค User-assigned identities of ${GATEWAY}:"
az aigateway identity show -g $RG -n $GATEWAY --query userAssignedIdentities -o jsonterraform apply ended with Apply complete! Resources: 11 added, 0 changed, 0 destroyed., and the list shows
your identity, keyed by its resource ID, with its clientId and principalId.
az role assignment list --assignee "$IDENTITY_PRINCIPAL_ID" --scope "$FOUNDRY_ID" --query "[].roleDefinitionName" -o tsv
prints Foundry User.
Role assignments can take several minutes to take effect. If you switch the provider before then, model calls
fail with 403 from the backend until the assignment propagates.
Point the model provider at the identity
The provider still uses the system-assigned identity. Setting clientId in its managed identity settings
switches it to your identity. Clients don't change: they keep calling the same alias with the same key or token.
Update the provider's authentication
The portal picks the identity only when you import a Foundry account: the Authentication method step offers
Managed identity with a choice of the system-assigned identity or any attached user-assigned identity, and
grants the selected identity Foundry User. To switch a provider that already exists, run this Azure CLI
command, for example in Azure Cloud Shell. It sets clientId in the provider's
managed identity settings and keeps the rest:
# Set clientId to your identity's client ID; the CLI merges it into the provider's other settings
echo "๐ Authentication of $PROVIDER:"
az aigateway model-provider update -g "$RG" --gateway-name "$GATEWAY" -n "$PROVIDER" \
--foundry "{authentication:{managedIdentity:{clientId:$IDENTITY_CLIENT_ID}}}" \
--query properties.authentication# Set clientId to your identity's client ID; the CLI merges it into the provider's other settings
Write-Host "๐ Authentication of ${PROVIDER}:"
az aigateway model-provider update -g $RG --gateway-name $GATEWAY -n $PROVIDER `
--foundry "{authentication:{managedIdentity:{clientId:$IDENTITY_CLIENT_ID}}}" `
--query properties.authenticationUpdate the provider's authentication
--foundry takes only the settings to change: the CLI merges them into the provider's settings, and writes
authentication to the top level of its properties. Set clientId, and the endpoint and accounts stay as they
are. Models are separate resources, so they don't change.
# Set clientId to your identity's client ID; the CLI merges it into the provider's other settings
echo "๐ Authentication of $PROVIDER:"
az aigateway model-provider update -g "$RG" --gateway-name "$GATEWAY" -n "$PROVIDER" \
--foundry "{authentication:{managedIdentity:{clientId:$IDENTITY_CLIENT_ID}}}" \
--query properties.authentication# Set clientId to your identity's client ID; the CLI merges it into the provider's other settings
Write-Host "๐ Authentication of ${PROVIDER}:"
az aigateway model-provider update -g $RG --gateway-name $GATEWAY -n $PROVIDER `
--foundry "{authentication:{managedIdentity:{clientId:$IDENTITY_CLIENT_ID}}}" `
--query properties.authenticationRedeploy the provider with the identity
When useUserAssignedIdentity is true, infra/main.bicep calls infra/provider.bicep. It
redeploys the quick start's provider with the same endpoint and account, and adds clientId to its managed identity
settings. authentication sits at the top level of the provider's properties, and the setting it holds,
managedIdentity or headers, picks the method:
authentication: {
managedIdentity: {
resource: 'https://cognitiveservices.azure.com/'
clientId: identityClientId // omit clientId to use the system-assigned identity
}
}A deployment replaces the provider's properties, so the template sets all of them, including the display name, which
is required, and the description. Models and aliases are separate resources and aren't touched. You can also deploy
infra/provider.bicep on its own to a gateway that lab 02's Bicep track created, with az deployment group create,
passing gatewayName, providerName, foundryAccountId, and identityClientId. If you created the provider in
the portal or with the CLI, use the Azure CLI track's commands instead, which change only the authentication.
// Points an AI Gateway Foundry model provider at a managed identity.
// Set identityClientId to the client ID of a user-assigned identity that's attached to the gateway and holds
// Foundry User on the account. Leave it empty to switch back to the gateway's system-assigned identity.
// This redeploys the provider that lab 02's Bicep track creates, with the same endpoint and account. Deploying
// replaces the provider's properties, so pass the display name and description you want to keep. Models and
// aliases are separate resources and stay as they are.
targetScope = 'resourceGroup'
@description('Name of the existing AI Gateway (Microsoft.ApiManagement/aigateways) in this resource group.')
param gatewayName string
@description('Name of the existing Foundry model provider in the gateway.')
param providerName string = 'foundry-models'
@description('Resource ID of the Foundry (Azure AI Services) or Azure OpenAI account that the provider serves.')
param foundryAccountId string
@description('Client ID of a user-assigned managed identity attached to the gateway. Empty uses the system-assigned identity.')
param identityClientId string = ''
@description('Display name of the provider.')
param displayName string = 'Foundry models'
@description('Description of the provider.')
param providerDescription string = 'Managed-identity Foundry provider created by the first-model-call lab.'
var foundryAccountName = last(split(foundryAccountId, '/'))
var foundrySubscriptionId = split(foundryAccountId, '/')[2]
var foundryResourceGroup = split(foundryAccountId, '/')[4]
var cognitiveServicesAudience = 'https://cognitiveservices.azure.com/'
#disable-next-line BCP081
resource aiGateway 'Microsoft.ApiManagement/aigateways@2026-11-01' existing = {
name: gatewayName
}
#disable-next-line BCP081
resource defaultWorkspace 'Microsoft.ApiManagement/aigateways/workspaces@2026-11-01' existing = {
parent: aiGateway
name: 'default'
}
resource foundryAccount 'Microsoft.CognitiveServices/accounts@2025-04-01-preview' existing = {
scope: resourceGroup(foundrySubscriptionId, foundryResourceGroup)
name: foundryAccountName
}
var foundryEndpoint = foundryAccount.properties.endpoint
var normalizedFoundryEndpoint = endsWith(foundryEndpoint, '/') ? foundryEndpoint : '${foundryEndpoint}/'
#disable-next-line BCP081
resource foundryProvider 'Microsoft.ApiManagement/aigateways/workspaces/modelProviders@2026-11-01' = {
parent: defaultWorkspace
name: providerName
properties: {
modelProviderType: 'Foundry'
displayName: displayName
description: providerDescription
foundry: {
endpoint: {
url: normalizedFoundryEndpoint
}
resourceIds: [
foundryAccountId
]
}
// The identity that the gateway uses to call the account. Without clientId, it's the system-assigned identity.
authentication: {
managedIdentity: empty(identityClientId)
? {
resource: cognitiveServicesAudience
}
: {
resource: cognitiveServicesAudience
clientId: identityClientId
}
}
}
}
output providerName string = foundryProvider.name
output identityInUse string = empty(identityClientId) ? 'system-assigned' : identityClientIdazd reads the parameter from USE_USER_ASSIGNED_IDENTITY. Set it, provision again, and read the provider's
authentication settings:
# Tell azd to point the Foundry provider at your identity
azd env set USE_USER_ASSIGNED_IDENTITY true &&
echo "๐ USE_USER_ASSIGNED_IDENTITY is true"
# Provision again, which now redeploys the provider with infra/provider.bicep
azd provision &&
echo "๐ Provider $PROVIDER is redeployed with identity $IDENTITY"
# Show the provider's authentication settings
echo "๐ Authentication of $PROVIDER:"
az aigateway model-provider show -g "$RG" --gateway-name "$GATEWAY" -n "$PROVIDER" \
--query properties.authentication -o json# Tell azd to point the Foundry provider at your identity
azd env set USE_USER_ASSIGNED_IDENTITY true
if ($?) { Write-Host "๐ USE_USER_ASSIGNED_IDENTITY is true" }
# Provision again, which now redeploys the provider with infra/provider.bicep
azd provision
if ($?) { Write-Host "๐ Provider $PROVIDER is redeployed with identity $IDENTITY" }
# Show the provider's authentication settings
Write-Host "๐ Authentication of ${PROVIDER}:"
az aigateway model-provider show -g $RG --gateway-name $GATEWAY -n $PROVIDER `
--query properties.authentication -o jsonEach azd provision deploys the quick start's gateway and provider first, with the system-assigned identity, then
attaches your identity and points the provider at it again. In between, model calls can fail for a few seconds with
500, so don't provision again while the gateway serves real traffic. To switch back, set
USE_USER_ASSIGNED_IDENTITY to false and run azd provision.
Update the provider with the identity
terraform/model-provider.tf declares the Foundry provider. When the use_user_assigned_identity variable is
true, it adds your identity's clientId to the provider's managed identity settings. Otherwise clientId is
null, which leaves it out, so the provider uses the system-assigned identity:
# The Foundry model provider. It calls the account with a managed identity: the gateway's system-assigned identity,
# or your user-assigned identity when use_user_assigned_identity is true, which adds its clientId.
resource "azapi_resource" "provider" {
type = "Microsoft.ApiManagement/aigateways/workspaces/modelProviders@2026-11-01"
name = "foundry-models"
parent_id = local.workspace_id
body = {
properties = {
modelProviderType = "Foundry"
displayName = "Foundry models"
foundry = {
endpoint = {
url = "https://${local.foundry_name}.cognitiveservices.azure.com/"
}
resourceIds = [azurerm_cognitive_account.foundry.id]
}
authentication = {
managedIdentity = {
resource = "https://cognitiveservices.azure.com/"
# A null clientId is left out of the request, so the provider uses the system-assigned identity. Unlike a
# missing key, null makes the plan show the change when you switch back.
clientId = var.use_user_assigned_identity ? azurerm_user_assigned_identity.backends.client_id : null
}
}
}
}
schema_validation_enabled = false
depends_on = [
azurerm_role_assignment.gateway_foundry_user,
azurerm_role_assignment.identity_foundry_user,
]
}Plan the change with the variable, apply the plan, and read the provider's authentication settings:
# Plan the change: point the Foundry provider at your identity
terraform plan -var use_user_assigned_identity=true -out tfplan &&
echo "๐ The plan adds clientId to the provider's managed identity settings"
# Apply the plan, which updates only the provider
terraform apply tfplan &&
echo "๐ Provider $PROVIDER uses identity $IDENTITY"
# Show the provider's authentication settings
echo "๐ Authentication of $PROVIDER:"
az aigateway model-provider show -g "$RG" --gateway-name "$GATEWAY" -n "$PROVIDER" \
--query properties.authentication -o json# Plan the change: point the Foundry provider at your identity
terraform plan -var use_user_assigned_identity=true -out tfplan
if ($?) { Write-Host "๐ The plan adds clientId to the provider's managed identity settings" }
# Apply the plan, which updates only the provider
terraform apply tfplan
if ($?) { Write-Host "๐ Provider $PROVIDER uses identity $IDENTITY" }
# Show the provider's authentication settings
Write-Host "๐ Authentication of ${PROVIDER}:"
az aigateway model-provider show -g $RG --gateway-name $GATEWAY -n $PROVIDER `
--query properties.authentication -o jsonThe plan ends with Plan: 0 to add, 1 to change, 0 to destroy.: Terraform updates the provider in place, and the
gateway, models, and aliases don't change. Pass the same -var to every later plan. A plan without it switches the
provider back to the system-assigned identity, with the same one change.
The CLI output shows a managedIdentity with clientId equal to $IDENTITY_CLIENT_ID and resource set to
https://cognitiveservices.azure.com/: the provider's properties.authentication.managedIdentity.clientId.
Verify
Confirm which identity the provider uses
# Read the client ID that the provider signs in with, and compare it with your identity's client ID
PROVIDER_CLIENT_ID="$(az aigateway model-provider show -g "$RG" --gateway-name "$GATEWAY" -n "$PROVIDER" \
--query properties.authentication.managedIdentity.clientId -o tsv)"
echo "๐ Provider's client ID: $PROVIDER_CLIENT_ID"
echo "๐ค Identity's client ID: $IDENTITY_CLIENT_ID"# Read the client ID that the provider signs in with, and compare it with your identity's client ID
$PROVIDER_CLIENT_ID = az aigateway model-provider show -g $RG --gateway-name $GATEWAY -n $PROVIDER `
--query properties.authentication.managedIdentity.clientId -o tsv
Write-Host "๐ Provider's client ID: $PROVIDER_CLIENT_ID"
Write-Host "๐ค Identity's client ID: $IDENTITY_CLIENT_ID"Both lines print the same client ID. In the portal, Managed identitiesView access now lists your provider under your identity's name instead of System-assigned. The list reflects the configured binding, not the live role assignment on the Foundry account, so a missing role still shows up only as a failed call.
Call the model through the gateway
# Call the alias through the gateway with your runtime key, and print only the HTTP status code
echo "๐ค HTTP status of a call to $AI_GATEWAY_MODEL through the gateway:"
curl -sS -o /dev/null -w "HTTP %{http_code}\n" "${AI_GATEWAY_URL%/}/default/models/openai/v1/chat/completions" \
-H "Authorization: Bearer $AI_GATEWAY_API_KEY" -H "Content-Type: application/json" \
-d "{\"model\":\"$AI_GATEWAY_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"ping\"}]}"# Build a one-message request for the alias
$body = @{ model = $env:AI_GATEWAY_MODEL; messages = @(@{ role = "user"; content = "ping" }) } | ConvertTo-Json -Depth 5
# Call the alias through the gateway with your runtime key, and print only the HTTP status code
Write-Host "๐ค HTTP status of a call to $env:AI_GATEWAY_MODEL through the gateway:"
(Invoke-WebRequest -Method Post -Uri "$($env:AI_GATEWAY_URL.TrimEnd('/'))/default/models/openai/v1/chat/completions" `
-Headers @{ Authorization = "Bearer $env:AI_GATEWAY_API_KEY" } -ContentType "application/json" -Body $body -SkipHttpErrorCheck).StatusCodeExpect HTTP 200. A 403 that mentions permissions on the Foundry account means the role assignment hasn't
propagated yet: wait a few minutes and retry.
You called the same alias with the same key as in lab 02. Only the gateway's outbound credential changed, and no backend key was stored or sent.
The provider names your user-assigned identity, View access shows the new binding, and the model still
answers with 200.
Go further
Use stored credentials when a backend can't take a managed identity
Managed identity needs a backend that accepts Microsoft Entra tokens. When it doesn't, store the backend's own credential in the gateway, never in the calling app.
| Backend | How the gateway authenticates |
|---|---|
| Microsoft Foundry and Azure OpenAI | Managed identity (recommended) or API key, chosen in the import's Authentication method step |
| OpenAI, Anthropic, AWS Bedrock, Google Vertex AI, and other custom models | The provider's API key, entered when you add the custom model (lab 03) |
| MCP server backends | None, API key, OAuth 2.0, or Managed identity, set per backend (lab 04) |
- Prefer managed identity whenever the backend supports it.
- The gateway stores backend keys and tokens with the asset or connection and never returns them to clients.
- Rotate backend credentials on their own schedule. They're independent of the runtime keys callers use.
At API version 2026-11-01, a provider stores its key as one header in authentication.headers, in place of
managedIdentity, for example "authentication": { "headers": [ { "name": "api-key", "value": "<foundry-key>" } ] }
for Foundry. A read returns only the header's name, never its value. So a script that reads a provider and writes
it back must send the key again, or the provider loses it.
Call MCP backends as the signed-in user
A managed identity calls a backend as the gateway, so every caller gets the gateway's access. Some MCP backends, such as an expenses API, must instead see who the user is and return only that user's data. For those, an MCP server backend can use OAuth 2.0 with the On behalf of profile: the client signs the user in with a Microsoft Entra token for the gateway, and the gateway exchanges it for a delegated token for the backend. A token exchange app registration holds the delegated permissions, and a user-assigned identity attached to the gateway, like the one in this lab, authenticates that app through a federated credential, so no client secret is stored. See Access MCP server backends with user credentials. 33 ยท Connect Microsoft 365 Copilot to MCP tools as the signed-in user builds the whole chain, from Copilot Cowork to an MCP server on Azure Container Apps.
Drop access the system identity no longer needs
After every asset that calls the Foundry account uses the user-assigned identity, the system-assigned identity's
Foundry User assignment on that account is unused. Check View accessBackend access first: remove
the assignment only if no other asset lists System-assigned for that account, because later labs in this
series use it. A call that still returns 200 a few minutes after you remove it also proves that the provider
uses the user-assigned identity.
Clean up
Pick the track you followed.
Keep the system-assigned identity and its Foundry User role. Later labs use them. Remove the user-assigned identity in this order, so the provider never points at an identity it can't use.
Switch the provider back to the system-assigned identity
Removing clientId selects the system-assigned identity again. A null value removes a setting:
# Remove clientId (null removes a setting), so the provider signs in with the system-assigned identity again
echo "๐ Authentication of $PROVIDER:"
az aigateway model-provider update -g "$RG" --gateway-name "$GATEWAY" -n "$PROVIDER" \
--foundry "{authentication:{managedIdentity:{clientId:null}}}" \
--query properties.authentication# Remove clientId (null removes a setting), so the provider signs in with the system-assigned identity again
Write-Host "๐ Authentication of ${PROVIDER}:"
az aigateway model-provider update -g $RG --gateway-name $GATEWAY -n $PROVIDER `
--foundry "{authentication:{managedIdentity:{clientId:null}}}" `
--query properties.authenticationThe output no longer shows clientId.
Detach the identity from the gateway
Remove your identity from the gateway. identity remove returns when the gateway is ready again:
# Detach your identity from the gateway, and wait until the gateway is ready again
az aigateway identity remove -g "$RG" -n "$GATEWAY" --user-assigned "$IDENTITY_ID" -o none &&
echo "๐ฎ Identity $IDENTITY is detached from $GATEWAY"# Detach your identity from the gateway, and wait until the gateway is ready again
az aigateway identity remove -g $RG -n $GATEWAY --user-assigned $IDENTITY_ID -o none
if ($?) { Write-Host "๐ฎ Identity $IDENTITY is detached from $GATEWAY" }This detaches only your identity. The system-assigned identity and any other user-assigned identities stay attached.
In the portal, select the identity's checkbox in User-assigned identities, select the trash icon in the selection bar, then Detach. The confirmation says that detaching removes the identity from this gateway only: the identity and its role assignments stay.
Remove the role assignment and delete the identity
# Remove your identity's Foundry User role assignment from the Foundry account
az role assignment delete --assignee "$IDENTITY_PRINCIPAL_ID" --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" --scope "$FOUNDRY_ID" &&
echo "๐ฎ The Foundry User role assignment of $IDENTITY is deleted"
# Delete the identity, now that nothing uses it
az identity delete -g "$RG" -n "$IDENTITY" &&
echo "๐ฎ Identity $IDENTITY is deleted"# Remove your identity's Foundry User role assignment from the Foundry account
az role assignment delete --assignee $IDENTITY_PRINCIPAL_ID --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" --scope $FOUNDRY_ID
if ($?) { Write-Host "๐ฎ The Foundry User role assignment of $IDENTITY is deleted" }
# Delete the identity, now that nothing uses it
az identity delete -g $RG -n $IDENTITY
if ($?) { Write-Host "๐ฎ Identity $IDENTITY is deleted" }Delete the role assignment first. Deleting the identity alone leaves an orphaned assignment on the account.
The model call from Verify still returns 200, and View access shows the provider under
System-assigned again.
Delete everything azd created
In the aigateway/labs/12-backend-identity folder, delete the resource group with the gateway, the Foundry account,
and the identity with its 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/12-backend-identity/terraform folder, delete the resource group with the gateway, the Foundry
account, and the identity with its role assignment. The azurerm
provider also purges the soft-deleted Foundry account. It takes a few
minutes.
# Delete everything that terraform apply created, and purge the soft-deleted Foundry account
cd ~/aigateway/labs/12-backend-identity/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 system-assigned identity, because the
Bicep + azd and Terraform tracks created their own gateway.
Next steps
- Go keyless with Microsoft Entra ID and RBAC: remove keys on the inbound side too.
- Federate MCP tools behind one endpoint: set backend authentication for tool servers.
- Lock down backend traffic with private networking: keep backend traffic off the public internet.
- Docs: Security and identity and Microsoft Foundry and AI Gateway.