Skip to content

Step-up auth: Group-based OIDC Step-up Authentication

Problem / Motivation

Currently, GitLab provides uniform access controls across all groups within an instance. However, enterprise organizations often have varying security requirements:

  • Some groups contain highly sensitive intellectual property requiring device-based authentication
  • Different groups may need different authentication context classes (ACRs) based on their security classification
  • Group owners need the flexibility to configure step-up authentication requirements independently
  • Users should be prevented from accessing any resources within a protected group namespace without proper step-up authentication

Without group-level step-up authentication, organizations must either:

  1. Apply the highest security level instance-wide (reducing usability)
  2. Accept lower security for sensitive groups (increasing risk)
  3. Manage separate GitLab instances (increasing operational overhead)

Proposal / Solution

Implement group-based OIDC step-up authentication that allows group owners to:

  1. Enable/disable step-up authentication for their group
  2. Select the OIDC provider that should perform the step-up authentication
  3. Configure the required ACR level for group access
  4. Inherit protection from parent groups (if parent group requires step-up auth, all subgroups inherit this requirement)

Protection Scope

When step-up authentication is enabled for a group, users must be step-up authenticated to:

  • Access the group's main page
  • View group settings and configuration pages
  • Access any projects within the group namespace
  • Perform any actions within projects in the group (including merge requests, issues, etc.)
  • Access subgroups and their resources
  • View group-level CI/CD pipelines and jobs
  • Etc.

Configuration Approach

Follow the same configuration approach with the gitlab.yml as proposed and implemented for step-up authentication for admin mode.

We simply propose to add a new scope namespace to the step-up auth config. The following collapsed section shows an example for how to configure an openid_connect provider to allow step-up authentication for groups.

Click to expand the example for step-up auth config for groups 
   production: &base
     omniauth:
       providers:
       - { name: 'openid_connect',
           label: 'Provider name',
           args: {
             name: 'openid_connect',
             # ...
             allow_authorize_params: ["claims"], # Match this to the parameters defined in `step_up_auth => namespace => params`
           },
           step_up_auth: {
             admin_mode: {
               id_token: {
                 required: {
                   acr: 'gold'
                 }
               }
             },
             namespace: {
               id_token: {
                 required: {
                   acr: 'silver'
                 },
                 included: {
                   amr: ['mfa', 'fpt']
                 },
               },
               params: {
                 claims: {
                   id_token: {
                     acr: {
                       essential: true,
                       values: ['silver']
                     }
                   }
                 }
               }
             },
           }
         }

Implementation Flow

Click to expand the flow chart 
flowchart LR
    1[1. User requests access to
    protected group resource]
    2{2. GitLab checks if group
    requires step-up auth}
    3{3. Check if user session
    has required ACR for group}
    4[4. Allow access to
    group resource]
    5[5. Redirect to OIDC provider
    with required ACR for group]
    6[6. Wait for OIDC provider
    authentication and callback]
    7[7. Store ACR in session
    and redirect to original resource]

    1 --> 2
    2 -->|No step-up required| 4
    2 -->|Step-up required| 3
    3 -->|Valid ACR exists| 4
    3 -->|ACR missing/insufficient| 5
    5 --> 6
    6 --> 7
    7 --> 4

Related Issues and Merge Requests

Acceptance Criteria

Implementation Plan

Benefits of MR Split Approach

  1. Incremental Delivery: Each phase can be merged independently with feature flag protection
  2. Focused Reviews: Reviewers can concentrate on specific aspects (UI, backend, enforcement)
  3. Reduced Risk: Problems are isolated to specific layers with clear rollback strategies
  4. Clear Dependencies: Linear progression without circular dependencies
  5. Early Value: Configuration UI available immediately, backend ready for testing

This implementation follows a 5-phase MR split approach to ensure incremental delivery and focused reviews:

✅ Phase 1: Group Settings and Model => Step-up auth: Group protection (Model and UI se... (!199423 - merged)

  • Database & Models: Added step_up_auth_required_oauth_provider field to namespace_settings
  • Group Settings UI: Built interface for group owners to enable/disable step-up authentication and select OIDC providers
  • Model Validations: Added validation for provider selection and helper methods
  • Feature Flag: Configured omniauth_step_up_auth_for_namespace feature flag
  • Audit Events: Set up audit event tracking for step-up auth configuration changes
  • Documentation: Updated OIDC documentation with namespace scope configuration examples
  • Basic Testing: Feature tests for group settings UI and helper tests for provider selection

✅ Phase 2: OIDC Backend Extensions => Step-up auth: Group protection (OIDC backend su... (!204102 - merged)

  • OIDC Provider Integration: Extended existing OIDC step-up flow to handle namespace-scoped authentication
  • Dual Scope Support: Enhanced authentication flow to support both admin_mode and namespace scopes simultaneously
  • Session Management: Implemented provider-specific and scope-specific session tracking
  • OAuth Callback Handling: Updated callback controller to process namespace scope tokens
  • Middleware Enhancement: Extended request phase middleware to handle namespace scope requests
  • Comprehensive Testing: Unit tests for OIDC classes, controller tests for OAuth callbacks, and middleware tests

✅ Phase 3: UI Components & Auth Helper => Step-up auth: Group protection (frontend flow a... (!207665 - merged)

  • Auth Helper: Create helper methods for generating step-up authentication URLs
  • Step-up Auth Controller: Implement dedicated controller for group step-up authentication flow
  • UI Templates: Create user-facing templates for step-up authentication process
  • Route Configuration: Add routes for group step-up authentication endpoints
  • Internationalization: Add necessary translations for step-up auth UI
  • Helper Testing: Unit tests for auth helper methods
  • Request Testing: Request specs for step-up auth controller

🛠️ Phase 4: Controller Enforcement & Full Tests => Step-up auth: Group protection (final integrati... (!199800)

  • Access Control: Add before_action callbacks to enforce step-up authentication requirements in group controllers
  • Enforcement Logic: Implement group-level ACR requirement checking and redirect logic to step-up auth flow
  • Admin Bypass: Ensure admin bypass functionality works correctly for users in admin mode
  • Integration Testing: End-to-end testing of the complete authentication flow
  • Performance Validation: Ensure no regressions in group access performance
  • Feature Testing: Comprehensive feature tests covering all step-up authentication scenarios
  • Helper Testing: Unit tests for auth helper methods
  • Request Testing: Request specs for step-up auth controller
  • Route Configuration: Add routes for group step-up authentication endpoints

🔄 Phase 5: Future Enhancements (OPTIONAL)

Open Questions

  • Should there be instance-level policies that can override group-level step-up settings?
  • How should step-up authentication interact with existing group access tokens and deploy keys?
  • What should be the inheritance behavior when parent and child groups have different step-up requirements?
Edited by Gerardo Navarro