Step-up auth: Add automated verification and developer guidance for step-up authentication enforcement coverage

Proposal

Implement automated verification and proactive developer guidance to ensure complete step-up authentication enforcement coverage across all controllers that access group/namespace resources. Currently, there is no mechanism to prevent developers from accidentally omitting step-up authentication enforcement when working with group-related controllers, creating potential security gaps.

🛠️ with ❤️ at Siemens

Background

Step-up authentication provides an additional layer of security for group/namespace resources by requiring users to complete additional authentication before accessing protected resources. The enforcement logic is implemented as a controller concern in /app/controllers/concerns/enforces_step_up_authentication_for_namespace.rb.

The Problem

Incomplete Enforcement Coverage: Not all controllers that access group resources inherit from Groups::ApplicationController, making it easy to miss enforcement requirements. Examples include:

ProjectsController (inherits from Projects::ApplicationController)
Various API and specialized controllers that access group resources?

No Proactive Prevention Mechanism: There is currently no system to:

Automatically verify that controllers accessing group resources include step-up auth enforcement
Actively remind developers during development that enforcement may be required
Prevent code from being merged without proper enforcement coverage
Ensure consistent application of the security requirement across the codebase

Reactive Rather Than Proactive: Developers must remember to include the concern manually, which is error-prone and relies on:

Individual awareness of step-up authentication requirements
Manual code review catching missing enforcement
Post-merge discovery of security gaps

Proposed Solution

Implement a two-pronged approach to ensure complete enforcement coverage through proactive prevention:

1. Automated Verification with RuboCop

Create a custom RuboCop cop that actively verifies step-up authentication enforcement coverage:

Rule name: Gitlab/EnforceStepUpAuthForGroupControllers
Proactive detection during development and CI:
- Controllers that access @group instance variable but don't include the concern
- Controllers that call Group.find*, Group.where, or similar methods
- Controllers with routes under /groups/:id or /groups/:group_id
- Missing include EnforcesStepUpAuthenticationForNamespace when needed
Active feedback: Provide clear messages and autocorrect suggestions during development
Flexibility: Allow intentional exceptions via inline comments when enforcement is not needed
CI integration: Block merges when enforcement is missing (unless explicitly exempted)

2. Developer Guidance and Documentation

Create comprehensive developer guidance that actively supports enforcement coverage:

What: Overview of step-up authentication and enforcement requirements
When: Clear criteria for identifying if a controller needs enforcement
How: Step-by-step integration guide with code examples
Why: Security rationale and compliance requirements
Testing: Recommendations for verifying proper enforcement

Documentation placement for maximum utility:

doc/development/auth/step_up_authentication.md - comprehensive developer guide
Enhanced comments in the concern itself with usage examples
References in controller development guidelines
Integration with security documentation

Implementation Details

Create custom RuboCop cop to detect missing step-up auth enforcement in group controllers
Implement detection logic for controllers accessing group resources
Add comprehensive RuboCop cop specs and documentation
Create developer documentation for step-up authentication enforcement
Update existing concern documentation with enhanced usage examples
Test RuboCop rule against existing controllers and refine detection logic
Validate complete enforcement coverage across all group-related controllers

Success Criteria and Expected Outcomes

Enforcement Coverage:

100% of controllers accessing group resources either include step-up auth enforcement or have explicit documented exemptions
Zero new security gaps: No code accessing group resources can be merged without proper enforcement (verified via RuboCop in CI)

Automated Verification:

RuboCop rule achieves ≥90% detection rate for controllers requiring enforcement
False positive rate <10% (addressable with inline comments)
Immediate feedback during development when enforcement is missing

Developer Experience:

Developers can correctly determine if their controller needs enforcement using the documentation
Clear guidance enables successful integration without assistance
Confidence that code meets security requirements

Security and Compliance:

Automated verification of enforcement coverage replaces reliance on manual code review
Clear audit trail of intentional exemptions
Consistent application of step-up authentication requirements across the codebase

Additional Considerations

GraphQL: GraphQL controllers may need special handling since they don't follow traditional controller patterns. Consider whether the RuboCop rule should detect GraphQL resolvers accessing group resources or if a separate resolver concern is needed.
API Controllers: REST API controllers under /api/v4/groups/ may need similar enforcement. The RuboCop rule should detect these and verify enforcement coverage.
Performance: Ensure RuboCop rule is efficient and doesn't significantly slow down the linting process. Consider caching strategies for complex detection logic.
Backwards Compatibility: The RuboCop rule should not require immediate fixes to all existing code. Allow a grace period or exemption mechanism for legacy controllers while ensuring new code has proper coverage.
Exemption Documentation: Establish clear guidelines for when exemptions are acceptable and require inline documentation explaining why enforcement is not needed.