GitLab.comにTOTPの2FA (2要素認証) でログインできなくなった場合の対応方法 (2023/07/06 更新)

2023/07/06　GitLab.com Enterprise Edition 16.2.0-pre の画面に差し替え、一部の文言を更新しました。

皆様こんにちは。SEの小池と申します。

今回は、GitLab.comにTOTPの2FA (2要素認証) でログインできなくなった場合の対応 を簡単にまとめました。

本記事ではGitLab.comで2FAをTOTPで設定し、且つ、クラウドベースではないAuthenticatorを使用している場合において、ログインできなくなったときの対処方法を記載します。

それ以外の方法で2FAを利用している場合の対処法は、記載しておりません。

本記事の対象の方
今回のブログのゴール
事前ご連絡事項
GitLab.comにおける2FA概要
公式ドキュメント
対応方法 : リカバリコードが記載されたファイルを探す
対応方法 : SSHで接続してリカバリコードを再発行する
対応方法 : 既存のパーソナルアクセストークンを使ってAPI経由でSSHキーを設定する
対応方法 :【Premium以上限定】サポートに2FAの無効化を依頼する
最後に

本記事の対象の方

GitLab.comで以下の両方を満たす方法で2FAを使っていて、ログインできなくなった方。

TOTP (時間ベースのワンタイムパスワード)
クラウドベースではないAuthenticator

GitLab.comの2FAについて情報収集なさっている方。

今回のブログのゴール

このブログのゴールはこちらです。

今回のゴール

GitLab.comに TOTP (時間ベースのワンタイムパスワード) 且つ クラウドベースではないAuthenticator の2FAでログインできなくなった場合の対処法を把握する。

事前ご連絡事項

本記事はSaaS版 (GitLab.com) の Enterprise Edition 15.11.0-pre における仕様をベースに記載しております。それ以外のエディションやバージョンではこの記事に記載の通りではない可能性がございます。
本記事で紹介している各種手順はGitLab.com (SaaS版) のみが対象であり、Self-Managed版 (オンプレミス版) は対象外です。
本記事はGitやCI/CDに関する知識ゼロのSEによるなんちゃって記事です。GitLabのディープな使用法についてはGitLabの公式オンラインドキュメント (こちら) をご参照ください。
本ブログに掲載されている情報は正確性・安全性を保証するものではありません。本ブログの情報を利用することによって発生した損失や損害については、一切の責任を負いかねます。

本記事に記載された対応を実施する前に
本記事では、2023/04/25以降に各種Authenticatorで発生する仕様変更については考慮しません。
Authenticatorによっては、デバイスを紛失した場合でもTOTPのコード生成をAuthenticator側の機能で復旧できる仕様に変更されている可能性が有ります。
本記事に記載されている対応方法以外に、ご利用中のAuthenticator側でTOTPのコード生成を復旧できないかご確認ください。

GitLab.comにおける2FA概要

現在進行形でログインできなくて困っていらっしゃる方は、この章をすっ飛ばして次の章からご参照ください。

GitLab.comでは以下の2FA (Two-factor authentication) をサポートしています。

TOTP (Time-based One-Time Password Algorithm)
WebAuthn デバイス

このうちTOTPについては、Google Authenticator, Microsoft Authenticator の他、Authy, DUO 等が使用可能です。

なお、TOTPの2FA利用時は、デバイスを紛失しても自分自身でリカバリするのが容易であるという理由から、クラウドベースのAuthenticatorの利用が推奨されています。

GitLab.comにおける2FAの有効化方法には、利用者自身がプロファイルから2FAを有効にする方法と、特定のグループに所属する全ユーザーに2FAを強制する方法があります。
特定のグループに所属する全ユーザーに2FAを強制する方法については、後日別の記事で記載予定です。

うれしいことに、2FAは全ティアで (無償利用しているGitLab.comユーザーも) 有効化が可能です。
GitLab.comはデフォルトでは2FAは無効ですが、2FAを使用することにより、よりセキュアなアクセスが実現できます。

参考 : Two-factor authentication | GitLab

公式ドキュメント

GitLabにおける 2FA (Two-factor authentication) に関する公式ドキュメントはこちらです。

最新版のGitLab.comでの2FAの仕様や、2FAの有効化/無効化手順、緊急時のリカバリ方法等が記載されています。

後述する手順は、一部を除き公式ドキュメントで紹介されている手法です。

対応方法 : リカバリコードが記載されたファイルを探す

WebAuthnデバイスを使用している場合を除き、GitLab.comでワンタイムパスワードの2FAを正常に有効にしたタイミングでリカバリコードが表示され、ファイルをダウンロードするように求められたはずです。

まずは、2FAを有効化した際に表示されたリカバリコードがどこかに残っていないか、ご確認ください。

2023/07/07現在、上の画面の [コードをダウンロード] をクリックした場合、ファイル gitlab-recovery-codes.txt がダウンロードされます。
この名前のファイルを探してみてください。

ファイル名を変更している可能性が有る場合は、サイズ や 更新日時 で探してみてください。
リカバリコードが10個記載されたファイルのサイズはおよそ 169バイト です。

リカバリコードが見つかったら、それをGitLab.comのログイン時に表示される2FAのコード入力画面で入力し、ログインを試行してください。

リカバリコードを使ってログインした後は、2FAを再設定する等の処置をお忘れなく。

対応方法 : SSHで接続してリカバリコードを再発行する

リカバリコードが見当たらなくても、SSHでGitLab.comに接続してリカバリコードを再発行することが可能です。

参考 : Two-factor authentication - Generate new recovery codes using SSH| GitLab

この方法は、対象のGitLab.comのアカウントでSSHキーを使用タイプ 認証と署名 か、認証で登録済であることが前提です。

SSHキーを設定していない、または、タイプ Signing で登録しているSSHキーしかない場合は、本章に記載している方法は実施できません。
(SSHキーの登録タイプが不明な方は、このままこの章の手順を実施してみてください。タイプ Signing で登録している場合はリカバリコードが生成されません。)

リカバリコードの再発行の影響
この方法でリカバリコードを再発行した場合、既存のリカバリコードは全て無効になります。

SSHキーのキーペアを作成したユーザー (秘密鍵を保有するユーザー) で、以下のコマンドを実行します。

$ ssh git@gitlab.com 2fa_recovery_codes

確認メッセージが表示されるので、yesで進めます。

$ ssh git@gitlab.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

リカバリコードが10個生成されますので、メモしておきます。

$ ssh git@gitlab.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:

recoverycode0001
recoverycode0002
recoverycode0003
recoverycode0004
recoverycode0005
recoverycode0006
recoverycode0007
recoverycode0008
recoverycode0009
recoverycode0010

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.

GitLab.comのログイン時に表示される2FAのコード入力画面で、先ほど再発行したリカバリコードを入力し、ログインを試行してください。

リカバリコードを使ってログインした後は、2FAを再設定する等の処置をお忘れなく。

対応方法 : 既存のパーソナルアクセストークンを使ってAPI経由でSSHキーを設定する

リカバリコードが見当たらず、SSHキーを設定していなかった場合でも、パーソナルアクセストークンがあればAPIでSSHキーを設定することができます。

この手順の場合、以下の2ステップの作業をすることで、ログインができるようになります。

既存のパーソナルアクセストークンを使ってAPIでSSHキーを設定する。
SSHでGitLab.comに接続してリカバリコードを再発行する。

この方法を実施する際には、既存のパーソナルアクセストークンにスコープ api が必要です。
(既存のパーソナルアクセストークンのスコープが不明の場合は、このままこの章の手順を実施してみてください。スコープに不足があればSSHキーは登録できません。)

条件を満たすパーソナルアクセストークンをお持ちの場合は、まずローカルでSSHキーペアを作成します。
以下はアルゴリズム ED25519 でキーペアを作成するコマンド例です。

$ ssh-keygen -t ed25519 -C "＜GitLab.comのアカウントのE-mailアドレス＞"

キーペアを作成したら、公開鍵をAPIでGitLab.comに登録します。
以下にSSHキーを my_sshkey という名前でGitLab.comに登録するコマンド例を示します。
この例では、パーソナルアクセストークンを変数 PERSONAL_TOKEN に、公開鍵を変数 SSH_PUB_KEY にエクスポートした状況で実行しています。

$ curl --request POST --header "PRIVATE-TOKEN: $PERSONAL_TOKEN" \
          --data "title=my-sshkey" \
          --data "key=$SSH_PUB_KEY" \
          "https://gitlab.com/api/v4/user/keys"

SSHキーの登録に成功した場合、以下のような出力になります。

$ curl --request POST --header "PRIVATE-TOKEN: $PERSONAL_TOKEN" \
          --data "title=my-sshkey" \
          --data "key=$SSH_PUB_KEY" \
          "https://gitlab.com/api/v4/user/keys"
{"id":12345678,"title":"my-sshkey","created_at":"2023-04-25T07:29:09.735Z","expires_at":null,"key":"＜公開鍵＞ ＜GitLab.com上のユーザーの表示名＞ (gitlab.com)","usage_type":"auth_and_signing"}

これで、SSHキーの登録が完了しました。
(ここで登録したSSHキーは使用タイプ "認証と署名" です。)

あとは前述の対応方法 : SSHで接続してリカバリコードを再発行するを実施することで、リカバリコードを再発行できます。