## Summary Make an IAM-native dynamically registered client fully usable, end-to-end on dev localhost, staging.gitlab.com and gitlab.com. Route DCRs through Workhorse first (percentage rollout), then Cloudflare at stable release per [AUTH-011](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/blob/main/proposals/011-oauth-gradual-rollout-plan.md). ## Implementation Plan - [x] MR1: [Fall back to IAM on a Rails OAuth client lookup miss](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/256842) - [x] MR2: [Add register_routing Workhorse route to snapshot](https://gitlab.com/gitlab-org/cells/http-router/-/merge_requests/1418) - [x] MR3: [Proxy /oauth/register to the IAM Auth service](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/256841) - [x] MR4: [Docs: Add a guide for testing the DCR flow on GDK with an MCP client](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/701) - [x] MR5: [Skip IAM workhorse egress IPs before CF origin routing](https://gitlab.com/gitlab-com/gl-infra/platform/runway/provisioner/-/merge_requests/2021) - [x] MR6: [Rate limit oauth_register workhorse endpoint before routing it to IAM](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/262946) - [x] MR7: [Docs: Record DCR in Proposal-005 and the Workhorse routing in Proposal-011](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/merge_requests/148) - [x] MR8: [Docs: Add Dynamic Client Registration decisions](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/merge_requests/142) - [ ] MR9: [Docs: Update DCR IAM Setup](https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/987) #### Rollout - [ ] Make it ready for rollout in staging and production environments - [ ] Create a detailed rollout issue: https://gitlab.com/gitlab-org/gitlab/-/work_items/631994#environments <details> <summary>2nd draft</summary> ## Summary Make an IAM-registered DCR client usable end to end on GitLab.com. Route DCR through Workhorse first (percentage rollout), then Cloudflare at stable release per [AUTH-011](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/blob/main/proposals/011-oauth-gradual-rollout-plan.md). ## Plan 1. MR1 (Workhorse): proxy `/oauth/register` to IAM for the percentage rollout, behind `proxy_oauth_requests_to_iam_service`, like https://gitlab.com/gitlab-org/gitlab/-/work_items/594504. https://gitlab.com/gitlab-org/gitlab/-/merge_requests/256841 - Proxies [`/oauth/register`](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/app/controllers/jwks_controller.rb#L8) only. The base discovery docs stay on Rails during the interim and move to IAM at the Cloudflare cutover. 2. MR2 (IAM): mint a routable `gliamdc-` prefix on dynamically registered client_ids so Workhorse can route them. https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/700 3. MR3 (Workhorse): fix the `/oauth/authorize` routing gap by matching the `gliamdc-` prefix. https://gitlab.com/gitlab-org/gitlab/-/merge_requests/256842 - [The routing decision](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/lib/api/internal/workhorse.rb#L48-L53) looks up `client_id` in the Rails DB, so an IAM-only client falls to Doorkeeper with `invalid_client`. - 2 options were considered: - Option 1: match a routable prefix on IAM client_ids in the [authorize handler](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/workhorse/internal/oauthproxy/oauthproxy.go#L72-L90) before the Rails lookup. Cheapest, a string check with no round-trip, but IAM has to mint prefixed client_ids (MR2). - Option 2: have `oauth_routing` ask IAM when the Rails lookup misses. Keeps client_ids opaque, but adds a per-request IAM call, latency, and an amplification risk from unknown client_ids. - To maintain parity with the [token-prefix routing](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/workhorse/internal/oauthproxy/oauthproxy.go#L37-L44), I went with Option 1. 4. MR4 (ADRs): update the proposals to match. https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/merge_requests/142 - [Proposal 005](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/blob/main/proposals/005-oauth_protocells.md): include dynamic client applications. - [AUTH-011](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/blob/main/proposals/011-oauth-gradual-rollout-plan.md): add `/oauth/register` and base `/.well-known/oauth-authorization-server` as IAM-served, and exclude `oauth-protected-resource` from the `/.well-known/*` rule. 5. MR5 (IAM docs): add GDK docs for testing the full DCR flow with an MCP client. https://gitlab.com/gitlab-org/auth/iam/-/merge_requests/701 6. Cloudflare cutover (infra owns the CF rules): at stable release, `/oauth/*` and base `/.well-known/*` route to IAM via a CF Origin Rule, with `/.well-known/oauth-protected-resource` excluded. ## Acceptance criteria - [ ] DCR works end to end through the Workhorse path for an IAM-registered client (register, authorize, token). - [ ] Add a full working demo using each of the MCP clients listed in the [GitLab MCP server docs](https://docs.gitlab.com/user/model_context_protocol/mcp_server/). - [ ] Base `/.well-known/oauth-authorization-server` and `/.well-known/openid-configuration` resolve to IAM. - [ ] `/.well-known/oauth-protected-resource` stays on Rails. - [ ] Non-IAM clients keep hitting Rails, unaffected. - [ ] The rollout is gated by a feature flag, so rollback is disabling the flag with no deploy. - [ ] Proposal 005 and AUTH-011 updated to match. </details> </details> </details> <details> <summary>1st draft</summary> ## Summary The auth design docs predate DCR and the MCP discovery documents. Two proposals need updates so the docs match the decided architecture. ## Proposal - [ ] Update [proposal 005](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/blob/main/proposals/005-oauth_protocells.md): the "authoritative data store for OAuth application" statement needs the [Option A](https://gitlab.com/gitlab-org/gitlab/-/work_items/602404#note_3708392531) carve-out for dynamic clients. - [ ] Update [AUTH-011](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/blob/main/proposals/011-oauth-gradual-rollout-plan.md): 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. **NB**: Clarify whether `/oauth/register` needs to be proxied through [Workhorse as a temporary layover](https://gitlab.com/gitlab-org/gitlab/-/work_items/594504#top) before rollout, or whether all DCR routing waits for CloudFlare. See: "[Once the rollout is complete and the refresh token migration has finished, `/oauth/*` requests are routed directly to the IAM Auth service using a **Cloudflare Origin Rule**.](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/blob/main/proposals/011-oauth-gradual-rollout-plan.md#routing-logic-during-rollout)" - If we are letting CF handle the routing per [AUTH-011](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/blob/main/proposals/011-oauth-gradual-rollout-plan.md#routing-logic-during-rollout): - No interim work. Follow AUTH-011 and add the [CF Origin Rules](https://developers.cloudflare.com/rules/origin-rules/) at rollout. - [`/oauth/register`](https://datatracker.ietf.org/doc/html/rfc7591#section-3) rides the `/oauth/*` rule and the [OAUTH_PATHS discovery documents](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/app/controllers/jwks_controller.rb#L10-L16) ride the `/.well-known/*` rule (with the `oauth-protected-resource` exclusions above). - If we are letting Workhorse handle the routing before rollout: - Like https://gitlab.com/gitlab-org/gitlab/-/work_items/594504+, proxy [DYNAMIC_REGISTRATION_PATH](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/app/controllers/jwks_controller.rb#L8) and [OAUTH_PATHS](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/app/controllers/jwks_controller.rb#L10-L16) to the IAM service. - The gap is `/oauth/authorize`. [The routing decision](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/lib/api/internal/workhorse.rb#L48-L53) looks the client_id up in the Rails DB and unknown ids fall back to `rails`, so a client that only exists on IAM lands on Doorkeeper and fails with invalid_client. - [ ] Update the `/oauth/authorize` routing logic, either: - Give IAM-registered client_ids a routable prefix and match it in [Workhorse's authorize handler](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/workhorse/internal/oauthproxy/oauthproxy.go#L72-L90) before the Rails lookup, like the existing [iamTokenPrefixes](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/workhorse/internal/oauthproxy/oauthproxy.go#L37-L44) match on the token endpoints. - Or extend the [oauth_routing decision](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/lib/api/internal/workhorse.rb#L48-L53) to ask IAM when the Rails lookup misses, and route to `iam` when IAM knows the client. - Or many see if previous route matches a DCR route...etc.. ## Dev Add-on - [ ] Add IAM docs on how to test the full DCR flow on GDK with an MCP client. - We could use [GDK nginx](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/support/templates/nginx/conf/nginx.conf.erb) to mimic [CF Origin Rules](https://developers.cloudflare.com/rules/origin-rules/) on GDK instead of the below. - [ ] Add a dev-only override so the [PRM](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/app/controllers/oauth/protected_resource_metadata_controller.rb#L29) returns `authorization_servers: [Authn::IamAuthService.url]` instead of `Gitlab.config.gitlab.url` when [Authn::IamAuthService.enabled?](https://gitlab.com/gitlab-org/gitlab/-/blob/bcefb7d66026/lib/authn/iam_auth_service.rb#L11-L13) is on in GDK. No new config needed. - [ ] Create a new IAM docs matching the flow in [mcp-flow](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#sequence-diagram). - [ ] Full demo of a MCP-Client creating a DCR using the IAM service ## Reference(s) - https://gitlab.com/gitlab-org/gitlab/-/work_items/602404#note_3708392531, the Option A decision </details>