`gitlab-sshd`によるインスタンスレベルのSSH証明書

プラン: Free、Premium、Ultimate
提供形態: GitLab Self-Managed

あなたのGitLab Self-Managedインスタンスがgitlab-sshdを使用している場合、インスタンスレベルのSSH証明書認証を設定できます。

認証局 (CA) 証明書を使用して、SSH認証を一元的に管理します。
Rails APIコールやデータベースの変更は必要ありません。

このアプローチは、OpenSSHのTrustedUserCAKeysディレクティブに相当するgitlab-sshdであり、OpenSSHベースのSSH証明書設定の代替手段です。

`gitlab_sshd`認証ワークフロー

gitlab_sshd認証ワークフローは次のプロセスに従います。

管理者はCAキーペアを生成します。
管理者は、CA公開キーのパスをsshd.trusted_user_ca_keysの下のconfig.ymlに追加します。
管理者は、ユーザーのSSH公開キーをCA秘密キーで署名します。証明書のKeyIdはユーザーのGitLabユーザー名に設定されます。
ユーザーが証明書で接続すると:
- gitlab-sshdは証明書の署名と有効期限を検証します。
- gitlab-sshdはKeyIdを抽出し、それをGitLabユーザー名として使用します。
- 標準のGitLabアクセス制御チェックが続行されます (ユーザーの存在、プロジェクトの権限)。

gitlab-sshdプロセスは、証明書の検証自体にRails APIコールまたはデータベース呼び出しを必要としません。/allowedエンドポイントは、他のSSH接続と同様に、認可のために引き続き呼び出されます。

他のSSH証明書メソッドとの比較

GitLabはいくつかのSSH証明書認証アプローチをサポートしています:

機能	インスタンスレベル (`gitlab-sshd`)	インスタンスレベル (OpenSSH)	グループレベル
設定場所	`config.yml`	`sshd_config`	GitLab API/UI
SSHサーバー	`gitlab-sshd`	OpenSSH	`gitlab-sshd`
提供形態	GitLab Self-Managed	GitLab Self-Managed	GitLab.com
プラン	Free、Premium、Ultimate	Free、Premium、Ultimate	Premium、Ultimate
スコープ	インスタンス全体（ネームスペースの制限なし）	インスタンス全体（ネームスペースの制限なし）	トップレベルグループ
ユーザー名マッピング	証明書`KeyId`	`AuthorizedPrincipalsCommand`による証明書キーID	APIによる証明書のID
Enterpriseユーザーの要件	いいえ	いいえ	はい
ドキュメント	このページ	OpenSSH `AuthorizedPrincipalsCommand`	グループSSH証明書

前提条件

インスタンスレベルのSSH証明書を設定する前に:

GitLab Self-Managedインスタンスでgitlab-sshdが有効になっている必要があります。詳細については、gitlab-sshdを有効にするを参照してください。
CAキーを作成し、config.ymlを編集するには、サーバーのファイルシステムにアクセスできる必要があります。
SSH証明書のKeyIdフィールドは、正確なGitLabユーザー名と一致する必要があります。

信頼できるCAキーの設定

インスタンスレベルのSSH証明書認証を設定するには:

CAキーペアを生成します:
```
ssh-keygen -t ed25519 -f ssh_user_ca -C "GitLab SSH User CA"
```
プロンプトが表示されたら、CA秘密キーを保護するための強力なパスフレーズを入力します。
このコマンドは2つのファイルを作成します:
- ssh_user_ca: CA秘密キー。
- ssh_user_ca.pub: CA公開キー。
公開キーのみをGitLabサーバーにコピーします:
```
sudo cp ssh_user_ca.pub /etc/gitlab/ssh_user_ca.pub
```
CA秘密キーは、GitLabサーバーではないオフラインシステムなど、安全な場所に保管してください。秘密キーは、ユーザー証明書に署名するためにのみ必要です。
CA公開キーファイルパスをgitlab-sshd設定に追加します。
1. /etc/gitlab/gitlab.rbを編集します:
  gitlab_sshd['trusted_user_ca_keys'] = ['/etc/gitlab/ssh_user_ca.pub']
2. ファイルを保存し、GitLabを再設定します:
  sudo gitlab-ctl reconfigure
1. CA公開キーを含むKubernetesシークレットを作成します:
  kubectl create secret generic my-ssh-ca-keys \ --from-file=ca.pub=ssh_user_ca.pub
2. Helmの値をエクスポートします:
  helm get values gitlab > gitlab_values.yaml
3. gitlab_values.yamlを編集してシークレットを参照します:
  gitlab: gitlab-shell: sshDaemon: gitlab-sshd config: trustedUserCAKeys: secret: my-ssh-ca-keys keys: - ca.pub
4. ファイルを保存し、新しい値を適用します:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
Helmチャートの設定の詳細については、GitLab Shellチャートドキュメントを参照してください。

gitlab-sshdが正常に起動したことをログで確認します:

Loaded trusted user CA keys for instance-level SSH certificates count=1

ユーザーにSSH証明書を発行する

信頼できるCAキーを設定したら、ユーザーに証明書を発行します:

ユーザーの公開SSHキー (id_ed25519.pubなど) を取得します。
CAでユーザーの公開キーに署名し、-I (ID/KeyId) フラグをユーザーの正確なGitLabユーザー名に設定します:
```
ssh-keygen -s ssh_user_ca -I <gitlab-username> -V +1d user-key.pub
```
このコマンドは、1日間有効な証明書ファイル (user-key-cert.pubなど) を作成します。
より長い有効期間を設定するには、-Vフラグを調整します。例えば、30日間の場合は-V +30d、1年間の場合は-V +52wを使用します。
証明書ファイルをユーザーに配布します。
ユーザーは証明書を使用して接続します:
```
ssh git@gitlab.example.com
```
証明書ファイルがデフォルトの命名規則 (<key>-cert.pubと<key>) に従っている場合、SSHはそれを自動的に使用します。そうでない場合は、証明書を明示的に指定します:
```
ssh -o CertificateFile=~/.ssh/id_ed25519-cert.pub git@gitlab.example.com
```

複数の認証局を使用する

CAローテーションまたはマルチCA設定のために、複数のCA公開キーファイルを指定できます。

/etc/gitlab/gitlab.rbを編集します:

gitlab_sshd['trusted_user_ca_keys'] = [
  '/etc/gitlab/ssh_user_ca_current.pub',
  '/etc/gitlab/ssh_user_ca_next.pub'
]

ファイルを保存し、GitLabを再設定します:
```
sudo gitlab-ctl reconfigure
```

両方のCA公開キーを含むKubernetesシークレットを作成します:

kubectl create secret generic my-ssh-ca-keys \
  --from-file=ca_current.pub=ssh_user_ca_current.pub \
  --from-file=ca_next.pub=ssh_user_ca_next.pub

Helmの値をエクスポートします:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yamlを編集してシークレットを参照します:

gitlab:
  gitlab-shell:
    sshDaemon: gitlab-sshd
    config:
      trustedUserCAKeys:
        secret: my-ssh-ca-keys
        keys:
          - ca_current.pub
          - ca_next.pub

ファイルを保存し、新しい値を適用します:
```
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```

1つのファイルに複数のCA公開キーを1行に1つ含めることもできます。gitlab-sshdはファイル間でキーを自動的に重複排除します。

セキュリティに関する考慮事項

インスタンスレベルのSSH証明書は、CA秘密キーを保持する誰にでも認証権限を付与します。デプロイする前に、以下のセキュリティに関する考慮事項を確認してください。

CA秘密キーへのアクセスを持つ人は誰でも、インスタンス上の任意の GitLabユーザーの証明書に署名できます。制限的なファイル権限、ハードウェアセキュリティモジュール (HSM)、またはオフライン環境など、適切なアクセス制御でCA秘密キーを保護してください。

証明書の失効なし

gitlab-sshdには、組み込みの証明書失効メカニズムは含まれていません。証明書またはCAキーが危険にさらされた場合、trusted_user_ca_keys設定からCAを削除し、新しいCAで証明書を再発行します。短命の証明書 (例えば24時間) を使用して、露出期間を最小限に抑えるようにしてください。

CA設定変更の監査イベントなし

GitLabは、config.ymlにおけるtrusted_user_ca_keysへの変更を監査イベントとして記録しません。インフラストラクチャモニタリングツールを使用して、この設定ファイルへの変更をモニタリングします。

gitlab-sshdは、成功および失敗したSSH証明書認証の試行を、ssh_user、public_key_fingerprint、signing_ca_fingerprint、certificate_identity、およびcertificate_usernameを含むフィールドでログに記録します。

クラスターデプロイ

複数のgitlab-sshdノードがある環境では、設定とCA公開キーファイルをすべてのノード間で同期します。一貫性のない設定は、断続的な認証失敗を引き起こす可能性があります。Helmチャートのデプロイの場合、Kubernetesシークレットはポッド間で自動的に共有されます。

トラブルシューティング

`gitlab-sshd`がCAキー追加後に起動失敗

CAキーファイルが読み取れないか、有効でないコンテンツが含まれている場合、gitlab-sshdは起動しません。エラーメッセージのログ出力を確認してください。例えば:

failed to load trusted user CA keys: ファイルを読み取ることができませんでした。ファイルが存在し、正しい権限 (gitユーザーが読み取り可能) があることを確認します。
failed to parse trusted user CA key in file: ファイルの内容は有効なSSH公開キーではありません。ファイルにOpenSSH形式の有効な公開キーが含まれていることを確認します。
trusted_user_ca_keys configured but no valid CA keys were loaded: 設定にはCAキーファイルがリストされていますが、有効なキーは含まれていませんでした。

`certificate rejected: not a user certificate`

証明書がユーザー証明書ではなくホスト証明書として生成されました。ssh-keygenで署名するときは-hフラグを使用しないでください。

`certificate KeyId does not match GitLab username format`

証明書のKeyIdは、GitLabユーザー名のルールに準拠していません。署名中に使用された-Iの値が正確なGitLabユーザー名と一致することを確認します。

`ssh: cert has expired`

証明書の有効期間が過ぎています。-Vフラグを使用して、適切な有効期間の新しい証明書を発行します。

gitlab-sshdによるインスタンスレベルのSSH証明書

gitlab_sshd認証ワークフロー