Commit d5e58013 authored by Boris Budini's avatar Boris Budini

Uploads

parent 6c1c9307
Pipeline #350 passed with stages
in 37 seconds
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
......@@ -7,5 +7,7 @@ Lorem Ipsum
.. toctree::
:maxdepth: 1
../shared/securitypractices
securitypractices
../shared/2fa
emailsetup
==================
General Guidelines
General Tips
==================
.. note::
......
......@@ -7,4 +7,6 @@ Lorem Ipsum
.. toctree::
:maxdepth: 1
../shared/general-guidelines
general-tips
code-of-conduct
../shared/2fa
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
==================
Two-Factor Authentication
==================
.. note::
**This page was uploaded from GitLab's Handbook**
Two-Factor Authentication
=========================
Two-factor Authentication (2FA) provides an additional level of security
to your GitLab account. Once enabled, in addition to supplying your
username and password to login, you'll be prompted for a code generated
by your one time password authenticator. For example, a password manager
on one of your devices.
By enabling 2FA, the only way someone other than you can log into your
account is to know your username and password *and* have access to your
one time password secret.
Overview
--------
**Note:** When you enable 2FA, don't forget to back up your recovery
codes.
In addition to one time authenticators (TOTP), GitLab supports U2F
(universal 2nd factor) devices as the second factor of authentication.
Once enabled, in addition to supplying your username and password to
login, you'll be prompted to activate your U2F device (usually by
pressing a button on it), and it will perform secure authentication on
your behalf.
The U2F workflow is only `supported
by <https://caniuse.com/#search=U2F>`__ Google Chrome, Opera and Firefox
at this point, so we *strongly* recommend that you set up both methods
of two-factor authentication, so you can still access your account from
other browsers.
Enabling 2FA
------------
There are two ways to enable two-factor authentication: via a one time
password authenticator or a U2F device.
Enable 2FA via one time password authenticator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**In GitLab:**
1. Log in to your GitLab account.
2. Go to your **Profile Settings**.
3. Go to **Account**.
4. Click **Enable Two-factor Authentication**.
.. figure:: ../images/security/2fa/2fa.png
:alt: Two-factor setup
Two-factor setup
**On your phone:**
1. Install a compatible application. We recommend `Google
Authenticator <https://support.google.com/accounts/answer/1066447?hl=en>`__
(proprietary) or `FreeOTP <https://freeotp.github.io/>`__ (open
source).
2. In the application, add a new entry in one of two ways:
- Scan the code with your phone's camera to add the entry
automatically.
- Enter the details provided to add the entry manually.
**In GitLab:**
1. Enter the six-digit pin number from the entry on your phone into the
**Pin code** field.
2. Click **Submit**.
If the pin you entered was correct, you'll see a message indicating that
Two-Factor Authentication has been enabled, and you'll be presented with
a list of recovery codes.
Enable 2FA via U2F device
~~~~~~~~~~~~~~~~~~~~~~~~~
**Notes:** - GitLab officially only supports
`Yubikey <https://www.yubico.com/products/yubikey-hardware/>`__ U2F
devices. - Support for U2F devices was added in GitLab 8.8.
**In GitLab:**
1. Log in to your GitLab account.
2. Go to your **Profile Settings**.
3. Go to **Account**.
4. Click **Enable Two-Factor Authentication**.
5. Plug in your U2F device.
6. Click on **Set up New U2F Device**.
7. A light will start blinking on your device. Activate it by pressing
its button.
You will see a message indicating that your device was successfully set
up. Click on **Register U2F Device** to complete the process.
.. figure:: ../images/security/2fa/2fa_u2f_register.png
:alt: Two-Factor U2F Setup
Two-Factor U2F Setup
Recovery Codes
--------------
**Note:** Recovery codes are not generated for U2F devices.
Should you ever lose access to your one time password authenticator, you
can use one of the ten provided backup codes to login to your account.
We suggest copying them, printing them, or downloading them using the
**Download codes** button for storage in a safe place.
CAUTION: **Caution:** Each code can be used only once to log in to your
account.
If you lose the recovery codes or just want to generate new ones, you
can do so `using SSH <#generate-new-recovery-codes-using-ssh>`__.
Logging in with 2FA Enabled
---------------------------
Logging in with 2FA enabled is only slightly different than a normal
login. Enter your username and password credentials as you normally
would, and you'll be presented with a second prompt, depending on which
type of 2FA you've enabled.
Log in via mobile application
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Enter the pin from your one time password authenticator's application or
a recovery code to log in.
.. figure:: ../images/security/2fa/2fa_auth.png
:alt: Two-Factor Authentication on sign in via OTP
Two-Factor Authentication on sign in via OTP
Log in via U2F device
~~~~~~~~~~~~~~~~~~~~~
1. Click **Login via U2F Device**.
2. A light will start blinking on your device. Activate it by pressing
its button.
You will see a message indicating that your device responded to the
authentication request. Click on **Authenticate via U2F Device** to
complete the process.
.. figure:: ../images/security/2fa/2fa_u2f_authenticate.png
:alt: Two-Factor Authentication on sign in via U2F device
Two-Factor Authentication on sign in via U2F device
Disabling 2FA
-------------
1. Log in to your GitLab account.
2. Go to your **Profile Settings**.
3. Go to **Account**.
4. Click **Disable**, under **Two-Factor Authentication**.
This will clear all your two-factor authentication registrations,
including mobile applications and U2F devices.
Personal access tokens
----------------------
When 2FA is enabled, you can no longer use your normal account password
to authenticate with Git over HTTPS on the command line or when using
`GitLab's API <../../../api/README.md>`__, you must use a `personal
access token <../personal_access_tokens.md>`__ instead.
Recovery options
----------------
To disable two-factor authentication on your account (for example, if
you have lost your code generation device) you can:
- `Use a saved recovery code <#use-a-saved-recovery-code>`__.
- `Generate new recovery codes using
SSH <#generate-new-recovery-codes-using-ssh>`__.
- `Ask a GitLab administrator to disable two-factor authentication on
your
account <#ask-a-gitlab-administrator-to-disable-two-factor-authentication-on-your-account>`__.
Use a saved recovery code
~~~~~~~~~~~~~~~~~~~~~~~~~
Enabling two-factor authentication for your account generated several
recovery codes. If you saved these codes, you can use one of them to
sign in.
To use a recovery code, enter your username/email and password on the
GitLab sign-in page. When prompted for a two-factor code, enter the
recovery code.
**Note:** Once you use a recovery code, you cannot re-use it. You
can still use the other recovery codes you saved.
Generate new recovery codes using SSH
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Users often forget to save their recovery codes when enabling two-factor
authentication. If an SSH key is added to your GitLab account, you can
generate a new set of recovery codes with SSH.
1. Run ``ssh git@gitlab.example.com 2fa_recovery_codes``.
2. You are prompted to confirm that you want to generate new codes.
Continuing this process invalidates previously saved codes.
::
bash
$ ssh git@gitlab.example.com 2fa_recovery_codes
Are you sure you want to generate new two-factor recovery codes?
Any existing recovery codes you saved will be invalidated. (yes/no)
yes
Your two-factor authentication recovery codes are:
119135e5a3ebce8e
11f6v2a498810dcd
3924c7ab2089c902
e79a3398bfe4f224
34bd7b74adbc8861
f061691d5107df1a
169bf32a18e63e7f
b510e7422e81c947
20dbed24c5e74663
df9d3b9403b9c9f0
During sign in, use one of the codes above when prompted for your
two-factor code. Then, visit your Profile Settings and add a new device
so you do not lose access to your account again.
3. Go to the GitLab sign-in page and enter your username/email and
password. When prompted for a two-factor code, enter one of the
recovery codes obtained from the command-line output.
**Note:** After signing in, visit your **Profile settings >
Account** immediately to set up two-factor authentication with a new
device.
Ask a GitLab administrator to disable two-factor authentication on your account
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you cannot use a saved recovery code or generate new recovery codes,
ask a GitLab global administrator to disable two-factor authentication
for your account. This will temporarily leave your account in a less
secure state. Sign in and re-enable two-factor authentication as soon as
possible.
Note to GitLab administrators
-----------------------------
- You need to take special care to that 2FA keeps working after
`restoring a GitLab backup <../../../raketasks/backup_restore.md>`__.
- To ensure 2FA authorizes correctly with TOTP server, you may want to
ensure your GitLab server's time is synchronized via a service like
NTP. Otherwise, you may have cases where authorization always fails
because of time differences.
- The GitLab U2F implementation does *not* work when the GitLab
instance is accessed from multiple hostnames, or FQDNs. Each U2F
registration is linked to the *current hostname* at the time of
registration, and cannot be used for other hostnames/FQDNs.
For example, if a user is trying to access a GitLab instance from
``first.host.xyz`` and ``second.host.xyz``:
- The user logs in via ``first.host.xyz`` and registers their U2F
key.
- The user logs out and attempts to log in via ``first.host.xyz`` -
U2F authentication succeeds.
- The user logs out and attempts to log in via ``second.host.xyz`` -
U2F authentication fails, because the U2F key has only been
registered on ``first.host.xyz``.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment