Federated Authentication With IAM Auth service
## Overview
This epic tracks the implementation of **Federated Authentication with the IAM Auth service** for GitLab ProtoCells. The goal is to enable external provider authentication (GitHub, Google, etc.) using a federated OIDC approach where the IAM service acts as an OIDC provider and federation broker.
The design proposal is documented in [gitlab-org/architecture/auth-architecture/design-doc!81](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/merge_requests/81) (merged).
## Proposed Architecture
Rather than the existing pattern (GitLab Rails acting directly as an OAuth client to external providers) or the earlier proposal (IAM as OAuth client sending a custom signed payload to the user's Cell), this epic implements a cleaner federated OIDC approach:
```mermaid
graph LR
User[👤 User]
Cell[GitLab Cell<br/><b>OIDC Client</b>]
IAM[IAM Service<br/><b>OIDC Provider</b><br/><b>Federation Broker</b>]
Provider[GitHub/Google<br/><b>OAuth Provider</b>]
User -->|OIDC Flow| Cell
Cell <-->|OpenID Connect<br/>Authorization Code Flow| IAM
IAM <-->|OAuth 2.0<br/>Authorization Code Flow| Provider
Cell -->|Session| User
style Cell fill:#1f77b4,color:#fff
style IAM fill:#2ca02c,color:#fff
style Provider fill:#ff7f0e,color:#fff
```
**Key difference from previous proposals:** The IAM service acts as a standards-compliant **OIDC Provider** (not a custom signed payload issuer), and each GitLab Cell acts as an **OIDC Client**. This eliminates the non-standard token handoff from the earlier design.
## Key Components
- **IAM proxy middleware** - handles federation brokering between Cells and external OAuth providers
- **Org-aware routes** - organization-aware callback URLs for correct Cell routing
- **Cells-aware OmniAuth strategy** - updated OmniAuth integration in GitLab Rails to support OIDC flow via IAM
- **Configuration** - updates to GitLab Rails and IAM service configuration
## Security Considerations
- OAuth 2.0 with PKCE
- Standard OIDC token validation (no custom payload formats)
- Cell routing through organization-aware callback URLs
epic