## 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](https://docs.gitlab.com/administration/auth/oidc/#enable-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. <details><summary>Click to expand the example for step-up auth config for groups</summary> ```yaml 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'] } } } } }, } } ``` </details> ### Implementation Flow <details><summary>Click to expand the flow chart</summary> ```mermaid 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 ``` </details> ## Related Issues and Merge Requests * **Original Issue**: [OIDC step-up auth: Allow higher trust levels for admin area and groups / projects](https://gitlab.com/gitlab-org/gitlab/-/issues/474650) => has been promoted to EPIC &16818 * **Implementation step-up auth for admin mode**: [Implement step-up authentication for admin area](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/171643) * **Documentation for step-up authentication for admin mode**: [OIDC Authentication Documentation](https://docs.gitlab.com/administration/auth/oidc/#step-up-authentication-for-admin-mode) * **Group Model Changes**: [Add model attribute for required provider for group](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176295) ## Acceptance Criteria * [x] Group owners can enable/disable step-up authentication for their groups => !199423+ * [x] Group owners can select which OIDC provider handles step-up authentication => !199423+ * [x] Group owners can configure required ACR levels for group access => !199423+ * [x] OIDC backend supports namespace scope for step-up authentication => !204102+ * [x] Session management handles group-specific ACR requirements => !204102+ * [x] Configuration follows the same pattern as admin mode step-up authentication => !199423+ * [x] Comprehensive documentation covers configuration scenarios => !199423+ * [ ] Users cannot access protected group resources without proper step-up authentication * [ ] Subgroups inherit step-up requirements from parent groups => !199628+ * [ ] Admin users can bypass group step-up requirements when in admin mode * [ ] Full end-to-end testing and feature completion ## 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 => !199423+ - [x] **Database & Models**: Added `step_up_auth_required_oauth_provider` field to `namespace_settings` - [x] **Group Settings UI**: Built interface for group owners to enable/disable step-up authentication and select OIDC providers - [x] **Model Validations**: Added validation for provider selection and helper methods - [x] **Feature Flag**: Configured `omniauth_step_up_auth_for_namespace` feature flag - [x] **Audit Events**: Set up audit event tracking for step-up auth configuration changes - [x] **Documentation**: Updated OIDC documentation with namespace scope configuration examples - [x] **Basic Testing**: Feature tests for group settings UI and helper tests for provider selection ### ✅ Phase 2: OIDC Backend Extensions => !204102+ - [x] **OIDC Provider Integration**: Extended existing OIDC step-up flow to handle namespace-scoped authentication - [x] **Dual Scope Support**: Enhanced authentication flow to support both `admin_mode` and `namespace` scopes simultaneously - [x] **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 ### :white_check_mark: Phase 3: UI Components & Auth Helper => !207665+ - [x] **Auth Helper**: Create helper methods for generating step-up authentication URLs - [x] **Step-up Auth Controller**: Implement dedicated controller for group step-up authentication flow - [x] **UI Templates**: Create user-facing templates for step-up authentication process - [~] **Route Configuration**: Add routes for group step-up authentication endpoints - [x] **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 ### :tools: Phase 4: Controller Enforcement & Full Tests => !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) - [x] **Subgroup Inheritance**: Implement step-up requirement inheritance from parent groups => !199628+ - [ ] **Enhanced UI Flow**: Improved user experience during step-up auth flow with better error handling - [x] **API Integration**: Create dedicated API endpoints for managing group step-up authentication settings => !203429+ / !204475+ - [ ] **Advanced Configuration**: Instance-level policies that can override group-level step-up settings ## 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?