스마트 카드 인증
GitLab은 스마트 카드를 사용한 인증을 지원합니다.
기존 패스워드 인증
기본적으로, 기존 사용자는 스마트 카드 인증이 활성화되어 있더라도 사용자 이름과 패스워드로 로그인을 계속할 수 있습니다.
기존 사용자가 스마트 카드 인증만 사용하도록 강제하려면, 사용자 이름 및 패스워드 인증을 비활성화하십시오.
인증 방법
GitLab은 두 가지 인증 방법을 지원합니다:
- 로컬 데이터베이스와 함께 X.509 인증서 사용
- LDAP 서버
X.509 인증서를 사용한 로컬 데이터베이스 인증
경고: 로컬 데이터베이스에 대한 스마트 카드 인증은 향후 릴리스에서 변경되거나 완전히 제거될 수 있습니다.
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 인증서를 사용한 로컬 데이터베이스 인증
SAN 확장을 사용하는 X.509 인증서를 사용하여 GitLab에 인증할 수 있습니다.
참고: 이것은 실험적 기능입니다. 로컬 데이터베이스에 대한 스마트 카드 인증은 향후 릴리스에서 변경되거나 완전히 제거될 수 있습니다.
로컬 데이터베이스와 함께 GitLab에서 스마트 카드와 X.509 인증서를 사용하려면,
- GitLab 12.4 이상에서는 최소한 하나의
subjectAltName(SAN) 확장이URI내에서 사용자 ID(email)를 정의해야 합니다.URI: 는Gitlab.config.host.gitlab과 일치해야 합니다. -
GitLab 12.5부터, 인증서에 하나의 SAN 이메일 항목만 포함된 경우,
URI와email을 일치시키기 위해 추가하거나 수정할 필요가 없습니다.
예:
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 인증서 매칭 규칙을 사용합니다. 사전 요구 사항으로는:
-
certificateExactMatch매칭 규칙을 지원해야 합니다. - 인증서가
userCertificate속성에 저장되어 있어야 합니다.
Active Directory LDAP 서버를 사용한 인증
Active Directory는 certificateExactMatch 규칙이나 userCertificate 속성을 지원하지 않습니다. 스마트 카드와 같은 인증에 대한 대부분의 도구는 각 사용자마다 여러 인증서를 포함할 수 있는 altSecurityIdentities 속성을 사용합니다. 이 필드의 데이터는
Microsoft에서 권장하는 형식 중 하나와 일치해야합니다.
인증서 데이터의 필드 및 형식을 사용자화하려면 다음 속성을 사용하십시오:
-
smartcard_ad_cert_field- 검색할 필드 이름을 지정합니다. 이는 사용자 개체의 어떤 속성이어도 상관없습니다. -
smartcard_ad_cert_format- 인증서로부터 수집된 정보의 형식을 지정합니다. 이 형식은 다음 값 중 하나여야 합니다. 가장 일반적인issuer_and_serial_number은 비-Active Directory LDAP 서버의 동작과 일치시키기 위한 것입니다.
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를 사용하여 Entra ID의 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이 스마트 카드 인증을 통해 생성된 사용자의 비밀번호를 생성 및 설정하는 개요를 제공합니다.
도움말