GitLab과 Kerberos 통합

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

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

  • 사용자가 Kerberos 자격 증명으로 로그인할 수 있도록 GitLab을 구성할 수 있습니다.
  • 전달된 비밀번호를 가로채거나 도청하는 사람을 방지하기 위해 Kerberos를 사용할 수 있습니다.(방지)

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

caution
GitLab CI/CD는 Kerberos를 사용하는 GitLab 인스턴스에서 전용 포트를 사용하도록 설정하지 않으면 작동하지 않습니다.

구성

GitLab에서 Kerberos 토큰 기반 인증을 제공하려면 다음 사전 준비 작업을 수행하세요. 여전히 Kerberos 사용을 위해 시스템을 구성해야 하며, 예를 들어 영역을 지정해야 합니다. GitLab은 시스템의 Kerberos 설정을 사용합니다.

GitLab keytab

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

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

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

GitLab 구성

직접 컴파일한 설치

note
직접 컴파일한 설치의 경우 kerberos gem 그룹이 설치되었는지 확인하세요.

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

    omniauth:
  enabled: true
  allow_single_sign_on: ['kerberos']
   
kerberos:
  # Git 클라이언트에서 HTTP 네고시에이션 인증 방법 허용
  enabled: true
     
  # Kerberos 5 keytab 파일. keytab 파일은 GitLab 사용자가 읽을 수 있어야 하며, 시스템의 다른 keytab과는 달라야 합니다.
  # (기본값: Krb5 구성의 기본 keytab 사용)
  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 토큰으로 인증할 수 있습니다.

단일 사인온 활성화

공통 설정을 구성하여 kerberos를 단일 사인온 공급자로 추가하세요. 이렇게 하면 기존 GitLab 계정이 없는 사용자에 대해 즉시 계정 프로비저닝이 가능해집니다.

Kerberos 계정 생성 및 연결

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

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

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

  1. 왼쪽 사이드바에서 맨 아래에서 관리 영역을 선택하세요.
  2. 개요 > 사용자를 선택하세요.
  3. 사용자를 선택한 후 신원 탭을 선택하세요.
  4. 공급자 드롭다운 디렉터리에서 Kerberos를 선택하세요.
  5. 식별자가 Kerberos 사용자명과 일치하는지 확인하세요.
  6. 변경 사항 저장을 선택하세요.

관리자가 아닌 경우:

  1. 왼쪽 사이드바에서 사용자 아바타를 선택하세요.
  2. 프로필 편집을 선택하세요.
  3. 왼쪽 사이드바에서 계정을 선택하세요.
  4. 서비스 로그인 섹션에서 Kerberos 연결을 선택하세요. 만약 서비스 로그인에서 Kerberos 옵션이 보이지 않는다면 단일 사인온 활성화에 대한 요구 사항을 확인하세요.

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

최초 로그인 시 계정 생성

Kerberos 계정으로 최초로 GitLab에 로그인하는 경우 GitLab이 해당하는 계정을 만듭니다.

계속하기 전에 Omnibus 및 GitLab 소스에서 공통 구성 설정 옵션을 검토하세요. kerberos를 반드시 포함해야 합니다.

이제 다음을 수행하세요:

  1. allow_single_sign_on 설정에 'kerberos'를 포함하세요.
  2. 현재는 기본 block_auto_created_users 옵션인 true를 수용합니다.
  3. Kerberos 자격 증명으로 로그인하려는 사용자는 새 계정이 생성됩니다.

    • block_auto_created_users가 true인 경우, Kerberos 사용자는 다음과 같은 메시지를 볼 수 있습니다. 

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

    • block_auto_created_users가 false인 경우, Kerberos 사용자가 인증되어 GitLab에 로그인됩니다.

caution
block_auto_created_users의 기본값을 유지하는 것을 권장합니다. 관리자에게 알지 못하는 Kerberos 사용자가 계정을 만들면 보안 위험이 될 수 있습니다.

Kerberos와 LDAP 계정 연결

만약 사용자가 Kerberos로 로그인하지만 LDAP 통합이 활성화된 경우, 사용자는 첫 번째 로그인 시 LDAP 계정에 연결됩니다. 이 기능을 사용하려면 몇 가지 전제 조건을 충족해야 합니다:

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

Kerberos realm은 LDAP 사용자의 Distinguished Name의 도메인 부분과 일치해야 합니다. 예를 들어, Kerberos realm이 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과 같은 형식이어야 한다는 의미입니다.

사용자 정의 허용되는 realm

GitLab 13.5에서 도입됨.

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

리눅스 패키지 (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를 할 수 있습니다. 다시 말하면 각 작업마다 비밀번호를 보내지 않아도 됩니다.

caution
버전 7.64.1 이전의 libcurl에서는 연결을 재사용하지 않아 http.postBuffer 구성을 사용하여 push가 클 경우 권한 부여 문제가 발생하는 알려진 문제가 있습니다. 이를 방지하려면 최소한 libcurl 7.64.1을 사용하고 있는지 확인하십시오. 설치된 libcurl 버전을 확인하려면 curl-config --version을 실행하십시오.

Kerberos 토큰으로 HTTP Git 접근 (비밀번호 없는 인증)

현재 Git 버전의 버그로 인해 git CLI 명령은 HTTP 서버가 제공할 경우 negotiate 인증 방법만 사용하고, 이 방법이 실패하더라도(예를 들어 클라이언트에 Kerberos 토큰이 없는 경우) 후속 기본(또는 basic) 인증으로 되돌아갈 수 없습니다.

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

note
Git 2.4 이상은 사용자 이름과 암호가 대화식 또는 자격 증명 관리자를 통해 전달된 경우 basic 인증으로 되돌아가는 것을 지원합니다. 그러나 URL의 일부로 사용자 이름과 암호가 전달된 경우에는 되돌아가지 않습니다. 예를 들어, 이는 GitLab CI/CD 작업에서 CI/CD 작업 토큰으로 인증하는 경우에 발생할 수 있습니다.
리눅스 패키지 (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을 재구성합니다.

HTTPS로 소스로 직접 컴파일하는 경우

  1. GitLab의 NGINX 구성 파일(예: /etc/nginx/sites-available/gitlab-ssl)을 편집하고 표준 HTTPS 포트 외에 8443 포트에서도 NGINX가 듣도록 구성: 

    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:
  # 특별한 포트: Git 2.4 이전의 버전은 Negotiate가 실패할 때 기본 인증으로 되돌아가지 않습니다.
  # 이전 버전의 Git에서 basic 및 Negotiate 방법 모두를 지원하려면 nginx를 추가 포트(예: 8443)에
  # GitLab으로 프록시하는 방법을 구성하고 다음 줄을 주석 처리하여 이 포트를 Kerberos 인증에 전용으로 지정합니다. (기본: 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에 제출해야 했습니다.

deprecated 이후에 GitLab 14.3에서 패스워드 기반 Kerberos 로그인이 되지 않게 되었으며, GitLab 15.0에서는 제거되었습니다. 티켓 기반 로그인으로 전환해야 합니다.

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

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

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을 재시작하세요.

note
kerberos OmniAuth 제공자를 제거하면 HTTPS를 통해 클론을 시도할 때 드문 Krb5Auth::Krb5::Exception (No credentials cache found) 오류(500 오류)를 해결할 수 있습니다. ## Active Directory Kerberos 환경 지원

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

Windows AD에서 AES-만 암호화를 사용하여 작성된 Keytab 사용

Advanced Encryption Standard (AES)만 암호화를 사용하여 keytab을 만드는 경우, 해당 계정에 대해 AD 서버에서 이 계정은 Kerberos AES <128/256> bit 암호화를 지원 확인란을 선택해야 합니다. 확인란이 128비트인지 256비트인지는 keytab을 만들 때 사용한 암호화 강도에 따라 다릅니다. 이를 확인하려면 Active Directory 서버에서:

  1. 사용자 및 그룹 도구를 엽니다.
  2. 키탭을 만들 때 사용한 계정을 찾습니다.
  3. 계정을 마우스 오른쪽 단추로 클릭하고 속성을 선택합니다.
  4. 계정 탭의 계정 옵션에서 적절한 AES 암호화 지원 확인란을 선택합니다.
  5. 저장하고 닫습니다.

문제 해결

Windows AD에서 Kerberos 인증을 사용하여 Google Chrome 사용

Kerberos로 GitLab에 Google Chrome을 사용하여 로그인할 때 전체 사용자 이름을 입력해야 합니다. 예를 들어, 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에 따라 다릅니다.

klist를 사용하여 keytab 파일 내에서 사용 가능한 서비스 주체 이름(SP) 및 각 SPN의 암호화 유형을 확인하세요: 

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를 verbose 모드로 사용하여 GitLab이 keytab 파일을 사용하여 Kerberos 서버에 연결할 수 있는지 테스트하세요: 

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

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

지원되지 않는 GSSAPI 메커니즘

Kerberos SPNEGO 인증을 사용하는 경우, 브라우저가 GitLab이 지원하는 메커니즘 디렉터리을 보내야 합니다. 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 통합

GitLab CI/CD는 Kerberos가 활성화된 GitLab 인스턴스와 함께 작동하지 않습니다. 이 경우, Kerberos 통합이 전용 포트를 사용하도록 구성되어 있어야 합니다.

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

이러한 문제는 일반적으로 브라우저가 Kerberos 서버에 직접 연락할 수 없는 경우에 발생합니다. 이 경우, 지원되지 않는 메커니즘인 IAKERB를 사용하려고 하며, GitLab 서버를 Kerberos 서버로 사용하려고 시도합니다.

이러한 오류를 경험하는 경우, 클라이언트 기계와 Kerberos 서버 간에 연결이 있는지 확인해야 합니다. 이는 필수 사항입니다. 방화벽에 의해 트래픽이 차단될 수 있거나 DNS 레코드가 잘못될 수 있습니다.

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

GitLab이 CNAME 레코드로 참조될 때 Kerberos에서 이 오류가 발생합니다. 이 문제를 해결하려면 GitLab의 DNS 레코드가 A 레코드인지 확인해야 합니다.

GitLab 인스턴스 호스트 이름의 전방 및 후방 DNS 레코드 불일치

또 다른 실패 모드는 GitLab 서버의 전방 및 후방 DNS 레코드가 일치하지 않을 때 발생합니다. 이 경우 Windows 클라이언트는 작동하지만 Linux 클라이언트는 실패합니다. Linux 클라이언트는 Kerberos 영역 감지를 위해 역방향 DNS을 사용합니다. 올바른 영역을 가져오지 못하면 일반 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 이상을 사용하고 클론할 때 위의 오류가 발생하는 경우 다음을 수행하여 http.emptyAuth Git 옵션을 true로 설정할 수 있습니다. 

git config --global http.emptyAuth true

참조: Git v2.11 릴리스 노트

유용한 링크