ADR-018: roles, scopes and the OAuth flow of the MCP endpoint
Context. Roles and permissions (six roles, 17 permissions, five key scopes) are defined in
src/extractit/api/auth/matrix.py and documented in Roles and permissions.
T47 adds OAuth 2.1 access to the MCP endpoint.
Decision (T47).
- The MCP endpoint is an OAuth 2.1 protected resource (RFC 9728 metadata at
/.well-known/oauth-protected-resource[/mcp]); the authorization server is the deployment's IdP (T13). No own authorization server. - Tokens are validated with FastMCP's
JWTVerifier: JWKS signature (RS256), configured issuer,audequal to the canonical resource URL built fromDX_MCP_BASE_URL(never fromHost), expiry. API keys are accepted next to tokens (MultiAuth). - Effective permissions = token scopes ∩ the permissions of the user's role in the organization.
A wider scope that the role allows is requested by step-up (
403 insufficient_scopewithscopeandresource_metadata); a role that forbids it gives a plain403. - Calls reach the API in process as a 60-second internal token (
DX-Internal-Auth, HMAC with a per-process secret) accepted by an extra link of the T12 authenticator chain; the client's token is never forwarded. - Destructive tools need a person's approval (
approvaltable, 10 minutes, single use, bound to the canonical arguments). Approving needs a human Admin/Owner or a key withadmin; agent keys are created without it.
See MCP authorization for the flow and the test matrix.