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
/plugin marketplace add anthropics/financial-services
/plugin install claude-for-msft-365-install@claude-for-financial-servicesWhat 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_scopefor 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-services2Manually: put the files in place
.claude/commands/entra-app.mdCall it with /entra-app. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/entra-app.mdCall it with /prompts:entra-app. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/entra-app.prompt.mdManually: put the files in place
.gemini/commands/entra-app.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
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 <tenant>**. 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