From 8895d85fa5345e7d391910615f6d4cd11947a202 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= <anarcat@debian.org>
Date: Tue, 16 Jun 2020 14:20:50 -0400
Subject: [PATCH] document gitlab's 2FA setup

---
 tsa/howto/gitlab.md | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/tsa/howto/gitlab.md b/tsa/howto/gitlab.md
index 21b4b115..7852ad80 100644
--- a/tsa/howto/gitlab.md
+++ b/tsa/howto/gitlab.md
@@ -62,7 +62,35 @@ lists: <tor-dev@lists.torproject.org> would be best.
 
 # How-to
 
-<!-- more in-depth procedure that may require interpretation -->
+## Setting up two-factor authentication (2FA)
+
+We strongly recommend you enable two-factor authentication on
+GitLab. This is [well documented in the GitLab manual](https://gitlab.torproject.org/help/user/profile/account/two_factor_authentication.md#two-factor-authentication), but basically:
+
+ 1. first, pick a 2FA "app" (and optionally a hardware token) if you
+    don't have one already
+
+ 2. head to your [account settings](https://gitlab.torproject.org/profile/account)
+
+ 3. register your 2FA app and save the recovery codes somewhere. if
+    you need to enter a URL by hand, you can scan the qrcode with your
+    phone or create one by following this format:
+
+        otpauth://totp/$ACCOUNT?secret=$KEY&issuer=gitlab.torproject.org
+
+    where...
+
+      * `$ACCOUNT` is the `Account` field in the 2FA form
+      * `$KEY` is the `Key` field in the 2FA form, without spaces
+
+ 4. register the 2FA hardware token if available
+
+GitLab requires a 2FA "app" even if you intend to use a hardware
+token. The 2FA "app" must implement the TOTP protocol, for example the
+[Google Authenticator](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2) or a free alternative (for example [free OTP
+plus](https://github.com/helloworld1/FreeOTPPlus/), see also this [list from the Nextcloud project](https://github.com/nextcloud/twofactor_totp#readme)). The
+hardware token must implement the U2F protocol, which is supported by
+security tokens like the [YubiKey](https://en.wikipedia.org/wiki/YubiKey), [Nitrokey](https://www.nitrokey.com/), or similar.
 
 ## Pager playbook
 
-- 
GitLab