Configure an application to connect to a Foundry project

Connecting an application to a project is four things that must all be right: the correct resource kind, the correct endpoint shape, a credential the platform accepts, and a role assignment that actually grants what the code needs. When a connection fails, the error rarely names which of the four is wrong — so knowing the failure signatures is the practical skill.

Why This Matters

The resource kind decides what exists. An Azure OpenAI resource serves only /openai/v1. No project endpoint, no Agent Service. A scenario built on an existing Azure OpenAI resource that then asks for agents is testing this.

The endpoint shape is memorisable and asked directly. Project endpoints have one form, and the custom subdomain occupies a specific slot in it.

Working authentication is not sufficient authentication. A key connects and grants full access without role restrictions. Entra connects and grants exactly what a role assignment says — including nothing, if the assignment is missing.

One RBAC behaviour is genuinely counterintuitive. The automatic Foundry User assignment happens only through the portal UI. Create a project with the SDK or CLI and nobody is enrolled.

Prerequisites

• The difference between a Foundry resource, a project, and a deployment.
• What a custom subdomain is on an Azure resource.
• DefaultAzureCredential and its credential chain.
• That RBAC assignments are scoped, and scope narrows what a role grants.

Learning Objectives

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

1. Choose the right resource kind for a stated requirement.
2. Construct a project endpoint correctly, including the custom subdomain.
3. Authenticate with Entra and explain why keys fail governance requirements.
4. Assign the correct Foundry role at the correct scope.
5. Diagnose a failed connection from its symptom.

Building Blocks

Resource kinds. A Foundry resource hosts projects, the Agent Service, connections, and the full tool surface. An Azure OpenAI resource serves only /openai/v1 — model inference and nothing else.

The project endpoint.

The custom subdomain replaces <resource-name>. That subdomain is not decorative: token-based authentication requires it, which is why a resource created without one can authenticate by key and fail with Entra.

The roles.

These were renamed from Azure AI User, Owner, Account Owner, and Project Manager. Role IDs are unchanged, so existing assignments by ID keep working — and a distractor naming a Cognitive Services * role or Azure AI Developer is wrong.

Scope. Assignments apply at resource, project, or agent scope, with agent scope evaluated only for endpoint access. Two agents in one project can therefore differ in who may call them.

The portal-only automatic assignment. Automatic Foundry User assignment happens only via the portal UI. Projects created through the SDK or CLI do not get it, so users must be assigned explicitly.

Keys. Keys grant full access without role restrictions — no scoping, no per-agent permission, no auditable identity.

Deep Dive

The resource kind, first

The cheapest mistake to avoid is building on the wrong resource.

An Azure OpenAI resource exposes only /openai/v1. It runs model inference well and has no project endpoint, no Agent Service, no connections, and no built-in tool surface. A Foundry resource has all of it.

The examinable version is a scenario that opens "the team already has an Azure OpenAI resource" and then requires agents, a project endpoint, or connected tools. The answer is not a configuration change on that resource — those capabilities do not exist on it. The correct move is a Foundry resource with a project.

Endpoint, subdomain, and the token-auth dependency

The project endpoint is https://<resource-name>.services.ai.azure.com/api/projects/<project-name>, and the custom subdomain replaces <resource-name>.

The subdomain has a functional role beyond naming: token-based authentication requires it. That produces a diagnostic signature worth memorising — a resource without a custom subdomain works with a key and fails with Entra. A team that develops with a key and switches to managed identity for production hits this precisely at the environment boundary, and the failure looks like an authentication bug rather than a resource-configuration one.

The second shape to keep separate is the model endpoint. Model inference on an Azure OpenAI resource lives under /openai/v1; the project endpoint carries /api/projects/<project-name>. Mixing them produces 404s that look like a missing deployment.

The RBAC behaviour that catches people

The automatic Foundry User assignment fires only through the portal UI.

Provision a project in the portal and the creator is enrolled. Provision the identical project with the SDK, the CLI, or infrastructure-as-code — the normal path for anything reproducible — and nobody is assigned. Authentication then succeeds and every call returns a permission error, which reads as a broken credential rather than a missing assignment.

The rule to carry: automated provisioning must assign roles explicitly. In a question, "the project was created via the CLI" or "deployed through a pipeline" alongside a permission failure is naming its own answer.

The second RBAC point is naming. The roles were renamed from Azure AI User, Owner, Account Owner, and Project Manager to Foundry equivalents, with role IDs unchanged — so assignments made by ID are unaffected, and any answer offering Cognitive Services User, Cognitive Services Contributor, or Azure AI Developer for project access is wrong.

Scope, and least privilege that means something

Three scopes exist: resource, project, and agent — with agent scope evaluated only for endpoint access.

That granularity is what makes least privilege expressible. A reporting application that must call one agent gets Foundry Agent Consumer at agent scope on that agent; it cannot reach the others. A platform team managing projects gets Foundry Project Manager at resource scope. A developer needing to read gets Foundry User.

Contrast a key, which grants full access without role restrictions. Any requirement mentioning least privilege, per-application permissions, auditable identity, or credential rotation eliminates key authentication outright — and keys remain the default in samples and local development, which is exactly how they reach production.

Diagnosing a failed connection

Each failure has a signature.

Works with a key, fails with Entra → no custom subdomain, or a missing role assignment. Check the subdomain first: token auth requires it.

Authenticates, then every call is forbidden → the credential is fine and the role assignment is missing. Suspect portal-only automatic assignment if the project was created by SDK, CLI, or pipeline.

404 on a project path → wrong endpoint shape, or an Azure OpenAI resource that has no project endpoint at all.

Works for one agent and not another → an assignment made at agent scope rather than project scope.

Worked Examples

Example 1 — an existing Azure OpenAI resource, now needing agents. A team has an Azure OpenAI resource in production and wants agents with File Search and an MCP tool.

An Azure OpenAI resource serves only /openai/v1 — it has no project endpoint and no Agent Service, so no configuration change adds them. Create a Foundry resource and a project. The existing deployments can keep serving inference during migration.

Example 2 — pipeline-provisioned project, permission errors everywhere. A project is created by an infrastructure pipeline. The application authenticates with its managed identity and every call returns forbidden.

Automatic Foundry User assignment happens only via the portal UI, so an SDK, CLI, or pipeline-created project enrols nobody. Assign explicitly — Foundry User to read, Foundry Agent Consumer to invoke agents — at the appropriate resource, project, or agent scope.

Example 3 — works locally, fails in production. Local development uses a key and succeeds. Production uses a managed identity and fails to authenticate.

Token-based authentication requires the custom subdomain, which the key path does not. Confirm the resource has one and that the endpoint uses it in the <resource-name> slot; then confirm a role assignment exists for the managed identity. The key masked both requirements.

Visual Explanations

The four things that must be right:

Failure signatures:

Common Mistakes

Trying to add agents to an Azure OpenAI resource. It serves only /openai/v1.

Omitting the custom subdomain. Token authentication requires it.

Confusing the model endpoint with the project endpoint.

Expecting SDK or CLI project creation to assign roles. Automatic assignment is portal-only.

Choosing a Cognitive Services * role or Azure AI Developer. The Foundry roles are the correct set.

Assuming a rename changed the role IDs. They are unchanged.

Validating with a key and deploying with a managed identity. The key masks both the subdomain and the role requirement.

Assigning at resource scope when agent scope was intended.

Practice Exercises

1. Write the project endpoint template and say what the custom subdomain replaces.
2. A pipeline-created project returns forbidden for every call by an authenticated identity. Diagnose it.
3. Why does an application work with a key and fail with a managed identity?
4. Name the five Foundry roles and what changed in the rename.
5. Which scopes exist, and which is evaluated only for endpoint access?

Summary & Concept Map

Connecting an application is four aligned decisions. The resource kind decides what exists at all — an Azure OpenAI resource serves only /openai/v1, so projects and agents require a Foundry resource. The endpoint is https://<resource-name>.services.ai.azure.com/api/projects/<project-name>, where the custom subdomain fills the resource-name slot and is required for token authentication — the reason key-based development can hide a production failure. The credential should be Entra with a managed identity, because keys grant full access without role restrictions. And the role assignment must be explicit: Foundry User, Owner, Account Owner, Project Manager, and Agent Consumer — renamed with IDs unchanged — assigned at resource, project, or agent scope, and never assigned automatically outside the portal UI.

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.