Skip to main content
Version: 11.5.0

Microsoft Foundry

Overview​

A Microsoft Foundry connector routes your developers' requests through HYPR AgentPass™ to the Microsoft Foundry or Azure OpenAI resource in your own Azure subscription. Every request is subject to your policies and recorded in the Request Log.

The connector works with these developer tools:

  • GitHub Copilot CLI
  • The GitHub Copilot desktop app
  • GitHub Copilot in Visual Studio
  • Claude Code
  • Codex

Microsoft Foundry is for developer tools that call your own model deployments. To govern Microsoft 365 Copilot, use the Microsoft 365 Copilot connector instead.

This page explains how the connector works and prepares Foundry for it. Microsoft Foundry Setup creates the connector and connects each tool.

How It Works​

AgentPass sits between your developers' tools and your Foundry resource. Developers keep their own credential. AgentPass stores no Azure key and adds none.

A developer's tool signs in to Microsoft Entra ID, sends each request with its credential to HYPR AgentPass, which names the developer, applies policies and records the request, then forwards it with the credential unchanged to the Microsoft Foundry resource in your Azure subscription. Direct access from the developer's computer to Foundry is blocked on enrolled desktops.
  1. The developer signs in to your Entra tenant, such as with az login, or holds a Foundry resource key.
  2. Their tool sends each request to AgentPass, with that credential.
  3. AgentPass names the developer, applies your policies and records the request. It then forwards the request to your Foundry resource with the credential unchanged.
  4. Foundry checks the credential and the developer's role, as it does for a direct call. The response returns the same way.

Azure authenticates and authorizes every call, so a developer reaches only what their Azure roles allow. To keep developers from going around AgentPass, block Foundry's own hostnames on enrolled desktops. See Block Direct Access to Foundry.

How Developers Are Identified​

The credential a developer's tool sends decides how AgentPass names them in the Request Log.

CredentialWho AgentPass records
Microsoft Entra sign-in, such as az loginThe named person, from their sign-in. The agent is named _grace.hopper@hb.com's Foundry Agent_
Microsoft Entra sign-in by an application or managed identityThe application
Foundry resource keyOne shared identity for everyone who uses that key, named Shared Foundry key
Foundry resource key, plus an AgentPass agent tokenThe agent the token names

Prefer Entra sign-in wherever the tool supports it: it names each developer, and it is the only route that Require Approval can hold. Copilot CLI, Claude Code and Codex sign in with Entra ID. The Copilot desktop app and Visual Studio reach AgentPass with a resource key only.

Foundry in Brief​

Microsoft Foundry is Azure's service for hosting AI models in your own subscription. These are the parts the connector relies on.

TermWhat it is
Foundry resourceThe Azure resource that hosts your models, in a subscription, resource group and region you choose. It has its own hostnames, such as contoso-ai.services.ai.azure.com. An Azure OpenAI resource works the same way for OpenAI models
ProjectA workspace inside a resource. The Foundry portal opens on a project, and shows its details and endpoint
Model deploymentA model made available on the resource, under a name you choose. Tools ask for the deployment name, not the model name
Project endpointThe project's address, shown on its Project details page. You paste it into the connector
Resource keyA secret shared by the whole resource. Anyone who holds it can call every deployment on the resource
RoleAn Azure role assignment on the resource. It lets an Entra user, group or application call the models

Prerequisites: Set Up Foundry​

Work through these steps in the Microsoft Foundry portal and the Azure portal. If your organization already uses Foundry, check each step against your existing resource.

You need permission to create resources in the subscription, and to assign roles on them.

Create a Resource and Project​

In the Foundry portal, create a project. Foundry creates a resource for it, in the subscription, resource group and region you pick. Choose a region that offers the models your developers need.

The connector serves resources in Azure commercial regions. A resource that accepts connections only through Private Link cannot be reached.

Deploy Models​

A tool can call only the models deployed on your resource.

To see which models your project can use, open Catalog, then the Models tab, and choose Available in my project. Filter by Publisher, such as Anthropic for the Claude models that Claude Code calls.

The Foundry portal's model catalog, filtered to Anthropic models available in the project, showing each model's context window, token limits and hosting

To deploy a model:

  1. In the Foundry portal, open Build, then Models, and the Deployments tab.
  2. Click Deploy a base model, and choose a model.
  3. Keep the suggested deployment name, or enter your own, and deploy.
The Foundry portal's Models page, Deployments tab, listing three succeeded model deployments with their names, models and versions, and the Deploy a base model button

The Name column is the deployment name your developers enter in their tools. Deploy the models that suit each tool:

ToolModels it calls
Claude CodeAnthropic Claude models
GitHub Copilot CLI, the Copilot desktop app and CodexOpenAI models, such as GPT
GitHub Copilot in Visual StudioThe deployments the developer picks in Visual Studio

Copy the Project Endpoint and Tenant ID​

  1. In the Foundry portal, open Manage, then Project details.
  2. Copy the Project endpoint and the Tenant ID.
The Foundry portal's Project details page, showing the project's name, Project endpoint, API key, parent resource, resource group, subscription and Tenant ID, each with a copy button

You paste both into the connector. AgentPass uses only the resource part of the project endpoint. The Tenant ID is the Entra tenant your developers sign in to, the same ID Microsoft Entra ID → Overview shows.

Give Developers a Role​

Developers who sign in with Entra ID need the Foundry User role on the Foundry resource. Without it, Foundry refuses their requests, even though AgentPass accepts their sign-in. Assign it to an Entra group of your developers, as Microsoft Foundry RBAC describes.

Decide on Resource Keys​

The Copilot desktop app and Visual Studio reach AgentPass with the resource key. Everyone who uses the same key is recorded under one shared identity. The key appears as API Key on Project details. Visual Studio reads it through the developer's own account.

To name key users one by one, give each developer an AgentPass agent token to send alongside the key. See How Developers Are Identified.

note

If you turn off key access on the resource, only Entra sign-in works. The Copilot desktop app and Visual Studio then cannot connect through AgentPass.

Microsoft Foundry RBAC​

Azure role-based access control (RBAC) decides which developers can call your Foundry models. Give each developer who signs in with Entra ID the Foundry User role on the Foundry resource.

Azure checks the role on every request AgentPass forwards. A developer without it gets 403 from Foundry, with the code PermissionDenied. The message reads Principal does not have access to API/Operation. Resource-key callers need no role.

When someone with permission to assign roles creates the resource in the Azure portal or the Foundry portal, Azure gives them Foundry User automatically. Requests then work for the resource's creator and fail for everyone else until you assign the role.

Choose the Role​

Foundry User is the role to assign. The following table lists every role that lets a developer use Foundry through AgentPass.

RoleAssign it when
Foundry UserA developer signs in with Entra ID. It lets them call every model deployed on the resource. It was formerly named Azure AI User
Cognitive Services OpenAI UserA developer calls only OpenAI models, such as on an Azure OpenAI resource
Cognitive Services UserA developer uses GitHub Copilot in Visual Studio, which reads the resource key through the developer's account

Some roles sound broader, yet don't let a developer call models:

  • Owner and Contributor manage the resource and deploy models, but grant no access to call them.
  • Azure AI Developer applies to Azure Machine Learning workspaces and Foundry hubs, not to Foundry resources.
  • Microsoft Entra ID directory roles, such as Global Administrator, manage the directory, not Azure resources.
Assign the role on the resource, not the project

AgentPass sends requests to the Foundry resource's own endpoint, so the role must apply at the resource. Assign it on the resource, or on its resource group or subscription. A role assigned only on a project doesn't apply.

Assign the Role to a Group​

Assign Foundry User once, to a Microsoft Entra security group, then manage access through group membership. Adding or removing a group member takes effect immediately. A new role assignment can take up to five minutes to take effect.

To create the group:

  1. In the Azure portal, open Microsoft Entra ID, then Groups, and click New group.
  2. Set Group type to Security, and enter a name, such as Foundry Developers.
  3. Under Members, add your developers, and click Create.

To assign roles, you need the Owner or User Access Administrator role on the resource, its resource group or its subscription.

Assign the Role in the Azure Portal​

  1. In the Foundry portal, open Manage, then Resource details.

  2. Click Open in Azure portal. The Foundry resource opens in the Azure portal.

    The Foundry portal's Resource details page for the parent resource, showing its name, endpoint, resource group, subscription and tenant ID, and the Open in Azure portal link
  3. Open Access control (IAM), click Add, and choose Add role assignment.

    The Foundry resource's Access control (IAM) page in the Azure portal, with the Add menu offering Add role assignment
  4. On the Role tab, under Job function roles, search for Foundry.

  5. Choose Foundry User, and click Next. If the list shows the role's former name, choose Azure AI User.

    The Role tab of Add role assignment, with Job function roles filtered on Foundry and the Foundry User role selected in the results
  6. On the Members tab, keep User, group, or service principal, and click Select members.

  7. Search for your developer group, or for individual developers. Choose them, and click Select.

    The Members tab of Add role assignment for the Foundry User role, with the Select members panel listing matching Entra users
  8. Click Review + assign. Check that Scope ends with /accounts/ and your resource name, with no /projects/ part.

    The Review + assign tab, showing the Foundry User role, a scope ending in the Foundry resource's accounts path, and the selected member
  9. Click Review + assign again to save the assignment.

Assign the Role in the Foundry Portal​

The Foundry portal can assign the role to one developer at a time. Use it for a quick change. Use a group for your developer population.

  1. In the Foundry portal, open Manage, then Resource details.
  2. Open the Users tab, and click Add user. The button appears only for people who can assign roles.
  3. Under Add people, choose the developer.
  4. Under Role, choose Foundry User, and click Add user.
The Foundry portal's Add user dialog, with a developer's email address under Add people and Foundry User chosen as the role

The Users tab lists everyone with a role on the resource. Regular marks a role assigned on the resource itself. Inherited access marks one assigned on its resource group or subscription, which you change in the Azure portal.

The Foundry portal's Users tab on the resource, listing each user's access type and role, with two developers holding Foundry User as regular access

Assign the Role with the Azure CLI​

The Azure CLI assigns the role by its ID, which stays the same whichever name the portal shows. Replace the placeholders with your own values.

RESOURCE_ID=$(az cognitiveservices account show --name <your resource> --resource-group <your resource group> --query id -o tsv)
GROUP_ID=$(az ad group show --group "Foundry Developers" --query id -o tsv)

az role assignment create \
--role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
--assignee-object-id "$GROUP_ID" \
--assignee-principal-type Group \
--scope "$RESOURCE_ID"

To check a developer's roles on the resource, including those they hold through a group:

az role assignment list --scope "$RESOURCE_ID" --assignee <developer's sign-in name> --include-groups --include-inherited -o table

Check a Developer Can Connect​

Ask the developer to sign in with az login and choose a subscription in your Entra tenant, the one set on the connector.

The output of az login, listing the subscription and tenant the developer can sign in to and confirming the selected tenant and subscription

If their account belongs to several tenants, they run az login --tenant <your tenant ID> instead. They then retry their tool. If it still fails, see Troubleshooting.

Next Steps​

Microsoft Foundry Setup creates the connector and connects each tool, then covers onboarding, the Request Log, policies and troubleshooting.