Support Microsoft Entra ID for MCP OAuth

[josipmrsic]

Hi! We found Artifact Server a few weeks ago and really like it. We're setting it up as a private-team installation for our company (about 300 people), and like many companies we sign in with Microsoft Entra ID.

Browser login with Entra worked out of the box. /mcp didn't, and the deployment guide already says so ("Microsoft Entra ID cannot protect /mcp this way"). This PR closes that gap with three optional settings and one narrower discovery check. Without the new settings, every installation behaves exactly as before.

What stood in the way

We tested against a real Entra tenant with Claude Code as the MCP client:

1. Discovery omits the PKCE methods. Entra supports S256, but its v2.0 discovery document has no code_challenge_methods_supported, so startup turned MCP OAuth off ("OIDC discovery does not advertise S256 PKCE").
2. aud is the API's client ID. Entra v2.0 access tokens always name the resource app's client ID, never a URL.
3. Clients need the API's own scope. Without it, Entra hands out a Microsoft Graph token nobody else can verify, and clients learn the scope from scopes_supported, which wasn't published.
4. sub is pairwise per app registration. oid is the stable per-person ID in the tenant. With sub, moving to a new app registration would orphan every member binding.

What changes

Setting	Default	Entra value
ARTIFACT_SERVER_OIDC_SUBJECT_CLAIM	sub	oid
ARTIFACT_SERVER_OIDC_MCP_AUDIENCE	<origin>/mcp	the app's client ID
ARTIFACT_SERVER_OIDC_MCP_SCOPES	none	<origin>/mcp/<scope>

• Discovery accepts an issuer that leaves code_challenge_methods_supported out. One that lists methods without S256 is still refused, and clients always send S256.
• A configured audience replaces <origin>/mcp rather than adding to it. The protected-resource metadata still names <origin>/mcp as the resource, since MCP clients check it against the URL they connected to.
• The subject claim applies to browser login and MCP together, so the oidc:<issuer> + subject binding stays one per person. A missing or blank claim is refused.
• The new variables join the ARTIFACT_SERVER_OIDC_* family, so the all-or-nothing and WorkOS-exclusion checks cover them. Helm, both Compose files and the .env examples carry them.

One piece of the puzzle needs no code: Claude Code sends <origin>/mcp as the RFC 8707 resource parameter, and Entra refuses a resource that doesn't match the scope's app (AADSTS9010010). Setting the app's Application ID URI to <origin>/mcp fixes that; the new "Use Microsoft Entra ID" section in docs/deployment.md walks through it.

What we deliberately left out

• No email fallback. Entra access tokens carry no email or email_verified. We kept 0028's rule as it is rather than mapping preferred_username; a person who signed in through the browser once is recognized on /mcp by issuer and subject.
• Cloudflare. Its worker has no generic OIDC MCP path yet, so we didn't touch its deployment contract.

Spec and tests

• Decision 0029 records the change and amends the audience rule of 0028 (with a pointer added there).
• New requirement AUTH-029 (implementing, with a proof gap for deployment evidence). Its tests use the existing stub issuer, which happens to omit the PKCE methods just like Entra, plus an oid claim knob.
  • AUTH-029-B: browser login binding oid, a changed sub keeping one membership, and an email-less access token with the client-ID audience reaching /mcp as the same member.
  • AUTH-029-F: refusal of a missing claim, the default audience beside a configured one, ID tokens sharing the audience, PKCE lists without S256, and malformed configuration.
• MCP-013's wording now allows the configured audience. Its proof gap says no MCP client had completed browser approval against a generic OIDC issuer; Claude Code just did that against Entra. We left the status alone for you to judge.

Verification

• pnpm check passes locally.
• Full verify:iteration tier on our fork, Linux and macOS both green: https://github.com/josipmrsic/artifact-server/actions/runs/37789296735
  That run's branch also carries a one-line update of the pinned Amazon RDS CA bundle checksum. AWS replaced global-bundle.pem on 2026-09-29, and since then the OCI build fails on main with a digest mismatch (your nightly full gate too). We're sending that fix as its own small PR.
• Manual: Entra browser login, then Claude Code /mcp → authenticate → tool calls, recognized as the same single member.

Happy to rename the variables, split the PR, or change anything else to fit how you'd like this to look.