[UX] Top level group enforcement for fine-grained PATS

Release notes

Top level group owners on SaaS and Self-Managed can enforce the use of fine-grained personal access tokens.

Problem to solve

GitLab and customers need the ability to enforce the adoption of fine-grained Personal Access Tokens (PATs) to reduce security risks from token leaks or abuse.

  • Enable top-level groups on GitLab.com to enforce fine-grained PAT usage
  • Ensure all members of the top-level group use fine-grained PATs when accessing group resources

Proposal

Implement a top-level group setting that enforces access to group resources using only fine-grained PATs created after a specified date.

  • Group owners enables the setting at the top-level group or Self Managed>Settings>General
  • GitLab validates the token type used to access top-level groups resources (broad-access vs fine-grained)
  • For SaaS: Tokens created before the enforcement date continue to work (backward compatibility) in the user's personal account token list. User can still create broad-access tokens
  • For Self Managed: Tokens created before the enforcement date continue to work (backward compatibility) in the user's personal account token list. User can no longer create broad-access tokens.
  • Tokens must be fine-grained to access resources within the enforced group hierarchy

This solution was selected after evaluating three options (Enterprise Users, Top-level Setting, Token Policy): see discussion

Intended users
  • Group Owners (Primary)
  • Group members: required to adopt fine-grained PATs
User
User Experience for SaaS
User Experience for Self Managed
Admin / Top level group owners
  • Navigate to Top-level group > General setting
  • Enable "Require fine-grained personal access tokens after a specific date"
  • Set enforcement date: tokens used to access group resources after this date must be fine-grained
  • All subgroups and projects inherit this enforcement

SAAS_Settings _ General.png
  • Navigate to Admin>Settings>General
  • Enable "Require fine-grained personal access tokens"
  • Set enforcement date: tokens created after this date must be fine-grained)
  • All subgroups and projects inherit this enforcement

ADMIN _ Settings _ General.png

For group/project members

  • Existing broad-scoped tokens created before enforcement date continue being active in the user's list

  • API calls in enforced group with broad access tokens receive clear error messages with remediation steps:

    Access denied: "my/cool/project" requires a fine grained personal access token with the following permissions: [read_api, write_repository].

  • Existing broad-scoped tokens created before enforcement date continue working

  • [Diff] New token creation after enforcement date requires fine-grained PAT selection

  • API calls with non-compliant tokens receive clear error messages with remediation steps

    Access denied: "my/cool/project" requires a fine grained personal access token with the following permissions: [read_api, write_repository].

Feature usage

  • # of top-level groups with enforcement enabled
  • # of API calls blocked due to broad access PAT usage

Does this feature require an audit event?

Yes. The following events should be audited:

  • Group owner enables/disables fine-grained PAT enforcement
  • Group owner modifies enforcement date

Related Issues

Edited by Ilonah Pelaez