Files

T

Dan MilneandClaude Opus 4.8 7149b98b7b Add OAuth device flow, token introspection, and dynamic client registration

Adds three OAuth surfaces to the OIDC provider so CLIs, terminal agents, and
MCP connectors can authenticate as real users instead of using static API keys.

Device Authorization Grant (RFC 8628):
- OidcDeviceCode model (HMAC device_code, short plaintext user_code, nullable
  user until approval, slow_down polling state), mirroring OidcAuthorizationCode
- POST /oauth/device_authorization issues the code pair + verification URIs
- device_code grant on /oauth/token returns authorization_pending / slow_down /
  access_denied / expired_token, then the standard token triple; single-use
- Authenticated /device approval page, gated by Application#user_allowed?

Token Introspection (RFC 7662):
- POST /oauth/introspect: confidential-caller-authenticated; returns active,
  scope, and the user's groups so resource servers can authorize on membership

Dynamic Client Registration (RFC 7591):
- POST /oauth/register creates public/confidential clients (PKCE required)
- Runtime toggle via a new Setting store + admin switch on the Applications page;
  off by default, env var CLINCH_DCR_ENABLED as bootstrap fallback
- New clients are default-deny (no allowed_groups) until an admin grants access
- RFC 8414 metadata alias at /.well-known/oauth-authorization-server;
  registration_endpoint advertised only while the window is open

Discovery advertises all three grants/endpoints. Seeds add a clinch-cli public
client and a c2a2-introspection confidential client. ADRs in docs/decisions
record the opaque-vs-JWT, device-flow, and DCR-security decisions.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F7cwhwDJp3MJJDoNPVE6zq

2026-07-19 12:30:02 +10:00

2.9 KiB

Raw Blame History

0003 — Dynamic Client Registration (RFC 7591), runtime-gated

Status: Accepted · Date: 2026-07-19

Decision

Clinch supports OAuth 2.0 Dynamic Client Registration (RFC 7591) at POST /oauth/register, so clients (notably MCP connectors like Claude) can register themselves instead of being hand-created. It is off by default and toggled at runtime by an admin from the Applications page. A newly registered client is default-deny: it has no allowed_groups until an admin attaches one.

We also serve the RFC 8414 metadata alias at /.well-known/oauth-authorization-server (the OIDC discovery document is a superset), and advertise registration_endpoint only while registration is enabled.

Context

MCP connectors expect to self-register via anonymous DCR rather than being pre-provisioned. But open registration is a real risk: anyone could register a legitimate-looking client and attempt consent phishing — luring a user to approve it, then holding a token that acts as that user against any resource server that trusts clinch tokens (via introspection, see 0001).

Two controls make this safe:

Runtime window, not always-on. DCR is a toggle (persisted Setting, admin UI), so the operator opens it briefly, lets the client register, attaches a group, and closes it again. The CLINCH_DCR_ENABLED env var is only a bootstrap default when the setting is unset. Default is off.
Default-deny for new clients. Clinch's authorize flow already gates on Application#user_allowed? (group membership), evaluated before the consent screen renders. A group-less registered client therefore can't show any user an approve button — the consent-phishing path dead-ends until an admin explicitly grants a group. ForwardAuth services are gated by the user's session cookie, not client tokens, so DCR doesn't widen that surface at all.

Implementation notes

OidcRegistrationController#create: validates token_endpoint_auth_method (none/client_secret_basic/client_secret_post), grant_types (authorization_code/refresh_token), response_types (code), and redirect_uris (https anywhere; http only for loopback). Creates a public or confidential Application with require_pkce: true, returns the RFC 7591 response (client_secret once, for confidential clients).
Setting is a small key/value store; Application.dynamic_registration_enabled? reads it with the env var as fallback. Admin toggle: Admin::DynamicClientRegistrationController.

Consequences

MCP connectors can self-register when the window is open, then operate normally once an admin grants a group.
No always-on anonymous registration surface; the risky window is short and operator-driven.
Remaining MCP pieces (resource indicators RFC 8707, protected-resource metadata RFC 9728 on the resource server) are separate, smaller follow-ups.

2.9 KiB Raw Blame History