スマートカード認証

GitLabはスマートカードを使った認証をサポートしています。

既存のパスワード認証

GitLab 12.6 で導入されました。

デフォルトでは、スマートカード認証が有効な場合、既存ユーザーはユーザー名とパスワードでサインインし続けることができます。

既存のユーザーにスマートカード認証のみを使用させるには、ユーザー名とパスワードによる認証を無効にします。

認証方法

GitLabは2つの認証方法をサポートしています：

  • X.509証明書とローカルデータベース。
  • LDAPサーバー。

X.509証明書を使用したローカルデータベースに対する認証

GitLab 11.6で実験的な機能として導入されました。

caution
ローカルデータベースに対するスマートカード認証は、今後のリリースで変更されるか、完全に削除される可能性があります。

X.509証明書付きのスマートカードはGitLabでの認証に使用できます。

X.509証明書付きのスマートカードを使用してGitLabでローカルのデータベースを認証するには、証明書にCN とemailAddress を定義する必要があります。例えば

Certificate:
    Data:
        Version: 1 (0x0)
        Serial Number: 12856475246677808609 (0xb26b601ecdd555e1)
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: O=Random Corp Ltd, CN=Random Corp
        Validity
            Not Before: Oct 30 12:00:00 2018 GMT
            Not After : Oct 30 12:00:00 2019 GMT
        Subject: CN=Gitlab User, emailAddress=gitlab-user@example.com

X.509証明書とSAN拡張を使ったローカルデータベースに対する認証

GitLab 12.3 で導入されました。

SAN拡張を使用したX.509証明書付きスマートカードをGitLabの認証に使用できます。

note
これは実験的な機能です。ローカルデータベースに対するスマートカード認証は、将来のリリースで変更されるか、完全に削除される可能性があります。

X.509証明書付きのスマートカードを使ってGitLabでローカルデータベースを認証するには：

  • GitLab 12.4 以降では、GitLab インスタンス (URI) URI内で、subjectAltName (SAN) 拡張機能のうち少なくともひとつがユーザー ID (email) を定義する必要がURIあります。 URI:Gitlab.config.host.gitlabと一致する必要があります。
  • GitLab 12.5以降では、証明書にSANメールのエントリーが1つしか含まれていない場合、email をURIと一致させるために追加または修正する必要はありません。

使用例：

Certificate:
    Data:
        Version: 1 (0x0)
        Serial Number: 12856475246677808609 (0xb26b601ecdd555e1)
    Signature Algorithm: sha256WithRSAEncryption
        Issuer: O=Random Corp Ltd, CN=Random Corp
        Validity
            Not Before: Oct 30 12:00:00 2018 GMT
            Not After : Oct 30 12:00:00 2019 GMT
        ...
        X509v3 extensions:
            X509v3 Key Usage:
                Key Encipherment, Data Encipherment
            X509v3 Extended Key Usage:
                TLS Web Server Authentication
            X509v3 Subject Alternative Name:
                email:gitlab-user@example.com, URI:http://gitlab.example.com/

LDAPサーバーに対する認証

GitLab 11.8で実験的な機能として導入されました。LDAPサーバーに対するスマートカード認証は将来変更されるか、完全に削除される可能性があります。

GitLabはRFC4523に従った証明書照合の標準的な方法を実装しています。これはuserCertificate 属性に対するcertificateExactMatch 証明書マッチングルールを使用します。前提として、以下のようなLDAPサーバーを使用する必要があります：

  • certificateExactMatch マッチングルールをサポートしていること。
  • userCertificate 属性に証明書が格納されています。
note
Active DirectoryはcertificateExactMatch マッチングルールをサポートしていないため、現時点ではサポートされていません。詳細については、関連するイシューを参照してください。

スマートカード認証のためのGitLabの設定

Linuxパッケージ・インストールの場合：

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

    # Allow smartcard authentication
gitlab_rails['smartcard_enabled'] = true
   
# Path to a file containing a CA certificate
gitlab_rails['smartcard_ca_file'] = "/etc/ssl/certs/CA.pem"
   
# Host and port where the client side certificate is requested by the
# webserver (NGINX/Apache)
gitlab_rails['smartcard_client_certificate_required_host'] = "smartcard.example.com"
gitlab_rails['smartcard_client_certificate_required_port'] = 3444
    note
    gitlab_rails['smartcard_client_certificate_required_host'] またはgitlab_rails['smartcard_client_certificate_required_port'] 以下の変数のうち、少なくともひとつに値を割り当ててください。

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

セルフコンパイルによるインストールの場合：

  1. クライアント側の証明書を要求するようにNGINXを設定します。

    NGINXの設定において、同じ設定で追加のサーバーコンテキストを定義する必要があります：

    • 追加の NGINX サーバーコンテキストは、別のポートで実行するように設定する必要があります：

       listen *:3444 ssl;

    • また、別のホスト名で実行するように設定することもできます：

       listen smartcard.example.com:443 ssl;

    • 追加の NGINX サーバーコンテキストは、クライアント側の証明書を必要とするように設定する必要があります：

       ssl_verify_depth 2;
 ssl_client_certificate /etc/ssl/certs/CA.pem;
 ssl_verify_client on;

    • 追加の NGINX サーバーコンテキストは、クライアント側の証明書を転送するように設定する必要があります：

       proxy_set_header    X-SSL-Client-Certificate    $ssl_client_escaped_cert;

    例えば、以下はNGINX設定ファイル（/etc/nginx/sites-available/gitlab-ssl など）のサーバーコンテキストの例です：

    server {
    listen smartcard.example.com:3443 ssl;
   
    # certificate for configuring SSL
    ssl_certificate /path/to/example.com.crt;
    ssl_certificate_key /path/to/example.com.key;
   
    ssl_verify_depth 2;
    # CA certificate for client side certificate verification
    ssl_client_certificate /etc/ssl/certs/CA.pem;
    ssl_verify_client on;
   
    location / {
        proxy_set_header    Host                        $http_host;
        proxy_set_header    X-Real-IP                   $remote_addr;
        proxy_set_header    X-Forwarded-For             $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Proto           $scheme;
        proxy_set_header    Upgrade                     $http_upgrade;
        proxy_set_header    Connection                  $connection_upgrade;
   
        proxy_set_header    X-SSL-Client-Certificate    $ssl_client_escaped_cert;
   
        proxy_read_timeout 300;
   
        proxy_pass http://gitlab-workhorse;
    }
}

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

    ## Smartcard authentication settings
smartcard:
  # Allow smartcard authentication
  enabled: true
   
  # Path to a file containing a CA certificate
  ca_file: '/etc/ssl/certs/CA.pem'
   
  # Host and port where the client side certificate is requested by the
  # webserver (NGINX/Apache)
  client_certificate_required_host: smartcard.example.com
  client_certificate_required_port: 3443
    note
    client_certificate_required_host またはclient_certificate_required_port 以下の変数のうち、少なくともひとつに値を割り当ててください。

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

SAN拡張機能を使用する際の追加手順

Linuxパッケージ・インストールの場合：

  1. /etc/gitlab/gitlab.rb に追加してください：

    gitlab_rails['smartcard_san_extensions'] = true

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

セルフコンパイルによるインストールの場合：

  1. スマートカードセクション内のconfig/gitlab.yml にsan_extensions 行を追加してください：

    smartcard:
   enabled: true
   ca_file: '/etc/ssl/certs/CA.pem'
   client_certificate_required_port: 3444
   
   # Enable the use of SAN extensions to match users with certificates
   san_extensions: true

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

LDAPサーバーに対して認証を行う際の追加手順

Linuxパッケージ・インストールの場合：

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

    gitlab_rails['ldap_servers'] = YAML.load <<-EOS
main:
  # snip...
  # Enable smartcard authentication against the LDAP server. Valid values
  # are "false", "optional", and "required".
  smartcard_auth: optional
EOS

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

セルフコンパイルによるインストールの場合：

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

    production:
  ldap:
    servers:
      main:
        # snip...
        # Enable smartcard authentication against the LDAP server. Valid values
        # are "false", "optional", and "required".
        smartcard_auth: optional

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

Gitへのアクセスにスマートカードサインインによるブラウザセッションを要求

Linuxパッケージ・インストールの場合：

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

    gitlab_rails['smartcard_required_for_git_access'] = true

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

セルフコンパイルによるインストールの場合：

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

    ## Smartcard authentication settings
smartcard:
  # snip...
  # Browser session with smartcard sign-in is required for Git access
  required_for_git_access: true

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

スマートカード認証で作成したユーザーのパスワード

統合認証で作成されたユーザーのパスワード生成ガイドでは、スマートカード認証で作成されたユーザーのパスワードをGitLabがどのように生成・設定するかの概要を説明しています。