スマートカード認証

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

既存のパスワード認証

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

既存のユーザー名とパスワードによる認証のみを強制的に使用させるには、ユーザー名とパスワード認証を無効にしてください。

認証方法

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

• ローカルデータベースを使用したX.509証明書。
• LDAPサーバー。

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

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拡張機能を使用したローカルデータベースに対する認証

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

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

• 少なくとも1つのsubjectAltName（SAN）拡張機能は、GitLabインスタンス（URI）内でユーザーID（email）を定義する必要があります。
• URIはGitlab.config.host.gitlabと一致する必要があります。
• 証明書に1つのSANメールエントリのみが含まれている場合、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は、RFC4523に従って、証明書照合の標準的な方法を実装しています。これは、certificateExactMatch証明書照合ルールをuserCertificate属性に対して使用します。前提条件として、次のLDAPサーバーを使用する必要があります:

• certificateExactMatch照合ルールをサポートします。
• userCertificate属性に保存されている証明書があります。

Active Directory LDAPサーバーに対する認証

Active Directoryは、certificateExactMatchルールまたはuserCertificate属性をサポートしていません。スマートカードなどの証明書ベースの認証用のほとんどのツールは、altSecurityIdentities属性を使用します。これには、ユーザーごとに複数の証明書を含めることができます。フィールド内のデータは、Microsoftが推奨する形式のいずれかと一致する必要があります。

次の属性を使用して、GitLabがチェックするフィールドと証明書データの形式をカスタマイズします:

• smartcard_ad_cert_field - 検索するフィールドの名前を指定します。これは、ユーザーオブジェクトの任意の属性にすることができます。
• smartcard_ad_cert_format - 証明書から収集された情報の形式を指定します。この形式は、次のいずれかの値である必要があります。最も一般的なのは、Active Directory以外のLDAPサーバーの動作と一致させるためのissuer_and_serial_numberです。

issuer_and_serial_numberの場合、<SR>の部分はリバースバイトオーダーで、最下位バイトが最初になります。詳細については、altSecurityIdentities属性を使用して、ユーザーを証明書にマップする方法を参照してください。

リバース発行者形式は、発行者文字列を最小単位から最大単位にソートします。一部のActive Directoryサーバーは、この形式で証明書を保存します。

Azure IDドメインサービスに対する認証

Microsoft Azure ID（旧称Azure Active Directory）は、企業および組織向けのクラウドベースのディレクトリを提供します。Azureドメインサービスは、ディレクトリへの安全な読み取り専用LDAPインターフェースを提供しますが、Azure IDが持つフィールドの限られたサブセットのみを公開します。

Azure IDは、ユーザーのクライアント証明書を管理するためにCertificateUserIdsフィールドを使用しますが、このフィールドはLDAP / Azure IDドメインサービスでは公開されません。クラウドのみのセットアップでは、GitLabがLDAPを使用してユーザーのスマートカードを認証することはできません。

ハイブリッドオンプレミスおよびクラウド環境では、エンティティはオンプレミスのActive DirectoryコントローラーとクラウドAzure IDの間でAzure Connectを使用して同期されます。Entra ID Connectを使用してAzure IDのcertificateUserIds属性にaltSecurityIdentities属性を同期する場合は、このデータをLDAP / Azure IDドメインサービスで公開して、GitLabで認証できるようにすることができます:

1. Azure ID Connectにルールを追加して、Azure IDの追加の属性にaltSecurityIdentities属性を同期します。
2. その追加の属性をAzure IDドメインサービスの拡張属性として有効にします。
3. この拡張属性を使用するように、GitLabのsmartcard_ad_cert_fieldフィールドを構成します。

スマートカード認証用のGitLabを構成する

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

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

   # Allow smart card 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

   次の変数の少なくとも1つ（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を編集します:

   ## Smart card authentication settings
   smartcard:
     # Allow smart card 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

   次の変数の少なくとも1つ（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 smart card authentication against the LDAP server. Valid values
     # are "false", "optional", and "required".
     smartcard_auth: optional
   
     # If your LDAP server is Active Directory, you can configure these two fields.
     # Specify which field contains certificate information, 'altSecurityIdentities' by default
     smartcard_ad_cert_field: altSecurityIdentities
   
     # Specify format of certificate information. Valid values are:
     # principal_name, rfc822_name, issuer_and_subject, subject, issuer_and_serial_number
     smartcard_ad_cert_format: issuer_and_serial_number
   EOS

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

自己コンパイルによるインストールの場合:

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

   production:
     ldap:
       servers:
         main:
           # snip...
           # Enable smart card authentication against the LDAP server. Valid values
           # are "false", "optional", and "required".
           smartcard_auth: optional
   
           # If your LDAP server is Active Directory, you can configure these two fields.
           # Specify which field contains certificate information, 'altSecurityIdentities' by default
           smartcard_ad_cert_field: altSecurityIdentities
   
           # Specify format of certificate information. Valid values are:
           # principal_name, rfc822_name, issuer_and_subject, subject, issuer_and_serial_number
           smartcard_ad_cert_format: issuer_and_serial_number

2. ファイルを保存して、変更を有効にするためにGitLabを再起動してください。

Gitアクセスにスマートカードサインインによるブラウザセッションを必須にする

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

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

   gitlab_rails['smartcard_required_for_git_access'] = true

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

自己コンパイルによるインストールの場合:

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

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

2. ファイルを保存して、変更を有効にするためにGitLabを再起動してください。

スマートカード認証を介して作成されたユーザーのパスワード

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