Blog Post

Microsoft Foundry Blog
11 MIN READ

Claude Code on Microsoft Foundry with Claude apps gateway and UI Console

NaveenGopalakrishna's avatar
Nov 18, 2026

A step-by-step guide to putting Anthropic's Claude apps gateway in front of Claude models in Microsoft Foundry: developers sign in with Microsoft Entra ID, no model key reaches a laptop, and administrators get spend caps, access control and chargeback from a small web console. Written for someone deploying it for the first time.

I built and tested an open-source deployment of Anthropic's Claude apps gateway on Azure Container Apps, in front of Claude models in Microsoft Foundry. This post walks through what it is, what gets deployed, how to install it, and what I learned along the way, including the permission errors that stop a first install and how to fix them.

Everything here comes from the public repository naveenneog/claude-apps-gateway-foundry. Each step links to the detailed article in that repository.

What problem does this solve?

When a team starts using Claude Code against Microsoft Foundry, three questions come up quickly:

  1. How do developers sign in without giving each laptop an API key or an Azure role on the Foundry account?
  2. Who can use which model, for example Sonnet for everyone and Opus for a smaller group?
  3. How much is each person, team or department spending, and how do we stop a runaway month?

The Claude apps gateway is a server that Anthropic ships inside Claude Code. It signs developers in through an OpenID Connect identity provider (here, Microsoft Entra ID), applies per-group model access and spend limits, and forwards requests to an upstream such as Microsoft Foundry.

The repository adds the Azure parts: an installer, an admin console, scheduled jobs, client onboarding scripts and tests.

Terms used in this post

TermMeaning
GatewayThe Claude apps gateway server. It runs in a container and receives every Claude Code request
Admin consoleA small web app, titled Claude apps gateway - Foundry, for spend caps, developer access, models and chargeback
App roleA role defined on an Entra app registration. Developers get Gateway.Standard or Gateway.Premium; console admins get AdminUi.Admin
Managed identityAn Azure identity for a resource, so it can call other Azure services without a stored secret
Admin fileA JSON file listing the gateway's roles, models, which role may use which model, and spend caps. The installer turns it into the gateway's configuration

Architecture

Figure 1. Architecture diagram drawn for this post with the Microsoft Azure Architecture Icons (V25). It shows the test topology the installer deploys; numbers match the request steps below.

What happens on a request:

  1. Claude Code on the developer machine sends a Messages API request to the gateway with a gateway session token.
  2. The gateway signs developers in with Microsoft Entra ID and admits only users who hold one of its app roles. It then issues its own session token, valid for one hour, and a refresh token.
  3. The gateway calls Microsoft Foundry with its managed identity (id-claude-gw). No model key or Azure credential is stored on the developer machine.
  4. Admins open the admin console in a browser. Container Apps authentication admits only users with the AdminUi.Admin role.
  5. The console sets spend caps through the gateway's admin API, over the environment's internal network.
  6. The console grants developer roles through Microsoft Graph, so admins do not need the Entra admin center for day-to-day access changes.

What the installer creates in one resource group:

ResourcePurpose
Container Apps environmentHosts both apps and two scheduled jobs
ca-claude-gw container appThe Claude apps gateway
ca-admin-ui container appThe admin console
job-spend-pacer (every 5 minutes)Turns a monthly cap into a daily pace near the end of the budget
job-signin-renewer (daily)Renews the gateway's Entra sign-in certificate before it expires
Azure Database for PostgreSQL flexible serverSessions, spend records and business-unit tags
Azure Container RegistryThe gateway and console images, deployed by digest
Two user-assigned managed identitiesid-claude-gw for Foundry; id-admin-ui for Microsoft Graph and the gateway app
Log Analytics workspaceContainer logs, including the gateway's audit events

The installer does not create the Foundry account or the Claude model deployments. You point it at an existing Foundry account.

Before you start

You needWhy
Owner on the Azure subscription (or resource group)The install creates resources and assigns Azure roles, including one on the Foundry account
A Microsoft Foundry account with Claude models deployedThe gateway forwards requests to these deployments
An account that can register applications in Entra IDThe installer creates the gateway's app registration
Someone with Privileged Role Administrator (or Global Administrator) for one stepGranting Microsoft Graph application permissions to the console's managed identity needs this directory role (Microsoft guidance)
PowerShell 7, Node.js 22 or later, the Azure CLI and GitThe installer runs in these. Azure Cloud Shell has them all

If you are not a directory administrator yourself, line up that person before you start. In every install I ran without that role, the install stopped at the Graph grant step. That stop is expected and safe: everything before it is already deployed. More on this below.

Step 1: Get the files and sign in

git clone https://github.com/naveenneog/claude-apps-gateway-foundry.git
Set-Location claude-apps-gateway-foundry
az login
az account set --subscription "<subscription name or ID>"
az extension add --name containerapp --upgrade

Step 2: Describe your gateway in the admin file

List your Foundry deployments, then copy the example admin file and edit it.

$foundryRg = '<resource group of your Foundry account>'
$foundry   = '<name of your Foundry account>'
az cognitiveservices account deployment list -g $foundryRg -n $foundry --query "[].{deployment:name,model:properties.model.name}" -o table

Copy-Item config/gateway-admin.example.json config/gateway-admin.azure-eval.json
notepad config/gateway-admin.azure-eval.json

In the admin file you set which models exist, which roles may use which models, and the starting spend caps. The repository's configuration article explains each field.

Step 3: Preview, then install

$rg      = 'rg-claude-gw-eval'
$admins  = az account show --query user.name -o tsv
$regions = 'eastus2,centralus,westus3'

pwsh -File infra/azure-test/Install-ClaudeGateway.ps1 -ResourceGroup $rg -AdminFile config/gateway-admin.azure-eval.json -FoundryResourceGroup $foundryRg -FoundryAccount $foundry -AppRegistrationName claude-apps-gateway-eval -SignInAdmins $admins -DatabaseLocation $regions -Plan

pwsh -File infra/azure-test/Install-ClaudeGateway.ps1 -ResourceGroup $rg -AdminFile config/gateway-admin.azure-eval.json -FoundryResourceGroup $foundryRg -FoundryAccount $foundry -AppRegistrationName claude-apps-gateway-eval -SignInAdmins $admins -DatabaseLocation $regions

-Plan runs read-only checks and prints every command it would run, without changing anything. Fix any FAIL line before running the real install.

The installer runs in stages: config, preflight, base, entra, image, app, budgets, admin-ui. Each stage can be rerun on its own with -Steps. If one stops, the installer names the stage and the article section with the manual Azure portal or Cloud Shell steps. In my test runs, an install into an empty resource group took about 8 minutes without the managed database and about 25 minutes with it.

To install into a resource group that already exists, such as the one that holds the Foundry account, add -UseExistingResourceGroup.

The one Entra step that needs a directory administrator

The admin console's managed identity needs four Microsoft Graph application permissions: User.Read.All, Application.Read.All, AppRoleAssignment.ReadWrite.All and Application.ReadWrite.OwnedBy. They let it find users, list the gateway's roles and grant roles from the console. The Entra admin center has no page for granting these to a managed identity, so a Privileged Role Administrator runs the grant in Cloud Shell. The exact commands are in the admin-ui stage of the stage-by-stage guide.

After that, rerun only the console stage:

pwsh -File infra/azure-test/Install-ClaudeGateway.ps1 -ResourceGroup $rg -AdminFile config/gateway-admin.azure-eval.json -FoundryResourceGroup $foundryRg -FoundryAccount $foundry -AppRegistrationName claude-apps-gateway-eval -SignInAdmins $admins -Steps admin-ui

It reports already granted four times and finishes.

Step 4: Give developers access

Developers need one of the gateway's app roles. The roles live on the gateway's app registration in Entra ID.

Figure 2. The gateway's app registration in the Microsoft Entra admin center with its two app roles. Screenshot from a lab tenant, cropped.

You can assign roles in the Entra admin center (Enterprise applications → the gateway app → Users and groups → Add user/group) or from the admin console's Developers page. An Entra group can hold a role too, so a whole team gets access at once (group assignment needs Entra ID P1 or P2).

Figure 3. Full Developers page, including navigation, the Grant a role form, and role holders. Actual console UI with made-up sample data; no Azure changes.

Watch: add a developer

Enter the existing Entra user’s sign-in email, select a gateway role, and choose Grant role. This assigns access; it does not create an Entra account.

Demo 1. Adding a developer through the full console UI. Recorded with sample data and local test dependencies; no directory or Azure resource was changed.

Watch: manage model access

In Access & models, select which models a role can use, choose Review changes, and confirm Apply and roll out. The review shows exactly what will change.

Demo 2. Granting Opus access to Gateway.Standard and reviewing the change. The UI is real; the Azure rollout response is simulated for this demonstration.

Full-console review screen: one role’s model access changes, while the other role is unchanged.

To add another console administrator, assign the AdminUi.Admin role on the console's own sign-in application, named <app registration>-admin-ui-signin, under Enterprise applications → Users and groups.

Step 5: Connect Claude Code on a developer machine

The admin console has a client kit that packages the onboarding files for this gateway: a developer folder for one machine, an Intune folder for many machines, and Claude Desktop policy files.

Figure 4. Full Settings page with the client onboarding section expanded, plus sign-in and permission information. Sample-only data and gateway address.

On one Windows machine, in the developer folder:

powershell -NoProfile -ExecutionPolicy Bypass -File .\Install-ClaudeGatewayProfile.ps1 -GatewayUrl https://<your gateway host>

The script writes a separate Claude Code profile (your normal %USERPROFILE%\.claude is left alone) and starts a browser sign-in. Claude Code shows a short code:

Figure 5. Claude Code waiting for the gateway sign-in. Terminal capture; the code and gateway host are masked.

The browser opens the gateway's device page, then Microsoft Entra sign-in:

Figure 6. The gateway's device verification page. Cropped browser capture.

After sign-in, claude-gateway.cmd in the profile folder starts Claude Code through the gateway. The session is saved encrypted with Windows DPAPI for that user, and refreshed in the background.

A note on clients: the launcher also works in the VS Code integrated terminal. Whether the VS Code extension's side panel reuses the gateway sign-in has not been verified yet. Claude Desktop uses a separate machine policy (bootstrapUrl), which the client kit generates.

Step 6: Watch and control spend

Spend caps can be set for the whole organization, for a role, or for one person, by day, week or month. The gateway checks them before each request, and Claude Code shows a warning as a person approaches a cap.

Watch: set a user spend cap

On Budgets, select User, enter the email, amount in USD and period, then choose Set cap. Email lookup requires the user to have made a model request through the gateway.

Demo 3. Setting a monthly user cap of $70 and verifying the configured cap. Actual console UI using sample-only gateway responses; no customer budget was changed.

Full Budgets page with organization and per-user caps. Both amounts are sample values.

A soft limit slows spending down before a monthly cap is reached. Past a chosen share of the cap (for example 80%), the spend pacer job spreads the rest of the cap over the days left in the month by setting a daily cap every five minutes.

Figure 7. Full Access & models page, including the soft-limit control at the bottom. Actual UI with sample-only data.

For chargeback, each person can carry five tags: department, cost center, company, office and division. Tags are stored in the gateway's PostgreSQL database, not in Entra ID, so the console does not need permission to change users in your directory. You can edit them one by one or import a CSV file.

Figure 8. Full Chargeback page with a business-unit row being edited. Contoso people, tags and spend are made-up sample data.

The Chargeback page then groups spend by any tag:

Figure 9. Full Chargeback page with department totals, user spend, and business units. Sample values are gateway estimates, not an Azure invoice.

Lessons from real installs

These are issues I hit while helping deploy this for real users, and what changed because of them.

What happenedCauseFix
The install stopped at the admin-ui stage with Authorization_RequestDeniedGranting Microsoft Graph application permissions to a managed identity needs Privileged Role Administrator or Global AdministratorPlan this step with your directory team. A directory administrator runs the grant, then you rerun -Steps admin-ui
Console buttons such as Set cap returned HTTP 403 with no error textContainer Apps authentication rejects cookie-based POST requests that carry no Referer header (cross-site request protection); the console sent Referrer-Policy: no-referrerThe console now sends same-origin. Existing consoles update with admin-ui/infra/Update-AdminUi.ps1, which replaces only the image
Apply and roll out returned 403 LinkedAuthorizationFailedUpdating a container app is also checked against its environment (Microsoft.App/managedEnvironments/join/action) and against each user-assigned identity it uses (.../userAssignedIdentities/assign/action). A role scoped to the app alone does not cover themThe console identity now also gets Container Apps Operator on the environment and Managed Identity Operator on the gateway's identity, both scoped to those single resources. The update guide has the commands for consoles installed earlier
Role 'Container Apps Operator' doesn't exist from the Azure CLIThe CLI could not resolve the role's display name at that scopeUse the built-in role ID instead: f3bd1b5c-91fa-40e7-afe7-0c11d331232c

The common thread: give each identity the smallest built-in role, scoped to the one resource it needs, and check linked resources when Azure answers LinkedAuthorizationFailed.

When to use this, and when to use Azure API Management

The repository also compares this route with an Azure API Management (APIM) based gateway. In short:

 Claude apps gateway (this post)APIM-based gateway
Developer sign-inBrowser sign-in to the gateway; no Azure CLI or cloud credential on the machineaz login; Claude Code sends an Entra token that APIM validates
Model accessPer Entra role or group, set in the gateway configurationPer tier, from Entra group lists published to APIM
Spend controlUSD caps checked before each request, with warnings in Claude CodeToken limits per developer and budgets reconciled on a schedule
What you runA container, PostgreSQL and this consoleA managed Azure service
CI and unattended jobsNot supported: no service-token flowSupported

The full comparison, with sources for each row, is in GATEWAY-COMPARISON.md.

Limits to know

  • The gateway server runs on Linux only; here it runs in a container on Azure Container Apps.
  • The test topology gives the gateway a public Container Apps address, protected by Entra sign-in and an optional IP range. Claude Code's built-in /login flow expects a gateway on private addresses, so developers on this topology use the developer profile instead. The repository also has a network-restricted tutorial for a gateway with no public endpoint.
  • Foundry sees every request as coming from the gateway's one managed identity. Per-person attribution lives in the gateway's records and the console's chargeback.
  • There is no unattended service-token flow, so CI pipelines cannot use the gateway.

Where to go next

GoalArticle
First install, with every value explainedTutorial: install the gateway and onboard developers
A stage stopped and you need the manual stepsInstall stage by stage
Day-to-day administrationUse the admin console
Update a console already deployedUpdate an existing admin console
Error messages and fixesTroubleshoot
Anthropic's own documentationClaude apps gateway
Claude models in FoundryClaude models in Microsoft Foundry

If you try it, I'd like to hear what was unclear. Issues and pull requests are welcome on the repository.

Updated Nov 18, 2026
Version 2.0
No CommentsBe the first to comment