Skip to main content

Azure authentication

Two auth planes​

There are two distinct authentication flows in this system:

  1. Caller → API (APIM): end users/services call the API through APIM.
  2. API → Azure services: the running app calls Azure services (OpenAI/Foundry, Content Safety, SQL) using Managed Identity.

Caller → API (via APIM)​

APIM typically requires both:

  • Authorization: Bearer {JWT}
  • Ocp-Apim-Subscription-Key: {subscriptionKey}

Requests are then forwarded to the backing App Service.

Getting the JWT (client credentials)​

A common pattern is OAuth 2.0 client credentials against Azure Entra ID:

  • Token endpoint: https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token
  • Scope: api://{api-scope}/.default
  • Grant type: client_credentials

Example token request:

curl -X POST "https://login.microsoftonline.com/${TENANT_ID}/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=${CLIENT_ID}&client_secret=${CLIENT_SECRET}&scope=api://{api-scope}/.default&grant_type=client_credentials"

The response includes access_token, which is used as the bearer token for APIM.

Why APIM also needs a subscription key​

APIM subscription keys are used for:

  • product-level access control
  • throttling and analytics
  • an additional “shared secret” style gate

Note: Subscription keys are an APIM-level artifact and convenient for quick curl examples; for tenant-hosted automation and production workflows prefer OAuth bearer tokens (client credentials) issued by the Azure Entra tenant.

API → services in the Azure tenant (Managed Identity)​

When the app is running in Azure App Service, it can use a Managed Identity to authenticate to downstream services deployed in the Azure tenant.

This repo explicitly supports Managed Identity for tenant-hosted resources, including:

  • Azure AI Inference (Foundry model access) (via DefaultAzureCredential) in src/mastra/providers/azure-ai-inference.ts
  • Azure AI Content Safety in src/mastra/providers/azure-content-safety.ts
  • SQL Server (token-credential auth) in packages/platform-data/src/sqlserver-client.ts

Operationally:

  • The App Service identity is granted access to the target resources in the tenant.
  • Environment variables select Managed Identity vs key/password fallbacks.

Common Managed Identity toggles​

  • SQL Server:
    • AZURE_SQL_USE_MANAGED_IDENTITY=true
    • Optional: AZURE_SQL_MANAGED_IDENTITY_CLIENT_ID
  • Content Safety:
    • AZURE_CONTENT_SAFETY_USE_MANAGED_IDENTITY=true
  • Azure AI Inference:
    • AZURE_FOUNDRY_USE_MANAGED_IDENTITY=true