docs: add the Entra ID provider walkthrough

The README's OIDC section is written against Authentik and stays that
way; Entra differs enough that inlining it would have doubled a file
that is already 32k. The new doc parallels the README's A/B structure so
the two are diffable, and leads with the traps, since every one of them
surfaces as an opaque 401 rather than as anything resembling its cause:
the access token version, the tenant-specific authority, `aud` being the
client-ID GUID while the requested scope is an `api://` URI, redirect-URI
platform types, and group GUIDs.

Sections 7 and 10b document the identity and overage behaviour shipped
in the previous commit, including the one upgrade-ordering caveat: an
existing Entra deployment should sign a user into the Web UI once before
reconnecting their MCP client, or the pre-migration row is stranded.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-12 10:51:39 -07:00
co-authored by Claude Opus 5
parent bbea0f74f3
commit 4d6694620a
2 changed files with 695 additions and 0 deletions
+7
View File
@@ -249,6 +249,13 @@ shape is the same on any OIDC provider; the UI labels differ:
| Redirect URI list | Provider's "Redirect URIs / Origins" | App's "Redirect URIs" | Client's "Valid Redirect URIs" |
| Audience claim | Scope mapping or property mapping | "Expose an API" + scope | Client scope with audience mapper |
> **Using Microsoft Entra ID?** The differences are large enough that Entra
> gets its own walkthrough: **[docs/oidc-entra-id.md](docs/oidc-entra-id.md)**.
> It follows the same A/B structure as the steps below, and covers the
> Entra-specific traps — access token version, tenant-specific authority,
> `aud` vs. scope URI, redirect-URI platform type, group GUIDs and overage —
> which otherwise surface only as opaque 401s.
### A. Web UI provider
**Admin → Applications → Providers → Create → OAuth2/OpenID Provider**