Skip to main content

LDAP 사용

LDAP(Lightweight Directory Access Protocol)를 사용하여 애플리케이션 간 액세스를 중앙 집중화하는 경우 인스턴스에 대한 LDAP 인증을 구성하여 GitHub Enterprise Server를 통합할 수 있습니다.

GitHub Enterprise Server에 대한 LDAP 인증 정보

LDAP는 디렉터리 정보 서비스의 액세스와 유지 관리를 위한 많이 사용되는 애플리케이션 프로토콜이며 타사 소프트웨어를 대기업 사용자 디렉터리와 통합하는 데 사용되는 가장 일반적인 프로토콜 중 하나입니다. 자세한 내용은 Wikipedia의 “Lightweight Directory Access Protocol”을 참조하세요.

중앙 집중식 인증에 LDAP 디렉터리를 사용하는 경우 GitHub Enterprise Server 인스턴스를 사용하는 사용자에 대해 LDAP 인증을 구성할 수 있습니다.

참고: SAML 또는 LDAP를 사용할 수 있지만, 둘 다 사용할 수는 없습니다.

외부 인증 공급자에 계정이 없는 일부 사용자에 대해 인증을 허용하려면 GitHub Enterprise Server 인스턴스의 로컬 계정에 대한 대체 인증을 허용할 수 있습니다. 자세한 내용은 "공급자 외부 사용자에게 기본 제공 인증 허용"을 참조하세요.

지원되는 LDAP 서비스

GitHub Enterprise Server는 다음 LDAP 서비스와 통합됩니다.

  • Active Directory
  • FreeIPA
  • Oracle Directory Server Enterprise Edition
  • OpenLDAP
  • Open Directory
  • 389-ds

LDAP를 사용하는 사용자 이름 고려 사항

GitHub Enterprise Server에서는 외부 인증 공급자 값을 정규화하여 GitHub Enterprise Server 인스턴스에서 각 새 개인 계정의 사용자 이름을 확인합니다. 자세한 내용은 "외부 인증에 대한 사용자 이름 고려 사항"을(를) 참조하세요.

GitHub Enterprise Server 인스턴스를 사용하여 LDAP 구성

LDAP를 구성한 후 사용자는 LDAP 자격 증명을 사용하여 인스턴스에 로그인할 수 있습니다. 사용자가 처음으로 로그인하면 해당 프로필 이름, 메일 주소 및 SSH 키가 디렉터리의 LDAP 특성으로 설정됩니다.

관리 콘솔을 통해 사용자에 대한 LDAP 액세스를 구성하는 경우 사용자가 인스턴스에 처음 로그인할 때까지 사용자 라이선스가 사용되지 않습니다. 그러나 사이트 관리자 설정을 사용하여 계정을 수동으로 만들면 사용자 라이선스는 즉시 고려됩니다.

경고: GitHub Enterprise Server 인스턴스에서 LDAP를 구성하기 전에 LDAP 서비스가 페이징된 결과를 지원하는지 확인합니다.

  1. 페이지의 오른쪽 상단에 있는 GitHub Enterprise Server의 관리 계정에서 을 클릭합니다.
  2. “Site admin”(사이트 관리자) 페이지에 아직 없는 경우 왼쪽 상단에서 Site admin(사이트 관리자)을 클릭합니다.
  3. " 사이트 관리자" 사이드바에서 관리 콘솔 을 클릭합니다.
  4. "설정" 사이드바에서 인증을 클릭합니다.
  5. “인증” 아래에서 LDAP를 선택합니다.
  6. 필요에 따라 외부 인증 시스템에 계정이 없는 사용자가 기본 제공 인증으로 로그인할 수 있도록 하려면 기본 제공 인증 허용을 선택합니다. 자세한 내용은 "공급자 외부 사용자에게 기본 제공 인증 허용"을 참조하세요.
  7. 구성 설정을 추가합니다.

LDAP 특성

해당 특성을 사용하여 GitHub Enterprise Server 인스턴스에 대한 LDAP 구성을 완료합니다.

Attribute nameRequired설명
HostLDAP 호스트로, 예를 들면 ldap.example.com 또는 10.0.0.30입니다. 내부 네트워크에서만 호스트 이름을 사용할 수 있는 경우 내부 이름 서버를 사용하여 호스트 이름을 확인할 수 있도록 GitHub Enterprise Server 인스턴스의 DNS를 먼저 구성해야 할 수 있습니다.
Port호스트의 LDAP 서비스가 수신 대기하는 포트입니다. 389 및 636(LDAPS의 경우)을 예로 들 수 있습니다.
EncryptionLDAP 서버에 대한 통신을 보호하는 데 사용되는 암호화 방법입니다. 예를 들어 일반(암호화 없음), SSL/LDAPS(처음부터 암호화됨), StartTLS(연결되면 암호화된 통신으로 업그레이드)가 있습니다.
Domain search user인증을 허용하기 위해 로그인하는 다른 사용자를 조회하는 LDAP 사용자입니다. 일반적으로 타사 통합을 위해 특별히 만들어진 서비스 계정입니다. cn=Administrator,cn=Users,dc=Example,dc=com 같은 정규화된 이름을 사용합니다. Active Directory를 사용하면 Active Directory를 사용하는 도메인 검색 사용자에 대한 [DOMAIN]\[USERNAME] 구문(예: WINDOWS\Administrator)을 사용할 수도 있습니다.
Domain search password도메인 검색 사용자의 암호입니다.
Administrators group이 그룹의 사용자는 어플라이언스에 로그인할 때 사이트 관리자로 승격됩니다. LDAP 관리자 그룹을 구성하지 않으면 어플라이언스에 로그인하는 첫 번째 LDAP 사용자 계정이 자동으로 사이트 관리자로 승격됩니다.
Domain base사용자 및 그룹을 검색하려는 LDAP 하위 트리의 정규화된 Distinguished Name(DN)입니다. 각 그룹은 해당 그룹에 속한 사용자와 동일한 도메인 기반에서 정의되어야 합니다. 제한된 사용자 그룹을 지정하는 경우 해당 그룹에 속한 사용자만 범위에 포함됩니다. LDAP 디렉터리 트리의 최상위 수준을 도메인 기반으로 지정하고 제한된 사용자 그룹을 사용하여 액세스를 제어하는 것이 좋습니다. 여러 도메인 기반을 구성할 수 있습니다. 그러나 GitHub Enterprise Server는 구성된 각 도메인 기반에 대해 순차적으로 사용자 및 그룹 구성원을 검색하므로 여러 도메인 기반을 구성하면 수행되는 LDAP 쿼리 수가 늘어날 수 있습니다. 인스턴스의 성능과 안정성을 보장하려면 도메인 기반을 3개 이하로 구성하는 것이 좋습니다.
Restricted user groups지정된 경우 해당 그룹의 사용자만 로그인할 수 있습니다. 그룹의 CN(일반 이름)만 지정하면 됩니다. 그룹을 지정하지 않으면 지정된 도메인 기반 범위 내의 모든 사용자가 GitHub Enterprise Server 인스턴스에 로그인할 수 있습니다. 제한된 여러 사용자 그룹을 구성할 수 있습니다. 그러나 각 그룹은 각 사용자에 대해 GitHub Enterprise Server가 수행하는 그룹 구성원 LDAP 쿼리 수를 늘립니다. 인증 시간 제한을 방지하고 성능 이슈를 동기화하려면 그룹을 3개 이하로 구성하는 것이 좋습니다.
User ID인증을 시도하는 LDAP 사용자를 식별하는 LDAP 특성입니다. 매핑이 설정되면 사용자는 GitHub Enterprise Server 사용자 이름을 변경할 수 있습니다. 이 필드는 대부분의 Active Directory 설치에 대해 sAMAccountName이어야 하지만 OpenLDAP 같은 다른 LDAP 솔루션에 대해서는 uid일 수 있습니다. 기본값은 uid입니다.
Profile name사용자의 GitHub Enterprise Server 프로필 페이지에 표시되는 이름입니다. LDAP 동기화를 사용하도록 설정하지 않으면 사용자는 프로필 이름을 변경할 수 있습니다.
Emails사용자 GitHub Enterprise Server 계정의 메일 주소입니다.
SSH keys사용자 GitHub Enterprise Server 계정에 연결된 퍼블릭 SSH 키입니다. 키는 OpenSSH 형식이어야 합니다.
GPG keys사용자 GitHub Enterprise Server 계정에 연결된 GPG 키입니다.
Disable LDAP authentication for Git operations이 옵션을 선택하면 LDAP 암호를 사용하여 Git 작업을 인증하는 사용자의 기능이 꺼집니다.
Enable LDAP certificate verification이 옵션을 선택하면 LDAP 인증서 확인이 켜집니다.
Synchronization이 옵션을 선택하면 LDAP 동기화가 켜집니다.

Git 작업에 암호 인증 사용 안 함

Git 액세스 시 personal access token 또는 SSH 키를 사용하도록 하여 LDAP 인증 요청으로 인한 서버 오버로드를 방지하려면, Git 작업에 암호 인증을 사용하지 않도록 설정하면 됩니다.

특히 폴링으로 인한 많은 수의 요청과 느린 응답 LDAP 서버가 결합되면 성능 문제 및 중단을 빈번하게 일으키므로 이 설정을 사용하는 것이 좋습니다.

Git 작업에 암호 인증을 사용하지 않도록 설정하려면 LDAP 설정에서 Git 작업에 사용자 이름 및 암호 인증 사용 안 함을 선택합니다.

이 옵션을 선택할 경우 사용자가 명령줄을 통해 Git 작업에 암호를 사용하려고 하면 Password authentication is not allowed for Git operations. You must use a personal access token.이라는 오류 메시지가 표시됩니다.

LDAP 인증서 확인 사용

LDAP 인증서 검증을 사용하도록 설정해 TLS로 사용하는 LDAP 서버 인증서의 유효성을 검사할 수 있습니다.

LDAP 인증서 검증을 사용하도록 설정하려면 LDAP 설정에서 LDAP 인증서 검증 사용을 선택합니다.

이 옵션을 선택하면 다음을 확인하도록 인증서의 유효성이 검사됩니다.

  • 인증서에 SAN(주체 대체 이름)이 하나 이상 포함된 경우 SAN 중 하나가 LDAP 호스트 이름과 일치합니다. 그렇지 않으면 CN(일반 이름)이 LDAP 호스트 이름과 일치합니다.
  • 인증서가 만료되지 않았습니다.
  • 신뢰할 수 있는 CA(인증 기관)이 인증서에 서명합니다.

LDAP 동기화 사용

설정된 LDAP 그룹에 대해 GitHub Enterprise Server 사용자 및 팀 구성원 자격을 동기화하여 LDAP 서버에서 사용자에 대한 역할 기반 액세스 제어를 설정할 수 있습니다. 자세한 내용은 "팀 만들기"을(를) 참조하세요.

LDAP 동기화는 GitHub Enterprise Server 인스턴스에 사용자 계정을 만들지 않습니다. 자세한 내용은 "LDAP 사용자 보기 및 만들기”를 참조하세요.

참고: 1499명을 초과하는 그룹으로 LDAP 동기화를 사용하면 팀 구성원 자격 동기화 실패가 발생할 수 있습니다.

특히 Active Directory를 사용하는 경우, 팀 또는 관리 콘솔에 구성된 LDAP 그룹의 구성원이 1500명을 초과하면 Active Directory의 MaxValRange 제한으로 인해 사용자 조회 및 팀 동기화가 실패할 수 있습니다. 해결 방법으로 1,500명 미만의 구성원을 포함하는 Active Directory 그룹을 사용하거나 Active Directory 관리자와 협력하여 도메인 컨트롤러의 MaxValRange 값을 늘릴 수 있습니다. 자세한 내용은 Microsoft Learn의 Ntdsutil.exe를 사용하여 Active Directory에서 LDAP 정책 보기 및 설정을 참조하세요.

MaxValRange를 수정하는 것이 Active Directory 환경에 적합한 방법인지 판단하는 데 도움이 필요한 경우 Microsoft 지원에 문의하세요.

LDAP 동기화를 사용하도록 설정하려면 LDAP 설정에서 동기화를 선택합니다.

모든 사용자와 모든 팀에 대한 동기화 간격을 선택하려면 드롭다운 메뉴를 클릭합니다. 그런 다음 1시간마다, 4시간마다 또는 24시간마다를 선택합니다.

LDAP의 특정 특성을 자동으로 동기화하려면 "사용자 이메일, SSH 및 GPG 키 동기화"에서 이메일 동기화, SSH 키 동기화 및/또는 GPG 키 동기화를 클릭합니다.

LDAP 동기화를 사용하도록 설정하면 지정된 시간 간격으로 동기화 작업이 실행되어 각 사용자 계정에 대해 다음 작업이 수행됩니다.

  • ID 공급 기업 외부의 사용자에 대해 기본 제공 인증을 허용했고 사용자가 기본 제공 인증을 사용하는 경우 다음 사용자로 이동합니다.
  • 사용자에 대한 LDAP 매핑이 없는 경우 사용자를 디렉터리의 LDAP 항목에 매핑해 봅니다. 사용자를 LDAP 항목에 매핑할 수 없는 경우 사용자를 일시 중단하고 다음 사용자로 이동합니다.
  • LDAP 매핑이 있고 디렉터리에 해당 LDAP 항목이 없는 경우 사용자를 일시 중단하고 다음 사용자로 이동합니다.
  • 해당 LDAP 항목이 비활성화된 것으로 표시되고 사용자가 아직 일시 중단되지 않은 경우 사용자를 일시 중단하고 다음 사용자로 이동합니다.
  • 해당 LDAP 항목이 사용 안 함으로 표시되어 있지 않고 사용자가 일시 중단되었으며 관리 센터에서 _일시 중단된 사용자 재활성화_를 사용 설정한 경우 사용자의 일시 중단을 해제합니다.
  • 하나 이상의 제한된 사용자 그룹이 인스턴스에 구성되어 있고 해당 LDAP 항목이 해당 그룹 중 하나에 없는 경우 사용자를 일시 중단합니다.
  • 하나 이상의 제한된 사용자 그룹이 인스턴스에 구성되어 있고 해당 LDAP 항목이 해당 그룹 중 하나에 있으며 관리 센터에서 _일시 중단된 사용자 재활성화_를 사용 설정한 경우 사용자의 일시 중단을 해제합니다.
  • 해당 LDAP 항목에 name 특성이 포함된 경우 사용자의 프로필 이름을 업데이트합니다.
  • 해당 LDAP 항목이 관리자 그룹에 있는 경우 사용자를 사이트 관리자로 승격합니다.
  • 해당 LDAP 항목이 관리자 그룹에 없는 경우 계정이 일시 중단되지 않은 한 사용자를 일반 계정으로 강등합니다. 일시 중단된 관리자는 강등되지 않으며 "사이트 관리자" 및 "엔터프라이즈 소유자" 페이지에 계속 나열됩니다.
  • 메일에 대해 LDAP 사용자 필드가 정의된 경우 사용자의 메일 설정을 LDAP 항목과 동기화합니다. 첫 번째 LDAP mail 항목을 기본 메일로 설정합니다.
  • 퍼블릭 SSH 키에 대해 LDAP 사용자 필드가 정의된 경우 사용자의 퍼블릭 SSH 키를 LDAP 항목과 동기화합니다.
  • GPG 키에 대해 LDAP 사용자 필드가 정의된 경우 사용자의 GPG 키를 LDAP 항목과 동기화합니다.

참고: LDAP 항목은 Active Directory를 사용하고 userAccountControl 특성이 존재하며 ACCOUNTDISABLE가 지정된 경우에만 비활성화된 것으로 표시할 수 있습니다. AD LDS 및 ADAM과 같은 일부 Active Directory 변형은 userAccountControl 특성을 지원하지 않습니다.

또한 동기화 작업은 LDAP 그룹에 매핑된 각 팀에서 다음 작업을 수행하도록 지정된 시간 간격으로 실행됩니다.

  • 팀의 해당 LDAP 그룹이 제거된 경우 팀에서 모든 구성원을 제거합니다.

  • LDAP 구성원 항목이 LDAP 그룹에서 제거된 경우 팀에서 해당 사용자를 제거합니다. 사용자가 더 이상 조직의 팀의 구성원이 아니고 조직의 소유자가 아닌 경우 조직에서 사용자를 제거합니다. 결과적으로 사용자가 리포지토리에 액세스할 수 없게 되면 해당 리포지토리의 프라이빗 포크를 삭제합니다.

    참고: 사용자가 해당 조직의 소유자인 경우 LDAP 동기화로 조직에서 사용자가 제거되지 않습니다. 다른 조직 소유자가 대신 사용자를 수동으로 제거해야 합니다.

  • LDAP 구성원 항목이 LDAP 그룹에 추가된 경우 해당 사용자를 팀에 추가합니다. 결과적으로 사용자가 리포지토리에 대한 액세스 권한을 다시 얻은 경우 사용자가 지난 90일 동안 액세스 권한을 잃었기 때문에 삭제된 리포지토리의 프라이빗 포크를 복원합니다.

최적화 구성의 일부로 LDAP 동기화는 중첩 팀 구조를 전송하지 않습니다. 하위 및 상위 팀 관계를 만들려면 중첩 팀 구조를 수동으로 다시 만들고 해당 LDAP 그룹과 동기화해야 합니다. 자세한 내용은 "팀 만들기"을 참조하세요.

보안 경고:

LDAP 동기화를 사용 설정하면 사이트 관리자와 조직 소유자는 LDAP 디렉터리에서 팀을 매핑할 그룹을 검색할 수 있습니다.

이렇게 하면 다음을 포함하여 계약자 또는 기타 권한 없는 사용자에게 중요한 조직 정보를 공개할 수 있습니다.

  • _도메인 검색 사용자_에게 표시되는 특정 LDAP 그룹의 존재.
  • GitHub Enterprise Server 사용자 계정이 있는 LDAP 그룹의 구성원. 해당 LDAP 그룹과 동기화된 팀을 만들 때 공개됩니다.

이러한 정보 공개를 원하지 않는 경우 회사 또는 조직은 관리자 콘솔에서 구성된 _도메인 검색 사용자_의 권한을 제한해야 합니다. 이와 같은 제한이 불가능한 경우 GitHub Enterprise 지원을(를) 방문하여 문의하세요.

지원되는 LDAP 그룹 개체 클래스

GitHub Enterprise Server는 다음과 같은 LDAP 그룹 개체 클래스를 지원합니다. 그룹은 중첩할 수 있습니다.

  • group
  • groupOfNames
  • groupOfUniqueNames
  • posixGroup

LDAP 사용자 보기 및 만들기

LDAP를 사용하는 경우 누군가가 LDAP 자격 증명을 사용하여 성공적으로 로그인할 때 인스턴스가 사용자 계정을 만듭니다. 또는 사용자 계정을 수동으로 프로비전할 수 있습니다.

인스턴스에 대한 액세스 권한이 있는 LDAP 사용자의 전체 목록을 보고 새 사용자를 프로비저닝할 수 있습니다.

  1. http(s)://HOSTNAME/login에서 GitHub Enterprise Server 인스턴스에 로그인합니다.
  2. 페이지의 오른쪽 상단에 있는 GitHub Enterprise Server의 관리 계정에서 을 클릭합니다.
  3. “Site admin”(사이트 관리자) 페이지에 아직 없는 경우 왼쪽 상단에서 Site admin(사이트 관리자)을 클릭합니다.
  4. 왼쪽 사이드바에서 LDAP 사용자를 클릭합니다.
  5. 사용자를 검색하려면 사용자 이름 전체 또는 일부를 입력하고 검색을 클릭합니다. 기존 사용자가 검색 결과에 표시됩니다. 사용자가 없는 경우 만들기를 클릭하여 새 사용자 계정을 프로비저닝합니다.

LDAP 계정 업데이트

LDAP 동기화를 사용 설정하지 않으면 LDAP 계정에 대한 변경 내용이 GitHub Enterprise Server와 자동으로 동기화되지 않습니다.

LDAP 계정 수동 동기화

  1. http(s)://HOSTNAME/login에서 GitHub Enterprise Server 인스턴스에 로그인합니다.
  2. 페이지의 오른쪽 상단에 있는 GitHub Enterprise Server의 관리 계정에서 을 클릭합니다.
  3. “Site admin”(사이트 관리자) 페이지에 아직 없는 경우 왼쪽 상단에서 Site admin(사이트 관리자)을 클릭합니다.
  4. "사용자, 조직, 팀, 리포지토리, gist, 애플리케이션 검색"의 텍스트 필드에 사용자의 이름을 입력합니다.
  5. 텍스트 필드 오른쪽에 있는 검색을 클릭합니다. "사이트 관리자" 설정의 "검색" 페이지 스크린샷. "검색"이라는 레이블이 지정된 사용자 검색 단추가 주황색 윤곽선으로 표시되어 있습니다.
    • 정확히 일치하는 계정 이름을 찾을 수 없는 경우 "검색 결과 – 계정"의 "유사 항목 일치" 섹션에서 관리하려는 사용자의 이름을 클릭합니다. "사이트 관리자" 설정의 검색 결과 스크린샷. "유사 항목 일치" 섹션에서 사용자 이름 예시가 주황색 윤곽선으로 표시되어 있습니다.
  6. 사이트 관리자 페이지에서 사용자 세부 정보를 검토하여 올바른 사용자를 식별했는지 확인합니다. 사이트 관리자 계정 개요 페이지의 스크린샷.
  7. 페이지의 오른쪽 위 모서리에서 관리자를 클릭합니다. 사용자나 리포지토리에 대한 "사이트 관리자" 페이지의 머리글 스크린샷. "관리자" 탭이 주황색 윤곽선으로 강조되어 있습니다.
  8. “LDAP”에서 지금 동기화를 클릭하여 LDAP 서버의 데이터로 계정을 수동 업데이트합니다.

API를 사용하여 수동 동기화를 트리거할 수도 있습니다.

GitHub Enterprise Server 인스턴스에 대한 액세스 취소

LDAP 동기화를 사용 설정할 경우 다음 동기화 실행 후 사용자의 LDAP 자격 증명을 제거하면 해당 계정이 일시 중단됩니다.

LDAP 동기화를 사용 설정하지 않은 경우 LDAP 자격 증명을 제거한 후 GitHub Enterprise Server 계정을 수동으로 일시 중단해야 합니다. 자세한 내용은 "사용자 일시 중단 및 일시 중단 취소"을(를) 참조하세요.

LDAP 로깅 정보

LDAP에 대한 로그 이벤트는 GitHub Enterprise Server 인스턴스의 systemd 저널 로그에 표시됩니다. LDAP 작업과 관련한 이벤트는 github-unicorngithub-resqued에 대한 로그에서 확인할 수 있습니다. 자세한 내용은 "시스템 로그 정보"을(를) 참조하세요.

GitHub Enterprise Server에 대한 LDAP 제한 사항

GitHub Enterprise Server LDAP 인증 시간 제한 설정은 10초입니다. 즉, GitHub Enterprise Server에 로그인하는 LDAP 사용자의 경우 사용자 인증 및 그룹 구성원 쿼리(관리 콘솔에서 관리자 및 제한된 사용자 그룹이 구성된 경우)에 필요한 모든 LDAP 쿼리는 10초 이내에 성공적으로 완료되어야 합니다. GitHub Enterprise Server는 어플라이언스의 다른 서비스에 부정적인 영향을 미칠 수 있으며 성능 저하 또는 예기치 않은 중단으로 이어질 수 있기 때문에 현재 이 10초 LDAP 인증 시간 제한을 연장하는 것을 지원하지 않습니다. 인증 시간 제한 초과를 방지하려면 GitHub Enterprise Server와 LDAP 서버 간의 네트워크 대기 시간을 제한하는 것이 좋습니다.