Edit

Configure Foundry Local inference authentication for Agentic Retrieval

After you deploy the Agentic Retrieval extension with foundryClientId, configure the Foundry Local managed identity authorization layers in this article.

Use this article only for Foundry Local managed identity authentication. For bring-your-own-model API key authentication, see Configure authentication for BYOM.

Important

Agentic Retrieval in Foundry Local is currently in PREVIEW. See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

Prerequisites

Before you begin, make sure you:

For background on how these authorization checks work, see Required roles for Foundry Local inference.

Assign the Foundry app role (Layer 1)

After you deploy the Agents and Tools extension and its managed identity principal ID exists, assign the FoundryInferenceAccess app role in your Foundry Local app registration to the extension managed identity.

For detailed app role assignment steps, see Configure authentication for Foundry Local.

Configure Azure RBAC role assignments (Layers 2 and 3)

Configure Azure role assignments so that:

  • The Agents and Tools extension managed identity can call the Foundry inference endpoint.
  • The Foundry operator can perform ARM RBAC validation.

Choose when to assign roles

You can assign these roles as you create identities during deployment, or assign them together after you deploy all extensions:

  • Assign Layer 2 (Reader for the connected cluster managed identity) after az connectedk8s connect.
  • Assign Layer 3 (Reader for the Foundry operator managed identity) after you deploy the inference-operator extension.
  • Assign Layer 3 (Cognitive Services OpenAI User and Reader for the Agents and Tools managed identity) after you deploy the Agents and Tools extension.

You can apply these role assignments at either subscription or resource group scope for broader coverage, or at connected cluster resource scope for least privilege. Choose the scope option that best fits your deployment in the following sections.

Set scope and principal IDs

Set your scope and principal IDs by using one of the following options. Replace placeholder values in angle brackets, such as <subscription_id>, <resource_group>, and <cluster_name>, with values from your environment where applicable.

Option 1: Subscription or resource group scope

Use this option for broader coverage and simpler setup.

# Set subscription or resource group scope
SCOPE="/subscriptions/<subscription_id>"

# Or use resource group scope
# SCOPE="/subscriptions/<subscription_id>/resourceGroups/<resource_group>"

# Set managed identity principal IDs
FOUNDRY_PRINCIPAL_ID="<foundry_app_principal_id>"
EXTENSION_PRINCIPAL_ID="<agents_and_tools_app_principal_id>"

Option 2: Connected cluster resource scope (least privilege)

Use this option for least-privilege access scoped to one connected cluster.

# Set connected cluster resource scope
SCOPE=$(az connectedk8s show -g <resource_group> -n <cluster_name> --query "id" -o tsv)

# Get managed identity principal IDs
FOUNDRY_PRINCIPAL_ID=$(az k8s-extension show -g <resource_group> -c <cluster_name> \
    -t connectedClusters --name inference-operator --query "identity.principalId" -o tsv)
EXTENSION_PRINCIPAL_ID=$(az k8s-extension show -g <resource_group> -c <cluster_name> \
    -t connectedClusters --name <extension_name> --query "identity.principalId" -o tsv)

Assign roles by using the selected scope

After you set SCOPE, FOUNDRY_PRINCIPAL_ID, and EXTENSION_PRINCIPAL_ID, run the following commands:

# Assign roles at the selected scope

# 1. Reader role for Foundry operator identity (required for ARM RBAC validation)
az role assignment create \
    --assignee-object-id $FOUNDRY_PRINCIPAL_ID \
    --role "Reader" \
    --scope $SCOPE \
    --assignee-principal-type ServicePrincipal

# 2. Cognitive Services OpenAI User role for Agents and Tools identity (for model inference)
az role assignment create \
    --assignee-object-id $EXTENSION_PRINCIPAL_ID \
    --role "Cognitive Services OpenAI User" \
    --scope $SCOPE \
    --assignee-principal-type ServicePrincipal

# 3. Reader role for Agents and Tools identity (for managed identity token ARM RBAC checks)
az role assignment create \
    --assignee-object-id $EXTENSION_PRINCIPAL_ID \
    --role "Reader" \
    --scope $SCOPE \
    --assignee-principal-type ServicePrincipal

Handle role propagation delays

Role assignments can take 5 to 30 minutes to propagate across Azure infrastructure. If you still get 401 or 403 errors after assigning roles, wait 10 to 15 minutes and then restart the affected pods.

kubectl -n arc-rag delete azureclusteridentityrequests --all
kubectl -n arc-rag rollout restart deployment \
    inferencingflow-deployment agents-runtime-deployment \
    agents-manager-deployment

Don't rerun the role assignment commands. The assignments are recorded immediately, but downstream services might not see them until propagation completes.

Related content

  • Last updated on