智能卡认证

GitLab 支持使用智能卡进行认证。

现有密码认证

默认情况下，当启用智能卡认证时，现有用户仍可以继续使用用户名和密码登录。

要强制现有用户仅使用智能卡认证，请禁用用户名和密码认证。

认证方法

GitLab 支持两种认证方法：

• 结合本地数据库的 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

使用带有 SAN 扩展的 X.509 证书与本地数据库进行认证

使用 SAN 扩展的 X.509 证书的智能卡可用于向 GitLab 进行身份认证。

要使用带有 X.509 证书的智能卡与 GitLab 的本地数据库进行认证：

• 至少一个 subjectAltName (SAN) 扩展必须在 GitLab 实例 (URI) 中定义用户身份 (email)。
• URI 必须与 Gitlab.config.host.gitlab 匹配。
• 如果您的证书只包含一个 SAN email 条目，则无需添加或修改它来使 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 - 指定从证书中收集的信息的格式。此格式必须是以下值之一。最常见的是 issuer_and_serial_number，以匹配非 Active Directory LDAP 服务器的行为。

对于 issuer_and_serial_number，<SR> 部分是反向字节序，最低有效字节在前。更多信息，请参阅如何使用 altSecurityIdentities 属性将用户映射到证书。

反向颁发者格式将颁发者字符串从最小单位到最大单位排序。一些 Active Directory 服务器以这种格式存储证书。

与 Entra ID Domain Services 进行认证

Microsoft Entra ID（前身为 Azure Active Directory）为公司及组织提供基于云的目录服务。Entra Domain Services 为该目录提供一个安全的只读 LDAP 接口，但仅公开 Entra ID 所拥有字段的有限子集。

Entra ID 使用 CertificateUserIds 字段来管理用户的客户端证书，但该字段在 LDAP / Entra ID Domain Services 中不可见。在纯云环境中，GitLab 无法通过 LDAP 认证用户的智能卡。

在混合本地和云环境中，实体通过 Entra Connect 在本地 Active Directory 控制器和云端的 Entra ID 之间同步。如果您使用 Entra ID Connect 将 altSecurityIdentities 属性同步到 Entra ID 中的 certificateUserIds，则可以在 LDAP / Entra ID Domain Services 中公开此数据，以便 GitLab 可以对其进行认证：

1. 向 Entra ID Connect 添加一条规则，以将 altSecurityIdentities 同步到 Entra ID 中的一个附加属性。
2. 将该额外属性启用为 Entra ID Domain Services 中的扩展属性。
3. 在 GitLab 中配置 smartcard_ad_cert_field 字段以使用此扩展属性。

为智能卡认证配置 GitLab

对于 Linux 包安装：

1. 编辑 /etc/gitlab/gitlab.rb：

   # 启用智能卡认证
   gitlab_rails['smartcard_enabled'] = true
   
   # 包含 CA 证书的文件路径
   gitlab_rails['smartcard_ca_file'] = "/etc/ssl/certs/CA.pem"
   
   # Web 服务器 (NGINX/Apache) 请求客户端证书的主机和端口
   gitlab_rails['smartcard_client_certificate_required_host'] = "smartcard.example.com"
   gitlab_rails['smartcard_client_certificate_required_port'] = 3444

   必须为以下至少一个变量赋值： gitlab_rails['smartcard_client_certificate_required_host'] 或 gitlab_rails['smartcard_client_certificate_required_port']。

2. 保存文件并重新配置 GitLab 以使更改生效。

对于自编译安装：

1. 配置 NGINX 以请求客户端证书

   在 NGINX 配置中，必须定义一个额外的 server 上下文，其配置相同，但有以下例外：

   • 额外的 NGINX server 上下文必须配置为在不同的端口上运行：

     listen *:3444 ssl;

   • 它也可以配置为在不同的主机名上运行：

     listen smartcard.example.com:443 ssl;

   • 额外的 NGINX server 上下文必须配置为需要客户端证书：

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

   • 额外的 NGINX server 上下文必须配置为转发客户端证书：

     proxy_set_header    X-SSL-Client-Certificate    $ssl_client_escaped_cert;

   例如，以下是 NGINX 配置文件（如 /etc/nginx/sites-available/gitlab-ssl）中的 server 上下文示例：

   server {
       listen smartcard.example.com:3443 ssl;
   
       # 用于配置 SSL 的证书
       ssl_certificate /path/to/example.com.crt;
       ssl_certificate_key /path/to/example.com.key;
   
       ssl_verify_depth 2;
       # 用于客户端证书验证的 CA 证书
       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:
     # 启用智能卡认证
     enabled: true
   
     # 包含 CA 证书的文件路径
     ca_file: '/etc/ssl/certs/CA.pem'
   
     # Web 服务器 (NGINX/Apache) 请求客户端证书的主机和端口
     client_certificate_required_host: smartcard.example.com
     client_certificate_required_port: 3443

   必须为以下至少一个变量赋值： 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. 将 san_extensions 行添加到 config/gitlab.yml 的智能卡部分内：

   smartcard:
      enabled: true
      ca_file: '/etc/ssl/certs/CA.pem'
      client_certificate_required_port: 3444
   
      # 启用 SAN 扩展以将用户与证书匹配
      san_extensions: true

2. 保存文件并重启 GitLab 以使更改生效。

与 LDAP 服务器进行认证时的额外步骤

对于 Linux 包安装：

1. 编辑 /etc/gitlab/gitlab.rb：

   gitlab_rails['ldap_servers'] = YAML.load <<-EOS
   main:
     # snip...
     # 启用针对 LDAP 服务器的智能卡认证。有效值为 "false"、"optional" 和 "required"。
     smartcard_auth: optional
   
     # 如果您的 LDAP 服务器是 Active Directory，则可以配置这两个字段。
     # 指定哪个字段包含证书信息，默认为 'altSecurityIdentities'
     smartcard_ad_cert_field: altSecurityIdentities
   
     # 指定证书信息的格式。有效值为：
     # 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...
           # 启用针对 LDAP 服务器的智能卡认证。有效值为 "false"、"optional" 和 "required"。
           smartcard_auth: optional
   
           # 如果您的 LDAP 服务器是 Active Directory，则可以配置这两个字段。
           # 指定哪个字段包含证书信息，默认为 'altSecurityIdentities'
           smartcard_ad_cert_field: altSecurityIdentities
   
           # 指定证书信息的格式。有效值为：
           # 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：

   ## 智能卡认证设置
   smartcard:
     # snip...
     # Git 访问需要使用智能卡登录的浏览器会话
     required_for_git_access: true

2. 保存文件并重启 GitLab 以使更改生效。

通过智能卡认证创建的用户的密码

通过集成认证创建的用户的生成密码指南概述了 GitLab 如何为通过智能卡认证创建的用户生成和设置密码。