GitLabとSSHキー

Gitは分散バージョン管理システムであり、ローカルで作業することができます。 さらに、変更を他のサーバーと共有したり、「プッシュ」することもできます。 GitLabはSSHキーを使用して、Gitとサーバー間のセキュアな通信をサポートしています。

SSHプロトコルはこのセキュリティを提供し、GitLabリモートサーバーに対して毎回ユーザー名やパスワードを入力することなく認証することができます。

このページは、GitLabリポジトリへの接続をセキュアにするために使用できるセキュアSSHキーの設定に役立ちます。

要件

SSHをサポートするために、GitLabはOpenSSHクライアントのインストールを必要とします。これはGNU/LinuxとmacOSにはプリインストールされていますが、Windowsにはありません。

お使いのシステムに SSH バージョン 6.5 以降が含まれていることを確認してください。 このバージョンでは、現在安全でない MD5 署名スキームが除外されています。 次のコマンドは、お使いのシステムにインストールされている SSH のバージョンを返します： 

ssh -V

GitLabはMicrosoft Windowsへのインストールをサポートしていませんが、SSHキーを設定してWindowsをクライアントとして設定することができます。

SSHキーのオプション

GitLabはRSA、DSA、ECDSA、ED25519鍵の使用をサポートしています。

ヒント：公開されている文書によると、ED25519 の方がよりセキュリティが高いようです。 RSA 鍵を使用する場合、米国国立科学技術研究所（National Institute of Science and Technology）のPublication 800-57 Part 3(PDF)では、少なくとも 2048 ビットの鍵サイズを推奨しています。

したがって、この文書ではED25519とRSA鍵の使用を中心に説明します。

管理者は、許可するキーとその最小長を制限できます。

既存のSSHキーのレビュー

既存のSSHキーがあれば、それを使ってGitLabリポジトリとの接続をセキュアにできるかもしれません。デフォルトでは、LinuxやmacOSシステムのSSHキーはユーザーのホームディレクトリの.ssh/ サブディレクトリに保存されます。以下の表は、各SSHキーアルゴリズムのデフォルトファイル名です：

アルゴリズム 公開鍵 秘密鍵
ED25519（推奨） id_ed25519.pub id_ed25519
RSA（少なくとも2048ビットのキーサイズ） id_rsa.pub id_rsa
DSA（非推奨） id_dsa.pub id_dsa
イーシーディーエスエー id_ecdsa.pub id_ecdsa

推奨事項については、SSHキーのオプションを参照してください。

新しいSSHキー・ペアの生成

作りたいなら：

  • ED25519キー、ED25519SSHキーと読みます。
  • RSAキー、RSASSHキーをお読みください。

ED25519 SSHキー

Practical Cryptography With Goという本によると、ED25519鍵は RSA 鍵よりもセキュリティが高く、性能も高いようです。

OpenSSH 6.5 では 2014 年に ED25519 SSH キーが導入されたので、現在のどのオペレーティングシステムでも利用できるはずです。

ED25519 キーは、以下のコマンドで作成および設定できます： 

ssh-keygen -t ed25519 -C "<comment>"

-C フラグにメールアドレスなどのコメントを書くと、 SSH キーにラベルを付けることができます。

というような返答が表示されます： 

Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/user/.ssh/id_ed25519):

ガイダンスについては、共通のステップに進んでください。

RSA SSHキー

SSH で RSA キーを使用する場合、米国国立標準技術研究所は少なくとも 2048 ビットのキーサイズを使用することを推奨しています。 デフォルトでは、ssh-keygen コマンドは 1024 ビットの RSA キーを作成します。

RSA鍵の作成と設定は、以下のコマンドで行えます。必要であれば、推奨される最小鍵サイズである2048を置き換えてください： 

ssh-keygen -t rsa -b 2048 -C "email@example.com"

-C フラグにメールアドレスなどのコメントを書くと、 SSH キーにラベルを付けることができます。

というような返答が表示されます： 

Generating public/private rsa key pair.
Enter file in which to save the key (/home/user/.ssh/id_rsa):

ガイダンスについては、共通のステップに進んでください。

注意:OpenSSH のバージョンが 7.8 以下の場合は、エンコーディングに関連する問題を考慮してください。

SSHキー・ペアを生成する一般的な手順

ED25519鍵であれRSA鍵であれ、ssh-keygen 。この時点で、コマンドラインに次のようなメッセージが表示されます（ED25519鍵の場合）： 

Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/user/.ssh/id_rsa):

SSH キーペアをまだ持っておらず、デプロイキーを生成しない場合は、提案されたファイルとディレクトリを受け入れます。 SSH クライアントは、追加の設定なしで結果の SSH キーペアを使用します。

また、新しいSSHキーペアを別の場所に保存することもできます。 ディレクトリとファイル名は自由に設定できます。 そのSSHキーペアを特定のホストに割り当てることもできます。

SSHキーを保存するファイルを指定したら、SSHキーのパスフレーズを設定します： 

Enter passphrase (empty for no passphrase):
Enter same passphrase again:

成功すれば、ssh-keygen コマンドがあなたのIDと秘密鍵を保存した場所の確認が表示されます。

必要に応じて、以下のコマンドでパスフレーズを更新できます： 

ssh-keygen -p -f /path/to/ssh_key

バージョン 6.5 から 7.8 までの RSA 鍵と OpenSSH

OpenSSH 7.8 より前のバージョンでは、RSA 鍵のデフォルトの公開鍵指紋は MD5 に基づいていました。

OpenSSH のバージョンがバージョン 6.5 からバージョン 7.8 (内部も含む) の間にある場合は、-o オプションをつけてssh-keygen を実行し、より安全な OpenSSH フォーマットで秘密鍵を保存してください。

すでにRSA SSHキーペアをGitLabで使っている場合は、よりセキュリティの高いパスワード暗号化形式にアップグレードすることを検討しましょう。 次のコマンドでそうすることができます： 

ssh-keygen -o -f ~/.ssh/id_rsa

あるいは、以下のコマンドで、よりセキュリティの高い暗号化形式で新しいRSA鍵を生成することもできます： 

ssh-keygen -o -t rsa -b 4096 -C "email@example.com"
注意:ssh-keygen の man ページにあるように、 ED25519 はすでに鍵をよりセキュリティの高い OpenSSH 形式に暗号化しています。

GitLabアカウントへのSSHキーの追加

これで、作成した SSH キーを GitLab アカウントにコピーできるようになりました。 コピーするには、以下の手順に従います：

  1. 公開 SSH キーをテキスト形式で情報を保存する場所にコピーします。 以下のオプションは、ED25519 キーの情報を指定したオペレーティング・システムのクリップボードに保存します：

    MacOS： 

    pbcopy < ~/.ssh/id_ed25519.pub

    Linux（xclipパッケージが必要です：） 

    xclip -sel clip < ~/.ssh/id_ed25519.pub

    Windowsでのgit Bash： 

    cat ~/.ssh/id_ed25519.pub | clip

    RSA鍵を使用している場合は、適宜読み替えてください。

  2. http://gitlab.com 、サインインしてください。
  3. 右上のアバターを選択し、「設定」をクリックします。
  4. SSHキーをクリックします。
  5. コピーした公開鍵を「Key」テキストボックスに貼り付けます。
  6. キーには、「Work Laptop」や「Home Workstation」のように、「Title」テキストボックスに説明的な名前が含まれていることを確認してください。
  7. Expires at “セクションの下に、鍵の有効期限を(オプションで)記述します。 (GitLab 12.9で導入されました)。
  8. Add keyボタンをクリックします。

この手順で “expired “したSSHキーは、GitLabのワークフローではまだ有効です。 GitLabが設定した有効期限はSSHキー自体には含まれないので、必要に応じて公開SSHキーをエクスポートすることができます。

注意:公開 SSH キーを手動でコピーした場合は、ssh-ed25519 (またはssh-rsa) で始まり、メールアドレスで終わるキー全体をコピーしたことを確認してください。

すべてが正しく設定されているかのテスト

SSH キーが正しく追加されたかどうかを調べるには、ターミナルで次のコマンドを実行します（gitlab.com を GitLab のインスタンスドメインに置き換えてください）： 

ssh -T git@gitlab.com

初めてSSHでGitLabに接続するときは、接続先のGitLabホストの信頼性を確認するよう求められます。例えば、GitLab.comに接続するときは、yes に答えてGitLab.comを信頼済みホストのリストに追加します： 

The authenticity of host 'gitlab.com (35.231.145.151)' can't be established.
ECDSA key fingerprint is SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'gitlab.com' (ECDSA) to the list of known hosts.
注意:GitLab.com の場合は、SSHホスト鍵のフィンガープリントのセクションを参照し、正しいサーバーに接続していることを確認しましょう。 たとえば、上記のリンク先のセクションにある ECDSA 鍵のフィンガープリントを参照します。

一度既知のホストのリストに追加すれば、GitLabのホストの信頼性を確認する必要はありません。 上記のコマンドをもう一度実行すると、Welcome to GitLab,@username! というメッセージが表示されるだけです。

ウェルカムメッセージが表示されない場合は、次のコマンドを使用してsshを冗長モードで実行することで、問題のトラブルシューティングを行うことができます： 

ssh -Tvvv git@gitlab.com

デフォルトでないSSHキーペアパスでの作業

GitLab SSH鍵ペアにデフォルト以外のファイルパスを使用した場合は、SSHクライアントがGitLab SSH秘密鍵を指すように設定してください。

これらの変更を行うには、以下のコマンドを実行します： 

eval $(ssh-agent -s)
ssh-add <path to private SSH key>

これらの設定を~/.ssh/config ファイルに保存します。GitLab 専用の SSH キーの例を二つ示します： 

# GitLab.com
Host gitlab.com
  Preferredauthentications publickey
  IdentityFile ~/.ssh/gitlab_com_rsa

# Private GitLab instance
Host gitlab.company.com
  Preferredauthentications publickey
  IdentityFile ~/.ssh/example_com_rsa

公開SSHキーはGitLabにとって一意である必要があります。 SSHキーはSSH経由でコードをプッシュするときの唯一の識別子であり、だからこそ一人のユーザーに一意に対応する必要があるのです。

リポジトリごとのSSHキー

作業中のリポジトリによってキーを使い分けたい場合は、リポジトリ内で以下のコマンドをイシューしてください： 

git config core.sshCommand "ssh -o IdentitiesOnly=yes -i ~/.ssh/private-key-filename-for-this-repository -F /dev/null"

これはSSHエージェントを使わず、少なくともgit 2.10が必要です。

一つのGitLabインスタンスに複数のアカウント

リポジトリごとの方法は、ひとつの GitLab インスタンス内で複数のアカウントを使う場合にも使えます。

あるいは、~.ssh/configでホストにエイリアスを直接割り当てることも可能です。.ssh/configのHost ブロックの外側にIdentityFile が設定されている場合、SSH、ひいては git はログインに失敗します。これは SSH がIdentityFile エントリをどのように組み立てるかに起因するもので、IdentitiesOnly をyesに設定しても変わりません。IdentityFile エントリは SSH 鍵ペアの秘密鍵を指すようにします。

注：秘密鍵と公開鍵は、ユーザのみが読めるようにしておく必要があります。 LinuxとMacOSでは、chmod 0400 ~/.ssh/<example_ssh_key> とchmod 0400 ~/.ssh/<example_sh_key.pub>を実行してください。
# User1 Account Identity
Host <user_1.gitlab.com>
  Hostname gitlab.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/<example_ssh_key1>

# User2 Account Identity
Host <user_2.gitlab.com>
  Hostname gitlab.com
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/<example_ssh_key2>
注意:Host のエイリアス例は、効率と透明性のためにuser_1.gitlab.com とuser_2.gitlab.com として定義されています。 高度な設定はメンテナーが難しくなります。このタイプのエイリアスを使うことで、git remote サブコマンドのような他のツールを使うときにわかりやすくなります。 SSH はどのような文字列でもHost エイリアスとして理解するので、Tanuki1 とTanuki2も、それがどこを指しているのかほとんどわからないにもかかわらず、動作します。

gitlab リポジトリのクローンは通常このようになります： 

git clone git@gitlab.com:gitlab-org/gitlab.git

user_1にクローンするには、gitlab.com を SSH エイリアスuser_1.gitlab.comに置き換えてください： 

git clone git@<user_1.gitlab.com>:gitlab-org/gitlab.git

git remote コマンドを使用して、以前にクローンしたリポジトリを修正します。

以下の例では、リモートリポジトリのエイリアスがoriginであると仮定しています。 

git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git

デプロイキー

デプロイキーのドキュメントをお読みください。

アプリケーション

エクリプス

EGitを使っている場合は、SSHキーをEclipseに追加することができます。

GitLabサーバーのSSH

GitLabはシステムにインストールされたSSHデーモンとインテグレーションしており、すべてのアクセスリクエストを処理するユーザー（通常はgit）を指定しています。SSH経由でGitLabサーバーに接続するユーザーは、ユーザー名の代わりにSSHキーで識別されます。

GitLabサーバー上で実行されるSSHクライアントオペレーションは、このユーザーとして実行されます。 このユーザーのSSH設定を変更して、例えばこれらのリクエストを認証するためにSSH秘密鍵を提供することは可能ですが、この方法はサポートされておらず、重大なセキュリティリスクをもたらすので強く推奨されません。

GitLabのチェックプロセスにはこの条件のチェックが含まれており、サーバーがこのように設定されている場合は、このセクションに移動します： 

$ gitlab-rake gitlab:check

Git user has default SSH configuration? ... no
  Try fixing it:
  mkdir ~/gitlab-check-backup-1504540051
  sudo mv /var/lib/git/.ssh/id_rsa ~/gitlab-check-backup-1504540051
  sudo mv /var/lib/git/.ssh/id_rsa.pub ~/gitlab-check-backup-1504540051
  For more information see:
  doc/ssh/README.md in section "SSH on the GitLab server"
  Please fix the error above and rerun the checks.

カスタム設定はできるだけ早く削除してください。 これらのカスタマイズは明示的にサポートされていないため、いつでも機能しなくなる可能性があります。

Microsoft Windows用オプション

Windows 10を実行している場合、Windows Subsystem for Linux(WSL)、およびその最新のWSL 2バージョンは、GitとSSHクライアントを含むさまざまなLinuxディストリビューションのインストールをサポートしています。

現在のWindowsのバージョンでは、Gitfor WindowsでGitとSSHクライアントをインストールすることもできます。

代替ツールには以下があります：

トラブルシューティング

git cloneでgit@gitlab.com's password:のようなパスワードの入力を求められる場合は、SSHの設定が間違っています。

  • SSHキーペアを正しく生成し、公開SSHキーをGitLabプロファイルに追加したことを確認します。
  • ssh-agent を使って手動で SSH 秘密鍵を登録してみてください。
  • ssh -Tv git@example.comを実行して接続をデバッグしてみてください（example.com を GitLab ドメインに置き換えてください）。