GitLab과 Kerberos 통합하기

Tier: Free, Premium, Ultimate Offering: Self-Managed

GitLab은 인증 메커니즘으로 Kerberos를 통합할 수 있습니다.

  • GitLab을 구성하여 사용자가 Kerberos 자격 증명으로 로그인할 수 있습니다.
  • Kerberos를 사용하여 전송된 암호를 가로채거나 도청하는 것을 방지할 수 있습니다.

Kerberos는 GitLab Enterprise Edition (EE)를 사용하는 인스턴스에서만 사용할 수 있습니다. Kerberos를 사용하려면 다음 중 하나를 수행할 수 있습니다:

  • 인스턴스에 대해 GitLab EE를 활성화합니다.
  • Linux 패키지를 사용하여 GitLab Community Edition (CE) 인스턴스를 설정한 경우 CE에서 EE로 변환합니다.

경고: Kerberos가 활성화된 GitLab 인스턴스에서는 Kerberos 토큰 인증 없이 GitLab CI/CD가 작동하지 않습니다. 일반 포트를 사용하도록 통합되어야 합니다. (#http-git-access-with-kerberos-token-passwordless-authentication).

구성

GitLab이 Kerberos 토큰 기반 인증을 제공하려면 다음 사전 작업을 수행합니다. 여전히 Kerberos 설정, 예를 들어 realm 지정과 같은 시스템을 구성해야 합니다. GitLab은 시스템의 Kerberos 설정을 사용합니다.

GitLab keytab

  1. GitLab 서버의 HTTP 서비스를 위한 Kerberos 서비스 주체를 생성합니다. GitLab 서버가 gitlab.example.com이고 Kerberos realm이 EXAMPLE.COM이면 Kerberos 데이터베이스에서 HTTP/gitlab.example.com@EXAMPLE.COM 서비스 주체를 생성합니다.
  2. 위 서비스 주체에 대한 GitLab 서버의 keytab을 생성합니다. 예를 들어, /etc/http.keytab입니다.

keytab은 민감한 파일이며 GitLab 사용자가 읽을 수 있어야 합니다. 파일 소유권 및 보호를 적절히 설정합니다: 

sudo chown git /etc/http.keytab
sudo chmod 0600 /etc/http.keytab

GitLab 구성

자체 컴파일 설치

참고: 자체 컴파일 설치의 경우 kerberos 젬 그룹이 설치되었는지 확인합니다.

  1. gitlab.yml의 kerberos 섹션을 편집하여 Kerberos 티켓 기반 인증을 활성화합니다. 대부분의 경우 Kerberos를 활성화하고 keytab의 위치를 지정하기만 하면 됩니다: 

    omniauth:
  enabled: true
  allow_single_sign_on: ['kerberos']

kerberos:
  # Allow the HTTP Negotiate authentication method for Git clients
  enabled: true

  # Kerberos 5 keytab file. The keytab file must be readable by the GitLab user,
  # and should be different from other keytabs in the system.
  # (default: use default keytab from Krb5 config)
  keytab: /etc/http.keytab

  2. 변경 사항이 적용되려면 GitLab을 재시작합니다.

Linux 패키지 설치

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

    gitlab_rails['omniauth_allow_single_sign_on'] = ['kerberos']

gitlab_rails['kerberos_enabled'] = true
gitlab_rails['kerberos_keytab'] = "/etc/http.keytab"

    Kerberos를 통해 첫 번째 로그인 시 GitLab에서 사용자를 자동으로 생성하는 것을 피하려면 gitlab_rails['omniauth_allow_single_sign_on']에 kerberos를 설정하지 마세요.

  2. 변경 사항이 적용되려면 GitLab을 재구성합니다.

이제 GitLab은 Kerberos 토큰으로 로그인하고 HTTP Git 액세스를 위해 negotiate 인증 방법을 제공하여 이 인증 프로토콜을 지원하는 Git 클라이언트를 통해 인증할 수 있습니다.

단일 로그인 활성화

공통 설정을 구성하여 kerberos를 단일 로그인 제공자로 추가합니다. 이로써 기존의 GitLab 계정이 없는 사용자를 위해 실시간 계정 프로비저닝이 가능해집니다.

Kerberos 계정 생성 및 연결

Kerberos 계정을 기존의 GitLab 계정에 연결하거나, Kerberos 사용자가 로그인을 시도할 때 GitLab에서 새 계정을 생성하도록 설정할 수 있습니다.

기존의 GitLab 계정에 Kerberos 계정 연결

관리자인 경우 Kerberos 계정을 기존의 GitLab 계정에 연결할 수 있습니다. 다음과 같이 진행합니다:

  1. 왼쪽 사이드바에서 맨 아래 관리 영역을 선택합니다.
  2. 개요 > 사용자를 선택합니다.
  3. 사용자를 선택한 다음 아이덴티티 탭을 선택합니다.
  4. 제공자 드롭다운 목록에서 Kerberos를 선택합니다.
  5. 식별자가 Kerberos 사용자명과 일치하는지 확인합니다.
  6. 변경 사항 저장을 선택합니다.

관리자가 아닌 경우:

  1. 왼쪽 사이드바에서 사용자 아바타를 선택합니다.
  2. 프로필 편집을 선택합니다.
  3. 왼쪽 사이드바에서 계정을 선택합니다.
  4. 서비스 로그인 섹션에서 Kerberos 연결을 선택합니다. 서비스 로그인에서 Kerberos 옵션이 표시되지 않으면 단일 로그인 활성화 요구 사항을 따릅니다.

어느 경우든, 이제 Kerberos 자격 증명으로 GitLab 계정에 로그인할 수 있어야 합니다.

첫 번째 로그인 시 계정 생성

GitLab에서 사용자가 Kerberos 계정으로 처음으로 로그인할 때, GitLab은 해당 계정을 생성합니다. 계속하기 전에, 공통 구성 설정 옵션을 Omnibus 및 GitLab 소스에서 검토하세요. 또한 kerberos를 포함해야 합니다.

그 정보가 있으면:

  1. allow_single_sign_on 설정과 함께 'kerberos'를 포함하세요.
  2. 현재는 기본 block_auto_created_users 옵션인 true를 수락하세요.
  3. 사용자가 Kerberos 자격 증명으로 로그인하려고 시도하면, GitLab은 새 계정을 생성합니다.

    1. 만약 block_auto_created_users가 true이면, Kerberos 사용자는 다음과 같은 메시지를 볼 수 있습니다: 

      계정이 차단되었습니다. 이것이 오류라고 생각되면 GitLab 관리자에게 문의하세요.
      1. 관리자로서 새로운 차단된 계정을 확인할 수 있습니다:
        1. 왼쪽 사이드바에서 맨 아래쪽에서 관리 영역(Admin Area)을 선택합니다.
        2. 왼쪽 사이드바에서 개요 > 사용자를 선택하고 차단됨(Blocked) 탭을 검토합니다.
      2. 사용자를 활성화할 수 있습니다.

    2. 만약 block_auto_created_users가 false이면, Kerberos 사용자가 인증되어 GitLab에 로그인됩니다.

경고: block_auto_created_users를 기본값으로 유지하는 것을 권장합니다. 관리자의 지식 없이 GitLab에 계정을 생성하는 Kerberos 사용자는 보안 위험을 초래할 수 있습니다.

Kerberos 및 LDAP 계정 연결

사용자가 Kerberos로 로그인하지만 동시에 LDAP 통합이 활성화된 경우, 사용자는 첫 로그인 시 LDAP 계정에 연결됩니다. 이를 위해 일부 전제 조건을 충족해야합니다:

Kerberos 사용자 이름은 LDAP 사용자의 UID와 일치해야합니다. GitLab LDAP 구성에서 어떤 LDAP 속성이 UID로 사용되는지 선택할 수 있지만, Active Directory의 경우 sAMAccountName이어야 합니다.

Kerberos 영역은 LDAP 사용자의 Distinguished Name(DN)의 도메인 부분과 일치해야합니다. 예를 들어, Kerberos 영역이 AD.EXAMPLE.COM이라면, LDAP 사용자의 Distinguished Name은 dc=ad,dc=example,dc=com로 끝나야 합니다.

이러한 규칙을 종합하면, 사용자의 Kerberos 사용자 이름이 foo@AD.EXAMPLE.COM 형식이어야하고, 그들의 LDAP Distinguished Name은 sAMAccountName=foo,dc=ad,dc=example,dc=com과 같이 보여야 연결이 작동합니다.

사용자 정의 허용된 영역

GitLab 13.5에 도입되었습니다.

사용자의 Kerberos 영역이 사용자의 LDAP DN에서 도메인과 일치하지 않는 경우 사용자의 기대 도메인을 구성할 수 있습니다. 구성 값은 사용자가 가질 수 있는 모든 도메인을 지정해야 합니다. 다른 도메인은 무시되며 LDAP 식별이 연결되지 않습니다.

Linux 패키지(Omnibus)

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

    gitlab_rails['kerberos_simple_ldap_linking_allowed_realms'] = ['example.com','kerberos.example.com']

  2. 변경 사항이 적용되려면 파일을 저장하고 GitLab을 다시 구성하세요.

직접 설치 (소스)

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

    kerberos:
  simple_ldap_linking_allowed_realms: ['example.com','kerberos.example.com']

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

HTTP Git 액세스

연결된 Kerberos 계정을 통해 Kerberos 계정 및 표준 GitLab 자격 증명을 사용하여 git pull 및 git push할 수 있습니다.

연결된 Kerberos 계정을 사용하는 GitLab 사용자는 Kerberos 토큰을 사용하여 git pull 및 git push할 수 있습니다. 다시 말해서, 각 작업마다 비밀번호를 보내지 않아도 됩니다.

경고: http.postBuffer 구성보다 큰 푸시를 할 때 libcurl 버전 7.64.1 이전의 알려진 문제가 있으므로 연결을 재사용하지 않습니다. 이를 피하려면 Git이 적어도 libcurl 7.64.1을 사용하고 있는지 확인하세요. 설치된 libcurl 버전을 확인하려면 curl-config --version을 실행하세요.

Kerberos 토큰을 사용한 HTTP Git 액세스 (비밀번호 없는 인증)

현재의 Git 버전에 버그 때문에, git CLI 명령은 HTTP 서버가 제공하는 경우 negotiate 인증 방법만 사용하며, 이 방법이 실패해도 (예: 클라이언트에 Kerberos 토큰이 없는 경우) 후속적으로 내장된 사용자 이름과 비밀번호(basic로도 알려짐)를 사용하는 것으로는 돌아갈 수 없습니다.

현재의 Git 버전에서 GitLab 사용자가 basic 또는 negotiate 인증을 사용할 수 있도록 하려면, 표준 포트는 basic 인증만 제공하고 Kerberos 티켓을 기반으로 다른 포트(예: 8443)에서 인증을 제공할 수 있습니다.

참고: Git 2.4 및 이후에서 사용자 이름과 암호가 대화식으로 또는 자격 증명 관리자를 통해 전달되면 basic 인증으로 되돌아가도록 지원하지만, URL의 일부로 사용자 이름과 암호가 전달될 때 이 기능이 실패합니다. 예를 들어, 이것은 CI/CD 작업 토큰으로 인증하는 GitLab CI/CD 작업에서 발생할 수 있습니다.

Linux 패키지(Omnibus)

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

    gitlab_rails['kerberos_use_dedicated_port'] = true
gitlab_rails['kerberos_port'] = 8443
gitlab_rails['kerberos_https'] = true

  2. 변경 사항이 적용되려면 GitLab을 다시 구성하세요.

직접 설치 (소스) with HTTPS

  1. GitLab의 NGINX 구성 파일을 편집하세요 (예: /etc/nginx/sites-available/gitlab-ssl) 및 NGINX를 구성하여 표준 HTTPS 포트에 추가로 포트 8443을 수신하도록 설정하세요: 

    server {
  listen 0.0.0.0:443 ssl;
  listen [::]:443 ipv6only=on ssl default_server;
  listen 0.0.0.0:8443 ssl;
  listen [::]:8443 ipv6only=on ssl;

  2. gitlab.yml의 kerberos 섹션을 업데이트하세요: 

    kerberos:
  # Dedicated port: Git before 2.4 does not fall back to Basic authentication if Negotiate fails.
  # To support both Basic and Negotiate methods with older versions of Git, configure
  # nginx to proxy GitLab on an extra port (for example: 8443) and uncomment the following lines
  # to dedicate this port to Kerberos authentication. (default: false)
  use_dedicated_port: true
  port: 8443
  https: true

  3. 변경 사항이 적용되려면 GitLab과 NGINX를 다시 시작하세요.

이 변경 후, Git 원격 URL은 https://gitlab.example.com:8443/mygroup/myproject.git로 업데이트해야 Kerberos 티켓 기반 인증을 사용할 수 있습니다.

비밀번호 기반에서 티켓 기반 Kerberos 로그인으로 업그레이드

이전 GitLab 버전에서 사용자는 로그인할 때 Kerberos 사용자 이름과 암호를 GitLab에 제출해야 했습니다.

우리는 GitLab 14.3에서 비밀번호 기반 Kerberos 로그인을 폐기했으며 GitLab 15.0에서는 삭제했습니다. 티켓 기반 로그인으로 전환해야 합니다.

기존의 GitLab 구성에 따라 로그인으로 이동: Kerberos가 이미 GitLab 로그인 페이지에 표시될 수 있습니다. 그렇지 않은 경우 위에서 설명된 설정을 추가하세요.

비밀번호 기반 Kerberos 로그인을 비활성화하려면 gitlab.yml/gitlab.rb 파일에서 OmniAuth 제공자 kerberos를 제거하세요.

Linux 패키지 (Omnibus)

  1. /etc/gitlab/gitlab.rb 파일을 편집하고 gitlab_rails['omniauth_providers'] 아래의 { "name" => "kerberos" } 줄을 제거하세요. 

    gitlab_rails['omniauth_providers'] = [
  { "name" => "kerberos" } # <-- 이 항목을 제거하세요
]

  2. 변경 내용이 적용되려면 GitLab을 다시 구성하세요.

자체 컴파일 (소스)

  1. gitlab.yml 파일을 편집하고 OmniAuth 제공자 아래의 - { name: 'kerberos' } 줄을 제거하세요. 

    omniauth:
  # 나머지 구성은 생략
  # ...
  providers:
    - { name: 'kerberos' }  # <-- 이 줄을 제거하세요

  2. 변경 내용이 적용되려면 GitLab을 다시 시작하세요.

참고: kerberos OmniAuth 제공자를 제거하면 HTTPS를 통해 복제하려고 할 때 드문 Krb5Auth::Krb5::Exception (No credentials cache found) 오류 (GitLab의 500 오류)가 해결될 수 있습니다.

Active Directory Kerberos 환경 지원

Active Directory 도메인에서 Kerberos 티켓 기반 인증을 사용할 때, NGINX에서 허용된 최대 헤더 크기를 늘릴 필요가 있을 수 있습니다. Kerberos 프로토콜의 확장으로 인해 HTTP 인증 헤더가 기본 크기인 8 kB보다 큰 경우입니다. NGINX 구성에서 large_client_header_buffers를 더 큰 값으로 구성하세요.

Windows AD에서 Advanced Encryption Standard(AES)만 사용하여 생성된 Keytab 사용

고급 암호화 기준(AES)으로 생성된 keytab을 사용할 때는 AD 서버에서 해당 계정에 대해 This account supports Kerberos AES <128/256> bit encryption 확인란을 선택해야 합니다. 확인란이 128비트인지 256비트인지는 keytab을 생성할 때 사용한 암호화 강도에 따라 달라집니다. 이를 확인하려면 Active Directory 서버에서 다음을 수행하세요:

  1. Users and Groups 도구를 엽니다.
  2. Keytab을 만들 때 사용한 계정을 찾습니다.
  3. 계정을 마우스 오른쪽 버튼으로 클릭하고 속성을 선택합니다.
  4. 계정 탭의 Account Options에서 적절한 AES 암호화 지원 확인란을 선택합니다.
  5. 저장한 후 닫습니다.

문제 해결

Windows AD에서 Google Chrome과 함께 Kerberos 인증 사용

Google Chrome에서 Kerberos를 사용하여 GitLab에 로그인하려면 전체 사용자 이름을 입력해어합니다. 예를 들어 username@domain.com입니다.

전체 사용자 이름을 입력하지 않으면 로그인이 실패합니다. 이 로그인 실패의 증거로 로그를 확인하여 다음 이벤트 메시지를 확인할 수 있습니다: 

"message":"OmniauthKerberosController: failed to process Negotiate/Kerberos authentication: gss_accept_sec_context did not return GSS_S_COMPLETE: An unsupported mechanism was requested\nUnknown error"`.

GitLab과 Kerberos 서버 간 연결 테스트

GitLab 서버와 Kerberos 서버 간의 연결을 테스트하려면 kinit 및 klist와 같은 유틸리티를 사용할 수 있습니다. 이를 설치하는 방법은 해당 OS에 따라 다릅니다.

사용 가능한 서비스 주체 이름(SP) 및 각 SPN에 대한 암호화 유형을 볼 수 있도록 klist를 사용하세요: 

klist -ke /etc/http.keytab

Ubuntu 서버에서는 다음과 유사한 출력이 표시됩니다. 

Keytab name: FILE:/etc/http.keytab
KVNO Principal
---- --------------------------------------------------------------------------
   3 HTTP/my.gitlab.domain@MY.REALM (des-cbc-crc)
   3 HTTP/my.gitlab.domain@MY.REALM (des-cbc-md5)
   3 HTTP/my.gitlab.domain@MY.REALM (arcfour-hmac)
   3 HTTP/my.gitlab.domain@MY.REALM (aes256-cts-hmac-sha1-96)
   3 HTTP/my.gitlab.domain@MY.REALM (aes128-cts-hmac-sha1-96)

kinit을 상세 모드로 사용하여 GitLab이 keytab 파일을 사용하여 Kerberos 서버에 연결할 수 있는지 테스트하세요: 

KRB5_TRACE=/dev/stdout kinit -kt /etc/http.keytab HTTP/my.gitlab.domain@MY.REALM

이 명령은 인증 프로세스의 상세한 출력을 보여줍니다.

지원되지 않는 GSSAPI 메커니즘

Kerberos SPNEGO 인증을 사용할 때, 브라우저는 GitLab으로 지원하는 메커니즘 목록을 보내야 합니다. 지원되는 메커니즘 중 하나도 지원하지 않는 경우, 로그에 다음과 같은 메시지와 함께 인증이 실패합니다: 

OmniauthKerberosController: failed to process Negotiate/Kerberos authentication: gss_accept_sec_context did not return GSS_S_COMPLETE: An unsupported mechanism was requested Unknown error

이 오류 메시지에 대한 잠재적인 원인과 해결책이 있습니다.

전용 포트를 사용하지 않는 Kerberos 통합

Kerberos가 활성화된 GitLab 인스턴스에서 GitLab CI/CD는 전용 포트를 사용하지 않는 한 작동하지 않습니다.

클라이언트 기계와 Kerberos 서버 사이의 연결 부재

일반적으로 브라우저가 직접적으로 Kerberos 서버에 연락을 취할 수 없는 경우 발생합니다. 그렇게 되면 IAKERB라고 하는 지원되지 않는 매커니즘을 사용하려고 하며, GitLab 서버를 Kerberos 서버에 대리로 사용하려고 합니다.

이 오류를 경험 중이라면, 클라이언트 기계와 Kerberos 서버 사이에 연결이 있는지 확인하세요. 이는 선행 조건입니다! 트래픽이 방화벽에 의해 차단될 수도 있고, DNS 레코드가 올바르지 않을 수도 있습니다.

GitLab DNS 레코드는 CNAME 레코드 오류

GitLab이 CNAME 레코드로 참조될 때 Kerberos는 이 오류와 함께 실패합니다. 이 문제를 해결하려면 GitLab의 DNS 레코드가 A 레코드임을 확인하세요.

GitLab 인스턴스 호스트명의 순방향 및 역방향 DNS 레코드 불일치

순방향 및 역방향 DNS 레코드가 일치하지 않을 때 다른 실패 모드가 발생합니다. 종종, 윈도우 클라이언트는 이 경우에 작동하지만 리눅스 클라이언트는 실패합니다. 그들은 역방향 DNS를 사용하여 Kerberos 영역을 감지합니다. 영역이 잘못되면 일반적인 Kerberos 메커니즘이 실패하므로 클라이언트가 IAKERB를 시도하게 되어 위의 오류 메시지로 이어집니다.

이를 해결하려면 GitLab 서버의 순방향 및 역방향 DNS가 일치하는지 확인하세요. 따라서 예를 들어, gitlab.example.com로 GitLab에 액세스한다면, IP 주소 10.0.2.2로 해석되어야 하며, 2.2.0.10.in-addr.arpa는 gitlab.example.com에 대한 PTR 레코드여야 합니다.

브라우저 또는 클라이언트 기계에서 누락된 Kerberos 라이브러리

마지막으로, 브라우저나 클라이언트 기계에 Kerberos 지원이 전혀 없을 수 있습니다. Kerberos 라이브러리가 설치되어 있는지 확인하고, 다른 Kerberos 서비스에 인증할 수 있는지 확인하세요.

HTTP 기본: 복제 시 액세스 거부 

remote: HTTP Basic: Access denied
fatal: Authentication failed for '<KRB5 path>'

본인이 Git v2.11 이상을 사용하고 복제 시 위의 오류 메시지를 보는 경우, 다음을 수행하여 이를 해결할 수 있습니다: 

git config --global http.emptyAuth true

자세한 내용은 다음을 참조하세요: Git v2.11 릴리스 노트

유용한 링크