스마트 카드 인증

Tier: Premium, Ultimate Offering: Self-Managed

GitLab은 스마트 카드를 사용한 인증을 지원합니다.

기존 비밀번호 인증

기본적으로 기존 사용자는 스마트 카드 인증이 활성화된 경우에도 사용자 이름과 비밀번호로 계속해서 로그인할 수 있습니다.

기존 사용자에게 스마트 카드 인증만 사용하도록 강제하려면, 사용자 이름 및 비밀번호 인증을 비활성화하십시오.

인증 방법

GitLab은 두 가지 인증 방법을 지원합니다:

로컬 데이터베이스와 X.509 인증서
LDAP 서버

X.509 인증서를 사용한 로컬 데이터베이스와의 인증

Status: Experiment

X.509 인증서와 함께 스마트 카드를 사용하여 GitLab에 인증할 수 있습니다.

로컬 데이터베이스와 GitLab을 통해 X.509 인증서를 사용하여 스마트 카드를 사용하여 인증하려면, 인증서에 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 인증서 인증

Status: Experiment

SAN 확장을 사용하는 X.509 인증서와 스마트 카드를 사용하여 GitLab에 인증할 수 있습니다.

로컬 데이터베이스와 GitLab을 통해 X.509 인증서를 사용하여 스마트 카드를 사용하여 인증하려면:

최소한 하나 이상의 subjectAltName (SAN) 확장이 GitLab 인스턴스 내에서 사용자 식별(email)을 정의해야 합니다 (URI).
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 서버를 대상으로 한 인증

Status: Experiment

GitLab은 RFC4523을 따르는 인증서 일치의 표준 방법을 구현합니다. 이는 certificateExactMatch 인증서 일치 규칙을 userCertificate 속성에 대해 사용합니다. 필수 전제 조건으로 다음을 만족해야 합니다:

certificateExactMatch 일치 규칙을 지원해야 합니다.
userCertificate 속성에 인증서가 저장되어 있어야 합니다.

Active Directory LDAP 서버를 대상으로 한 인증

GitLab 16.9에서 도입.

Active Directory는 certificateExactMatch 규칙이나 userCertificate 속성을 지원하지 않습니다. 스마트 카드를 사용한 인증과 같은 대부분의 인증서 기반 도구는 각 사용자에 대해 여러 인증서를 포함할 수 있는 altSecurityIdentities 속성을 사용합니다. 이 필드의 데이터는 Microsoft가 권장하는 형식 중 하나와 일치해야 합니다.

GitLab이 확인하는 필드와 인증서 데이터의 형식을 사용자 정의하기 위해 다음 속성을 사용하십시오:

smartcard_ad_cert_field - 검색할 필드의 이름을 지정합니다. 이는 사용자 객체 내의 어떤 속성이든 될 수 있습니다.
smartcard_ad_cert_format - 인증서에서 수집된 정보의 형식을 지정합니다. 이 형식은 다음 값 중 하나여야 합니다. 가장 일반적인 형식은 비-Active Directory LDAP 서버의 동작과 일치하는 issuer_and_serial_number입니다.

`smartcard_ad_cert_format`	예시 데이터
`principal_name`	`X509:<PN>alice@example.com`
`rfc822_name`	`X509:<RFC822>bob@example.com`
`issuer_and_subject`	`X509:<I>DC=com,DC=example,CN=EXAMPLE-DC-CA<S>DC=com,DC=example,OU=UserAccounts,CN=cynthia`
`subject`	`X509:<S>DC=com,DC=example,OU=UserAccounts,CN=dennis`
`issuer_and_serial_number`	`X509:<I>DC=com,DC=example,CN=CONTOSO-DC-CA<SR>1181914561`

issuer_and_serial_number의 경우, <SR> 부분은 역바이트 순서로, 가장 낮은 유효 바이트부터 시작해야 합니다. 자세한 내용은 Microsoft의 altSecurityIdentities 형식 문서를 참조하십시오.

참고: 만약 smartcard_ad_cert_format를 지정하지 않았지만 LDAP 서버가 active_directory: true로 구성되어 있고 스마트 카드가 활성화되어 있다면, GitLab은 기본적으로 16.8 이전의 동작을 따르고, userCertificate 속성에서 certificateExactMatch를 사용합니다.

Entra ID 도메인 서비스를 대상으로 한 인증

GitLab 16.9에서 도입.

Microsoft Entra ID(구 Azure Active Directory)는 기업 및 조직을 위한 클라우드 기반 디렉터리를 제공합니다. Entra 도메인 서비스는 디렉터리에 대한 안전한 읽기 전용 LDAP 인터페이스를 제공하지만 Entra ID에 가용한 필드의 한정된 하위 집합만 노출시킵니다.

Entra ID는 클라이언트 인증서를 사용자 관리하기 위해 CertificateUserIds 필드를 사용하지만, 이 필드는 LDAP/Entra ID 도메인 서비스에서 노출되지 않습니다. 클라우드 전용 설정에서는 LDAP을 통해 GitLab이 사용자의 스마트 카드를 인증할 수 없습니다.

혼합 온프레미스 및 클라우드 환경에서 온프레미스 Active Directory 컨트롤러와 클라우드 Entra ID 간에 엔터티가 Entra Connect를 이용하여 동기화됩니다. 만약 Entra ID Connect를 사용하여 altSecurityIdentities 속성을 certificateUserIds로 동기화하는 경우, 여러분은 LDAP/Entra ID 도메인 서비스에서 이 데이터를 노출시켜 GitLab에서 인증할 수 있도록 구성할 수 있습니다:

Entra ID Connect에 규칙을 추가하여 altSecurityIdentities를 Entra ID의 추가 속성으로 동기화하십시오.
Entra ID 도메인 서비스에서 확장 속성으로 추가 속성을 활성화하십시오.
GitLab의 smartcard_ad_cert_field를 사용하여 이 추가 속성을 구성하십시오.

스마트 카드 인증을 위한 GitLab 구성

Linux 패키지 설치의 경우:

/etc/gitlab/gitlab.rb 파일을 편집합니다:

# 스마트 카드 인증 허용
gitlab_rails['smartcard_enabled'] = true

# CA 인증서를 포함하는 파일의 경로
gitlab_rails['smartcard_ca_file'] = "/etc/ssl/certs/CA.pem"

# 웹서버(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'].

파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성합니다.

자체 컴파일 설치의 경우:

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;

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

config/gitlab.yml 파일을 편집합니다:

## 스마트 카드 인증 설정
smartcard:
  # 스마트 카드 인증 허용
  enabled: true

  # CA 인증서를 포함하는 파일의 경로
  ca_file: '/etc/ssl/certs/CA.pem'

  # 웹서버(NGINX/Apache)에서 클라이언트 측 인증서를 요청하는 호스트 및 포트
  client_certificate_required_host: smartcard.example.com
  client_certificate_required_port: 3443

참고: 다음 변수 중 하나에 값을 할당합니다: client_certificate_required_host 또는 client_certificate_required_port.

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

SAN 확장을 사용하는 경우 추가 단계

Linux 패키지 설치의 경우:

/etc/gitlab/gitlab.rb에 다음을 추가합니다:

gitlab_rails['smartcard_san_extensions'] = true

파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성합니다.

자체 컴파일 설치의 경우:

스마트 카드 섹션 내부의 config/gitlab.yml에 san_extensions 라인을 추가합니다:

smartcard:
   enabled: true
   ca_file: '/etc/ssl/certs/CA.pem'
   client_certificate_required_port: 3444

   # SAN 확장을 사용하여 인증서와 사용자를 매치할 수 있도록 활성화
   san_extensions: true

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

LDAP 서버에 대한 인증 추가 단계

Linux 패키지 설치의 경우:

/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

파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성합니다.

자체 컴파일 설치의 경우:

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

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

Git 액세스에 스마트 카드 로그인이 필요한 브라우저 세션 필요

Linux 패키지 설치를 위해:

/etc/gitlab/gitlab.rb 파일을 편집하세요:

gitlab_rails['smartcard_required_for_git_access'] = true

파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성하세요.

자체 컴파일된 설치를 위해:

config/gitlab.yml 파일을 편집하세요:

## 스마트 카드 인증 설정
smartcard:
  # snip...
  # 브라우저 세션에서 스마트 카드 로그인이 Git 액세스에 필요합니다
  required_for_git_access: true

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

스마트 카드 인증으로 생성된 사용자의 비밀번호

통합 인증을 통해 생성된 사용자의 생성된 비밀번호 가이드에서는 GitLab이 스마트 카드 인증을 통해 생성된 사용자의 비밀번호를 생성하고 설정하는 개요를 제공합니다.

스마트 카드 인증

기존 비밀번호 인증

인증 방법

X.509 인증서를 사용한 로컬 데이터베이스와의 인증

SAN 확장을 사용한 로컬 데이터베이스와의 X.509 인증서 인증

LDAP 서버를 대상으로 한 인증

Active Directory LDAP 서버를 대상으로 한 인증

Entra ID 도메인 서비스를 대상으로 한 인증

스마트 카드 인증을 위한 GitLab 구성

SAN 확장을 사용하는 경우 추가 단계

LDAP 서버에 대한 인증 추가 단계

Git 액세스에 스마트 카드 로그인이 필요한 브라우저 세션 필요

스마트 카드 인증으로 생성된 사용자의 비밀번호

도움말

기능 사용 가능성과 제품 평가판

도움받기