/entra-app

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 w