## Summary This issue covers what the IAM service needs to fully support dynamic OAuth client registration (RFC 7591). The implementation approach is settled: the IAM service owns `POST /oauth/register` natively and is the authoritative source for dynamic clients. These are non-confidential, publicly-registered clients restricted to MCP flows with PKCE required. ## Settled approach **Ownership and source of truth** ([note_3708392531](https://gitlab.com/gitlab-org/gitlab/-/work_items/602404#note_3708392531), [note_3714905830](https://gitlab.com/gitlab-org/gitlab/-/work_items/602404#note_3714905830)): IAM owns `POST /oauth/register` and stores dynamic clients in its own database with `dynamic=true`, `confidential=false`. No `client_secret` is issued; `token_endpoint_auth_method` is `none`. A Rails `oauth_applications` row is never created for dynamic clients. **Routing** ([note_3714905830](https://gitlab.com/gitlab-org/gitlab/-/work_items/602404#note_3714905830), [note_3716123855](https://gitlab.com/gitlab-org/gitlab/-/work_items/602404#note_3716123855)): Requests route directly to IAM without topology classification. Interim routing is via Workhorse oauthproxy behind a feature flag; end-state sends `/oauth/*` to IAM via Cloudflare per [AUTH-011](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/blob/main/proposals/011-oauth-gradual-rollout-plan.md). AUTH-011 requires amendment: the RFC 9728 protected resource metadata (`/.well-known/oauth-protected-resource` and variants) stays on Rails and must be excluded from the general `/.well-known/*` rule; IAM serves RFC 8414 authorization server metadata at `/.well-known/oauth-authorization-server` and per-resource paths (child issues [#10](https://gitlab.com/gitlab-org/gitlab/-/work_items/623576) and [#11](https://gitlab.com/gitlab-org/gitlab/-/work_items/623577)). **Client behavior** ([note_3708392531](https://gitlab.com/gitlab-org/gitlab/-/work_items/602404#note_3708392531)): The register endpoint replicates `Oauth::DynamicRegistrationsController` exactly: `redirect_uris` as string or array, `resource` wins over `scope`, scopes restricted to `mcp`/`mcp_orbit`, "[Unverified Dynamic Application]" prefix, `invalid_client_metadata` on errors, 403 `access_denied` when DCR is disabled instance-wide, and JSON 429 rate limit. Dynamic clients must send S256 `code_challenge` at authorize (plain rejected) and `code_verifier` at token exchange, with the registered scope forced at authorize like Rails. Non-dynamic clients keep lenient Doorkeeper-parity behavior. **Consent** ([note_3708392531](https://gitlab.com/gitlab-org/gitlab/-/work_items/602404#note_3708392531)): The existing gRPC consent challenge back-channel carries client metadata from IAM's store, so Rails consent works for IAM-native clients without needing a client owner or reverse replication. **Configuration** ([note_3716123855](https://gitlab.com/gitlab-org/gitlab/-/work_items/602404#note_3716123855)): Only `dynamic_client_registration_enabled` controls DCR on IAM; when off, register returns 403 `access_denied` and `registration_endpoint` is omitted from discovery. `mcp_server_enabled` is enforced by the Rails MCP API. How the setting reaches IAM is covered in [child issue #8](https://gitlab.com/gitlab-org/gitlab/-/work_items/623574). **Rate limiting** ([note_3723263774](https://gitlab.com/gitlab-org/gitlab/-/work_items/602404#note_3723263774)): Cloudflare WAF rate limiting via Runway, 10 registrations/IP/hour (matching Rails), routed through `iam-auth-ext-gke` ([child issue #6](https://gitlab.com/gitlab-org/gitlab/-/work_items/623572)). **Origin signal** ([note_3876030915](https://gitlab.com/gitlab-org/gitlab/-/work_items/602404#note_3876030915), [note_3883217828](https://gitlab.com/gitlab-org/gitlab/-/work_items/602404#note_3883217828)): IAM distinguishes Rails-replicated from IAM-native clients by cell identifier presence. Added as `owning_cell_id` in [!687](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/687) and [#629574](https://gitlab.com/gitlab-org/gitlab/-/work_items/629574). **Future work** ([note_3883217828](https://gitlab.com/gitlab-org/gitlab/-/work_items/602404#note_3883217828)): The ADR is [AUTH-022: Dynamic Client Registration on IAM](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/merge_requests/142) in the auth-architecture design-doc repo. Existing Rails-registered dynamic clients need no migration ([note_3708392531](https://gitlab.com/gitlab-org/gitlab/-/work_items/602404#note_3708392531)), they continue routing to Rails until tokens expire or cleanup removes them. <details> <summary>Original Options</summary> The original options below document the pre-decision analysis and are superseded by the settled approach above; kept for reference. ## Routing Decision Required `POST /oauth/register` is unauthenticated — there is no user context (no email, no username) for the Topology Service to classify which cell to route to. This is an open architectural decision: **Option A: Route to IAM service directly** IAM owns `POST /oauth/register` natively. Dynamic clients are stored in IAM's own DB (YugabyteDB). Replication goes IAM → Rails for any cells that need client metadata (e.g. consent UI, authorized applications page). IAM becomes the source of truth for dynamic clients. This is the cleanest approach architecturally since IAM is the OAuth authority. **Option B: Route to a fixed cell (e.g. cell-1)** All unauthenticated OAuth registrations go to a canonical cell. Simpler in the short term but creates uneven load, a single point of failure, and still requires replication to other cells. **Current default (without a decision):** The HTTP Router will fall back to routing unauthenticated requests to the first cell, so `POST /oauth/register` will land on Rails on cell-1. This works as a stopgap but is not a long-term solution. A decision is needed before this can be fully implemented. Option A is recommended. ## Scope (assuming Option A: IAM owns registration) ### `POST /oauth/register` on IAM - Implement RFC 7591 dynamic client registration endpoint on the IAM service - Accept: `redirect_uris`, `client_name`, `resource`, `scope` - Resolve scope from `resource` URL or `scope` field, restricted to `mcp`/`mcp_orbit` only (matching current Rails `RESOURCE_SCOPE_MAP` logic) - Store the dynamic client in YugabyteDB with `dynamic: true`, `confidential: false` - Return: `client_id`, `client_id_issued_at`, `redirect_uris`, `token_endpoint_auth_method: "none"`, `grant_types: ["authorization_code"]`, `require_pkce: true`, `scope`, `client_name` - Apply rate limiting per IP (matching current Rails behaviour) ### Replication: IAM → Rails - Newly registered dynamic clients need to be synced to Rails cells so that: - The consent UI can display application metadata - The authorized applications page works correctly - This is the reverse direction of the existing OAuth application replication (Rails → IAM) and needs to be scoped accordingly ### PKCE enforcement for dynamic clients - On `GET /oauth/authorize`: require `code_challenge`, enforce `code_challenge_method: S256` - On `POST /oauth/token` (authorization_code grant): require `code_verifier` - On `POST /oauth/token` (refresh_token grant): do not require `code_verifier` (matching current Rails behaviour) ### Scope restriction for dynamic clients - At token issuance, cap scopes to `mcp`/`mcp_orbit` for any client flagged as dynamic, regardless of what scopes are requested ### `client_secret`-free token exchange - Accept token requests from dynamic clients without a `client_secret` (`token_endpoint_auth_method: none`) - Rely solely on PKCE for proof of possession ## Scope (if Option B: Rails cell-1 owns registration) - `POST /oauth/register` stays in Rails on cell-1 - OAuth application replication (Rails → IAM) picks up dynamic clients and syncs them to IAM - IAM still needs to implement items 3–5 above (PKCE enforcement, scope restriction, secret-free exchange) - No IAM → Rails replication needed for dynamic clients ## Dependencies - OAuth application replication epic: https://gitlab.com/groups/gitlab-org/-/work_items/22152 - HTTP Router routing for unauthenticated OAuth requests - Topology Service (not applicable for unauthenticated registration — this is part of why the routing decision is needed) ## References - Current Rails implementation: `app/controllers/oauth/dynamic_registrations_controller.rb` - RFC 7591: https://datatracker.ietf.org/doc/html/rfc7591 </details> <details> <summary>Child Items</summary> ## Work-items - [ ] [`Issue`](https://gitlab.com/gitlab-org/gitlab/-/work_items/604546)`#1 (IAM)`: Enforce PKCE for dynamically-registered OAuth clients - Reference(s): https://gitlab.com/gitlab-org/gitlab/-/merge_requests/197644, [PKCE RFC spec](https://datatracker.ietf.org/doc/html/rfc7636), [Rails enforcement being matched](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/app/controllers/oauth/authorizations_controller.rb#L211-L224) - MR: https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/473 - [ ] Store the dynamic flag on oauth_clients and carry it over the client replication API and the consent challenge. - [ ] Reject dynamic client authorize requests without an S256 code_challenge. - [ ] Reject the plain challenge method for dynamic clients. - [ ] Require the code_verifier when exchanging a dynamic client's code. - [ ] Force the registered scope at authorize, like Rails does. - [ ] [`Issue`](https://gitlab.com/gitlab-org/gitlab/-/work_items/623569)`#2 (IAM)`: Allow IAM to create Dynamic Client Registration applications - Reference(s): https://gitlab.com/gitlab-org/gitlab/-/merge_requests/197644, [OAuth dynamic registration RFC spec](https://datatracker.ietf.org/doc/html/rfc7591), [Rails DCR controller being ported](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/app/controllers/oauth/dynamic_registrations_controller.rb) - MR: https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/560 - [ ] Add ability to register an anonymous OAuth application by API. - [ ] Match the Rails behavior: redirect_uris as string or array, resource wins over scope, only mcp/mcp_orbit, the unverified name prefix, the invalid_client_metadata error. - [ ] Never issue a client_secret (DCR replaces it due to PKCE). - **Blocked by**: `Issue#1` - [x] [`Issue`](https://gitlab.com/gitlab-org/gitlab/-/work_items/623570)`#3 (Rails)`: Allow ownerless clients on the IAM consent page - Reference(s): https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/560#note_3727417648, [the mandatory check](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/app/services/authn/iam_service/get_consent_challenge_service.rb#L6-L7) - [ ] Stop requiring client_owner in the consent challenge service. - [ ] [Mirror Rails consent DCR text](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/560#note_3732119190). - [ ] [`Issue`](https://gitlab.com/gitlab-org/gitlab/-/work_items/623571)`#4 (Rails)`: Remove the owner mirroring in the replication drain worker - Reference(s): [the mirroring being removed](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/workers/authn/iam_replication/drain_worker.rb#L87-L92), https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/560#note_3739492544 - **Blocked by**: `Issue#3` (merging this first breaks consent for mirrored dynamic apps) - [x] [`Issue`](https://gitlab.com/gitlab-org/gitlab/-/work_items/597595)`#5 (Rails)`: Resolve FK constraint on oauth_consents.client_id → oauth_applications.uid for cross-cell compatibility - Reference(s): [loose foreign keys documentation](https://docs.gitlab.com/development/database/loose_foreign_keys), https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/560#note_3727417697 - DCR relevance: [accepting consent](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/app/services/authn/iam_service/accept_consent_challenge_service.rb#L50) writes an oauth_consents row and [the FK](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/db/structure.sql#L58992) requires a matching oauth_applications row, which DCR clients living only on IAM don't have. Until this is resolved, consent for them can't complete without mirroring the client into Rails. - **Blocked by**: [`Issue#2`](https://gitlab.com/gitlab-org/gitlab/-/work_items/623569) - [ ] [`Issue`](https://gitlab.com/gitlab-org/gitlab/-/work_items/623572)`#6 (IAM)`: Add rate limiting to /oauth/register - Reference(s): https://gitlab.com/gitlab-org/gitlab/-/merge_requests/197644, https://gitlab.com/gitlab-org/gitlab/-/merge_requests/248395, https://gitlab.com/gitlab-org/gitlab/-/work_items/602404#note_3723263774, [Runway rate limiting docs](https://docs.runway.gitlab.com/runtimes/kubernetes/rate-limiting/), [the Runway provisioner config to change](https://gitlab.com/gitlab-com/gl-infra/platform/runway/provisioner/-/blob/main/config/runtimes/gke/workloads.yml) - [ ] Add the rate limit to the [`iam-auth-ext-gke` entry](https://gitlab.com/gitlab-com/gl-infra/platform/runway/provisioner/-/blob/main/config/runtimes/gke/workloads.yml#L69) in the Runway provisioner config. - [ ] Cover `/oauth/register` with a matching limit in [Rails](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/lib/gitlab/application_rate_limiter/labkit_adapter/supported_rate_limits.rb#L412-L418). - [ ] [`Issue`](https://gitlab.com/gitlab-org/gitlab/-/work_items/623573)`#7 (IAM & Rails)`: Add the authorized-by username stamp for dynamic apps on IAM - Reference(s): https://gitlab.com/gitlab-org/gitlab/-/merge_requests/244666, [the Rails stamp](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/app/controllers/oauth/authorizations_controller.rb#L74-L99) - This is a **GitLab specific feature not part of the DCR RFC spec**. - [x] [`Issue`](https://gitlab.com/gitlab-org/gitlab/-/work_items/623574)`#8 (IAM & Rails)`: Reject registrations at IAM when the instance turns DCR off - Reference(s): https://gitlab.com/gitlab-org/gitlab/-/merge_requests/248615, [the discovery document gate that covers this today](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/app/controllers/jwks_controller.rb#L29-L33) - [x] Decide on how to get [::Gitlab::CurrentSettings.dynamic_client_registration_enabled?](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/app/models/application_setting.rb#L818-L820) from Rails to the IAM service: - Rails pushes the value over gRPC when the setting changes. - IAM queries Rails and caches it. - Rails rejects dynamic clients in the [consent flow](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/app/controllers/iam/consent_controller.rb) instead, no transport needed (easiest but lots of issues will arise once Consent becomes a bottleneck). - [x] Return [403 access_denied like Rails](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/app/controllers/oauth/dynamic_registrations_controller.rb#L123-L131) when off. - [x] [`Issue`](https://gitlab.com/gitlab-org/gitlab/-/work_items/623575)`#9 (IAM & Rails)`: Clean up dynamic clients when DCR is disabled - Reference(s): https://gitlab.com/gitlab-org/gitlab/-/merge_requests/246028, [the Rails cleanup worker being matched](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/app/workers/authn/oauth_applications/cleanup_dynamic_applications_worker.rb), https://gitlab.com/gitlab-org/gitlab/-/issues/593992 - [ ] Run a cleanup worker when the setting flips off. - [ ] Delete IAM's dynamic clients and revoke their tokens. - [ ] Delete their oauth_consents rows in Rails. - **NB**: nothing deletes them automatically after `Issue#5`. - [ ] [`Issue`](https://gitlab.com/gitlab-org/gitlab/-/work_items/623576)`#10 (IAM)`: Serve the authorization server metadata document from IAM - Reference(s): [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-server-discovery), [authorization server metadata RFC spec](https://datatracker.ietf.org/doc/html/rfc8414), [the Rails paths being matched](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/app/controllers/jwks_controller.rb#L10-L16) - [ ] Serve [`/.well-known/oauth-authorization-server`](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/app/controllers/jwks_controller.rb#L10-L16) and the per-resource paths that [MCP clients request](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/config/routes.rb#L61-L66), like `/.well-known/oauth-authorization-server/api/v4/mcp`. - [x] Hide registration_endpoint when DCR is off. - **Blocked by**: `Issue#8` - [ ] [`Issue`](https://gitlab.com/gitlab-org/gitlab/-/work_items/623577)`#11 (IAM)`: Deployment - Reference(s): [proposal 005](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/blob/main/proposals/005-oauth_protocells.md), [AUTH-011](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/blob/main/proposals/011-oauth-gradual-rollout-plan.md) - [ ] Update proposal 005: IAM owns dynamic clients (the Option A carve-out). - [ ] Update AUTH-011: add [`/oauth/register`](https://datatracker.ietf.org/doc/html/rfc7591#section-3) and [`/.well-known/oauth-authorization-server`](https://datatracker.ietf.org/doc/html/rfc8414#section-3) to the [endpoint table](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/blob/main/proposals/011-oauth-gradual-rollout-plan.md#oauth-request-surface) as both served by IAM. - [ ] Update AUTH-011: exclude [`/.well-known/oauth-protected-resource`](https://datatracker.ietf.org/doc/html/rfc9728#section-3) and its path variants from the `/.well-known/*` rule, and tag the infra engineers who own the CF rules. </details>