Skip to main content
command CX Codex official · Anthropic

entra-app — Claude Code command: what it does, how to install

This Claude Code command explains how to register a Microsoft Entra app in your own tenant. It covers sign-in setup for Outlook, gateways, Foundry, and sovereign clouds.

Apache-2.0 ★ 41,441 updated 2026-09-21

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add anthropics/financial-services
/plugin install claude-for-msft-365-install@claude-for-financial-services
Open on GitHub

What entra-app does

The command walks through registering a Microsoft Entra app in your tenant for configurations that need their own app registration. It covers redirect URIs, API permissions, admin consent, and token version. Separate setup paths cover Outlook, gateway auth, Foundry, and Bedrock WIF.

For backend validation, it lists expected iss, aud, and scp claims along with the JWKS address. GCC High, DoD, and 21Vianet have separate portal and authority details. Registration requires access to Entra admin center or the relevant sovereign-cloud portal.

Troubleshooting covers AADSTS50011, AADSTS65001, and Tag: 9n156. Foundry direct requires the user_impersonation permission and the Cognitive Services User role on the resource.

What it helps with

  • register an Entra app for Outlook sign-in
  • configure Graph permissions and grant admin consent
  • set the token audience for an API or Foundry resource
  • register an app in GCC High, DoD, or 21Vianet
  • diagnose redirect URI and consent errors

Example prompts for the agent

  • Walk me through Entra app registration for Outlook and list the required Graph permissions.
  • Explain how to set entra_scope for my API and validate the token claims.
  • Show the setup for Foundry direct in a sovereign cloud.

How to install entra-app

1Plugin marketplace

/plugin marketplace add anthropics/financial-services
/plugin install claude-for-msft-365-install@claude-for-financial-services

2Manually: put the files in place

.claude/commands/entra-app.md

Call it with /entra-app. For all projects use ~/.claude/commands/

Questions about entra-app

How do I install entra-app in Claude Code?

Run /plugin marketplace add anthropics/financial-services, then /plugin install claude-for-msft-365-install@claude-for-financial-services. The command file is also available at .claude/commands/entra-app.md.

What does entra-app do?

It explains how to register a Microsoft Entra app in your own tenant. The steps cover redirect URIs, permissions, admin consent, and token validation for several configurations.

What does entra-app need to work?

Access to your Microsoft Entra tenant and Entra admin center, or the matching sovereign-cloud portal, is required. Foundry direct also requires user_impersonation and the Cognitive Services User role on the resource.

Source text

entra-app.md · Apache-2.0
# Register your own Entra app

Several manifest configurations require an Entra (Azure AD) app registration in
**your** tenant rather than Anthropic's default multi-tenant app — because the
token's `aud` must match a resource you control, or because your tenant is in a
sovereign cloud where Anthropic's app doesn't exist. This page is the single
set of registration steps; the per-feature docs link here and tell you which
row of the permissions table applies.

You need this when setting any of:

| Manifest key | Why your own app |
|---|---|
| `graph_client_id` (Outlook) | Graph permissions are consented against your app, not Anthropic's |
| `entra_scope` | Access token must be audienced to *your* API resource |
| `gateway_auth_source=entra` | Your gateway — or a Foundry resource — validates a token audienced to that resource |
| `graph_cloud` ≠ `global` | Anthropic's app exists only in the commercial cloud |

## Register the app

In [Entra admin center](https://entra.microsoft.com) → *App registrations* →
*New registration*. Single-tenant. The simplest topology is one app acting as
both client (the add-in signs in as it) and resource (your backend validates
tokens audienced to it); split into two if your policy requires.

### 1. Redirect URIs

*Authentication* → *Add a platform* → **Single-page application** → add
**both**:

| URI | Used by |
|---|---|
| `brk-multihub://pivot.claude.ai` | [NAA broker](https://learn.microsoft.com/office/dev/add-ins/develop/enable-nested-app-authentication-in-your-add-in) — desktop Office and Outlook web. Missing this → `AADSTS50011` at sign-in. |
| `https://pivot.claude.ai/msal-redirect.html` | SPA fallback — Excel/Word/PowerPoint on Office for the web, which don't inject the NAA bridge. |

Both go under the SPA platform (not Web, not Mobile/desktop).

### 2. Permissions / API setup

What you configure here depends on what the token is for:

| Use case | Configure |
|---|---|
| **Outlook (Graph)** | *API permissions* → *Microsoft Graph* → Delegated → `Mail.ReadWrite`, `Calendars.Read`, `People.Read`, `User.Read`, `offline_access`. |
| **Gateway / bootstrap auth** (`entra_scope`, `gateway_auth_source=entra`) | *Expose an API* → set Application ID URI `api://<app-guid>` → *Add a scope* (e.g. `access_as_user`, admin-consent enabled). Then *API permissions* → *My APIs* → add that scope as a delegated permission (the app to itself, in single-app topology). |
| **Foundry direct, keyless** (`gateway_auth_source=entra` + `azure_resource_name`) | *API permissions* → *Azure Cognitive Services* → Delegated → `user_impersonation`. No *Expose an API* step — the token is audienced to Azure's `https://cognitiveservices.azure.com`, not your own app, so set `entra_scope=https://cognitiveservices.azure.com/.default`. Also grant each user the **Cognitive Services User** role on the Foundry resource (Azure Portal → resource → *Access control (IAM)*). |
| **Bedrock WIF** (`aws_role_arn`) | No API permissions needed — the ID token alone is the web identity. |

In all cases finish with *API permissions* → **Grant admin consent for
&lt;tenant&gt;**. Without it every user sees a consent prompt (or is blocked, if
user consent is disabled).

### 3. Token version

Only if you set up *Expose an API* above: in the app *Manifest*, set
`"accessTokenAcceptedVersion": 2`. Leave it unset and Entra issues v1.0 access
tokens (`iss` without `/v2.0`, no `preferred_username`), which most JWT
middleware rejects by default.

## What your backend validates

For `entra_scope` / `gateway_auth_source=entra`, the access token the add-in
sends as `Authorization: Bearer` carries:

| Claim | Expected |
|---|---|
| `iss` | `https://login.microsoftonline.com/<tenant-id>/v2.0` |
| `aud` | your Application ID URI (`api://<app-guid>`) |
| `scp` | the scope(s) you exposed, space-separated |
| JWKS | `https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys` |

For **Foundry direct keyless** there is no backend of yours — Azure validates the
token. The `aud` is `https://cognitiveservices.azure.com` and `scp` is
`user_impersonation`; Azure checks the signature and audience, then authorizes
the call by the user's **Cognitive Services User** role on the resource. You do
not set *Expose an API* or `accessTokenAcceptedVersion` for this path.

The role is specifically **Cognitive Services User** — the data-plane role for
direct model inference. Not *Cognitive Services OpenAI User* (OpenAI models
only), and not *Foundry User* / *Azure AI User* (the renamed role for the Foundry
agent and project plane, a different data plane). The `user_impersonation`
permission is a delegated permission for the add-in's per-user interactive
sign-in; it is not a server-side on-behalf-of exchange, which Azure AI resources
do not support.

## GCC High / DoD / 21Vianet

Same steps, different portal and endpoints — apps don't replicate across
Microsoft national clouds.

- **Register at** [`portal.azure.us`](https://portal.azure.us) (US Gov) or
  [`portal.azure.cn`](https://portal.azure.cn) (21Vianet), not the commercial
  portal.
- **Redirect URIs** are unchanged — `brk-multihub://pivot.claude.ai` and
  `https://pivot.claude.ai/msal-redirect.html`. The add-in is served from the
  same domain in every cloud.
- **Manifest** — add `graph_cloud=us-gov-high` (or `us-gov-dod`, `china`) per
  the [sovereign clouds](manifest.md#sovereign--national-clouds-gcc-high-dod-21vianet)
  table.
- **Admin consent URL** uses the sovereign authority:
  `https://login.microsoftonline.us/<tenant-id>/adminconsent?client_id=<app-id>`
- **Backend validation** — the token's `iss` and JWKS use the `.us` host:
  `https://login.microsoftonline.us/<tenant-id>/v2.0` and
  `https://login.microsoftonline.us/<tenant-id>/discovery/v2.0/keys`. A
  validator pinned to `.com` rejects every request. The same applies to any AWS
  OIDC identity provider in the chain.

## Troubleshooting

**`AADSTS50011` (redirect URI mismatch)** — one of the two URIs above is
missing, or was added under the wrong platform (must be SPA).

**`Tag: 9n156` on Outlook for Mac** — the host's auth broker can't complete.
Almost always a sovereign-cloud account hitting an app registered in commercial
(fix: register in `portal.azure.us` and set `graph_cloud`). If the app is
already in the right cloud, check Conditional Access — the deprecated *Require
approved client app* grant blocks NAA. The Correlation Id in the dialog is
resolvable in your Entra sign-in logs, not Anthropic's.

**`AADSTS65001` (consent required)** — *Grant admin consent* wasn't clicked, or
a permission was added after consent was granted (re-grant).

© Anthropic · Apache-2.0 · anthropics/financial-services

Similar slash commands

All slash commands for Cloud: AWS, Azure, GCP →

From the same set116

The whole set →
update-user-attrs The update-user-attrs Claude Code command sets per-user configuration through Microsoft Entra ID extension attributes. It updates one user or processes a CSV file. CX Codex +1 ★ 41,441repo stars setup A setup command for Claude Code that guides administrators through connecting the Claude Office add-in to their cloud infrastructure. CX Codex +1 ★ 41,441repo stars manifest This Claude Code command builds an add-in XML manifest with cloud settings. Outlook uses a separate template and needs Microsoft Graph admin consent before deployment. CX Codex +1 ★ 41,441repo stars export-data The export-data command for Claude Code copies chat history, skills, and settings before a machine is rebuilt. CX Codex +1 ★ 41,441repo stars debug debug — a command for diagnosing deployment issues with office add-ins. It triggers when connection errors occur, configurations become stale, or the add-in fails to appear in host applications. CX Codex +1 ★ 41,441repo stars consent This Claude Code command guides Azure admin consent for Entra SSO and Outlook access to Microsoft Graph. A tenant admin opens the supplied URL and approves the permissions. CX Codex +1 ★ 41,441repo stars bootstrap bootstrap — a command for Claude Code that builds an endpoint for dynamic configuration and MCP server management. It runs during extension startup to push user-specific settings. CX Codex +1 ★ 41,441repo stars access-policies Builds IAM-style access_policies configurations. It defines granular allow and deny rules for Microsoft 365 add-in features. CX Codex +1 ★ 41,441repo stars

Project sponsors

Companies that keep this analytics open