GitLab currently uses a single-step authentication process where users enter both email/username and password on the same page. This approach has several limitations:
- No organization-specific branding or authentication policies
- Limited support for organization-specific authentication methods (SAML, custom IdPs)
- No routing based on user's organizational context
- All users authenticate through the same generic endpoint
Modern enterprise applications like Google Workspace, Slack, and Microsoft 365 use multi-step authentication flows that first identify the user's organization context, then route them to organization-specific authentication experiences. This enables branded login pages, organization-specific authentication methods, and better user experience.
With the introduction of Organizations in GitLab, we need to implement a similar pattern to support organization-specific authentication while maintaining backward compatibility for existing users.
## Decision
We will implement a multi-step authentication flow that separates user identification from authentication:
### Step 1: User Identification
- Users visit `gitlab.com/users/sign_in` and enter their email address
- The system uses the Topology Service to determine which organization the user belongs to
- Users are redirected to their organization-specific login page at `gitlab.com/o/<org-path>/users/sign_in`
### Step 2: Organization-Specific Authentication
- Users authenticate using organization-configured methods (password, SAML, etc.)
- Organization branding and specific authentication policies are applied
- If 2FA is required, it appears as a separate screen after primary authentication
### Backward Compatibility
- Username-based login continues to work on the legacy `/users/sign_in` page
- All existing OAuth and SAML callback paths are preserved
- Direct organization access via `gitlab.com/o/<org-path>/users/sign_in` is supported
### Email Uniqueness
- Each email address belongs to exactly one organization across all GitLab instances
- Email domains can be restricted to specific organizations
- The Topology Service provides deterministic routing based on email domain mapping
### Alternative Access
- Users can directly access organization login pages via `gitlab.com/o/<org-path>/users/sign_in`
- Private organizations redirect anonymous users to their login page
- Public organizations show their page immediately with sign-in options
## Consequences
### Positive Consequences
-**Organization Branding**: Organizations can provide branded login experiences with custom logos and styling
-**Flexible Authentication**: Organizations can configure specific authentication methods (SAML-only, password + 2FA, etc.)
-**Scalable Architecture**: Supports distributed cell architecture with organization-specific authentication policies
### Technical Consequences
-**Legacy Cell Compatibility**: The `/users/sign_in` page continues to be served by the Legacy Cell or any Cell at later point
-**Topology Service Integration**: Rails integration required for email classification and organization routing
-**Callback Preservation**: All existing OAuth (`/oauth/callback`) and SAML (`/groups/my-group/-/saml/callback`) callback paths remain unchanged
-**Username Support**: Username-based authentication continues to work for backward compatibility
## Alternatives
### Subdomain-Based Routing
We evaluated using subdomains like `acme.gitlab.com` for organization-specific login. This was rejected because:
- Complex DNS management and SSL certificate requirements
- Not compatible with all GitLab services (SSH, API endpoints)
- Would break existing integrations and bookmarks
- Difficult to implement across all deployment models (SaaS, Self-Managed, Dedicated)
-**Email input**: Routes to user's organization via Topology Service
-**Username input**: Continues to work for default organization users on legacy cell
-**Direct access**: Users can always access `o/<org-path>/users/sign_in` directly
### Step 2: Organization-Specific Authentication
```mermaid
graph TD
A[User arrives at organization page] --> B[Organization login page loads]
B --> C{Authentication methods available}
C -->|SAML| D[SAML authentication]
C -->|Password| E[Password authentication]
D --> G[Success]
E --> H{2FA required?}
H -->|Yes| I[Separate screen: 2FA challenge]
H -->|No| G
I --> G
style B fill:#e8f5e8
style I fill:#fff3e0
style G fill:#e1f5fe
```
**Organization Login Page:**
```text
┌─────────────────────────────────────┐
│ [Org Logo] Acme Corporation │
│ │
│ user@acme.com (prefilled) │
│ │
│ ✓ Sign in with SAML │
│ ┌─────────────────────────────────┐│
│ │ [Continue with SAML] ││
│ └─────────────────────────────────┘│
│ │
│ ✓ Password Authentication │
│ ┌─────────────────────────────────┐│
│ │ [Password Field] ││
│ │ [Sign in Button] ││
│ └─────────────────────────────────┘│
│ │
│ [← Change email address] │
└─────────────────────────────────────┘
```
## Email Uniqueness
### Core Principle
The system enforces that **each email address belongs to exactly one organization** across all GitLab instances and cells.
System will also enforce that the particular e-mail domain can belong only to one organization, user would not be able to register into another organization with the e-mail domain belonging to the organization.
**Current Behavior:** OAuth callbacks use existing paths like `gitlab.com/oauth/callback`
**Future State:** This design maintains existing OAuth callback paths to avoid breaking changes. Users will be routed appropriately after callback processing based on their organization membership.
### SAML Applications
**Current Behavior:** SAML callbacks use group-scoped paths like `gitlab.com/groups/my-group/-/saml/callback`
**Backward Compatibility:** Existing SAML callback paths will continue to work exactly as they do today.
**Future Enhancement:** The system will scope callbacks to their appropriate context:
This ensures that callbacks remain contextually appropriate to where the SAML configuration was defined, while maintaining full backward compatibility with existing integrations.
Application would show button for all configured SAML applications in a Organization:
- Organization-scoped SAML application if configured.
- Organization having many top-level groups, with multiple SAML applications.
-**Clean Token Management**: No complex cross-cell token sharing (eg. CSRF)
-**Scoped Callbacks**: Future callback scoping aligns with configuration context
## Additional Notes and Remarks
### Authentication Method Coverage
-**2FA Definition**: Throughout this document, "2FA" includes various methods such as TOTP, hardware keys, passkeys, and other multi-factor authentication options
-**OAuth Flows**: OAuth authentication flows are out of scope for this document and will be defined at later point
### Technical Considerations
-**Callback Paths**: All existing OAuth and SAML callback paths are preserved to maintain backward compatibility
-**User Experience**: 2FA challenges appear as separate screens after successful password authentication
-**Organization Routing**: The Topology Service provides deterministic routing based on email or domain mapping
### Future enhancements
- Define behavior when GitLab is used as SP in OAuth flows
- Define behavior when GitLab is used as IdP in OAuth flows
