This epic tracks the Authentication team's deliverables to support the [Artifact Registry (AR) modular service](https://gitlab.com/groups/gitlab-org/-/work_items/19844). Following the direction set in [#595148](https://gitlab.com/gitlab-org/gitlab/-/work_items/595148), AR moves to a control plane / data plane model where SaaS AR serves multiple Rails instances (.com Cells, Dedicated, Self-Managed). The Authentication team owns the AuthN/AuthZ contract, Cloud Connector v2 integration, and the role assignment APIs that AR depends on. Scope covers both the interim approach (AR simulating the GATE enrichment layer inline) and then separately in future for target state (GATE Envoy enrichment layer + GLAZ embedded in AR), along with the migration path between them. See parent epic [&21559](https://gitlab.com/groups/gitlab-org/-/work_items/21559) for cross-team coordination. **Key deliverables** - **AR Auth API contract** — token formats, claims, and validation rules for both interim and GATE-final flows. - **Cloud Connector v2 → AR integration** — IJWT → GATE exchange for Private Key + CloudCreds, JWT minting on SM/Dedicated, local validation in AR (no callbacks to the GitLab instance). - **Role assignment API & storage** — APIs AR uses to read/write role assignments (org and repo scope) backed by GATE's relationships API, with a migration path to GATE/GLAZ. - **Identity & scope conventions** — supported identity formats (user, service, instance) and authorization scopes AR expects in tokens. - **Enrichment layer PoC** — validate AR's interim inline simulation of the GATE enrichment layer and a clear migration path to the target state. ## Sequence Diagrams ### Control plane ```mermaid sequenceDiagram participant Admin as GitLab.com Org Owner / AR Admin participant Rails as GitLab Rails (.com) participant IAM_Update as IAM Data Access participant Yugabyte as Yugabyte DB participant AR as Artifact Registry Note over Admin,AR: Role assignment Admin->>Rails: Manage AR permissions (UI) Rails->>AR: Fetch repository list (API) AR->>Rails: Repositories Admin->>Rails: Assign User A as contributor on Repository X Rails->>Rails: Generate JWT Rails->>IAM_Update: Create role assignment (user, role, repository) rect rgb(255, 255, 153) note right of Rails: Pass JWT for auth end IAM_Update->>Rails: Fetch root public key (cached) IAM_Update->>IAM_Update: Validate JWT signature (root public key) IAM_Update->>IAM_Update: Validate service token IAM_Update->>Yugabyte: Persist assignment ``` ### Data plane ```mermaid sequenceDiagram participant Client as Client participant Rails as GitLab Rails (.com) participant IAM_Lookup as IAM Data Access participant AR as Artifact Registry participant GLAZ as GLAZ (sidecare to AR) Note over Client,Rails: 1. Obtain token (out-of-band) Client->>Rails: Authenticate (PAT, CI job token, etc.) Rails->>Rails: Validate credentials, issue JWT signed with existing CC key Rails->>Client: JWT without CloudCreds (identity, request scoped permissions, hard coded entitlements) Note over Client,GLAZ: 2. Request artifact Client->>AR: Request artifact Note over AR,Rails: 3. AR: validate identity + enrich (simulating enrichment layer) AR->>Rails: Fetch root public key (cached) AR->>AR: Validate JWT signature (within IAM library) AR->>IAM_Lookup: Look up relationships tuples (relationships API) rect rgb(255, 255, 153) note right of IAM_Lookup: Pass JWT end IAM_Lookup->>AR: Relationships tuples AR->>AR: Cache relationships response Note over AR,GLAZ: 4. AR: evaluate domain-specific policies AR->>GLAZ: check(subject, action, resources, context) gRPC call GLAZ->>GLAZ: role<>permission evaluation + Cedar policy checks GLAZ->>AR: ALLOW or DENY AR->>Client: Response ``` <details> <summary>Cross-realm</summary> ### 1. Control plane: trust establishment and role assignment (interim state) ```mermaid sequenceDiagram participant Admin as SM Admin participant SM as Self-Managed Instance participant CDot as CustomersDot participant GLGO as GLGO participant IAM_Update as IAM Data Access participant Yugabyte as Yugabyte DB participant AR as Artifact Registry (SaaS) Note over Admin,AR: Phase 1: Bootstrap (existing flow, unchanged) SM->>CDot: cloudConnectorAccess GraphQL query (license key) CDot->>CDot: Verify license & subscriptions CDot->>SM: IJWT (instance-scoped token) Note over Admin,AR: Phase 2: Credential exchange (new) SM->>SM: Generate key pair SM->>GLGO: Present IJWT and Public Key for credential exchange GLGO->>GLGO: Validate IJWT against CDot signing key GLGO->>GLGO: Generate CloudCreds (JWS) encrypted with customer's public key GLGO->>SM: Encrypted CloudCreds SM->>SM: Decrypt CloudCreds, store in database Note over Admin,AR: Phase 3: Role assignment (as needed) Admin->>SM: Manage AR permissions (UI) SM->>AR: Fetch repository list (API) AR->>SM: Repositories Admin->>SM: Assign User A as contributor on Repository X SM->>IAM_Update: Create role assignment (user, role, repository) rect rgb(255, 255, 153) note right of SM: cloud.gitlab.com/v2/gate/relations end IAM_Update->>GLGO: Fetch root public key (cached, one key) IAM_Update->>IAM_Update: Validate CloudCreds signature (root key) IAM_Update->>IAM_Update: Validate JWT signature (public key from CloudCreds) IAM_Update->>Yugabyte: Store federated identity mapping SM identity to GATE identity IAM_Update->>Yugabyte: Persist assignment Note over Admin,AR: Phase 4: Credential rotation (periodic) SM->>GLGO: Request new credentials GLGO->>SM: Rotated Encrypted CloudCreds ``` ### 2. Data plane: interim state ```mermaid sequenceDiagram participant Client as Client participant SM as Self-Managed Instance participant GLGO as GLGO participant IAM_Lookup as IAM Data Access participant AR as Artifact Registry participant GLAZ as GLAZ (in AR) Note over Client,SM: 1. Obtain token (out-of-band) Client->>SM: Authenticate (PAT, CI job token, etc.) SM->>SM: Validate credentials, sign JWT with CC v2 Private Key SM->>Client: JWT + CloudCreds (identity, entitlements, request scoped permissions) Note over Client,GLAZ: 2. Request artifact Client->>AR: Request artifact Note over AR,GLGO: 3. AR: validate identity (using IAM library) + enrich (simulating enrichment layer) AR->>GLGO: Fetch root public key (cached, one key) AR->>AR: Validate CloudCreds signature (root key) AR->>AR: Validate JWT signature (public key from CloudCreds) AR->>IAM_Lookup: Look up role assignments for user (relationships API) rect rgb(255, 255, 153) note right of IAM_Lookup: Pass user JWT for authentication end IAM_Lookup->>AR: Relationships tuples AR->>AR: Cache relationships response Note over AR,GLAZ: 4. AR: evaluate domain-specific policies AR->>GLAZ: check(subject, action, resources, context) gRPC call GLAZ->>GLAZ: Cedar policy: role + AR access rules (tighten-only) GLAZ->>AR: ALLOW or DENY AR->>AR: Check entitlement from CloudCreds AR->>Client: Response ``` </details> **Key references** - Parent epic: [&21559](https://gitlab.com/groups/gitlab-org/-/work_items/21559) - Direction issue: [#595148](https://gitlab.com/gitlab-org/gitlab/-/work_items/595148) - Related: [#595150](https://gitlab.com/gitlab-org/gitlab/-/work_items/595150) - [ADR-020: Authentication Flow](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/artifact_registry/decisions/020_authentication_flow/) - [ADR-021: Authorization](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/artifact_registry/decisions/021_authorization/) - [Cloud Connector v2 proposal (GATE)](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/blob/main/proposals/009-gate-cloud-connector.md) -