GitLab Hardening: Least Privilege + MFA Guide

This guide walks you through hardening GitLab access by enforcing least privilege accounts and multi-factor authentication (MFA). You’ll learn how to restrict user permissions to the minimum needed, require MFA for all users, and configure session and token policies. This reduces the blast radius of compromised credentials and insider threats. You’ll need GitLab admin access (Owner role on the instance or group) and the ability to manage user accounts.

What You’ll Need

• GitLab instance or group with Owner or Admin role
• Access to GitLab Admin Area (for instance-level settings)
• List of current users and their roles
• An MFA method (TOTP app, WebAuthn, or YubiKey) for testing
• SSH keys or personal access tokens for service accounts (if applicable)

Step-by-Step

1. Audit current users and roles. Go to Admin Area → Users (or Group → Members). Export the list and note each user’s role. Identify any users with Owner, Maintainer, or Admin who don’t need it.
2. Define least privilege roles. Map job functions to GitLab roles: Guest for viewers, Reporter for issue-only, Developer for push/pull, Maintainer for merge approval and project settings, Owner only for project/group admins. Use Custom Roles (GitLab 16+) to fine-tune permissions if needed.
3. Remove unnecessary admin privileges. In Admin Area, review each admin user. Demote any that aren’t actively managing the instance. Never share admin accounts.
4. Enforce MFA at the instance level. Go to Admin Area → Settings → General → Sign-up restrictions (or Security and compliance). Enable Require two-factor authentication and set a grace period (e.g., 24 hours). Choose to Disable group two-factor authentication only if you have a reason; otherwise keep it enabled.
5. Enforce MFA at the group level. For each top-level group, go to Settings → General → Permissions and group features. Enable Require two-factor authentication and set a grace period. This overrides instance settings for that group.
6. Set up MFA enforcement for existing users. In Admin Area, you can manually force MFA by editing each user and selecting Require two-factor authentication. For groups, the group setting will prompt users on next login.
7. Limit personal access tokens. Go to Admin Area → Settings → Repository (or Security and compliance). Set a maximum token lifetime (e.g., 30 days) and restrict scopes. Encourage users to use short-lived, scoped tokens.
8. Configure session duration. In Admin Area → Settings → General → Account and limit, set Session duration to a reasonable value (e.g., 8 hours). Enable Session duration for GitLab.com if on SaaS.
9. Use service accounts for automation. For CI/CD and scripts, create dedicated service accounts with only Developer or Reporter access to specific projects. Never use personal accounts for automation.
10. Regularly review and revoke. Set a recurring schedule (monthly) to audit user roles, token usage, and MFA status. Remove inactive users and revoke unused tokens.

Common Mistakes

• Enabling MFA but giving a long grace period (e.g., 30 days) – users may forget or delay.
• Keeping admin rights on accounts that don’t need them – always demote to least privilege.
• Not restricting token scopes – a token with api scope can do almost anything.
• Forgetting to enforce MFA on groups that have their own settings – instance settings may not apply if group overrides.
• Using personal accounts for CI/CD – leads to token sprawl and higher risk.

Tips

• Use GitLab’s built-in Security Dashboard to monitor user activity and token usage.
• Enable Sign-out on password change to invalidate sessions after credential changes.
• Consider using SCIM (if on GitLab.com or Ultimate) to automate user provisioning and deprovisioning.
• For SSH keys, require users to set an expiration date (GitLab 15.4+).
• Use Audit Events to track changes to permissions and MFA settings.

Troubleshooting

• Users cannot log in after MFA enforcement. They will see a prompt to set up MFA. If they have lost access, an admin can temporarily disable MFA for that user (edit user → Disable two-factor authentication).
• Group MFA setting doesn’t apply. Check if the group has inheritance from a parent group. Ensure the setting is enabled at the top-level group.
• Tokens are still valid after setting max lifetime. The setting only affects new tokens; existing tokens remain until expiry. You may need to manually revoke long-lived tokens.
• Service account cannot push. Verify the role is at least Developer and that the project’s protected branches allow that role to push.
• MFA setup fails with TOTP app. Ensure the user’s device clock is synchronized. Try using a different TOTP app or WebAuthn.

Frequently Asked Questions

What is the difference between instance-level and group-level MFA enforcement?

Instance-level applies to all users on the GitLab instance. Group-level applies only to members of that group and overrides instance settings for those members. Use both for defense in depth.

Can I enforce MFA for only some users?

Yes, you can manually require MFA per user, or use group-level settings for specific groups. There’s no built-in way to target arbitrary user subsets, but you can create a group for those users.

How do I handle users who lose their MFA device?

An admin can disable MFA for that user temporarily. The user should then set up a new MFA method immediately. Consider having backup codes stored securely.

What token scopes should I allow?

Only the minimum needed. For read-only access, use read_repository or read_api. For CI/CD, use api only if necessary, otherwise write_repository or read_registry.

Does enforcing MFA affect SSH keys?

No, MFA is for web and API access. SSH keys are separate. However, you can require SSH keys to have an expiration date and add a passphrase.

Can I use a hardware key like YubiKey for MFA?

Yes, GitLab supports WebAuthn hardware keys. Users can register them in their profile settings.

Related

• Cloud Security Benefits Depend on Your Controls
• Access Geo Restricted Websites: 5 Ways That Work
• Showtime on Paramount Plus: How Streaming Works