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) 내의 사용자 ID(email)를 정의해야 합니다.
• URI는 Gitlab.config.host.gitlab과 일치해야 합니다.
• 인증서에 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을 따르는 표준 인증서 매칭 방식을 구현합니다. userCertificate 속성에 대해 certificateExactMatch 인증서 매칭 규칙을 사용합니다. 사전 요구 사항으로, 다음 조건을 충족하는 LDAP 서버를 사용해야 합니다.

• certificateExactMatch 매칭 규칙을 지원합니다.
• 인증서가 userCertificate 속성에 저장되어 있습니다.

Active Directory LDAP 서버에 대한 인증#

히스토리

• GitLab 16.9에서 도입되었습니다.
• GitLab 17.11에서 reverse_issuer_and_subject 및 reverse_issuer_and_serial_number 형식이 추가되었습니다.
• GitLab 18.6에서 smartcard_ad_formats_v2라는 기능 플래그와 함께 issuer_and_subject, reverse_issuer_and_subject, subject 형식이 갱신되었습니다. 기본적으로 활성화되어 있습니다. 이 형식을 이전 버전으로 되돌리려면 이 플래그를 비활성화합니다.
• GitLab 18.9에서 일반 공급되었습니다. 기능 플래그 smartcard_ad_formats_v2가 제거되었습니다.

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의 경우 부분은 최하위 바이트가 먼저 오는 역바이트 순서입니다. 자세한 내용은 altSecurityIdentities 속성으로 사용자를 인증서에 매핑하는 방법을 참고합니다.

역방향 발급자 형식은 발급자 문자열을 가장 작은 단위부터 가장 큰 단위 순으로 정렬합니다. 일부 Active Directory 서버는 인증서를 이 형식으로 저장합니다.

Entra ID 도메인 서비스에 대한 인증#

이전에 Azure Active Directory로 불렸던 Microsoft Entra ID는 기업과 조직을 위한 클라우드 기반 디렉터리를 제공합니다. 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를 편집합니다.

   # 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
   

   [!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을 편집합니다.

   ## 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
   

   [!note] 다음 변수 중 최소 하나에는 값을 지정합니다. client_certificate_required_host 또는 client_certificate_required_port.

3. 파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 시작합니다.

추가 보안 권장 사항#

보안을 강화하려면 CloudFlare WAF 같은 방화벽이나 ModSecurity를 실행하는 서버 뒤에 GitLab을 배포합니다. 다음 패턴과 일치하는 URL은 GitLab의 일부로 배포된 NGINX에서는 접근할 수 있어야 하지만 외부 클라이언트에서는 접근할 수 없어야 합니다.

/-/smartcard/extract_certificate
/-/smartcard/verify_certificate

이 경로는 NGINX에 할당된 스마트 카드 호스트 이름과 포트로만 외부에서 접근할 수 있어야 하고, GitLab의 기본 호스트 이름과 포트로는 외부에서 접근할 수 없어야 합니다. 이렇게 하면 HTTP Host 헤더 공격에 견딜 수 있어, 사용자가 NGINX를 거치지 않고 자신의 인증서 파라미터를 제출할 수 없습니다.

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 이 스마트 카드 인증으로 생성된 사용자의 비밀번호를 어떻게 생성하고 설정하는지 개괄적으로 설명합니다.