- 要件
- SSHキーのオプション
- 既存のSSHキーのレビュー
- 新しいSSHキー・ペアの生成
- GitLabアカウントへのSSHキーの追加
- すべてが正しく設定されているかのテスト
- デフォルトでないSSHキーペアパスでの作業
- リポジトリごとのSSHキー
- 一つのGitLabインスタンスに複数のアカウント
- デプロイキー
- アプリケーション
- GitLabサーバーのSSH
- トラブルシューティング
GitLabとSSHキー
Gitは分散バージョン管理システムであり、ローカルで作業することができます。 さらに、変更を他のサーバーと共有したり、「プッシュ」することもできます。 GitLabはSSHキーを使用して、Gitとサーバー間のセキュアな通信をサポートしています。
SSHプロトコルはこのセキュリティを提供し、GitLabリモートサーバーに対して毎回ユーザー名やパスワードを入力することなく認証することができます。
このページは、GitLabリポジトリへの接続をセキュアにするために使用できるセキュアSSHキーの設定に役立ちます。
- SSHキーの作成に関する情報が必要な場合は、SSHキーのオプションをご覧ください。
- GitLabアカウント専用のSSHキーを持っている場合は、デフォルト以外のSSHキーペアパスでの作業に興味があるかもしれません。
- すでにSSHキーペアをお持ちの場合は、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鍵の使用をサポートしています。
- GitLabはGitLab 11.0でDSAキーを非推奨としました。
- Practical Cryptography With Goで述べられているように、DSAに関するセキュリティのイシューはECDSAにも当てはまります。
したがって、この文書では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 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):
ガイダンスについては、共通のステップに進んでください。
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 アカウントにコピーできるようになりました。 コピーするには、以下の手順に従います:
-
公開 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鍵を使用している場合は、適宜読み替えてください。
-
http://gitlab.com
、サインインしてください。 - 右上のアバターを選択し、「設定」をクリックします。
- SSHキーをクリックします。
- コピーした公開鍵を「Key」テキストボックスに貼り付けます。
- キーには、「Work Laptop」や「Home Workstation」のように、「Title」テキストボックスに説明的な名前が含まれていることを確認してください。
- Expires at “セクションの下に、鍵の有効期限を(オプションで)記述します。 (GitLab 12.9で導入されました)。
- Add keyボタンをクリックします。
この手順で “expired “したSSHキーは、GitLabのワークフローではまだ有効です。 GitLabが設定した有効期限は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のホストの信頼性を確認する必要はありません。 上記のコマンドをもう一度実行すると、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 鍵ペアの秘密鍵を指すようにします。
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 ドメインに置き換えてください)。