Text of docs.gitlab.com › user › profile › account › two_factor_authentication as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Two-factor authentication | GitLab Docs

/ Two-factor authentication Tier : Free, Premium, Ultimate Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated Two-factor authentication (2FA) provides an additional level of security to your GitLab account. For others to access your account, they would need your username and password and access to your second factor of authentication. GitLab supports the following 2FA methods: Passkeys. During sign in, GitLab prompts you to authenticate with your passkey.

After you turn on 2FA, passkeys become an additional and default 2FA option. For more information, see passkeys . One-time password ( OTP ) authenticators. During sign in, GitLab prompts you for a code generated by your OTP authenticator. WebAuthn devices. During sign in, GitLab prompts you to prove ownership of your WebAuthn device. This is generally a physical device like a YubiKey, your phone, or your laptop. Email OTP.

During sign in, GitLab prompts you for a code sent to your email address. If you set up a device, also set up an OTP so you can still access your account if you lose the device. Enable two-factor authentication To enable 2FA, verify your email address and register an OTP authenticator, a WebAuthn device, or email OTP. Register an OTP authenticator If you lose access to your OTP authenticator, you might be locked out of your account.

To minimize this risk: Enable cloud backup in your authenticator app. Save your backup passwords, secret keys, or recovery credentials in a secure location. Review the documentation for your specific OTP authenticator. If you are already locked out, see recovery options and 2FA reset . To register an OTP authenticator: Configure GitLab. In the upper-right corner, select your avatar. Select Edit profile . In the left sidebar, select Access > Password and authentication .

In the One-time password authenticator section, select Register authenticator . A QR code and your OTP details are displayed. Configure your device. Install a compatible OTP application on your device. For example: Cloud-based (recommended because you can restore access if you lose the hardware device): Authy . Cisco Duo . Other (proprietary): Google Authenticator . Microsoft Authenticator . Other (Free Software) Aegis Authenticator .

FreeOTP . In the application, add a new entry in one of two ways: Scan the code displayed by GitLab with your device’s camera to add the entry automatically. Enter the details provided to add the entry manually. Complete the registration: Enter your current password. Enter the six-digit PIN generated from your authenticator. Select Register with two-factor app . If you entered the correct pin, GitLab displays a list of recovery codes .

Download them and keep them in a safe place. If your OTP authenticator supports cloud backups, consider configuring the feature now. For more information, see the documentation for your specific authenticator. Register a WebAuthn device Optional one-time password authentication for WebAuthn devices introduced in GitLab 15.10 with a feature flag named webauthn_without_totp . Generally available in GitLab 17.6. Feature flag webauthn_without_totp removed.

WebAuthn is supported by the following: Desktop browsers: Chrome Edge Firefox Opera Safari Mobile browsers: Chrome for Android Firefox for Android iOS Safari (since iOS 13.3) To register a WebAuthn-compatible device: If using a physical device, plug it in to your computer. In the upper-right corner, select your avatar. Select Edit profile . In the left sidebar, select Access > Password and authentication . In the WebAuthn devices section, select Register device .

Select Set up new device . Follow the directions in your browser window. Depending on your device, you might have to press a button or touch a sensor. Enter your GitLab account password and a device name. You might not need to enter this password if you have signed in through your identity provider. Select Register device . You should receive a message indicating that you successfully set up your device. When you set up 2FA with a WebAuthn-compatible device, that device is linked to a specific browser on a specific computer.

Depending on the browser and WebAuthn device, you might be able to configure settings to use the WebAuthn device on a different browser or computer. If this is the first time you have set up 2FA, you must download recovery codes so you can recover access to your account if you lose access. You can lose access to your account if you clear your browser data. Enable email OTP Introduced in GitLab 18.7 with a feature flag named email_based_mfa .

Disabled by default. Enabled on GitLab.com in GitLab 18.7, with progressive rollout to all users throughout 2026. New application setting email_otp_enabled introduced in GitLab 19.1. Disabled by default. Feature flag email_based_mfa removed in GitLab 19.2. Email OTP is now controlled by the email_otp_enabled application setting. Email OTP allows you to verify your identity by sending a six-digit verification code to your email address.

Prerequisites: Email OTP must be enabled for your instance. To enable email OTP for your account: In the upper-right corner, select your avatar. Select Edit profile . In the left sidebar, select Access > Password and authentication . Select Enable email OTP . Enter your current password and select Update email OTP settings . Add a Cisco Duo authenticator Offering : GitLab Self-Managed You can use Cisco Duo as an OTP provider in GitLab.

DUO® is a registered trademark of Cisco Systems, Inc., and/or its affiliates in the United States and certain other countries. Prerequisites: Your account must exist in both Cisco Duo and GitLab, with the same username in both applications. You must have configured Cisco Duo and have an integration key, secret key, and API hostname. For more information, see the Cisco Duo API documentation . Open the GitLab configuration file.

For Linux package installations: shell sudo editor /etc/gitlab/gitlab.rb For self-compiled installations: shell cd /home/git/gitlab sudo -u git -H editor config/gitlab.yml Add the provider configuration. For Linux package installations: ruby gitlab_rails [ 'duo_auth_enabled' ] = true gitlab_rails [ 'duo_auth_integration_key' ] = '<duo_integration_key_value>' gitlab_rails [ 'duo_auth_secret_key' ] = '<duo_secret_key_value>' gitlab_rails [ 'duo_auth_hostname' ] = '<duo_api_hostname>' For self-compiled installations: yaml duo_auth : enabled : true hostname : <duo_api_hostname> integration_key : <duo_integration_key_value> secret_key : <duo_secret_key_value> Save the configuration file.

For Linux package installations, reconfigure GitLab . For self-compiled installations, restart GitLab . Add a FortiAuthenticator authenticator Offering : GitLab Self-Managed On GitLab Self-Managed, by default this feature is not available. To make it available per user, an administrator can enable the feature flag named forti_authenticator . On GitLab.com and GitLab Dedicated, this feature is not available. You can use FortiAuthenticator as an OTP provider in GitLab.

Users must: Exist in both FortiAuthenticator and GitLab with the same username. Have FortiToken configured in FortiAuthenticator. You need a username and access token for FortiAuthenticator. The access_token shown below is the FortiAuthenticator access key. To get the token, see the REST API Solution Guide at Fortinet Document Library . Tested with FortiAuthenticator version 6.2.0. Configure FortiAuthenticator in GitLab.

On your GitLab server: Open the configuration file. For Linux package installations: shell sudo editor /etc/gitlab/gitlab.rb For self-compiled installations: shell cd /home/git/gitlab sudo -u git -H editor config/gitlab.yml Add the provider configuration. For Linux package installations: ruby gitlab_rails [ 'forti_authenticator_enabled' ] = true gitlab_rails [ 'forti_authenticator_host' ] = 'forti_authenticator.example.com' gitlab_rails [ 'forti_authenticator_port' ] = 443 gitlab_rails [ 'forti_authe

The rest of this page is on the live site.