## Problem The monolith has a per-endpoint authorization declaration mechanism. Modular features do not, and nothing in the GATE or LabBench roadmaps is building them one. The asymmetry is visible in the two shipped features: - **Orbit**, being Grape in the monolith, declares `route_setting :authorization, permissions: :read_knowledge_graph, boundary_type: :user` on every one of its eleven endpoints, plus a class-level `allow_access_with_scope :read_api`. That information exists, is structured, and reaches no consumer — the same `hidden true` that hides the endpoints from the spec hides their auth contract too. - **Artifact Registry**, being external, has no equivalent. Its spec says `bearerToken: {type: http, scheme: bearer}` and nothing more. Which of ten AR permissions an endpoint needs, and which of four AR roles grants it, lives in an ADR still marked Proposed and in Cedar policies AR authors itself. ### What the platform does and does not cover GATE's integration model for modular features is settled. LabBench services do not embed GATE: the chassis Inbound layer verifies that an incoming request carries a valid **URT**, a signed credential GATE attaches after authenticating and authorizing at the data plane via Envoy, and rejects any request that did not pass through GATE. This is a composed LabKit module, not reimplemented per service. What is explicitly deferred is the part this epic is about. Fine-grained, in-binary policy decisions are Mode 3 and are not in scope for the inbound layer's first phase. GATE's own decisions say the same thing from the other direction: AUTH-009 delegates fine-grained authorization to the service, AUTH-018 makes modular feature teams the authors of their own policies, and AUTH-021 states that in the interim "authorization remains the service's responsibility". AUTH-020 builds precisely the per-endpoint declaration mechanism this epic needs — for the monolith only. Per-endpoint scopes for modular feature APIs appear in no GATE document, and the shipped token-exchange endpoint scopes solely by `audience`, deliberately omitting a `scopes` claim. ### Multi-language settles where the fix has to live `route_setting :authorization, permissions:` is a Ruby and Grape mechanism. There is no cross-language equivalent. With two supported LabBench runtimes today and two more named in the schema, a code-level declaration mechanism would have to be built and maintained per runtime. So per-endpoint permission declaration has to live in the **schema or the proto**, not in the code, or it fragments the moment a second language appears. That is a constraint on the solution, not a preference. ### Why it matters now The Orbit and Artifact Registry epic is about to publish specs that do not say how to authenticate against them, for APIs whose authorization model is decided per service with no shared vocabulary. That is not a documentation gap — it is why a customer cannot generate a working client, and it is why Artifact Registry's own ADR flags that "a leaked CI job token carries the user's full permissions" as a deferred concern. ## Scope boundary with GATE Deliberately narrow, and drawn along lines GATE's own ADRs already state. | GATE / `group::authentication` owns | This epic owns | |---|---| | `POST /api/v4/token_exchange`, the JWT payload schema (AUTH-021), JWKS, TTLs | How a spec declares those schemes so a consumer can act on them | | URT issuance and the Envoy data-plane enforcement point | How an endpoint declares the permission it requires, in a form that reaches the spec | | GLAZ, Cedar, the L1/L2 split (AUTH-009), the role-to-permission YAML vocabulary (AUTH-015) | A consistent `401` and `403` error shape across modular feature APIs | | Each feature team authoring its own Cedar policies (AUTH-018) | Guidance on which of the live auth models a new feature should pick | If any row moves, it should be by explicit agreement with `group::authentication`, not by drift. ## Goal ### First iteration 1. Agree the boundary above with `group::authentication` in writing before anything is built. Do not start by claiming another team's roadmap. 2. Ask the one question that decides the shape of everything after: does AUTH-020's hierarchical actions model extend to modular services, or does API Platform define the modular-feature equivalent? Their answer, not our preference, sets the long-term scope. 3. Document the live auth models and when to choose each: in-monolith Grape, external service with client-side token exchange, and LabBench chassis with URT verification. 4. Express Artifact Registry's token-exchange flow in its OpenAPI spec as accurate `securitySchemes`, using the published spec as the worked example. 5. Agree a consistent authentication and authorization error shape. ### Long-term outcome - Every published modular feature spec is complete enough to generate a working client from, auth included. - Required permissions are declared per endpoint in a shared, language-neutral vocabulary, closing the gap between Orbit's `route_setting` and Artifact Registry's Cedar bundles. - Those declarations are structured enough to drive edge request validation rather than being prose. - A team building a modular feature picks an auth model from a documented default instead of designing one — which is what LabBench needs before it can implement the AuthN+Z responsibility its architecture docs already claim for the Inbound layer. ## Technical considerations - **Do not sequence this behind GATE delivery.** The design is settled but nothing is in production: GATE's `plan.md` self-describes as outdated since February 2026, `delivery/infra_help.md` shows the IAM services and Envoy as prototypes and sandbox deployments, and `ee/lib/api/authn/token_exchange.rb` describes itself as a PoC "expected to be superseded by GATE L2 later". Everything in the first iteration is achievable against the interim state. - Artifact Registry's shape may still move. Its interim model is blocked on Cloud Connector v2, which has no owner: https://gitlab.com/gitlab-org/gitlab/-/work_items/594941 - Artifact Registry's ADR-020 and ADR-021 are both status Proposed, and ADR-021 notes the handbook interface agreement currently contradicts them on roles. Treat neither as settled. - The declaration mechanism, if this epic ends up owning one, has to be language-neutral. See the epic "Establish one API definition model for all GitLab modular features" (https://gitlab.com/groups/gitlab-org/quality/-/work_items/465) — if LabBench's `inbound.proto` grows schemas, that is the natural home for a permission annotation too. ## Links **Contacts**: `group::authentication` (`#g_authentication`), João Pereira (Artifact Registry), Angelo Rivera (Orbit), Elliot Forbes (LabBench alignment) GATE design doc: https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc Token exchange implementation: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/236798 LabBench inbound layer and URT model: https://gitlab.com/gitlab-org/lab-bench/bench/-/work_items/4