Step-up auth: Add configurable session expiration option

Gerardo Navarrorequested to merge
gitlab-community/gitlab-org/gitlab:587814-gerardo-navarro-step-up-auth-configurable-session-expiration into master

What does this MR do and why?

Adds a session_expiration_enabled configuration option for step-up authentication in gitlab.yml. This allows administrators to control whether step-up authentication sessions expire based on the IdP token's exp claim.

Problem: Step-up authentication sessions currently expire based on the IdP token's exp claim, forcing users to re-authenticate frequently during long working sessions. Depending on the IdP configuration, this can significantly impact productivity and workflow continuity. Additionally, the team administering the GitLab self-hosted instance often has no control over the IdP token expiration settings, which are managed by a separate identity team or dictated by the IdP provider defaults.

Solution: A new session_expiration_enabled option (default: true) in the provider's step_up_auth configuration block. When set to false, the IdP token expiration (exp claim) is ignored, and step-up authentication remains valid for the duration of the GitLab session.

🗒️ Note:The GitLab session expiration itself is unaffected — when the GitLab session expires or the user logs out, step-up authentication is cleared and must be completed again on the next session.

Changes:

  • Added session_expiration_enabled? private method to StepUpAuthenticationFlow that reads the configuration from the provider config (defaults to true for security)
  • Modified expired? to skip expiration validation when session_expiration_enabled is false
  • Added comprehensive tests covering all configuration scenarios (enabled, disabled, not configured)
  • Added documentation for both Omnibus and source installations

Configuration example:

step_up_auth: {
  session_expiration_enabled: false,  # Disable for session-lifetime validity
  admin_mode: { ... },
  namespace: { ... }
}

🛠️ with ❤️ at Siemens

References

Screenshots or screen recordings

No UI changes. This is a backend configuration change.

Before After
Step-up auth sessions always expire based on the IdP token exp claim. Users are forced to re-authenticate repeatedly, with no way to opt out. Administrators can set session_expiration_enabled: false to ignore the IdP token expiration. Step-up auth remains valid for the GitLab session lifetime. Default behavior (expiration enabled) is unchanged.

How to set up and validate locally

Prerequisites: Keycloak and GDK setup

Follow Part 1 (Keycloak setup) and Part 2 (GDK configuration and gitlab.yml) from Step-up auth: Expiration validation - Basic cor... (!200566 - merged). Make sure to set a short token lifespan (e.g. 15 seconds) in Keycloak for easier testing, see the screen recording for more details.

Validate default behavior (expiration enabled)

  1. Ensure session_expiration_enabled is not set or set to true in your provider's step_up_auth block in config/gitlab.yml
  2. Sign in and navigate to the admin area — you should be redirected to Keycloak for step-up authentication
  3. Complete the step-up authentication challenge
  4. Wait 15+ seconds for the token to expire
  5. Refresh the page or navigate within the admin area
  6. Expected: You are logged out of the admin area with an expiration notice and must re-authenticate (same behavior as before this MR)

Validate expiration disabled

  1. Add session_expiration_enabled: false to the provider's step_up_auth block in config/gitlab.yml: 
    step_up_auth: {
  session_expiration_enabled: false,
  admin_mode: {
    # ... existing config ...
  }
}
  2. Restart GDK (gdk restart)
  3. Sign in and navigate to the admin area — complete the step-up authentication challenge
  4. Wait 15+ seconds (beyond the IdP token expiration)
  5. Refresh the page or navigate within the admin area
  6. Expected: You remain in the admin area without being prompted to re-authenticate
  7. Log out and log back in
  8. Expected: You are prompted for step-up authentication again (GitLab session was cleared on logout)

MR acceptance checklist

Please evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

MR Checklist (@gerardo-navarro)
Edited by Gerardo Navarro

Merge request reports