<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Label this issue](https://contributors.gitlab.com/manage-issue?action=label&projectId=278964&issueIid=585232) </details> <!--IssueSummary end--> ## Overview This task tracks the GitLab Rails changes required to support the OAuth client flow implementation in the IAM Service. This is part of the broader effort to implement OAuth client flow for the Cells Architecture. ## Context As part of [IAM Service: OAuth client flow (#580755)](https://gitlab.com/gitlab-org/gitlab/-/issues/580755), the IAM Service will handle OAuth flows with external providers and forward authenticated requests to the appropriate cell. This task focuses on the **GitLab Rails side** of the integration. **Note:** The original implementation in [!214782](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/214782) was too large for review. This plan breaks it down into smaller, incremental MRs. ## Scope This task covers the GitLab Rails changes needed to: 1. **Receive and verify signed payloads** from IAM Service containing user authentication data 2. **Process OAuth callback requests** forwarded by IAM Service after successful external provider authentication 3. **Provision/update user accounts** based on the identity information from IAM Service 4. **Link external identities** to GitLab user accounts 5. **Establish Rails sessions** for authenticated users 6. **Handle redirects** to the user's intended destination after authentication ## Implementation Plan ### Step 1 / MR 1: Support Basic Sign-in Flow, Introduce Feature Flag **Status:** 🔄 In Review - [!218776](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/218776) **Scope:** Core authentication flow with basic user provisioning **Changes:** - `Organizations::AuthController#callback` to receive IAM requests - JWT payload verification using existing JWKS validation - Transform JWT claims into OmniAuth auth hash format - User provisioning via existing `Gitlab::Auth::OAuth::User` - Session management using existing `sign_in` helper - Identity linking using existing `Identity` model - Basic redirect to dashboard after sign-in - Authentication event logging - Feature flag `iam_svc_login` **Deliverable:** Basic sign-in functionality with feature flag control ### Step 2 / MR 2: Support All Edge Cases **Scope:** Handle blocked users, 2FA, passkeys, banned users, and other edge cases **Changes:** - Validate user blocked status before sign-in (reject with error) - Handle deactivated user reactivation using existing flow - Handle banned users and prevent authentication - Support 2FA enforcement and validation - Support passkey authentication flows - Handle user state transitions (active, deactivated, blocked, banned) - Add user-friendly error messages for authentication failures - Support for remember me option - Add specs for all user state and edge case scenarios **Deliverable:** Robust handling of all user states and authentication edge cases ### Step 3 / MR 3: Account Provisioning and Onboarding **Scope:** Complete user provisioning and GitLab.com onboarding flow **Changes:** - Check signup enabled/disabled settings for new users - Create new user accounts from IAM Service authentication data - Update existing user attributes based on JWT claims - Handle user profile synchronization (name, email, etc.) - Check if user has accepted current terms after sign-in - Check if onboarding is enabled for the instance (EE SaaS) - Redirect new users to onboarding flow after sign-in - Handle organization provisioning using existing mechanisms - Track onboarding completion status - Skip onboarding for existing users - Add specs for provisioning, terms acceptance, and onboarding scenarios **Deliverable:** Complete user provisioning with terms compliance and seamless onboarding for new SaaS users ### Step 4 / MR 4: Implement Backward Compatibility with OmniAuth Layer **Scope:** Ensure full compatibility with existing OmniAuth infrastructure **Changes:** - Leverage existing `Gitlab::Auth::OAuth::User` infrastructure for user provisioning - Integrate with current OmniAuth provider configurations - Ensure compatibility with existing OAuth workflows - Reuse identity management and user linking logic - Support existing OmniAuth callbacks and hooks - Handle multiple identity linking for the same user - Prevent duplicate identity creation - Ensure existing OmniAuth-based features continue to work - Add integration tests for OmniAuth compatibility - Add specs for backward compatibility scenarios **Deliverable:** Full backward compatibility with existing OmniAuth layer ### Step 5 / MR 5: Security Hardening, Audit Events, Observability **Scope:** Production-ready security, audit trail, and monitoring **Changes:** - Add rate limiting to callback endpoint (per IP/user) - Implement safe redirect validation (allowlist, prevent open redirects) - Verify CSRF protection is properly applied - Add security headers to responses - Create audit events for user creation via IAM - Create audit events for user profile updates via IAM - Create audit events for identity linking/unlinking - Add structured logging for debugging (request ID, user ID, provider) - Ensure no sensitive data (tokens, JWTs) in logs - Add integration tests for complete authentication flow - Add specs for audit event creation - Add developer documentation (architecture, flow diagrams) - Add admin documentation (configuration, troubleshooting) - Add troubleshooting guide for common issues **Deliverable:** Production-ready security posture, complete audit trail, full observability, and documentation ## Expected Flow (Rails Perspective) 1. IAM Service completes OAuth flow with external provider (Google, GitHub, etc.) 2. IAM Service determines user's owning cell via Topology Service 3. IAM Service forwards request to OAuth callback endpoint on the user's cell with signed payload 4. **GitLab Rails (this task):** - Verifies the signed payload from IAM Service - Provisions or updates the user account - Links the external identity to the user - Handles terms acceptance if required - Manages onboarding flow for new users (EE SaaS) - Creates audit and authentication events - Creates a Rails session - Redirects user to intended destination ## Key Components to Implement/Modify - `Organizations::AuthController` to handle OAuth callbacks from IAM Service - JWT verification using existing JWKS infrastructure - User provisioning logic leveraging `Gitlab::Auth::OAuth::User` - Identity linking for external OAuth providers - Session establishment using existing session management - User state validation (blocked, banned, deactivated, 2FA, passkeys) - Terms acceptance flow integration - Onboarding flow integration for EE SaaS - OmniAuth backward compatibility layer - Audit event logging for authentication activities - Security hardening (rate limiting, redirect validation, CSRF) - Observability (metrics, structured logging) ## Dependencies - IAM Service OAuth client implementation (handled in parent issue) - Existing JWKS validation infrastructure (already merged) - Existing OmniAuth framework and infrastructure - Existing session management mechanisms - Topology Service integration (for cell routing) ## Related Work - [!214782 - Draft: Login using IAM service](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/214782) - Original implementation (too large, plan changed to incremental approach) - [!218776 - Add Basic Signin with IAM auth client](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/218776) - 🔄 **In Review** - Step 1: Basic sign-in functionality ## References - Parent: [IAM Service: OAuth client flow (#580755)](https://gitlab.com/gitlab-org/gitlab/-/issues/580755) - [OAuth Protocells Design Document](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/blob/main/proposals/005-oauth_protocells.md) - [Sequence Diagram: Login with Google on GitLab](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/blob/main/proposals/005-oauth_protocells.md#gitlab-as-oauth-client---login-with-external-provider) - [ADR: OAuth Cells](https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/blob/main/decisions/002_oauth_cells.md)