Configure security including managed identity, private networking, keyless credentials, and role policies

Security configuration in Foundry is dominated by one fact: role-based access control only applies on the Microsoft Entra path. Every carefully designed role assignment is bypassed while key authentication remains enabled. This lesson covers configuring identity, network isolation, and role policy in an order that reaches a keyless estate without an outage.

Why This Matters

Three properties make this objective more than a checklist.

A key is not a weaker credential; it is a different authorization model. "RBAC roles apply when you authenticate using Microsoft Entra ID. If you use key-based authentication instead, the key grants full access without role restrictions." So a leaked key does not grant a subset of what your roles allow — it grants everything.

The sequence is the design. Every step toward keyless is additive except the last. Disabling local authentication is irreversible in effect, breaks any caller you have missed, and is therefore a verification gate rather than an opening move.

Identity without authorization fails late. A managed identity that holds no role authenticates successfully and is denied at first use — which is why the failure appears in production, days after provisioning, looking like a deployment bug.

The exam tests this as ordering and least privilege: which role, at which scope, in which order.

Prerequisites

• The three scopes and five Foundry roles from earlier in this unit.
• What a managed identity is, and the idea of a token credential such as DefaultAzureCredential.
• That private networking is available for prompt agents and BYO VNet for hosted agents.
• The role rename, and that role IDs were unchanged.

Learning Objectives

By the end of this lesson you will be able to:

1. Explain why keys bypass RBAC and what that means for design.
2. Sequence a keyless migration with no outage.
3. Configure agent identity, including per-agent identities and On-Behalf-Of.
4. Apply role policies at the correct scope, including agent scope and custom roles.
5. Choose network controls appropriate to each agent type.

Building Blocks

Authentication paths. Microsoft Entra ID, where role assignments apply, or key-based, where they do not. The recommendation is explicit: "Microsoft recommends using Entra ID authentication for improved security and granular access control."

Managed identity. Removes stored secrets. The documented minimum setup assigns Foundry User on the Foundry resource to the project's managed identity as well as to your user principal — and both are automatic only for portal-UI-created projects.

Agent identity. "Each agent can have a dedicated Microsoft Entra identity, enabling secure, scoped access to resources and APIs without sharing credentials." Hosted agents get one "automatic, dedicated per agent". Agent identities "can authenticate to external MCP servers", and OAuth On-Behalf-Of (OBO) passthrough is supported when configured.

Tool authentication options. "Key-based access; Microsoft Entra (using the agent's managed identity or the project's managed identity); OAuth identity passthrough (On-Behalf-Of); and unauthenticated access, where appropriate."

Scopes for role policy. Resource, project, and agent — where the agent scope URI is /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>/agents/<agent>, "any role that can be assigned at the project scope can also be assigned at the agent scope", and such assignments are "currently evaluated only for agent endpoint access".

Custom roles. Available when built-ins do not fit, with a caution for managed compute: a wildcard such as Microsoft.CognitiveServices/locations/*/read "matches locations/usages/read but does not match locations/managedComputeCapacities/read", so capacity reads must be listed explicitly.

Network isolation. Private networking for prompt agents; BYO VNet for hosted agents, "where each session runs in a VM-isolated sandbox connected to your VNet".

Deep Dive

Why keyless is a sequence

The keyless migration has five steps, and only the last one can break anything.

1. Enable a managed identity for the workload, so there is an Entra principal to authorize. On its own this changes nothing.

2. Assign a least-privilege role to that identity at the right scope — Foundry User for a workload that builds and calls, Foundry Agent Consumer for one that only invokes agent endpoints. This is the step teams skip, and it is why the identity authenticates and is then denied.

3. Switch the client to a token credential such as DefaultAzureCredential, and deploy it while keys still work. This is what makes the migration safe: a misconfiguration degrades to the old path rather than failing.

4. Verify in telemetry that every caller now authenticates through Entra ID and none still presents a key. This is the gate, and it is the step that discovers the callers nobody documented.

5. Disable local authentication. Only now, because until this point a missed caller keeps working, and after it a missed caller is an outage.

Doing step 5 first is the classic incident: it is the step that defines keyless, so it feels like the place to start, and it instantly breaks every unmigrated caller including ones the team did not know existed.

Whose identity reaches the far end

For tools that read user-scoped data, the decisive configuration is which identity the downstream system sees.

With the agent's or project's managed identity, the downstream system sees the service. Every user gets whatever the service can see — which for a SharePoint library or a document store means a junior employee's query can return material they are not entitled to, with nothing in the response revealing it.

With OAuth On-Behalf-Of passthrough, the calling user's identity flows through and their own entitlements are enforced at the source. Any requirement phrased as "only what that user may see" is asking for OBO.

Per-agent identity solves a different problem: several agents in one project, each authenticating as itself to different downstream APIs, with access scoped per identity and no shared credential. The alternative pattern — one project identity plus an agent name in a header — is authentication by assertion, because the header is a claim the downstream API cannot verify while every agent still holds identical access.

Role policy in practice

Least privilege here means choosing both a role and a scope, and the scope choices are wider than teams expect.

For a principal that only calls one agent, assign Foundry Agent Consumer at the agent scope rather than moving the agent into its own project. That grants "access to a specific agent's endpoints without granting endpoint access to all agents in the project" — and note the boundary: agent-scope assignments do not confer control-plane or management permissions.

Avoid the two documented traps. Roles beginning with Cognitive Services "are designed for accessing AI Services resources directly and don't apply to Foundry scenarios." And Azure AI Developer is "scoped to Azure Machine Learning workspaces and Foundry hubs, not to Foundry projects or Foundry hosted agents", despite the name.

Write custom roles only when the built-ins genuinely do not fit — and if the role touches managed compute, list Microsoft.CognitiveServices/locations/managedComputeCapacities/read explicitly, because the obvious wildcard does not cover it.

Network controls by agent type

Both agent types can be isolated; the mechanisms differ.

Prompt agents support private networking, which matters because the "no infrastructure to manage" profile is often wrongly assumed to preclude isolation. A team can have both.

Hosted agents support BYO VNet, and the isolation model is stronger in one specific way: "each session runs in a VM-isolated sandbox connected to your VNet", so sessions do not share a runtime.

Alongside the network path sits the data destination — bring your own resources for storage, Azure AI Search, and Azure Cosmos DB for conversation state. A residency or retention requirement usually needs both: control the path and the destination.

Worked Examples

Example 1 — keyless with no outage. A platform team must move a production workload off API keys.

Enable the managed identity, assign a least-privilege Foundry role, deploy the token credential while keys still work, verify in telemetry that no caller presents a key, and disable local authentication last. Disabling first breaks every unmigrated caller; disabling immediately after creating the identity is worse, because the identity holds no role yet.

Example 2 — user-scoped SharePoint answers. An agent must return only what the signed-in user may see, from a library whose permissions change as staff move.

OAuth On-Behalf-Of, so the tool acts as the calling user and the source enforces their entitlements. A managed identity returns the service's view to everyone. Indexing nightly with a security filter derived from yesterday's memberships leaves a day of drift. Filtering the generated answer cannot recover a permission decision retrieval already got wrong.

Example 3 — one caller, one agent. A service principal must call exactly one agent among a dozen in a project.

Foundry Agent Consumer at the agent scope, using the agent's resource URI. A project-scope assignment permits every agent; configuration that merely chooses not to call the others is not authorization; moving the agent into its own project duplicates connections and deployments to obtain something the finer scope already offers.

Visual Explanations

The keyless sequence, and what breaks if reordered:

Whose identity the downstream system sees:

Common Mistakes

Disabling local authentication first. It is the verification gate, not the opening move.

Creating an identity and forgetting the role. It authenticates and is denied at first use.

Assuming a key is a limited credential. It grants full access with no role restrictions.

Using a managed identity where user permissions must apply. Everyone sees the service's view.

Passing an agent name in a header as identity. The downstream API cannot verify it, and all agents still hold the same access.

Assigning at project scope when one agent was meant. Grants endpoint access to all of them.

Reaching for Cognitive Services * or Azure AI Developer. Both are ruled out for Foundry work.

Wildcarding locations/*/read in a custom role for managed compute. It does not match managedComputeCapacities/read.

Practice Exercises

1. Why does disabling local authentication belong at the end of a keyless migration?
2. A workload's managed identity authenticates and is then denied. What is missing, and why does it fail at first use rather than at provisioning?
3. Which authentication option makes a tool honour the signed-in user's permissions, and what fails with a managed identity?
4. A principal must call exactly one agent of twelve. Give the role, the scope, and the boundary of that assignment.
5. Name the two role families explicitly ruled out for Foundry work, and why each is wrong.

Summary & Concept Map

Security configuration rests on one asymmetry: RBAC applies on the Entra path and keys bypass it entirely, granting full access without role restrictions. That makes keyless a sequence — identity, role, token credential deployed while keys still work, verification in telemetry, and only then disabling local authentication. Identity choices then decide whose permissions reach the far end: a managed identity shows every user the service's view, while On-Behalf-Of carries the calling user's entitlements. Role policy is a role and a scope, with the agent scope available to narrow endpoint access to one agent, and two role families explicitly ruled out. Network isolation is available to both agent types, with hosted agents adding per-session VM isolation — and a residency requirement usually needs the data destination controlled too.

Sources and freshness

Written against current Microsoft Learn documentation for the AI-103 skills measured (16 April 2026), reviewed 2026-08-20. Microsoft Learn controls every changing product contract — availability, preview status, quotas, limits, regional support, naming, and retirement dates all move independently of this lesson. Where a scenario turns on a specific number or a GA/preview boundary, confirm it against the product's own page before relying on it.