Kerberos を OAuth 2.0 認証プロバイダーとして使用します。

GitLabは認証メカニズムとしてKerberosとインテグレーションすることができます。

  • GitLabを設定して、ユーザーがKerberos認証情報でサインインできるようにすることができます。
  • Kerberosを使うことで、送信されたパスワードの傍受や盗聴を防ぐことができます。
caution
GitLab CI/CDは、インテグレーションが専用ポートを使用するように設定されていない限り、Kerberos対応のGitLabインスタンスでは動作しません。

設定

GitLabがKerberosトークンベースの認証を提供するためには、以下の前提条件を実行してください。realmsの指定など、Kerberosを使用するための設定が必要です。GitLabはシステムのKerberos設定を利用します。

GitLab keytab

  1. GitLabサーバーのHTTPサービス用のKerberosサービス・プリンシパルを作成します。GitLab サーバーがgitlab.example.com で、Kerberos レルムがEXAMPLE.COM の場合は、Kerberos データベースに Service PrincipalHTTP/gitlab.example.com@EXAMPLE.COM を作成します。
  2. GitLabサーバー上に上記のサービスプリンシパル用のkeytabを作成します。例えば、/etc/http.keytab 。

keytabは機密ファイルなので、GitLabユーザーが読めるようにしなければなりません。所有権を設定し、ファイルを適切に保護します：

sudo chown git /etc/http.keytab
sudo chmod 0600 /etc/http.keytab

GitLab の設定

セルフコンパイルによるインストール

note
セルフコンパイルでインストールする場合は、kerberos gemグループがインストールされていることを確認してください。

  1. gitlab.yml のkerberos セクションを編集して Kerberos チケットベース認証を有効にします。ほとんどの場合、Kerberosを有効にしてkeytabの場所を指定するだけです：

    omniauth:
  enabled: true
  allow_single_sign_on: ['kerberos']
   
kerberos:
  # Allow the HTTP Negotiate authentication method for Git clients
  enabled: true
   
  # Kerberos 5 keytab file. The keytab file must be readable by the GitLab user,
  # and should be different from other keytabs in the system.
  # (default: use default keytab from Krb5 config)
  keytab: /etc/http.keytab

  2. 変更を有効にするためにGitLabを再起動してください。

Linux パッケージのインストール

  1. /etc/gitlab/gitlab.rb を編集します：

    gitlab_rails['omniauth_allow_single_sign_on'] = ['kerberos']
   
gitlab_rails['kerberos_enabled'] = true
gitlab_rails['kerberos_keytab'] = "/etc/http.keytab"

    GitLabがKerberosを通して最初のサインイン時に自動的にユーザーを作成するのを避けるために、gitlab_rails['omniauth_allow_single_sign_on'] にkerberos を設定しないでください。

  2. 変更を有効にするには、GitLabを再設定してください。

GitLabはサインインとHTTP Gitアクセスにnegotiate 認証方法を提供するようになり、この認証プロトコルをサポートするGitクライアントがKerberosトークンで認証できるようになりました。

シングルサインオンの有効化

共通設定を構成して、シングルサインオンプロバイダとしてkerberos 。これにより、既存のGitLabアカウントを持っていないユーザーのためのJust-In-Timeアカウントプロビジョニングが可能になります。

Kerberosアカウントを既存のGitLabアカウントにリンクするか、KerberosユーザーがサインインしようとしたときにGitLabが新しいアカウントを作成するように設定します。

Kerberos SPNEGOはGitLab 15.4でKerberosに名称変更されました。

管理者であれば、Kerberosアカウントを既存のGitLabアカウントにリンクすることができます。それには

  1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
  2. Admin Areaを選択します。
  3. 左側のサイドバーで、[概要] > [ユーザー]を選択します。
  4. ユーザーを選択し、[Identities]タブを選択します。
  5. Provider］ドロップダウンリストから［Kerberos］を選択します。
  6. Identifierが Kerberos ユーザー名に対応していることを確認します。
  7. 変更を保存を選択します。

管理者でない場合

  1. 左のサイドバーで、自分のアバターを選択してください。
  2. プロフィールの編集を選択します。
  3. 左サイドバーで「アカウント」を選択します。
  4. サービス・サインイン］セクションで、［Kerberos接続］を選択します。Servicesign-inKerberos］オプションが表示されない場合は、［Enable single sign-on］の要件に従ってください。

どちらの場合でも、Kerberos認証を使ってGitLabアカウントにサインインできるようになります。

最初のサインインでアカウントを作成

ユーザーが初めてKerberosアカウントでGitLabにサインインするとき、GitLabはそれに一致するアカウントを作成します。続行する前に、OmnibusとGitLabソースの共通設定オプションをレビューしてください。また、kerberos.

その情報を手元に置いて

  1. allow_single_sign_on 設定で'kerberos' を含めます。
  2. 今のところ、デフォルトのblock_auto_created_users オプション、true を受け入れます。
  3. ユーザーが Kerberos 認証を使ってサインインしようとすると、GitLab は新しいアカウントを作成します。

    1. block_auto_created_users が true の場合、Kerberos ユーザーは次のようなメッセージを見るかもしれません：

      Your account has been blocked. Please contact your GitLab
administrator if you think this is an error.
      1. 管理者として、ブロックされた新しいアカウントを確認できます：
        1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
        2. Admin Areaを選択します。
        3. 左サイドバーで「概要」>「ユーザー」を選択し、「ブロック」タブをレビューします。
      2. ユーザーを有効にできます。

    2. block_auto_created_users が false の場合、Kerberos ユーザーは認証され、GitLab にサインインします。

block_auto_created_users block_auto_created_usersはデフォルトのままにしておくことをお勧めします。管理者が知らないうちにGitLabにアカウントを作成するKerberosユーザーは、セキュリティ・リスクになる可能性があります。

ユーザーがKerberosでサインインし、LDAPインテグレーションも有効にしている場合、ユーザーは最初のサインイン時にLDAPアカウントにリンクされます。これを機能させるには、いくつかの前提条件を満たす必要があります：

Kerberosユーザー名がLDAPユーザーのUIDと一致していること。どのLDAP属性をUIDとして使うかはGitLabLDAP設定で選択できますが、Active Directoryの場合はsAMAccountName 。

Kerberosレルムは、LDAPユーザーの識別名のドメイン部分と一致しなければなりません。例えば、Kerberos レルムがAD.EXAMPLE.COM の場合、LDAP ユーザーの識別名はdc=ad,dc=example,dc=com で終わる必要があります。

これらのルールをまとめると、リンクはユーザーのKerberosユーザー名がfoo@AD.EXAMPLE.COM 、LDAP識別名がsAMAccountName=foo,dc=ad,dc=example,dc=com のような場合にのみ機能します。

カスタム許可レルム

GitLab 13.5 で導入されました。

ユーザーのKerberosレルムがユーザーのLDAP DNのドメインと一致しない場合に、カスタム許可レルムを設定することができます。設定値には、ユーザーが持つと思われるドメインをすべて指定する必要があります。その他のドメインは無視され、LDAP ID はリンクされません。

Linux package (Omnibus)

  1. /etc/gitlab/gitlab.rb を編集します：

    gitlab_rails['kerberos_simple_ldap_linking_allowed_realms'] = ['example.com','kerberos.example.com']

  2. ファイルを保存し、変更を有効にするために GitLab を再設定します。

Self-compiled (source)

  1. config/gitlab.yml を編集します：

    kerberos:
  simple_ldap_linking_allowed_realms: ['example.com','kerberos.example.com']

  2. ファイルを保存して GitLab を再起動すると、変更が有効になります。

HTTP Gitアクセス

リンクされた Kerberos アカウントを使えば、標準の GitLab 認証情報だけでなく Kerberos アカウントを使ってgit pull やgit push にアクセスすることができます。

リンクされたKerberosアカウントを持つGitLabユーザーは、Kerberosトークンを使ってgit pull 、git push 。つまり、オペレーションごとにパスワードを送信する必要がありません。

caution
バージョン7.64.1より古いlibcurl には、ネゴシエーションの際にコネクションを再利用しないという既知のイシューがあります。これは、プッシュがhttp.postBuffer 設定よりも大きい場合に作成者のイシューにつながります。これを避けるlibcurl ために libcurl、Gitが少なくとも7libcurl.64.1を使って libcurlいることを確認してください。インストールされているバージョンをlibcurl 知るには libcurl、curl-config --version.

Kerberosトークンを使ったHTTP Gitアクセス（パスワードレス認証）

現在の Git のバージョンにはバグがあるため、git CLI コマンドは、HTTP サーバーがnegotiate 認証方法を提供している場合にのみ、この方法が失敗した場合 (クライアントが Kerberos トークンを持っていない場合など) にも使用します。そのため、Kerberos認証に失敗した場合に、ユーザー名とパスワードを埋め込んだ認証（basic ）にフォールバックすることはできません。

GitLabユーザーが現在のGitバージョンでbasic とnegotiate のどちらの認証も使えるようにするには、Kerberosチケットベースの認証を別のポート（例えば8443 ）で提供し、標準ポートではbasic 認証のみを提供するようにします。

note
Git 2.4 以降では、ユーザー名とパスワードが対話的に渡された場合や認証情報マネージャを経由した場合に、basic 認証にフォールバックすることができます。ユーザー名とパスワードが URL の一部として渡された場合は、フォールバックに失敗します。たとえば、basicCI/CD ジョブトークンで認証basicする GitLab CI/CD ジョブでこのようなことが起こる可能性があります。
Linux package (Omnibus)

  1. /etc/gitlab/gitlab.rb を編集します：

    gitlab_rails['kerberos_use_dedicated_port'] = true
gitlab_rails['kerberos_port'] = 8443
gitlab_rails['kerberos_https'] = true

  2. 変更を有効にするには、GitLabを再設定してください。

Self-compiled (source) with HTTPS

  1. GitLab用のNGINX設定ファイル（例えば、/etc/nginx/sites-available/gitlab-ssl ）を編集し、標準のHTTPSポートに加えて、ポート8443 をリッスンするようにNGINXを設定します：

    server {
  listen 0.0.0.0:443 ssl;
  listen [::]:443 ipv6only=on ssl default_server;
  listen 0.0.0.0:8443 ssl;
  listen [::]:8443 ipv6only=on ssl;

  2. gitlab.ymlのkerberos セクションを更新します：

    kerberos:
  # Dedicated port: Git before 2.4 does not fall back to Basic authentication if Negotiate fails.
  # To support both Basic and Negotiate methods with older versions of Git, configure
  # nginx to proxy GitLab on an extra port (for example: 8443) and uncomment the following lines
  # to dedicate this port to Kerberos authentication. (default: false)
  use_dedicated_port: true
  port: 8443
  https: true

  3. 変更を有効にするためにGitLabと NGINX を再起動します。

この変更後、Kerberosチケットベースの認証を使用するには、GitリモートURLをhttps://gitlab.example.com:8443/mygroup/myproject.git 。

パスワードベースからチケットベースの Kerberos サインインへのアップグレード

GitLabの以前のバージョンでは、ユーザーはサインイン時にKerberosのユーザー名とパスワードをGitLabに送信する必要がありました。

GitLab 14.3でパスワードベースのKerberosサインインを非推奨とし、GitLab 15.0で削除しました。チケットベースのサインインに切り替える必要があります。

既存のGitLab設定によっては、Sign in with：KerberosはすでにGitLabサインインページに表示されているかもしれません。そうでない場合は、上記の設定を追加してください。

パスワードベースのKerberosサインインを無効にするには、gitlab.yml/gitlab.rb ファイルからOmniAuthプロバイダkerberos を削除してください。

Linux package (Omnibus)

  1. /etc/gitlab/gitlab.rb を編集し、gitlab_rails['omniauth_providers'] の下の{ "name" => "kerberos" } 行を削除します：

    gitlab_rails['omniauth_providers'] = [
  { "name" => "kerberos" } # <-- remove this entry
]

  2. 変更を有効にするには、GitLabを再設定してください。

Self-compiled (source)

  1. gitlab.yml を編集し、OmniAuth providers の下にある- { name: 'kerberos' } 行を削除します：

    omniauth:
  # Rest of configuration omitted
  # ...
  providers:
    - { name: 'kerberos' }  # <-- remove this line

  2. 変更を有効にするためにGitLabを再起動してください。

note
kerberos OmniAuthプロバイダを削除することで、HTTPS経由でクローンしようとしたときに稀に発生するKrb5Auth::Krb5::Exception (No credentials cache found) エラー(500 error in GitLab)を解決することもできます。

Active Directory Kerberos環境のサポート

Active DirectoryドメインでKerberosチケットベースの認証を使用する場合、Kerberosプロトコルの拡張によりHTTP認証ヘッダーのサイズがデフォルトの8kBより大きくなる可能性があるため、NGINXで許可される最大ヘッダーサイズを大きくする必要がある場合があります。NGINXの設定で、large_client_header_buffers をより大きな値に設定します。

Windows AD で AES のみの暗号化を使用して作成されたキータブを使用します。

Advanced Encryption Standard(AES)- only encryptionを使用してキータブを作成する場合、ADサーバーのそのアカウントに対して、This account supports Kerberos AES <128/256> bit encryptionチェックボックスを選択する必要があります。チェックボックスが128ビットか256ビットかは、keytab作成時に使用した暗号化強度によって異なります。これを確認するには、Active Directoryサーバーで

  1. ユーザーとグループツールを開きます。
  2. キータブの作成に使用したアカウントを探します。
  3. アカウントを右クリックし、プロパティを選択します。
  4. アカウント] タブの [アカウント オプション] で、適切な [AES 暗号化サポート] チェックボックスを選択します。
  5. 保存して閉じます。

トラブルシューティング

Windows ADに対するKerberos認証でGoogle Chromeを使用する場合

Google Chrome を使って Kerberos 認証で GitLab にサインインする場合は、完全なユーザー名を入力しなければなりません。例えば、username@domain.com 。

完全なユーザー名を入力しないと、サインインに失敗します。ログをチェックすると、サインインに失敗した証拠として次のようなイベントメッセージが表示されます：

"message":"OmniauthKerberosController: failed to process Negotiate/Kerberos authentication: gss_accept_sec_context did not return GSS_S_COMPLETE: An unsupported mechanism was requested\nUnknown error"`.

GitLabとKerberosサーバー間の接続をテストしてください。

kinit やklist のようなユーティリティを使って、GitLabサーバーとKerberosサーバー間の接続性をテストすることができます。これらのインストール方法はOSによって異なります。

klist を使って、klist ファイルで利用可能なサービスプリンシパル名(SPN) と、各 SPN の暗号化タイプを確認します：

klist -ke /etc/http.keytab

Ubuntuサーバーの場合、出力は以下のようになります：

Keytab name: FILE:/etc/http.keytab
KVNO Principal
---- --------------------------------------------------------------------------
   3 HTTP/my.gitlab.domain@MY.REALM (des-cbc-crc)
   3 HTTP/my.gitlab.domain@MY.REALM (des-cbc-md5)
   3 HTTP/my.gitlab.domain@MY.REALM (arcfour-hmac)
   3 HTTP/my.gitlab.domain@MY.REALM (aes256-cts-hmac-sha1-96)
   3 HTTP/my.gitlab.domain@MY.REALM (aes128-cts-hmac-sha1-96)

verboseモードでkinit 。GitLabがkeytabファイルを使ってKerberosサーバーに接続できるかどうかをテストします：

KRB5_TRACE=/dev/stdout kinit -kt /etc/http.keytab HTTP/my.gitlab.domain@MY.REALM

このコマンドは認証プロセスの詳細な出力を表示します。

サポートされていない GSSAPI メカニズム

Kerberos SPNEGO認証では、ブラウザはサポートしているメカニズムのリストをGitLabに送ることになっています。GitLab がサポートしているメカニズムのどれにも対応していない場合は、認証に失敗してログにこのようなメッセージが表示されます：

OmniauthKerberosController: failed to process Negotiate/Kerberos authentication: gss_accept_sec_context did not return GSS_S_COMPLETE: An unsupported mechanism was requested Unknown error

このエラーメッセージにはいくつかの原因と解決策が考えられます。

専用ポートを使用していないKerberosインテグレーション

GitLab CI/CDは、Kerberosインテグレーションが専用ポートを使用するように設定されていない限り、Kerberos対応のGitLabインスタンスでは動作しません。

クライアントマシンとKerberosサーバー間の接続性の欠如

これは通常、ブラウザが直接Kerberosサーバーに接続できない場合に起こります。この場合、IAKERB として知られているサポートされていないメカニズムに戻ります。このメカニズムは、Kerberosサーバーへの仲介としてGitLabサーバーを使おうとします。

このエラーが発生する場合は、クライアントマシンと Kerberos サーバーが接続されていることを確認してください！ファイアウォールによってトラフィックがブロックされているか、DNSレコードが正しくない可能性があります。

GitLab DNS record is a CNAME record エラー

GitLabがCNAME レコードで参照されている場合、Kerberosはこのエラーで失敗します。このイシューを解決するには、GitLabのDNSレコードがA レコードであることを確認してください。

GitLabインスタンスのホスト名の順方向DNSレコードと逆方向DNSレコードが不一致です。

もう一つの失敗モードは、GitLabサーバーのフォワードDNSレコードとリバースDNSレコードが一致しない場合に起こります。この場合、Windowsクライアントは動作しますが、Linuxクライアントは失敗することがよくあります。逆引きDNSを使ってKerberosレルムを検出します。もし間違ったレルムを取得すると、通常のKerberosメカニズムが失敗し、クライアントはIAKERB 、上記のエラーメッセージにつながるネゴシエーションを試みます。

これを解決するには、GitLabサーバーのフォワードDNSとリバースDNSが一致していることを確認します。例えば、GitLab にgitlab.example.com としてアクセスし、IP アドレス10.0.2.2 に解決する場合、2.2.0.10.in-addr.arpa はgitlab.example.comのPTR レコードでなければなりません。

ブラウザやクライアントマシンにKerberosライブラリがない

最後に、ブラウザまたはクライアント・マシンがKerberosを完全にサポートしていない可能性があります。Kerberosライブラリがインストールされ、他のKerberosサービスに認証できることを確認してください。

HTTPベーシック：クローン作成時にアクセスが拒否されます 

remote: HTTP Basic: Access denied
fatal: Authentication failed for '<KRB5 path>'

Git v2.11以降を使用していてクローン作成時に上記のエラーが発生する場合は、http.emptyAuth Git オプションをtrue に設定することで解決します：

git config --global http.emptyAuth true

こちらも参照ください：Git v2.11 リリースノート