LDAP 문제 해결

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

관리자라면, LDAP 문제를 해결하기 위해 다음 정보를 사용하세요.

일반적인 문제 및 작업 흐름

연결

연결 거부됨

LDAP 서버에 연결하려고 할 때 연결 거부됨 오류 메시지가 표시되면, GitLab에서 사용하는 LDAP 포트 및 암호화 설정을 확인하세요. 일반적인 조합은 암호화: 'plain' 및 포트: 389 또는 암호화: 'simple_tls' 및 포트: 636입니다.

연결 시간 초과

GitLab이 LDAP 엔드포인트에 도달할 수 없는 경우 다음과 같은 메시지가 표시됩니다: 

Could not authenticate you from Ldapmain because "Connection timed out - user specified timeout".

구성된 LDAP 제공자 및/또는 엔드포인트가 오프라인이거나 GitLab에서 도달할 수 없는 경우, LDAP 사용자는 인증을 수행하고 로그인할 수 없습니다. GitLab은 LDAP 사용자의 인증을 제공하기 위해 자격 증명을 캐시하거나 저장하지 않습니다.

이 오류 메시지를 확인하면 LDAP 제공자나 관리자에게 문의하세요.

Referral 오류

로그에서 LDAP search error: Referral를 확인하거나 LDAP 그룹 동기화를 문제 해결할 때 이 오류가 표시되면 구성 문제를 나타낼 수 있습니다. LDAP 구성인 /etc/gitlab/gitlab.rb (Omnibus) 또는 config/gitlab.yml (소스)은 YAML 형식으로 되어 있으며 들여쓰기에 민감합니다. group_base 및 admin_group 구성 키가 서버 식별자를 기준으로 2개의 공백 만큼 들여쓰기되었는지 확인하세요. 기본 식별자는 main이며 예제 스니펫은 다음과 같습니다: 

main: # 'main' is the GitLab 'provider ID' of this LDAP server
  label: 'LDAP'
  host: 'ldap.example.com'
  ...
  group_base: 'cn=my_group,ou=groups,dc=example,dc=com'
  admin_group: 'my_admin_group'

LDAP 쿼리

Tier: Premium, Ultimate Offering: Self-managed

다음은 Rails 콘솔을 사용하여 LDAP에서 검색을 수행하는 방법을 보여줍니다. 수행하려는 작업에 따라 사용자 또는 그룹을 직접 쿼리하거나, 심지어 ldapsearch 사용하는 것이 더 의미있을 수 있습니다. 

adapter = Gitlab::Auth::Ldap::Adapter.new('ldapmain')
options = {
    # :base is required
    # .base 또는 .group_base를 사용합니다.
    base: adapter.config.group_base,
    
    # :filter is optional
    # 'cn'은 :base 아래의 모든 "cn"을 찾습니다.
    # '*'는 검색 문자열입니다. 여기서 와일드카드입니다.
    filter: Net::LDAP::Filter.eq('cn', '*'),
    
    # :attributes is optional
    # 반환받길 원하는 속성
    attributes: %w(dn cn memberuid member submember uniquemember memberof)
}
adapter.ldap_search(options)

필터에서 OID를 사용하는 경우 Net::LDAP::Filter.eq를 Net::LDAP::Filter.construct로 바꿉니다: 

adapter = Gitlab::Auth::Ldap::Adapter.new('ldapmain')
options = {
    # :base is required
    # .base 또는 .group_base를 사용합니다.
    base: adapter.config.base,
    
    # :filter is optional
    # 이 필터는 OID 1.2.840.113556.1.4.1941을 포함합니다.
    # 이는 LDAP 디렉터리에서 그룹 gitlab_grp의 직접 및 중첩 멤버를 모두 검색합니다.
    filter: Net::LDAP::Filter.construct("(memberOf:1.2.840.113556.1.4.1941:=CN=gitlab_grp,DC=example,DC=com)"),
    
    # :attributes is optional
    # 반환받길 원하는 속성
    attributes: %w(dn cn memberuid member submember uniquemember memberof)
}
adapter.ldap_search(options)

실행 방법 예제는 Adapter 모듈을 확인하세요.

사용자 로그인

사용자를 찾을 수 없음

LDAP 체크를 통해 LDAP에 연결할 수 있는 것을 확인했지만 GitLab은 출력에서 LDAP 사용자를 표시하지 않는 경우, 다음 중 하나가 아마도 사실입니다:

  • bind_dn 사용자는 사용자 트리를 탐색할 충분한 권한이 없습니다.
  • 사용자가 구성된 base에 포함되지 않습니다.
  • 구성된 user_filter가 사용자의 액세스를 차단합니다.

이 경우, /etc/gitlab/gitlab.rb에서 기존 LDAP 구성을 사용하여 ldapsearch를 사용하여 위의 내용 중 어떤 것이 사실인지 확인할 수 있습니다.

사용자가 로그인할 수 없음

사용자가 다양한 이유로 로그인에 문제를 겪을 수 있습니다. 시작하려면 다음과 같은 질문이 도움이 될 수 있습니다:

  • 사용자가 LDAP의 구성된 base에 속합니까? 사용자는 이 base에 속해야만 로그인할 수 있습니다.
  • 사용자가 구성된 user_filter를 통과합니까? 구성되지 않았다면,이 질문을 무시할 수 있습니다. 그렇지만 구성되어 있다면, 사용자는 또한 로그인할 수 있도록 이 필터를 통과해야 합니다.

위의 두 가지가 모두 괜찮다면, 문제를 찾을 수 있는 다음 장소는 문제가 발생하는 동안 로그 자체입니다.

  • 사용자에게 로그인하도록 요청하고 실패하게합니다.
  • 출력을 검토하여 로그인에 대한 오류 또는 다른 메시지를 찾습니다. 이 페이지에서 다른 오류 메시지 중 하나를 볼 수 있으며, 해당 섹션에서 문제를 해결하는 데 도움이 될 수 있습니다.

로그가 문제의 근본으로 이끌지 못하는 경우, rails console을 사용하여 이 사용자를 쿼리하여 GitLab이 LDAP 서버에서이 사용자를 읽을 수 있는지 확인할 수 있습니다.

또한 사용자 동기화를 디버깅하여 추가로 조사할 수도 있습니다.

로그인 시 잘못된 자격 증명

LDAP에서 사용한 로그인 자격 증명이 정확한 경우, 해당 사용자에 대해 다음이 사실임을 확인하십시오.

  • 바인딩할 사용자가 사용자 트리를 읽고 탐색할 충분한 권한이 있는지 확인하십시오.
  • user_filter가 그 외 유효한 사용자를 차단하고 있지 않은지 확인하십시오.
  • LDAP 체크 명령을 실행하여 LDAP 설정이 올바른지 및 GitLab에서 사용자를 볼 수 있는지 확인하십시오.

LDAP 계정에 대한 액세스 거부

Auditor level 액세스를 가진 사용자에게 영향을 미칠 수 있는 버그가 있습니다. Premium/Ultimate에서 다운그레이드하는 경우, 로그인을 시도하는 감사자 사용자는 다음 메시지가 표시됩니다: LDAP 계정에 액세스할 수 없음.

해당 사용자의 액세스 수준을 변경하는 기준을 토대로 우회 방법을 제공합니다:

  1. 왼쪽 사이드바에서 가장 아래에서 관리 영역(Admin Area)을 선택합니다.
  2. 개요 > 사용자를 선택합니다.
  3. 해당 사용자의 이름을 선택합니다.
  4. 오른쪽 상단에서 편집(EDIT)을 선택합니다.
  5. 사용자의 액세스 수준을 일반 사용자(Regular)에서 관리자(Administrator)로 변경합니다(또는 그 반대).
  6. 페이지 하단에서 변경사항 저장을 선택합니다.
  7. 오른쪽 상단에서 다시 편집(EDIT)을 선택합니다.
  8. 사용자의 원래 액세스 수준(일반 사용자 또는 관리자)을 복원하고 다시 변경사항 저장을 선택합니다.

이제 해당 사용자는 로그인할 수 있어야 합니다.

이미 사용 중인 이메일 주소

사용자가 올바른 LDAP 자격 증명으로 로그인을 시도하면 액세스가 거부되고 production.log에 다음과 같이 보이는 오류가 표시됩니다. 

(LDAP) Error saving user <USER DN> (email@example.com): ["Email has already been taken"]

이 오류는 LDAP의 이메일 주소 email@example.com을 참조합니다. 이메일 주소는 GitLab 및 LDAP의 사용자 기본 이메일에 고유해야 합니다(사용자의 여러 보조 이메일 중 하나가 아님). 다른 사용자(또는 동일 사용자)가 email@example.com 이메일을 보조 이메일로 설정했으므로 이 오류가 발생합니다.

충돌하는 이메일 주소가 어디에서 오는지 rails 콘솔을 사용하여 확인할 수 있습니다. 콘솔에서 다음을 실행하십시오. 

# 이것은 기본 및 보조 이메일 중에서 이메일을 검색합니다.
user = User.find_by_any_email('email@example.com')
user.username

이 명령은 해당 이메일 주소를 사용한 사용자를 보여줍니다. 여기서 취해야 할 두 가지 조치 중 하나를 취할 수 있습니다:

  • LDAP으로 로그인할 때 해당 사용자를 위해 새로운 GitLab 사용자/사용자 이름을 생성하여 충돌을 제거하려면 보조 이메일을 제거하십시오.
  • LDAP으로 사용할 기존 GitLab 사용자/사용자 이름을 위해 해당 이메일을 보조 이메일에서 제거하고 주 이메일로 설정하여 GitLab이 이 프로필을 LDAP 식별에 연결하도록 합니다.

사용자는 이러한 조치 중 하나를 프로필에서 수행하거나 관리자가 수행할 수 있습니다.

프로젝트 제한 오류

다음 오류는 한도 또는 제한이 활성화되었지만 연결된 데이터 필드에 데이터가 없음을 나타냅니다.

  • 프로젝트 제한을 비워둘 수 없습니다.
  • 프로젝트 제한은 숫자가 아닙니다.

이를 해결하려면 다음을 수행하십시오:

  1. 왼쪽 사이드바에서 가장 아래에서 관리 영역(Admin Area)을 선택합니다.
  2. 설정 > 일반을 선택합니다.
  3. 다음을 확장합니다:
    • 계정 및 제한(Account and limit).
    • 가입 제한(Sign-up restrictions).
  4. 예를 들어 기본 프로젝트 제한(Default projects limit) 또는 가입 허용 도메인(Allowed domains for sign-ups) 필드를 확인하고 관련 값이 구성되어 있는지 확인하십시오.

LDAP 사용자 필터 디버그

ldapsearch를 사용하여 구성된 사용자 필터를 테스트하여 예상대로 사용자를 반환하는지 확인할 수 있습니다. 

ldapsearch -H ldaps://$host:$port -D "$bind_dn" -y bind_dn_password.txt  -b "$base" "$user_filter" sAMAccountName
  • $로 시작하는 변수는 구성 파일의 LDAP 섹션에서 가져온 변수를 나타냅니다.
  • 일반 인증 방법을 사용하는 경우 ldaps://를 ldap://로 바꿉니다. 389는 기본 ldap:// 포트이며 636은 기본 ldaps:// 포트입니다.
  • bind_dn 사용자의 암호가 bind_dn_password.txt 파일에 있는 것으로 간주합니다.

모든 사용자 동기화

Tier: Premium, Ultimate Offering: Self-managed

매뉴얼 사용자 동기화 출력을 사용하여 GitLab이 LDAP 반대로 사용자를 동기화할 때 발생하는 현상을 확인할 수 있습니다. rails console에 입력한 후 다음을 실행하십시오. 

Rails.logger.level = Logger::DEBUG

LdapSyncWorker.new.perform

그 다음, 사용자 동기화 후의 출력 예제를 확인하십시오.

사용자 동기화 후 콘솔 출력 예시
Tier: Premium, Ultimate Offering: Self-managed

매뉴얼 사용자 동기화의 출력은 매우 상세하며 개별 사용자의 성공적인 동기화는 다음과 같이 표시될 수 있습니다. 

사용자 John, email@example.com 동기화 중
  Identity Load (0.9ms)  SELECT  "identities".* FROM "identities" WHERE "identities"."user_id" = 20 AND (provider LIKE 'ldap%') LIMIT 1
Gitlab::Auth::Ldap::Person의 LDIF로 인스턴스화:
dn: cn=John Smith,ou=people,dc=example,dc=com
cn: John Smith
mail: email@example.com
memberof: cn=admin_staff,ou=people,dc=example,dc=com
uid: John
  
  UserSyncedAttributesMetadata Load (0.9ms)  SELECT  "user_synced_attributes_metadata".* FROM "user_synced_attributes_metadata" WHERE "user_synced_attributes_metadata"."user_id" = 20 LIMIT 1
   (0.3ms)  BEGIN
  Namespace Load (1.0ms)  SELECT  "namespaces".* FROM "namespaces" WHERE "namespaces"."owner_id" = 20 AND "namespaces"."type" IS NULL LIMIT 1
  Route Load (0.8ms)  SELECT  "routes".* FROM "routes" WHERE "routes"."source_id" = 27 AND "routes"."source_type" = 'Namespace' LIMIT 1
  Ci::Runner Load (1.1ms)  SELECT "ci_runners".* FROM "ci_runners" INNER JOIN "ci_runner_namespaces" ON "ci_runners"."id" = "ci_runner_namespaces"."runner_id" WHERE "ci_runner_namespaces"."namespace_id" = 27
   (0.7ms)  COMMIT
   (0.4ms)  BEGIN
  Route Load (0.8ms)  SELECT "routes".* FROM "routes" WHERE (LOWER("routes"."path") = LOWER('John'))
  Namespace Load (1.0ms)  SELECT  "namespaces".* FROM "namespaces" WHERE "namespaces"."id" = 27 LIMIT 1
  Route Exists (0.9ms)  SELECT  1 AS one FROM "routes" WHERE LOWER("routes"."path") = LOWER('John') AND "routes"."id" != 50 LIMIT 1
  사용자 업데이트(1.1ms)  "users" SET "updated_at" = '2019-10-17 14:40:59.751685', "last_credential_check_at" = '2019-10-17 14:40:59.738714' WHERE "users"."id" = 20

여기에는 많은 내용이 포함되어 있으므로 디버깅 시 유용한 정보를 확인하겠습니다.

먼저, GitLab은 이전에 LDAP으로 로그인한 모든 사용자를 찾은 후 각 사용자의 동기화를 시작합니다. 각 사용자의 동기화는 사용자가 GitLab에 현재 존재하는 사용자 이름과 이메일로 시작하는 다음 줄에서 시작됩니다. 

사용자 John, email@example.com 동기화 중

특정 사용자의 GitLab 이메일을 출력에서 찾을 수 없으면, 해당 사용자는 아직 LDAP으로 로그인하지 않았습니다.

다음으로, GitLab은 구성된 LDAP 제공자와의 기존 연결을 찾기 위해 identities 테이블을 검색합니다. 

  Identity Load (0.9ms)  SELECT  "identities".* FROM "identities" WHERE "identities"."user_id" = 20 AND (provider LIKE 'ldap%') LIMIT 1

이 identity 객체에는 GitLab이 LDAP에서 사용자를 찾기 위해 사용하는 DN이 포함됩니다. DN이 발견되지 않으면 이메일이 대신 사용됩니다. 사용자가 LDAP에서 발견되므로 다음의 출력에서 볼 수 있는 것처럼 성공적으로 동기화됩니다. 

Gitlab::Auth::Ldap::Person의 LDIF로 인스턴스화:
dn: cn=John Smith,ou=people,dc=example,dc=com
cn: John Smith
mail: email@example.com
memberof: cn=admin_staff,ou=people,dc=example,dc=com
uid: John

만약 DN 또는 이메일로 LDAP에서 사용자를 찾지 못한 경우, 대신 다음 메시지를 볼 수 있습니다. 

LDAP search error: No Such Object

…이 경우, 사용자가 차단됩니다. 

  사용자 업데이트 (0.4ms) "users" SET "state" = $1, "updated_at" = $2 WHERE "users"."id" = $3  [["state", "ldap_blocked"], ["updated_at", "2019-10-18 15:46:22.902177"], ["id", 20]]

LDAP에서 사용자를 찾은 후 출력의 나머지 부분은 GitLab 데이터베이스에 변경 사항을 업데이트합니다.

LDAP에서 사용자 쿼리

이는 GitLab이 LDAP에 연결하여 특정 사용자를 읽을 수 있는지 테스트합니다. GitLab UI에서 무시되는 것처럼 보일 수 있는 LDAP 연결 및/또는 쿼리 오류를 드러낼 수 있습니다. 

Rails.logger.level = Logger::DEBUG

adapter = Gitlab::Auth::Ldap::Adapter.new('ldapmain') # `main`이 LDAP 제공자인 경우
Gitlab::Auth::Ldap::Person.find_by_uid('<uid>', adapter)

그룹 멤버십

Tier: Premium, Ultimate Offering: Self-managed

권한이 부여되지 않은 멤버십

특정 사용자가 LDAP 그룹 동기화를 통해 GitLab 그룹에 추가되어야 한다고 생각되지만 어떤 이유로 인해 그렇지 않은 경우가 있습니다. 이 상황을 디버깅하기 위해 몇 가지 확인할 사항이 있습니다.

  • LDAP 구성에 group_base가 지정되어 있는지 확인합니다. 그룹 동기화에는 이 구성이 필요합니다.
  • 올바른 LDAP 그룹 링크가 GitLab 그룹에 추가되었는지 확인합니다.
  • 사용자가 LDAP 식별자를 가지고 있는지 확인합니다:
    1. 관리자로서 GitLab에 로그인합니다.
    2. 왼쪽 사이드바에서 아래쪽으로 스크롤하여 관리자 영역을 선택합니다.
    3. 왼쪽 사이드바에서 개요 > 사용자를 선택합니다.
    4. 사용자를 검색합니다.
    5. 사용자를 선택하여 엽니다. 편집을 선택하지 마십시오.
    6. 정체 탭을 선택합니다. 여기에 식별자로 LDAP 식별자가 있어야 합니다. 그렇지 않은 경우 이 사용자는 아직 LDAP으로 로그인하지 않은 것입니다.
  • 그룹 동기화를 위해 한 시간이 지나거나 구성된 간격이 지났는지 확인합니다. 프로세스를 가속화하려면 GitLab 그룹의 관리 > 멤버로 이동하여 지금 동기화를 누르거나 그룹 동기화 Rake 작업을 실행합니다(모든 그룹 동기화).

위의 모든 사항이 좋아 보인다면, 더 고급스러운 디버깅 단계로 들어가보세요.

  1. Rails 콘솔로 이동.
  2. 테스트하려는 GitLab 그룹을 선택합니다. 해당 그룹은 이미 LDAP 그룹 링크가 구성되어 있어야 합니다.
  3. 디버그 로깅을 활성화하고 위의 GitLab 그룹을 찾아 LDAP과 동기화합니다.
  4. 동기화 출력을 확인합니다. 출력을 읽는 방법에 대한 예제 로그 출력을 참조하세요.
  5. 사용자가 추가되지 않는 이유를 여전히 확인하지 못했다면, 직접 LDAP 그룹을 쿼리하여 위의 출력에서 나열된 멤버를 확인하세요.
  6. 사용자의 DN 또는 UID가 위의 출력에서 나온 디렉터리 중에 있는지 확인하세요. 여기에 있는 DN 또는 UID 중 하나는 앞서 확인한 LDAP 식별자의 ‘식별자’와 일치해야 합니다. 그렇지 않으면 사용자는 LDAP 그룹에 없는 것으로 보입니다.

LDAP 동기화가 활성화된 경우 서비스 계정 사용자를 그룹에 추가할 수 없음

LDAP 동기화가 그룹에 대해 활성화된 경우, “초대” 대화 상자를 사용하여 새 그룹 멤버를 초대할 수 없습니다.

GitLab 16.8 이상에서 이 문제를 해결하려면, 그룹 멤버 API 엔드포인트를 사용하여 서비스 계정을 초대하고 그룹에서 제거할 수 있습니다.

관리자 권한이 부여되지 않음

관리자 동기화가 구성되었지만 구성된 사용자에게 올바른 관리자 권한이 부여되지 않은 경우, 다음 사항을 확인합니다.

  • group_base가 구성되어 있는지도 확인합니다.
  • gitlab.rb에서 구성된 admin_group이 DN이 아니라 CN이거나 배열이 아니라는 것을 확인합니다.
  • 구성된 admin_group이 구성된 group_base의 범위에 속하는지 확인합니다.
  • admin_group의 구성원이 이미 LDAP 자격 증명으로 GitLab에 로그인한 경우. GitLab은 이미 계정이 LDAP에 연결된 사용자에만 관리자 액세스를 부여합니다.

위의 모든 사항이 사실이고 사용자가 여전히 액세스를 받지 않는다면, Rails 콘솔에서 매뉴얼 그룹 동기화를 실행하고 출력을 확인하여 GitLab이 admin_group을 동기화할 때 어떤 일이 벌어지는지 확인하세요.

UI에서 동기화 지금 버튼이 멈춤

그룹의 그룹 > 멤버 페이지에 있는 동기화 지금 버튼이 멈출 수 있습니다. 버튼은 눌린 후 페이지가 다시로드되면 멈추게 되는데, 그 후 버튼을 다시 선택할 수 없게 됩니다.

동기화 지금 버튼이 멈출 수 있는 이유는 다양하며 특정 경우를 위해 디버깅이 필요합니다. 다음은 문제의 가능한 원인 및 문제에 대한 해결책 두 가지입니다.

유효하지 않은 멤버십

그룹의 일부 멤버 또는 요청 멤버가 유효하지 않은 경우 동기화 지금 버튼이 멈출 수 있습니다. 관련 이슈에서 이 문제의 가시성을 향상하는 진전 상황을 추적할 수 있습니다. 이 문제가 동기화 지금 버튼을 멈추게 하는 원인인지 확인하려면 Rails 콘솔을 사용하여 다음을 확인할 수 있습니다: 

# 해당 그룹 찾기
group = Group.find_by(name: 'my_gitlab_group')

# 그룹 스스로에 대한 오류 찾기
group.valid?
group.errors.map(&:full_messages)

# 그룹의 요청자 및 멤버 중에서 오류 찾기
group.requesters.map(&:valid?)
group.requesters.map(&:errors).map(&:full_messages)
group.members.map(&:valid?)
group.members.map(&:errors).map(&:full_messages)

표시된 오류로 문제를 확인하고 해결책을 찾을 수 있습니다. 예를 들어, 지원팀에서 다음과 같은 오류를 확인했습니다. 

irb(main):018:0> group.members.map(&:errors).map(&:full_messages)
=> [["The member's email address is not allowed for this group. Go to the group's &#39;Settings &gt; General&#39; page, and check &#39;Restrict membership by email domain&#39;."]]

이 오류는 관리자가 이메일 도메인별로 그룹 멤버십을 제한하도록 선택했지만 도메인에 오타가 있었음을 보여줍니다. 도메인 설정을 수정한 후 동기화 지금 버튼이 다시 작동했습니다.

Sidekiq 노드에서 LDAP 구성 누락

여러 노드에서 GitLab을 확장하고 LDAP 구성이 Sidekiq를 실행하는 노드의 /etc/gitlab/gitlab.rb에 누락된 경우, 지금 동기화 버튼이 멈추는 현상이 발생합니다. 이 경우 Sidekiq 작업이 사라진 것으로 보입니다.

LDAP는 로컬 LDAP 구성이 필요한 여러 작업을 비동기적으로 실행하기 때문에 Sidekiq 노드에서 필요합니다:

각 Sidekiq를 실행하는 노드에서 LDAP를 확인하는 Rake 작업을 실행하여 누락된 LDAP 구성이 문제인지 테스트할 수 있습니다. 이 노드에서 LDAP가 올바르게 설정되어 있다면 LDAP 서버에 연결되어 사용자를 반환합니다.

이 문제를 해결하려면 Sidekiq 노드에서 LDAP를 구성하세요. 구성한 후 LDAP를 확인하는 Rake 작업을 실행하여 GitLab 노드가 LDAP에 연결할 수 있는지 확인하세요.

모든 그룹 동기화

note
디버깅하는 동안 모든 그룹을 매뉴얼으로 동기화하려면, 대신 Rake 작업을 사용하세요.

매뉴얼 그룹 동기화의 출력은 GitLab이 LDAP 그룹 멤버십을 동기화할 때 발생하는 일련의 과정을 보여줍니다. rails 콘솔로 이동한 다음 다음을 실행하세요: 

Rails.logger.level = Logger::DEBUG

LdapAllGroupsSyncWorker.new.perform

다음으로 출력을 확인하는 방법을 배우세요.

그룹 동기화 후 콘솔 출력 예

사용자 동기화의 출력과 마찬가지로 매뉴얼 그룹 동기화의 출력도 매우 자세합니다. 그러나 많은 도움이 되는 정보가 포함되어 있습니다.

동기화가 실제로 시작되는 지점을 나타냅니다: 

'Sidekiq' 노드에서 'ldapmain' 공급자를 시작 중인 'my_group' 그룹의 동기화 시작

다음 항목은 GitLab이 LDAP 서버에서 본 모든 사용자 DN의 배열을 보여줍니다. 이 DN은 GitLab 그룹이 아닌 하나의 LDAP 그룹의 사용자입니다. 이 GitLab 그룹과 연결된 여러 LDAP 그룹이 있는 경우 각 LDAP 그룹마다 이와 같은 로그 항목이 표시됩니다. 이 로그 항목에 LDAP 사용자 DN이 없으면, GitLab이 조회할 때 LDAP에서 사용자를 반환하지 않는 것입니다. 이 로그 항목에 LDAP 사용자 DN이 표시되지 않는 경우 LDAP에서 사용자를 반환하지 않습니다. 사용자가 이 LDAP 그룹에 실제로 있는지 확인하세요. 

'ldap_group_1' LDAP 그룹의 구성원: ["uid=john0,ou=people,dc=example,dc=com",
"uid=mary0,ou=people,dc=example,dc=com", "uid=john1,ou=people,dc=example,dc=com",
"uid=mary1,ou=people,dc=example,dc=com", "uid=john2,ou=people,dc=example,dc=com",
"uid=mary2,ou=people,dc=example,dc=com", "uid=john3,ou=people,dc=example,dc=com",
"uid=mary3,ou=people,dc=example,dc=com", "uid=john4,ou=people,dc=example,dc=com",
"uid=mary4,ou=people,dc=example,dc=com"]

위 각 항목 이후 잠시 후에은 확인된 회원 액세스 레벨의 해시가 표시됩니다. 이 해시는 GitLab이 이 그룹에 액세스해야 하는 모든 사용자 DN과 해당 액세스 수준(역할)을 나타냅니다。 이 해시는 누적되며, 추가 LDAP 그룹 조회를 기반으로 더 많은 DN이 추가되거나 기존 항목이 수정될 수 있습니다. 이 항목의 매우 마지막 발생은 GitLab이 그룹에 추가해야 한 사용자를 정확히 나타내야 합니다.

note
10은 게스트, 20은 기고자, 30은 개발자, 40은 유지자, 50은 소유자입니다.
'my_group' 그룹 구성원 액세스 확인: {"uid=john0,ou=people,dc=example,dc=com"=>30,
"uid=mary0,ou=people,dc=example,dc=com"=>30, "uid=john1,ou=people,dc=example,dc=com"=>30,
"uid=mary1,ou=people,dc=example,dc=com"=>30, "uid=john2,ou=people,dc=example,dc=com"=>30,
"uid=mary2,ou=people,dc=example,dc=com"=>30, "uid=john3,ou=people,dc=example,dc=com"=>30,
"uid=mary3,ou=people,dc=example,dc=com"=>30, "uid=john4,ou=people,dc=example,dc=com"=>30,
"uid=mary4,ou=people,dc=example,dc=com"=>30}

다음과 같은 경고가 표시되는 것은 흔한 일입니다. 이는 GitLab이 사용자를 그룹에 추가했지만 사용자를 GitLab에서 찾을 수 없었음을 나타냅니다. 보통 이는 걱정할 필요가 없습니다.

특정 사용자가 이미 GitLab에 존재해야 하지만 이 항목을 보고 있다면, GitLab에 저장된 DN이 일치하지 않을 수 있습니다. 사용자의 LDAP 식별 정보를 업데이트하려면 사용자 DN 및 이메일이 변경됨을 참조하세요. 

DN `uid=john0,ou=people,dc=example,dc=com`를 가진 사용자는 'my_group' 그룹에 액세스해야 하지만 GitLab에 해당 IDENTITY로 사용자가 없습니다.
사용자가 처음으로 로그인할 때 멤버십이 업데이트될 것입니다.

마지막으로, 다음과 같은 항목이 나타나면 이 그룹의 동기화가 완료되었다는 것을 의미합니다: 

'my_group' 그룹 모든 공급자 동기화 완료

구성된 모든 그룹 링크가 동기화되면 GitLab은 관리자 또는 외부 사용자를 동기화하는 것을 찾습니다: 

'ldapmain' 공급자의 관리자 사용자 동기화 중

출력은 단일 그룹과 유사하게 보이며 이 항목이 전체 동기화를 의미합니다: 

'ldapmain' 공급자의 관리자 사용자 동기화 완료

관리자 동기화가 구성되지 않은 경우에는 다음과 같은 메시지가 표시됩니다: 

'ldapmain' 공급자에 대한 'admin_group' 구성이 없습니다. 건너뛰는 중

그룹 동기화

모든 그룹을 동기화하면 출력이 많이 생성되어 단일 GitLab 그룹의 멤버십에 관심이 있는 경우 주의를 산만하게 할 수 있습니다. 이 경우, 이 그룹만 동기화하고 해당 그룹의 디버그 출력을 볼 수 있습니다: 

Rails.logger.level = Logger::DEBUG

# GitLab 그룹을 찾습니다.
# 출력이 `nil`인 경우 그룹을 찾을 수 없습니다.
# 출력에 그룹 속성이 많이 있는 경우 그룹을 성공적으로 찾은 것입니다.
group = Group.find_by(name: 'my_gitlab_group')

# 이 그룹을 LDAP와 동기화합니다.
EE::Gitlab::Auth::Ldap::Sync::Group.execute_all_providers(group)

이 출력은 모든 그룹을 동기화한 후 얻는 출력과 유사합니다.

LDAP에서 그룹 쿼리

GitLab이 LDAP 그룹을 읽고 해당 멤버를 모두 볼 수 있는지 확인하려면 다음을 실행할 수 있습니다: 

# 어댑터와 그 그룹 자체를 찾습니다.
adapter = Gitlab::Auth::Ldap::Adapter.new('ldapmain') # `main`이 LDAP 제공자인 경우
ldap_group = EE::Gitlab::Auth::Ldap::Group.find_by_cn('group_cn_here', adapter)

# LDAP 그룹의 멤버 찾기
ldap_group.member_dns
ldap_group.member_uids

LDAP 동기화가 그룹 생성자를 그룹에서 제거하지 않음

LDAP 동기화는 LDAP 그룹의 생성자를 그룹에서 제거해야 하는데, 그 사용자가 그 그룹에 존재하지 않은 경우에 그렇게 해야 합니다. 만약 LDAP 동기화를 실행하여 이러한 동작을 하지 않는다면:

  1. 사용자를 LDAP 그룹에 추가합니다.
  2. LDAP 그룹 동기화 실행이 완료될 때까지 기다립니다.
  3. 사용자를 LDAP 그룹에서 제거합니다.

사용자 DN과 이메일이 변경되었습니다

만약 주 이메일 및 DN 둘 다 LDAP에서 변경되었다면, GitLab이 사용자의 올바른 LDAP 레코드를 식별할 수 없습니다. 그 결과로, GitLab은 그 사용자를 차단합니다. 그래서 GitLab이 LDAP 레코드를 찾을 수 있도록 기존 GitLab 프로필의 사용자 이메일 또는:

  • 새로운 주 이메일.
  • DN 값.

둘 중 적어도 하나를 업데이트합니다.

다음 스크립트는 이러한 사용자들의 차단을 방지하고 그들의 계정에 접근할 수 있도록 모든 제공된 사용자들의 이메일을 업데이트합니다.

note
다음 스크립트는 새로운 이메일 주소로된 계정을 먼저 제거해야만 합니다. GitLab에서 이메일 주소는 고유해야 합니다.

rails console로 이동하여 다음을 실행합니다: 

# 각 항목은 이전 사용자 이름과 새 이메일을 포함해야 합니다.
emails = {
  '기존_사용자이름' => '새_이메일_주소',
  ...
}

emails.each do |username, email|
  user = User.find_by_username(username)
  user.email = email
  user.skip_reconfirmation!
  user.save!
end

그런 다음 사용자 동기화를 실행하여 이 사용자들 각각의 최신 DN을 동기화할 수 있습니다.

“AzureActivedirectoryV2”에서 “잘못된 부여”로 인증할 수 없음

LDAP에서 SAML로 변환할 때 Azure에서 다음과 같은 오류가 발생할 수 있습니다: 

Authentication failure! invalid_credentials: OAuth2::Error, invalid_grant.

이 문제는 다음이 모두 참인 경우에 발생합니다:

  • SAML이 해당 사용자들을 위해 구성된 후에도 LDAP 식별이 존재합니다.
  • 해당 사용자들에 대해 LDAP을 비활성화합니다.

이는 Azure에서 LDAP 및 Azure 메타데이터를 로그에 수신하여 Azure에서 오류를 생성합니다.

단일 사용자의 임시 방편은 관리자 > 신원에 있는 사용자의 LDAP 식별을 제거하는 것입니다.

여러 LDAP 식별을 제거하려면 Ldapmain에서 "알 수 없는 제공자"로 인증할 수 없음 오류에 대한 해결 방법 중 하나를 사용하세요.

Ldapmain에서 "알 수 없는 제공자"로 인증할 수 없음

LDAP 서버로 인증할 때 다음과 같은 오류가 발생할 수 있습니다: 

Could not authenticate you from Ldapmain because "Unknown provider (ldapsecondary). available providers: ["ldapmain"]".

기존에 인증했던 계정이름/ID의 상태가 변경되었거나, GitLab 구성에서 삭제 또는 이름이 변경된 LDAP 서버로부터 인증하세요.

예를 들어:

  • 초기에, ldap_servers에서 main 및 secondary가 GitLab 구성에서 설정됩니다.
  • secondary 설정이 제거되거나 main으로 이름이 변경됩니다.
  • 로그인을 시도하는 사용자는 secondary에 대한 identify 레코드를 가지고 있지만, 더 이상 구성되지 않습니다.

레일 클노쟈로 가서 영향을 받는 사용자 디렉터리을 나열하고 그들이 어떤 LDAP 서버에 대한 식별이 있는지 확인합니다: 

ldap_identities = Identity.where(provider: "ldapsecondary")
ldap_identities.each do |identity|
  u=User.find_by_id(identity.user_id)
  ui=Identity.where(user_id: identity.user_id)
  puts "user: #{u.username}\n   #{u.email}\n   last activity: #{u.last_activity_on}\n   #{identity.provider} ID: #{identity.id} external: #{identity.extern_uid}"
  puts "   all identities:"
  ui.each do |alli|
    puts "    - #{alli.provider} ID: #{alli.id} external: #{alli.extern_uid}"
  end
end;nil

다음 두 가지 방법으로 이 오류를 해결할 수 있습니다.

LDAP 서버에 대한 참조를 이름 바꾸기

이 솔루션은 LDAP 서버가 서로의 복제본이고 영향을 받는 사용자들이 구성된 LDAP 서버를 사용하여 로그인할 수 있어야하는 경우에 적합합니다. 예를 들어, LDAP 고가용성을 관리하기 위해 로드 밸런서가 사용되고 별도의 보조 로그인 옵션이 더 이상 필요하지 않은 경우입니다.

note
LDAP 서버가 서로의 복제본이 아닌 경우, 이 솔루션은 영향을 받는 사용자의 로그인을 중지합니다.

더 이상 구성되지 않은 LDAP 서버에 대한 참조를 이름을 바꾸려면 다음을 실행합니다: 

sudo gitlab-rake gitlab:ldap:rename_provider[ldapsecondary,ldapmain]

제거된 LDAP 서버와 연관된 identity 레코드 제거

이 솔루션으로 영향을 받는 사용자는 구성된 LDAP 서버를 사용하여 로그인하고 GitLab에서 새로운 identity 레코드가 생성될 수 있습니다. 레일 클노쟈에서, 삭제할 ldapsecondary` 식별을 삭제합니다. 

ldap_identities = Identity.where(provider: "ldapsecondary")
ldap_identities.each do |identity|
  puts "Destroying identity: #{identity.id} #{identity.provider}: #{identity.extern_uid}"
  identity.destroy!
rescue => e
  puts 'Error generated when destroying identity:\n ' + e.to_s
end; nil

만료된 라이선스로 인한 여러 LDAP 서버 오류

여러 LDAP 서버 사용에는 유효한 라이선스가 필요합니다. 만료된 라이선스는 다음과 같은 문제를 일으킬 수 있습니다:

  • 웹 인터페이스에서 502 오류.

  • 로그에 다음과 같은 오류(실제 전략 이름은 /etc/gitlab/gitlab.rb에서 구성된 이름에 따라 다름)가 표시됩니다: 

    Could not find a strategy with name `Ldapsecondary'. Please ensure it is required or explicitly set it using the :strategy_class option. (Devise::OmniAuth::StrategyNotFound)

이 오류를 해결하려면 웹 인터페이스 없이 새 라이선스를 GitLab 인스턴스에 적용해야 합니다:

  1. 주 LDAP 서버 이외의 모든 LDAP 서버에 대한 GitLab 구성 라인을 제거하거나 주석 처리합니다.
  2. GitLab을 재구성하여 일시적으로 하나의 LDAP 서버만 사용하도록 합니다.
  3. Rails 콘솔을 열고 라이선스 키를 추가합니다.
  4. 추가 LDAP 서버를 GitLab 구성에 다시 활성화하고 GitLab을 다시 구성합니다.

사용자가 그룹에서 제거되고 다시 추가됨

사용자가 그룹 동기화 중에 추가되었다가 다음 동기화에서 제거되고 이러한 과정이 반복된 경우, 사용자가 여러 개나 중복된 LDAP 식별 정보를 가지고 있는지 확인하세요.

이러한 식별 정보 중 하나가 사용되지 않는 이전 LDAP 공급자를 위해 추가되었다면, 제거된 LDAP 서버에 관련된 identity 레코드를 제거해야 합니다.

디버깅 도구

LDAP 확인

LDAP를 확인하는 Rake 작업은 GitLab이 LDAP에 성공적으로 연결하고 사용자를 읽을 수 있는지 확인하는 데 유용한 도구입니다.

연결이 수립되지 않는 경우, 구성에 문제가 있거나 방화벽이 연결을 차단하고 있는 것일 수 있습니다.

  • 방화벽이 연결을 차단하고 있는지, 그리고 LDAP 서버가 GitLab 호스트에 접근 가능한지 확인합니다.
  • Rake 확인 출력에 오류 메시지가 있는지 확인하여 LDAP 구성 값을 확인하고 (host, port, bind_dn, password 등) 구성에 올바른 값이 있는지 확인합니다.
  • LDAP에 성공적으로 연결되지만 사용자가 반환되지 않는 경우, 사용자가 찾아지지 않는 경우를 참조하세요.

GitLab 로그

사용자 계정이 LDAP 구성으로 인해 차단되거나 차단 해제되면 메시지가 application_json.log에 기록됩니다.

LDAP 조회 중 예기치 않은 오류(구성 오류, 시간 초과)가 발생하면 로그인이 거부되고 메시지가 production.log에 기록됩니다.

ldapsearch

ldapsearch는 LDAP 서버를 쿼리할 수 있는 유틸리티입니다. LDAP 설정을 테스트하고 사용 중인 설정이 예상대로 결과를 제공하는지 확인할 수 있습니다.

ldapsearch를 사용할 때는 이미 gitlab.rb 구성에서 지정한 동일한 설정을 사용하여 정확히 그 설정을 사용했을 때 어떤 결과가 나타나는지 확인합니다.

GitLab 호스트에서 이 명령을 실행하여 GitLab 호스트와 LDAP 간에 방해가 없는지도 확인할 수 있습니다.

예를 들어, 다음과 같이 GitLab 구성을 고려해 보십시오: 

gitlab_rails['ldap_servers'] = YAML.load <<-'EOS' # remember to close this block with 'EOS' below
   main: # 'main' is the GitLab 'provider ID' of this LDAP server
     label: 'LDAP'
     host: '127.0.0.1'
     port: 389
     uid: 'uid'
     encryption: 'plain'
     bind_dn: 'cn=admin,dc=ldap-testing,dc=example,dc=com'
     password: 'Password1'
     active_directory: true
     allow_username_or_email_login: false
     block_auto_created_users: false
     base: 'dc=ldap-testing,dc=example,dc=com'
     user_filter: ''
     attributes:
       username: ['uid', 'userid', 'sAMAccountName']
       email:    ['mail', 'email', 'userPrincipalName']
       name:       'cn'
       first_name: 'givenName'
       last_name:  'sn'
     group_base: 'ou=groups,dc=ldap-testing,dc=example,dc=com'
     admin_group: 'gitlab_admin'
EOS

이 경우, bind_dn 사용자를 찾기 위해 다음 ldapsearch를 실행할 수 있습니다: 

ldapsearch -D "cn=admin,dc=ldap-testing,dc=example,dc=com" \
  -w Password1 \
  -p 389 \
  -h 127.0.0.1 \
  -b "dc=ldap-testing,dc=example,dc=com"

bind_dn, password, port, host, base는 모두 gitlab.rb 구성에서 구성된 것과 동일합니다.

start_tls 암호화로 ldapsearch 사용

이전 예제는 평문을 사용하여 포트 389에서 LDAP 테스트를 수행합니다. start_tls 암호화를 사용하는 경우에는 ldapsearch 명령에 다음을 포함하세요:

  • -Z 플래그.
  • LDAP 서버의 FQDN.

TLS 협상 중에 LDAP 서버의 FQDN이 해당 인증서와 평가되기 때문에 이러한 정보를 포함해야 합니다. 

ldapsearch -D "cn=admin,dc=ldap-testing,dc=example,dc=com" \
  -w Password1 \
  -p 389 \
  -h "testing.ldap.com" \
  -b "dc=ldap-testing,dc=example,dc=com" -Z

simple_tls 암호화로 ldapsearch 사용

simple_tls 암호화를 사용하는 경우(ldapsearch를 보통 636번 포트에서 사용합니다), ldapsearch 명령에 다음을 포함하세요:

  • -H 플래그와 포트를 사용하여 LDAP 서버 FQDN.
  • 전체 구성된 URI를 사용합니다. 
ldapsearch -D "cn=admin,dc=ldap-testing,dc=example,dc=com" \
  -w Password1 \
  -H "ldaps://testing.ldap.com:636" \
  -b "dc=ldap-testing,dc=example,dc=com"

더 많은 정보는 공식 ldapsearch 문서를 참조하세요.

AdFind 사용하기 (Windows)

Windows 기반 시스템에서 AdFind 유틸리티를 사용하여 LDAP 서버에 액세스하고 인증이 올바르게 작동하는지 테스트할 수 있습니다. AdFind는 Joe Richards가 만든 무료 유틸리티입니다.

모든 객체 반환

objectclass=* 필터를 사용하여 모든 디렉터리 객체를 반환할 수 있습니다. 

adfind -h ad.example.org:636 -ssl -u "CN=GitLabSRV,CN=Users,DC=GitLab,DC=org" -up Password1 -b "OU=GitLab INT,DC=GitLab,DC=org" -f (objectClass=*)

필터를 사용하여 단일 객체 반환

객체 이름 또는 전체 DN을 지정하여 단일 객체를 검색할 수도 있습니다. 이 예에서는 객체 이름인 CN=Leroy Fox만 지정합니다. 

adfind -h ad.example.org:636 -ssl -u "CN=GitLabSRV,CN=Users,DC=GitLab,DC=org" -up Password1 -b "OU=GitLab INT,DC=GitLab,DC=org" -f "(&(objectcategory=person)(CN=Leroy Fox))"

Rails 콘솔

caution
rails 콘솔을 사용하면 데이터를 쉽게 만들고, 읽고, 수정하고, 삭제할 수 있습니다. 명령을 정확히 입력하는지 확인하세요.

Rails 콘솔은 LDAP 문제를 디버그하는 데 유용한 도구입니다. 명령을 실행하고 GitLab의 응답을 확인하여 애플리케이션과 직접 상호 작용할 수 있습니다.

rails 콘솔 사용 방법에 대한 자세한 지침은 이 안내서를 참조하세요.

디버그 출력 활성화

GitLab의 작업 내용과 수행 방법을 보여주는 디버그 출력을 제공합니다. 이 값은 영구적으로 유지되지 않으며, Rails 콘솔 세션에서만 활성화됩니다.

rails 콘솔에서 디버그 출력을 활성화하려면 rails 콘솔을 시작하고 다음을 실행하세요: 

Rails.logger.level = Logger::DEBUG

그룹, 서브그룹, 구성원 및 요청자와 관련된 모든 오류 메시지 가져오기

그룹, 서브그룹, 구성원, 및 요청자와 관련된 오류 메시지를 수집합니다. 이를 통해 웹 인터페이스에 표시되지 않을 수 있는 오류 메시지를 확인할 수 있습니다. 이는 LDAP 그룹 동기화 문제나 사용자와 그룹 및 서브그룹 멤버십과 관련된 예상치 못한 동작을 문제 해결하는 데 특히 유용합니다. 

# 그룹과 서브그룹 찾기
group = Group.find_by_full_path("parent_group")
subgroup = Group.find_by_full_path("parent_group/child_group")

# 그룹과 서브그룹 오류
group.valid?
group.errors.map(&:full_messages)

subgroup.valid?
subgroup.errors.map(&:full_messages)

# 구성원과 요청자의 그룹과 서브그룹 오류
group.requesters.map(&:valid?)
group.requesters.map(&:errors).map(&:full_messages)
group.members.map(&:valid?)
group.members.map(&:errors).map(&:full_messages)
group.members_and_requesters.map(&:errors).map(&:full_messages)

subgroup.requesters.map(&:valid?)
subgroup.requesters.map(&:errors).map(&:full_messages)
subgroup.members.map(&:valid?)
subgroup.members.map(&:errors).map(&:full_messages)
subgroup.members_and_requesters.map(&:errors).map(&:full_messages)