Skip to main content
Version: 11.5.0

Microsoft Foundry Setup

Create the connector, then point each developer's tool at your gateway.

Before You Begin​

Finish the Foundry prerequisites first. Have these ready, both from the Foundry project's Project details page:

  • The Project endpoint
  • The Tenant ID

Create the Connector​

  1. In the console, open Connectors, and click Add connector.
  2. Under AI Providers, choose Microsoft Foundry.
  3. Paste the Project endpoint into Resource endpoint, and the Tenant ID into Entra tenant ID.
  4. Click Test connection. AgentPass checks that the endpoint answers and that Microsoft Entra knows the tenant. Microsoft Foundry is reachable confirms both.
  5. Click Next.
  6. Choose the onboarding mode. See Onboarding New Developers.
  7. Click Create Connector.

The form has these fields.

FieldDescription
Resource endpointYour Foundry or Azure OpenAI resource. Paste the project endpoint, or any of the resource's own endpoints. AgentPass uses only the resource part, and always forwards to the resource's services.ai.azure.com endpoint, which serves both the OpenAI and the Anthropic models
Entra tenant IDThe tenant your developers sign in to. AgentPass uses it to name developers who sign in with Entra ID. Sign-ins from any other tenant are refused

There is no key field. The connector accepts the credential each developer brings. An organization has one Microsoft Foundry connector. To point it at a different resource, edit the existing connector.

Connect Your Developers​

Once the connector exists, its Overview tab shows a Connect AI tools card. It has one tab per tool, with the settings filled in for your gateway. Each tab shows only the steps the tool needs. Alternatives and help open from the questions underneath, such as Can I use a resource key instead? and Where are the logs?

The Microsoft Foundry connector page, with the Connect AI tools card open on the Copilot CLI tab: the az login settings to copy, and questions that open a resource key alternative, the log location and how to block direct access

In every tool, the model is the name of your Foundry deployment, not the name of the underlying model.

GitHub Copilot CLI​

The developer signs in with az login, then sets these environment variables:

export COPILOT_PROVIDER_TYPE=openai
export COPILOT_PROVIDER_BASE_URL=<your gateway URL>/openai/v1
export COPILOT_PROVIDER_WIRE_API=responses
export COPILOT_MODEL=<your deployment name>
export COPILOT_PROVIDER_API_KEY_COMMAND="az account get-access-token --scope https://ai.azure.com/.default --query accessToken -o tsv"

Copilot CLI fetches a fresh Entra token for every request, so the developer is named and long sessions keep working.

To use a resource key instead, the developer sets COPILOT_PROVIDER_API_KEY to the key, in place of COPILOT_PROVIDER_API_KEY_COMMAND. Their requests are then shared, unless they also send their AgentPass agent token:

export COPILOT_PROVIDER_HEADERS="Hypr-Authorization: Bearer <your AgentPass agent token>"

Copilot CLI writes its logs to ~/.copilot/logs, or %USERPROFILE%\.copilot\logs on Windows.

GitHub Copilot Desktop App​

The Copilot desktop app reaches AgentPass with a resource key. Its Azure CLI sign-in works only when the app connects to Foundry directly, not through AgentPass.

  1. In the Copilot app, open Settings → Model providers, and click Add provider.
  2. Choose Microsoft Foundry, and complete the fields described in the following table.
  3. Save the provider, and add your deployment under Models.
FieldValue
Display nameAny name, such as Microsoft Foundry
Base URL<your gateway URL>/openai/v1
Wire APIresponses
AuthenticationAPI key
API keyYour Foundry resource key
Custom headers (JSON)Optional. { "Hypr-Authorization": "Bearer <your AgentPass agent token>" }, to be named rather than shared
The Copilot app's Edit Microsoft Foundry provider form, with the base URL set to the AgentPass gateway, the responses wire API, API key authentication and a Hypr-Authorization custom header

Once saved, the provider appears under Configured providers with its models. Choose the model in a Copilot chat to send requests through AgentPass.

The Copilot app's Model providers list, with Microsoft Foundry configured and one deployment under Models

Without the custom header, every request from the app is recorded under the key's shared identity.

GitHub Copilot in Visual Studio​

Visual Studio adds Microsoft Foundry as a model provider through the developer's Microsoft account, then needs its models pointed at AgentPass. Its requests use the resource key, so they are recorded under the key's shared identity.

Step 1: Add Microsoft Foundry as the model provider.

  1. In Copilot Chat, open Manage models, and click Add model provider.
  2. Under Choose an available provider, choose Microsoft Foundry.
  3. Pick the Entra account, then the Subscription, the Microsoft Foundry resource and the Project.
  4. Click Add, and choose the deployments to use.
Visual Studio's Language models settings, adding Microsoft Foundry as a model provider with an Entra account, subscription, Foundry resource and project selected

Visual Studio reads the resource key through the developer's account, so the developer needs a role that can list the resource's keys. See Microsoft Foundry RBAC.

Step 2: Point its models at AgentPass.

  1. Close Visual Studio. It overwrites the file below when it is open.

  2. Open %LOCALAPPDATA%\Microsoft\VisualStudio\Copilot\BringYourOwnModel\ConfiguredBringYourOwnModel_v2.json in a text editor.

  3. In every model of the Microsoft Foundry provider, set CustomURL to your gateway's address, with no path:

    "CustomURL": "<your gateway URL>/",
  4. Save the file, reopen Visual Studio, and choose the model in Copilot Chat.

The ConfiguredBringYourOwnModel_v2.json file, with CustomURL set to the AgentPass gateway on a Microsoft Foundry model

Visual Studio adds the rest of the path itself. Adding the provider again resets CustomURL, so repeat step 2 afterwards.

Visual Studio writes its Copilot logs to %TEMP%\VSGitHubCopilotLogs.

Claude Code​

The developer signs in with az login, then sets these environment variables:

export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_BASE_URL=<your gateway URL>/anthropic
export ANTHROPIC_MODEL=<your deployment name>

With ANTHROPIC_FOUNDRY_API_KEY unset, Claude Code gets and renews an Entra token from the developer's az login, so they are named. To use a resource key instead, set ANTHROPIC_FOUNDRY_API_KEY to the key. Requests are then shared.

Codex​

The developer signs in with az login, then adds this to ~/.codex/config.toml:

~/.codex/config.toml
model_provider = "foundry"
model = "<your deployment name>"

[model_providers.foundry]
name = "Microsoft Foundry via AgentPass"
base_url = "<your gateway URL>/openai/v1"
wire_api = "responses"

[model_providers.foundry.auth]
command = "az"
args = ["account", "get-access-token", "--scope", "https://ai.azure.com/.default", "--query", "accessToken", "-o", "tsv"]

On Windows, set command = "az.cmd". Codex runs the command itself, and finds the Azure CLI on Windows only by its full name. Codex fetches a fresh Entra token with the command, so the developer is named.

Block Direct Access to Foundry​

A developer whose tool calls Foundry directly bypasses AgentPass. To stop that on enrolled desktops, block the resource's own hostnames on Desktops → SaaS based AI:

  • <your resource>.services.ai.azure.com
  • <your resource>.openai.azure.com
  • <your resource>.cognitiveservices.azure.com

Add each hostname as an app of your own, then block it. See Adding an App of Your Own and Block an App. The Connect AI tools card lists the same hostnames under How do I block direct access to Foundry?

AgentPass reaches Foundry from its own servers, so the block does not affect traffic through the gateway. It applies only on desktops enrolled in AgentPass, with Watch SaaS based AI turned on.

Onboarding New Developers​

The connector's onboarding mode decides what happens the first time a developer reaches Foundry through the gateway. You choose it on the create form's last step, and can change it later on the connector page's Onboarding Mode card. See Onboarding Mode.

ModeWhat happens on a developer's first request
Observe only (the default)The request is forwarded, and the caller is recorded
Require ApprovalA developer who signs in with Entra ID is held until their supervisor approves them. Once approved, their traffic flows normally
DisabledSelf-service onboarding is off

Require Approval uses the same supervisor handshake as your other connectors. See Onboarding Your Agent for the supervisor's side.

Require Approval holds Entra ID sign-ins only

Resource-key callers are recorded under one shared identity, and are never held. Application and managed-identity callers are recorded, and are never held. Use Entra sign-in for every developer you want approved one by one.

Attribution and the Request Log​

Foundry traffic appears in the Request Log alongside your other connectors, with the model and token counts. Open a request to see its Microsoft Foundry caller section.

A Microsoft Foundry request in the Request Log's detail panel, attributed to a named person's Foundry Agent, with its coding session and the Microsoft Foundry caller section showing an Entra sign-in

The section shows these rows, when they apply.

RowWhat it shows
Identified byHow the caller was identified: Entra sign-in, a named person, Entra sign-in, an application, Resource key, shared by everyone who uses it, Entra token that could not be verified or No credential
PersonThe developer's sign-in name, for an Entra sign-in
ApplicationThe application, for an application or managed identity
Entra tenantThe tenant the sign-in came from
KeyA short fingerprint of the resource key. The key itself is never stored
Named by AgentPass tokenYes when the request carried an AgentPass agent token
RefusedWhy AgentPass refused the request's Entra token. See Troubleshooting
DeploymentThe deployment, when the request named one in its path
API versionThe API version the tool asked for
Source IPThe client address the request reports for itself. A client can set it, so treat it as a hint

A developer who signs in with Entra ID is one agent, whichever tool they use. Everyone who uses the same resource key shares one agent. Turning that shared agent off on Agents stops every request made with that key through AgentPass.

Coding Sessions​

Requests from GitHub Copilot (the CLI, the desktop app and Visual Studio), Claude Code and Codex carry a session identifier. AgentPass groups them into coding sessions, so a request's Coding session field links to everything that session did. The connector page's Recent Sessions and Session watch tabs work on Microsoft Foundry as they do on your other AI providers. See Agent Session Forensics.

Policies on Foundry Traffic​

Your AgentPass policies apply to every Foundry request, whichever credential the developer brought. Inference rules apply to the OpenAI and the Anthropic models alike. Lead a Foundry-specific rule with a template guard:

connector.template == "AZURE_FOUNDRY"

These attributes describe the caller behind a Foundry request.

AttributeTypeDescription
connector.azure.foundry.credential_typeStringresource_key, entra_user, entra_app, entra_unverified or none. Always present, so guard your rule on it
connector.azure.foundry.surfaceStringopenai_v1, openai_deployments, anthropic or other
connector.azure.foundry.hypr_agent_namedBoolThe request carried an AgentPass agent token
connector.azure.foundry.deploymentStringThe deployment name, on deployment-style paths only
connector.azure.foundry.api_versionStringThe API version the tool asked for, when it sent one
connector.azure.foundry.tenant_idStringEntra sign-ins only: the tenant
connector.azure.foundry.object_idStringEntra user sign-ins only: the person's object ID
connector.azure.foundry.upnStringEntra user sign-ins only: the person's sign-in name, when the token has one
connector.azure.foundry.app_idStringEntra sign-ins only: the application the token was issued to
connector.azure.foundry.source_ipStringThe client address the request reports for itself. See the caution below

For example, this rule matches any request made with a shared resource key:

connector.template == "AZURE_FOUNDRY" && connector.azure.foundry.credential_type == "resource_key"
The source IP comes from the client

source_ip is the address the request reports for itself, and a client can set it. Use it to inform a decision, never as the only check.

Troubleshooting​

Start with the symptom you see.

What you seeWhat to check
Test connection reports Not working yetCheck the endpoint is your resource's own endpoint, in Azure commercial, and the tenant ID is the Tenant ID from the project's Project details page
AgentPass refused this Microsoft Entra token: it was issued by a different Entra tenant than this connector's.The developer signed in to another tenant. They run az login --tenant <your tenant ID>. If your developers sign in to a different tenant, correct the connector's Entra tenant ID
AgentPass refused this Microsoft Entra token: it has expired. Sign in again.The developer runs az login again. A tool configured with the token command fetches a fresh token on every request
AgentPass refused this Microsoft Entra token: it is not valid yet. Check this computer's clock.The developer's clock is wrong. Set it to synchronize automatically
401 from AzureThe tool sent no credential, or Azure refused it. Check the developer is signed in, or that the resource key is current
403 from Azure, with PermissionDenied and Principal does not have access to API/Operation.The sign-in is valid, but the developer has no role that can call models. Assign Foundry User on the Foundry resource, not on a project. See Microsoft Foundry RBAC
Copilot CLI reports Authentication failed with provider … (HTTP 403)Copilot CLI doesn't show the reason. Open the request in the Request Log. A Refused row means AgentPass refused the token; the rows in this table that quote its message explain each reason. Otherwise Azure refused it: see Microsoft Foundry RBAC
Requests work for the person who created the Foundry resource, and fail for other developersThe creator was given Foundry User automatically. Assign it to your other developers
404 naming the deploymentThe model setting doesn't match a deployment on the resource. Use the name from the Foundry portal's Deployments list
400 mentioning max_tokensThe tool uses the Chat Completions API with a model that refuses it. Set the wire API to responses
Copilot app requests are recorded as Shared Foundry keyExpected without the custom header. Add the Hypr-Authorization custom header to name each developer
Visual Studio requests do not appear in the Request LogCheck CustomURL is set on every Foundry model, with Visual Studio closed while you edit. Adding the provider again resets it
Codex on Windows fails to run azSet command = "az.cmd"
A developer is not held under Require ApprovalOnly Entra sign-ins are held. Resource-key, application and managed-identity callers are recorded, not held
Requests reach Foundry without appearing in the Request LogThe tool is calling Foundry directly. Block direct access on enrolled desktops