Admin Mode - Justification Field for Audit Compliance

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Problem Statement

Customers in financial and highly regulated industries have strict audit requirements where administrators must provide and log justification when elevating privileges (switching to admin mode) in production environments.

Currently, GitLab's admin mode re-authentication process does not include a way to capture and log this justification, making it impossible to meet compliance requirements.

Proposed Solution

Add a required text input field on the re-authentication screen when enabling admin mode.

This justification text should be captured and stored with the admin mode activation event in the audit logs.

User Story

As an administrator of a self-managed GitLab instance in a regulated environment, I want to provide a justification when enabling admin mode so that all administrative actions are properly documented for audit compliance.

Expected Behavior

  1. When an administrator attempts to enable admin mode, the re-authentication screen includes a mandatory text field labeled "Justification"
  2. The administrator must enter a reason (limited to 200 characters to keep log messages small enough) before proceeding
  3. Upon successful authentication, the justification text is stored alongside the admin mode activation event in the audit logs (the important piece is the justification text content)
  4. The justification is then also retrievable during audit reviews via the already existing capabilities of GitLab (Event Streaming, Event API, Event Log)

Use Cases

  1. Security audit requires reviewing all instances of elevated privileges and the business justification for each
  2. Compliance team needs to verify that admin access was used appropriately and with valid reasons
  3. System administrators (or Production Support Staff) need to document emergency maintenance that required admin mode
  4. Security incident review needs to trace admin actions with their stated purpose
  5. Support personnel can document support ticket numbers when accessing admin mode for troubleshooting

Benefits

  • Enables compliance with financial / highly regulated industry customers and their requirements
  • Improves security governance by enforcing documentation of privileged access
  • Creates accountability for administrative actions
  • Simplifies audit processes by having justifications directly tied to admin mode events
  • Reduces risk of audit findings or compliance violations
  • Provides benefits also to GitLab's own support team ( @tmarsh1 explained, this would be helpful also to GitLAb support staff for their daily work), allowing them to reference support ticket numbers when they need to use admin mode, improving internal audibility at GitLab

Possible Implementation

  • Add a text field limited to "200" characters to the existing admin mode re-authentication page
  • Store the provided justification text in the existing audit event log alongside the admin mode activation event
  • Make the field required to ensure justification is always provided
  • Ensure the justification is included in any API responses, audit streaming or exports that include admin mode activation events, like we do already right now.

Additional Context

This feature is particularly important for organizations in regulated industries (financial services, healthcare, government) where privileged access documentation is a common compliance requirement. Many GitLab customers operating in these regulated environments need this capability to satisfy their audit obligations.

Additionally, this feature would benefit GitLab's own support team. When GitLab support staff need to access admin mode on customer instances to troubleshoot issues, they could use this field to document the related support ticket number. This would improve GitLab's internal processes for tracking and auditing support activities, creating a clear connection between admin actions and their corresponding support cases.

Current admin mode documentation: https://docs.gitlab.com/administration/settings/sign_in_restrictions/#admin-mode

Link to request from customer, which raised this with us initially: https://gitlab.my.salesforce.com/00161000015MAsE - 36,000 Seats - GitLab Ultimate -Self Managed

This customer confirmed that similar functionality exists in many other enterprise systems with elevated privilege mechanisms.

Impact

This is a critical compliance requirement for organizations in regulated industries.

Customer currently cannot fulfil their audit obligations without this feature, creating potential regulatory exposure. Implementation is needed to address this compliance gap.

Edited by 🤖 GitLab Bot 🤖