관리자인 경우, 다음 정보를 사용하여 LDAP 문제를 해결하세요.

일반적인 문제 및 워크플로#

연결#

연결 거부#

LDAP 서버에 연결할 때 Connection Refused 오류 메시지가 표시되면, GitLab에서 사용하는 LDAP port 및 encryption 설정을 검토하세요. 일반적인 조합은 encryption: 'plain' 및 port: 389, 또는 encryption: 'simple_tls' 및 port: 636입니다.

연결 시간 초과#

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

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

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

이 오류가 표시되면 LDAP 공급자 또는 관리자에게 문의하세요.

조회 오류#

로그에서 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 쿼리#

다음을 사용하면 Rails 콘솔을 통해 LDAP에서 검색을 수행할 수 있습니다. 무엇을 하려는지에 따라 사용자를 쿼리하거나 그룹을 쿼리하거나, ldapsearch를 사용하는 것이 더 적합할 수 있습니다.

adapter = Gitlab::Auth::Ldap::Adapter.new('ldapmain')
options = {
    # :base is required
    # use .base or .group_base
    base: adapter.config.group_base,

    # :filter is optional
    # 'cn' looks for all "cn"s under :base
    # '*' is the search string - here, it's a wildcard
    filter: Net::LDAP::Filter.eq('cn', '*'),

    # :attributes is optional
    # the attributes we want to get returned
    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
    # use .base or .group_base
    base: adapter.config.base,

    # :filter is optional
    # This filter includes OID 1.2.840.113556.1.4.1941
    # It will search for all direct and nested members of the group gitlab_grp in the LDAP directory
    filter: Net::LDAP::Filter.construct("(memberOf:1.2.840.113556.1.4.1941:=CN=gitlab_grp,DC=example,DC=com)"),

    # :attributes is optional
    # the attributes we want to get returned
    attributes: %w(dn cn memberuid member submember uniquemember memberof)
}
adapter.ldap_search(options)

실행 방법에 대한 예시는 Adapter 모듈 검토를 참조하세요.

사용자 로그인#

사용자를 찾을 수 없음#

LDAP에 대한 연결이 설정될 수 있다는 것을 확인했지만 GitLab이 출력에 LDAP 사용자를 표시하지 않는 경우, 다음 중 하나가 가장 가능성이 높습니다:

• bind_dn 사용자가 사용자 트리를 탐색할 수 있는 권한이 충분하지 않습니다.
• 사용자가 구성된 base 아래에 없습니다.
• 구성된 user_filter가 사용자에 대한 액세스를 차단합니다.

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

사용자가 로그인할 수 없음#

사용자는 여러 이유로 로그인에 어려움을 겪을 수 있습니다. 시작하려면 스스로에게 다음 질문을 해보세요:

• 사용자가 LDAP의 구성된 base 아래에 있나요? 로그인하려면 사용자가 이 base 아래에 있어야 합니다.
• 사용자가 구성된 user_filter를 통과하나요? 구성되지 않은 경우 이 질문은 무시할 수 있습니다. 구성된 경우, 사용자는 로그인이 허용되려면 이 필터도 통과해야 합니다.
  • 디버깅 user_filter에 대한 문서를 참조하세요.

이전 질문 모두 괜찮다면, 다음으로 문제를 재현하면서 로그 자체를 살펴볼 곳입니다.

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

로그가 문제의 근본 원인으로 이어지지 않으면, Rails 콘솔을 사용하여 이 사용자를 쿼리하여 GitLab이 LDAP 서버에서 이 사용자를 읽을 수 있는지 확인하세요.

더 자세한 조사를 위해 사용자 동기화를 디버그하는 것도 도움이 될 수 있습니다.

사용자에게 Invalid login or password. 오류가 표시됨#

히스토리

• GitLab 16.10에서 도입.

사용자에게 이 오류가 표시되면, LDAP 로그인 양식 대신 Standard 로그인 양식을 사용하여 로그인하려고 하기 때문일 수 있습니다.

해결하려면 사용자에게 LDAP 사용자 이름과 비밀번호를 LDAP 로그인 양식에 입력하도록 요청하세요.

로그인 시 잘못된 자격 증명#

LDAP에서 사용된 로그인 자격 증명이 정확한 경우, 해당 사용자에 대해 다음이 사실인지 확인하세요:

• 바인딩하는 사용자가 사용자 트리를 읽고 탐색할 수 있는 충분한 권한이 있는지 확인합니다.
• user_filter가 유효한 사용자를 차단하지 않는지 확인합니다.
• LDAP 체크 명령을 실행하여 LDAP 설정이 올바르고 GitLab이 사용자를 볼 수 있는지 확인합니다.

LDAP 계정에 대한 액세스 거부#

감사자 수준 액세스가 있는 사용자에게 영향을 줄 수 있는 버그가 있습니다. Premium/Ultimate에서 다운그레이드할 때, 로그인을 시도하는 감사자 사용자는 다음 메시지를 볼 수 있습니다: Access denied for your LDAP account.

해결 방법은 영향 받는 사용자의 액세스 수준을 변경하는 것입니다.

사전 요구 사항:

• 관리자 액세스.

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

이제 사용자가 로그인할 수 있습니다.

이메일이 이미 사용됨#

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

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

이 오류는 LDAP의 이메일 주소 email@example.com을 참조합니다. 이메일 주소는 GitLab에서 고유해야 하며 LDAP는 사용자의 기본 이메일(수많은 보조 이메일이 아닌)에 연결됩니다. 다른 사용자(또는 동일한 사용자)가 email@example.com을 보조 이메일로 설정했으며, 이것이 이 오류를 발생시키고 있습니다.

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

# This searches for an email among the primary AND secondary emails
user = User.find_by_any_email('email@example.com')
user.username

이렇게 하면 이 이메일 주소를 가진 사용자가 표시됩니다. 여기서 두 가지 중 하나의 단계를 취해야 합니다:

• LDAP로 로그인할 때 이 사용자를 위한 새 GitLab 사용자/사용자 이름을 만들려면, 충돌을 제거하기 위해 보조 이메일을 제거합니다.
• 이 사용자가 LDAP와 함께 사용할 기존 GitLab 사용자/사용자 이름을 사용하려면, 이 이메일을 보조 이메일에서 제거하고 기본 이메일로 만들어 GitLab이 이 프로필을 LDAP 아이덴티티와 연결하도록 합니다.

사용자는 프로필에서 또는 관리자가 이 단계 중 하나를 수행할 수 있습니다.

프로젝트 제한 오류#

다음 오류는 제한 또는 제한이 활성화되었지만 관련 데이터 필드에 데이터가 없음을 나타냅니다:

• Projects limit can't be blank.
• Projects limit is not a number.

해결하려면:

1. 오른쪽 상단 모서리에서 관리자를 선택합니다.
2. 설정 > 일반을 선택합니다.
3. 다음 두 항목을 모두 확장합니다:
   • 계정 및 제한.
   • 가입 제한.
4. 예를 들어 기본 프로젝트 제한 또는 가입 허용 도메인 필드를 확인하고 관련 값이 구성되어 있는지 확인합니다.

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에 있다고 가정합니다.

모든 사용자 동기화#

수동 사용자 동기화의 출력은 GitLab이 LDAP에 대해 사용자를 동기화하려고 할 때 어떤 일이 발생하는지 보여줄 수 있습니다. Rails 콘솔에 들어가서 다음을 실행합니다:

Rails.logger.level = Logger::DEBUG

LdapSyncWorker.new.perform

다음으로, 출력 읽는 방법을 알아봅니다.

사용자 동기화 후 콘솔 출력 예시#

수동 사용자 동기화의 출력은 매우 자세하며, 단일 사용자의 성공적인 동기화는 다음과 같이 보일 수 있습니다:

Syncing user John, email@example.com
  Identity Load (0.9ms)  SELECT  "identities".* FROM "identities" WHERE "identities"."user_id" = 20 AND (provider LIKE 'ldap%') LIMIT 1
Instantiating Gitlab::Auth::Ldap::Person with 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
  User Update (1.1ms)  UPDATE "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에 존재하는 사용자의 사용자 이름과 이메일이 포함된 다음 줄로 시작합니다:

Syncing user John, email@example.com

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

다음으로, GitLab은 identities 테이블에서 이 사용자와 구성된 LDAP 공급자 간의 기존 링크를 검색합니다:

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

아이덴티티 객체에는 GitLab이 LDAP에서 사용자를 찾기 위해 사용하는 DN이 있습니다. DN을 찾을 수 없으면 대신 이메일이 사용됩니다. 이 사용자가 LDAP에서 찾았음을 볼 수 있습니다:

Instantiating Gitlab::Auth::Ldap::Person with 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

이 경우 사용자가 차단됩니다:

  User Update (0.4ms)  UPDATE "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') # If `main` is the LDAP provider
Gitlab::Auth::Ldap::Person.find_by_uid('<uid>', adapter)

그룹 멤버십#

멤버십이 부여되지 않음#

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

• LDAP 구성에 group_base가 지정되어 있는지 확인합니다. 이 구성은 그룹 동기화가 제대로 작동하기 위해 필요합니다.
• 올바른 LDAP 그룹 링크가 GitLab 그룹에 추가되었는지 확인합니다.
• 사용자에게 LDAP 아이덴티티가 있는지 확인합니다:
  1. 관리자 사용자로 GitLab에 로그인합니다.
  2. 오른쪽 상단 모서리에서 관리자를 선택합니다.
  3. 왼쪽 사이드바에서 개요 > 사용자를 선택합니다.
  4. 사용자를 검색합니다.
  5. 이름을 선택하여 사용자를 엽니다. 편집을 선택하지 마세요.
  6. 아이덴티티 탭을 선택합니다. LDAP DN이 식별자인 LDAP 아이덴티티가 있어야 합니다. 없다면, 이 사용자가 아직 LDAP로 로그인하지 않았으며 먼저 그렇게 해야 합니다.
• 그룹이 동기화될 때까지 한 시간 또는 구성된 간격을 기다립니다. 프로세스를 가속화하려면 GitLab 그룹 관리 > 멤버로 이동하여 지금 동기화를 누르거나(하나의 그룹 동기화) 그룹 동기화 Rake 태스크를 실행합니다(모든 그룹 동기화).

모든 확인이 괜찮아 보이면 Rails 콘솔에서 좀 더 고급 디버깅으로 들어가세요.

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인지.
• 이 CN이 구성된 group_base의 범위 내에 있는지.
• admin_group의 멤버가 이미 LDAP 자격 증명으로 GitLab에 로그인했는지. GitLab은 계정이 이미 LDAP에 연결된 사용자에게만 관리자 액세스를 부여합니다.

이전 조건이 모두 사실이고 사용자가 여전히 액세스를 받지 못하는 경우, Rails 콘솔에서 수동 그룹 동기화를 실행하고 GitLab이 admin_group을 동기화할 때 어떤 일이 발생하는지 출력을 살펴봅니다.

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

그룹의 그룹 > 멤버 페이지의 지금 동기화 버튼이 멈출 수 있습니다. 버튼을 누르고 페이지를 다시 로드한 후 버튼이 멈추게 됩니다. 그러면 버튼을 다시 선택할 수 없습니다.

지금 동기화 버튼은 여러 이유로 멈출 수 있으며 특정 경우에 대한 디버깅이 필요합니다. 다음은 두 가지 가능한 원인과 문제에 대한 가능한 해결 방법입니다.

잘못된 멤버십#

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

# Find the group in question
group = Group.find_by(name: 'my_gitlab_group')

# Look for errors on the Group itself
group.valid?
group.errors.map(&:full_messages)

# Look for errors among the group's members and requesters
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 'Settings > General' page, and check 'Restrict membership by email domain'."]]

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

Sidekiq 노드에서 LDAP 구성 누락#

GitLab이 여러 노드에 걸쳐 확장되고 Sidekiq를 실행하는 노드의 /etc/gitlab/gitlab.rb에서 LDAP 구성이 누락된 경우 지금 동기화 버튼이 멈춥니다. 이 경우 Sidekiq 작업이 사라지는 것처럼 보입니다.

LDAP는 Sidekiq 노드에서 필요한데, LDAP에는 로컬 LDAP 구성이 필요한 비동기적으로 실행되는 여러 작업이 있기 때문입니다:

• 사용자 동기화.
• 그룹 동기화.

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

이 문제를 해결하려면 Sidekiq 노드에서 LDAP를 구성합니다. 구성 후 LDAP를 확인하는 Rake 태스크를 실행하여 GitLab 노드가 LDAP에 연결할 수 있는지 확인합니다.

모든 그룹 동기화#

수동 그룹 동기화의 출력은 GitLab이 LDAP에 대해 LDAP 그룹 멤버십을 동기화할 때 어떤 일이 발생하는지 보여줄 수 있습니다. Rails 콘솔에 들어가서 다음을 실행합니다:

Rails.logger.level = Logger::DEBUG

LdapAllGroupsSyncWorker.new.perform

다음으로, 출력 읽는 방법을 알아봅니다.

그룹 동기화 후 콘솔 출력 예시#

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

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

Started syncing 'ldapmain' provider for 'my_group' group

다음 항목은 GitLab이 LDAP 서버에서 보는 모든 사용자 DN의 배열을 보여줍니다. 이 DN들은 GitLab 그룹이 아닌 단일 LDAP 그룹의 사용자입니다. 이 GitLab 그룹에 여러 LDAP 그룹이 링크된 경우, 각 LDAP 그룹에 대해 하나씩 여러 로그 항목을 볼 수 있습니다. 이 로그 항목에 LDAP 사용자 DN이 표시되지 않으면, 조회를 수행할 때 LDAP가 사용자를 반환하지 않는 것입니다. 사용자가 실제로 LDAP 그룹에 있는지 확인합니다.

Members in 'ldap_group_1' LDAP group: ["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이 그룹에 추가되어야 한다고 믿는 사용자를 정확히 나타내야 합니다.

Resolved 'my_group' group member access: {"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 및 이메일이 변경됨을 참조하세요.

User with DN `uid=john0,ou=people,dc=example,dc=com` should have access
to 'my_group' group but there is no user in GitLab with that
identity. Membership will be updated when the user signs in for
the first time.

마지막으로, 다음 항목은 이 그룹의 동기화가 완료되었음을 나타냅니다:

Finished syncing all providers for 'my_group' group

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

Syncing admin users for 'ldapmain' provider

출력은 단일 그룹에서 발생하는 것과 유사하며, 이 줄이 동기화가 완료되었음을 나타냅니다:

Finished syncing admin users for 'ldapmain' provider

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

No `admin_group` configured for 'ldapmain' provider. Skipping

하나의 그룹 동기화#

모든 그룹 동기화는 출력에 많은 노이즈를 생성할 수 있는데, 단일 GitLab 그룹의 멤버십을 문제 해결하는 데만 관심이 있을 때 방해가 될 수 있습니다. 이 경우, 이 그룹만 동기화하고 디버그 출력을 보는 방법은 다음과 같습니다:

Rails.logger.level = Logger::DEBUG

# Find the GitLab group.
# If the output is `nil`, the group could not be found.
# If a bunch of group attributes are in the output, your group was found successfully.
group = Group.find_by(name: 'my_gitlab_group')

# Sync this group against LDAP
EE::Gitlab::Auth::Ldap::Sync::Group.execute_all_providers(group)

출력은 모든 그룹을 동기화할 때 얻는 것과 유사합니다.

LDAP에서 그룹 쿼리#

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

# Find the adapter and the group itself
adapter = Gitlab::Auth::Ldap::Adapter.new('ldapmain') # If `main` is the LDAP provider
ldap_group = EE::Gitlab::Auth::Ldap::Group.find_by_cn('group_cn_here', adapter)

# Find the members of the LDAP group
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 값.

다음 스크립트는 제공된 모든 사용자의 이메일을 업데이트하여 차단되거나 계정에 액세스할 수 없는 상황이 발생하지 않도록 합니다.

Rails 콘솔로 이동하여 다음을 실행합니다:

# Each entry must include the old username and the new email
emails = {
  'ORIGINAL_USERNAME' => 'NEW_EMAIL_ADDRESS',
  ...
}

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

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

Invalid grant로 인한 AzureActivedirectoryV2 인증 실패#

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

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

이 문제는 다음 두 가지가 모두 사실인 경우 발생합니다:

• 해당 사용자에 대해 SAML이 구성된 후에도 LDAP 아이덴티티가 사용자에 남아 있습니다.
• 해당 사용자에 대해 LDAP를 비활성화합니다.

로그에서 LDAP 및 Azure 메타데이터를 모두 받게 되어 Azure에서 오류가 발생합니다.

단일 사용자의 해결 방법은 관리자 > 아이덴티티에서 사용자의 LDAP 아이덴티티를 제거하는 것입니다.

여러 LDAP 아이덴티티를 제거하려면 아래 Could not authenticate you from Ldapmain because "Unknown provider" 오류에 대한 해결 방법 중 하나를 사용하세요.

오류: Could not authenticate you from Ldapmain because "Unknown provider"#

LDAP 서버로 인증할 때 다음 오류를 받을 수 있습니다:

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

이 오류는 GitLab 구성에서 이름이 변경되거나 제거된 LDAP 서버로 이전에 인증한 계정을 사용할 때 발생합니다. 예를 들어:

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

Rails 콘솔을 사용하여 영향받은 사용자를 나열하고 어떤 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 고가용성을 관리하기 위해 로드 밸런서가 이제 사용되고 별도의 보조 로그인 옵션이 더 이상 필요하지 않은 경우.

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

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

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

사전 요구 사항:

• auto_link_ldap_user가 활성화되어 있는지 확인합니다.

이 솔루션을 사용하면 아이덴티티가 삭제된 후 영향받은 사용자가 구성된 LDAP 서버로 로그인하고 GitLab에 의해 새 identity 레코드가 생성될 수 있습니다.

제거된 LDAP 서버가 ldapsecondary이므로, Rails 콘솔에서 모든 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 서버에 대한 GitLab 구성 줄을 제거하거나 주석 처리합니다.
2. GitLab을 재구성하여 임시로 하나의 LDAP 서버만 사용하도록 합니다.
3. Rails 콘솔에 들어가서 라이선스 키를 추가합니다.
4. GitLab 구성에서 추가 LDAP 서버를 다시 활성화하고 GitLab을 다시 재구성합니다.

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

그룹 동기화 중에 사용자가 그룹에 추가되고 다음 동기화 시 제거되며, 이것이 반복적으로 발생한다면, 사용자에게 여러 또는 중복된 LDAP 아이덴티티가 없는지 확인하세요.

해당 아이덴티티 중 하나가 더 이상 사용 중이지 않은 이전 LDAP 공급자를 위해 추가된 경우, 제거된 LDAP 서버와 관련된 identity 레코드를 제거하세요.

디버깅 도구#

LDAP 체크#

LDAP를 확인하는 Rake 태스크는 GitLab이 LDAP에 대한 연결을 성공적으로 설정하고 사용자를 읽을 수 있는지까지 확인하는 데 도움이 되는 유용한 도구입니다.

연결을 설정할 수 없는 경우, 구성 문제이거나 연결을 차단하는 방화벽 때문일 가능성이 높습니다.

• 연결을 차단하는 방화벽이 없고 LDAP 서버가 GitLab 호스트에서 접근 가능한지 확인합니다.
• Rake 체크 출력에서 오류 메시지를 찾아 LDAP 구성의 구성 값(특히 host, port, bind_dn, password)이 올바른지 확인합니다.
• 연결 실패를 추가로 디버깅하기 위해 로그에서 오류를 찾습니다.

GitLab이 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 암호화(일반적으로 포트 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)#

LDAP 서버에 액세스할 수 있고 인증이 올바르게 작동하는지 테스트하려면 (Windows 기반 시스템에서) AdFind 유틸리티를 사용할 수 있습니다. 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 콘솔#

Rails 콘솔은 LDAP 문제를 디버깅하는 데 도움이 되는 유용한 도구입니다. 명령을 실행하고 GitLab이 어떻게 응답하는지 봄으로써 애플리케이션과 직접 상호 작용할 수 있습니다.

Rails 콘솔 사용 방법에 대한 지침은 이 가이드를 참조하세요.

디버그 출력 활성화#

이것은 GitLab이 무엇을 하고 무엇을 사용하는지 보여주는 디버그 출력을 제공합니다. 이 값은 지속되지 않으며 Rails 콘솔에서의 이 세션에만 활성화됩니다.

Rails 콘솔에서 디버그 출력을 활성화하려면, Rails 콘솔에 들어가서 다음을 실행합니다:

Rails.logger.level = Logger::DEBUG

그룹, 하위 그룹, 멤버 및 요청자와 관련된 모든 오류 메시지 가져오기#

그룹, 하위 그룹, 멤버 및 요청자와 관련된 오류 메시지를 수집합니다. 이것은 웹 인터페이스에 나타나지 않을 수 있는 오류 메시지를 캡처합니다. 이것은 LDAP 그룹 동기화 문제 해결과 그룹 및 하위 그룹에서 사용자와 멤버십의 예상치 못한 동작에 특히 도움이 될 수 있습니다.

# Find the group and subgroup
group = Group.find_by_full_path("parent_group")
subgroup = Group.find_by_full_path("parent_group/child_group")

# Group and subgroup errors
group.valid?
group.errors.map(&:full_messages)

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

# Group and subgroup errors for the members AND requesters
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)