LDAP 문제 해결

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

관리자라면 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 쿼리

Tier: Premium, Ultimate Offering: Self-managed

다음은 레일즈 콘솔을 사용하여 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 콘솔을 사용하여 이 사용자를 쿼리하여 LDAP 서버에서 GitLab이 이 사용자를 읽을 수 있는지 확인하세요.

사용자 동기화를 디버그하는 것이 있으면 추가 조사하는 데 도움이 될 수 있습니다.

사용자가 “잘못된 로그인 또는 비밀번호” 오류를 보게 됩니다.

이 오류를 보게 되면 표준 로그인 양식 대신 LDAP 로그인 양식을 사용하여 로그인을 시도하여 발생할 수 있습니다.

해결 방법은 사용자에게 LDAP 사용자 이름 및 암호를 LDAP 로그인 양식에 입력하도록 요청하는 것입니다.

로그인 시 잘못된 자격 증명

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

  • 바인딩하는 사용자가 사용자 트리를 읽을 수 있도록 충분한 권한을 갖고 있는지 확인합니다.
  • user_filter가 그렇지 않으면 유효한 사용자를 차단하지는 않는지 확인합니다.
  • LDAP 설정이 올바른지 확인하기 위해 LDAP 검사 명령을 실행합니다.

LDAP 계정에 대한 액세스 거부

Auditor 수준 액세스를 가진 사용자에게 영향을 미칠 수 있는 버그가 있습니다. 프리미엄/얼티메이트에서 다운그레이드하면 로그인을 시도하는 감사자 사용자는 다음 메시지를 볼 수 있습니다: 당신의 LDAP 계정에 대한 액세스가 거부되었습니다.

해당 사용자의 액세스 수준을 전환하는 기반의 해결 방법이 있습니다:

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

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

이미 사용 중인 이메일

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

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

이 오류는 LDAP의 이메일 주소 email@example.com을 가리킵니다. 이메일 주소는 GitLab 및 LDAP에서 사용자의 기본 전자 메일에 연결되어 있어야 하므로 GitLab에서 이 주소를 기존 또는 (여러 개의 보조 이메일 중 하나가 아닌) 주 이메일로 설정한 다른 사용자 또는 같은 사용자가 이 주소를 가진 이메일로 설정한 경우 이 오류가 발생합니다.

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

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

이렇게 하면 해당 이메일 주소를 가진 사용자가 표시됩니다. 여기서 취해야 할 조치 중 하나는 다음과 같습니다:

  • LDAP로 로그인할 때 새로운 GitLab 사용자/사용자 이름을 만들고 충돌을 제거하려면 보조 이메일을 제거합니다.
  • LDAP 사용을 위해 기존 GitLab 사용자/사용자 이름을 사용하기 위해 이 이메일을 보조 이메일에서 제거하고 주 이메일로 설정하여 GitLab이 이 프로필을 LDAP ID에 연결할 수 있도록 합니다.

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

프로젝트 제한 오류

다음 오류는 제한 또는 제약이 활성화되어 있지만 연결된 데이터 필드에 데이터가 없을 때 발생합니다:

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

이를 해결하려면:

  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에서 사용자 쿼리

이는 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. Identities 탭을 선택합니다. 여기엔 Identifier로 LDAP DN이 있는 LDAP 식별 체계가 있어야 합니다. 그렇지 않다면, 이 사용자는 먼저 LDAP로 로그인해야 합니다.
  • 그룹 동기화를 위해 한 시간이나 구성된 간격을 기다렸습니다. 프로세스를 가속화하려면 GitLab 그룹 관리 > 멤버로 이동하여 지금 동기화를 누르거나 그룹 동기화 레일테스크를 실행합니다. (모든 그룹 동기화)

위의 모든 항목이 올바르다면, 레일즈 콘솔에서 좀 더 고급 디버깅으로 이동하세요.

  1. 레일즈 콘솔에 입력하세요.
  2. 테스트할 GitLab 그룹을 선택하세요. 해당 그룹은 이미 LDAP 그룹 링크가 구성되어 있어야 합니다.
  3. 디버그 로그를 활성화하고, 해당 GitLab 그룹을 찾아 LDAP과 동기화하세요.
  4. 동기화 출력을 살펴보세요. 출력을 읽는 방법에 대해 예시 로그 출력을 참조하세요.
  5. 여전히 사용자가 추가되지 않는 이유를 파악할 수 없다면, LDAP 그룹을 직접 쿼리하여 출력된 멤버를 확인하세요.
  6. 출력에서 사용자의 DN 또는 UID가 일치하는지 확인하세요. 여기에 있는 DN 또는 Uid 중 하나는 앞서 확인한 LDAP 식별 체계의 ‘Identifier’와 일치해야 합니다. 그렇지 않다면, 사용자는 LDAP 그룹에 나타나지 않습니다.

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

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

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

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

관리자 동기화가 구성된 경우에도, 구성된 사용자에게 올바른 관리자 권한이 부여되지 않는 경우, 다음이 올바른지 확인하세요:

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

위의 모든 항목이 올바르고 사용자가 여전히 액세스 권한을 얻지 못하는 경우, 레일즈 콘솔에서 수동 그룹 동기화를 실행하고 출력을 확인하여 GitLab이 admin_group을 동기화할 때 어떤 일이 발생하는지 확인하세요.

UI에서 동기화 지금 버튼이 멈춘 경우

그룹의 그룹 > 멤버 페이지에 있는 동기화 지금 버튼이 멈출 수 있습니다. 이 버튼은 누른 후 페이지를 새로 고친 후에 멈추게 됩니다. 그 후 버튼은 다시 선택할 수 없습니다.

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

유효하지 않은 멤버십

그룹의 일부 멤버 또는 요청 멤버가 유효하지 않으면 동기화 지금 버튼이 멈추게 됩니다. 이 문제의 가시성을 향상시키기 위한 진행 상황을 확인할 수 있습니다. 해당 문제에 대한 진행 상황을 확인할 수 있습니다. 이 문제가 동기화 지금 버튼이 멈추는 원인이 되는지 확인하기 위해 레일즈 콘솔을 사용할 수 있습니다: 

# 해당 그룹 찾기
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 구성이 /etc/gitlab/gitlab.rb의 노드에서 실행 중인 Sidekiq에서 누락된 경우 지금 동기화 버튼이 멈출 수 있습니다. 이 경우, Sidekiq 작업이 사라지는 것으로 보입니다.

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

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

모든 그룹 동기화

참고: 디버깅 시 수동으로 모든 그룹을 동기화하려면, 사용자 동기화를 실행해야 합니다.

수동으로 그룹 동기화를 실행하면 GitLab이 LDAP 그룹 멤버십을 동기화할 때 어떻게 되는지 확인할 수 있습니다. 레일즈 콘솔에 들어가서 다음을 실행하세요. 

Rails.logger.level = Logger::DEBUG

LdapAllGroupsSyncWorker.new.perform

다음으로, 그룹 동기화 후 출력을 읽는 방법을 알아보세요.

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

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

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

Started syncing 'ldapmain' provider for 'my_group' group

다음 항목은 GitLab이 LDAP 서버에서 보는 모든 사용자 DN의 배열을 보여줍니다. 이러한 DN은 GitLab 그룹이 아닌 단일 LDAP 그룹의 사용자입니다. 이 LDAP 그룹과 연결된 여러 LDAP 그룹이 있는 경우, 각 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이 정확히 어떤 사용자를 그룹에 추가해야 하는지 나타냅니다.

참고: 10은 “게스트”, 20은 “기고자”, 30은 “개발자”, 40은 “관리자”입니다. 

'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 및 이메일이 변경됨을 참조하세요. 

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

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

'my_group' 그룹의 모든 프로바이더 동기화 완료

모든 구성된 그룹 링크가 동기화된 후, GitLab은 관리자 또는 외부 사용자를 동기화합니다. 

'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 그룹의 생성자를 그 그룹에서 제거해야 합니다. 이를 수행해도 사용자가 그 그룹에 존재하지 않는 경우:

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

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

LDAP에서 기본 이메일 및 DN이 모두 변경된 경우 GitLab은 사용자의 올바른 LDAP 레코드를 식별할 수 없습니다. 따라서 GitLab은 해당 사용자를 차단합니다. GitLab이 LDAP 레코드를 찾을 수 있도록 기존의 사용자 GitLab 프로필을 다음 중 하나 이상으로 업데이트하십시오:

  • 새 기본 이메일.
  • DN 값.

다음 스크립트는 차단되거나 계정에 액세스할 수 없는 사용자의 이메일을 업데이트합니다.

참고: 다음 스크립트는 새로운 이메일 주소가 제거된 후에 실행해야 합니다. 이메일 주소는 GitLab에서 고유해야 합니다.

레일즈 콘솔로 이동한 후 다음을 실행합니다. 

# 각 항목은 기존 사용자 이름 및 새 이메일을 포함해야 합니다
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

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

“Invalid grant”로부터 AzureActivedirectoryV2에서 인증할 수 없음

LDAP에서 SAML로 변환할 때 Azure에서 다음과 같은 오류를 받을 수 있습니다. 

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

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

  • SAML이 이미 사용자에 대해 구성된 후에도 LDAP 식별이 계속 존재합니다.
  • 그 사용자에 대해 LDAP을 비활성화합니다.

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

단일 사용자에 대한 해결 방법은 Admin > Identities에서 사용자의 LDAP 식별을 제거하는 것입니다.

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

“Unknown provider”로부터 Ldapmain에서 인증할 수 없음

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

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

이 오류는 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 서버 사용에는 유효한 라이선스가 필요합니다. 만료된 라이선스로 인해 다음과 같은 문제가 발생할 수 있습니다:

  • 웹 인터페이스에서 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. 추가 LDAP 서버를 GitLab 구성에 다시 사용하도록 설정하고 다시 GitLab을 구성합니다.

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

그룹 동기화 중에 사용자가 그룹에 추가되었다가 다음 동기화에서 제거되고 이러한 일이 반복되면 사용자가 여러 개의 중복된 LDAP 신원을 가지지 않았는지 확인하십시오.

그 신원 중 하나가 더 이상 사용되지 않는 이전 LDAP 공급자를 위해 추가된 경우, 제거된 LDAP 서버와 관련된 신원 레코드를 제거하십시오.

디버깅 도구

LDAP 체크

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

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

  • 연결이 차단되지 않았는지 확인하고 LDAP 서버가 GitLab 호스트에 접근할 수 있는지 확인합니다.
  • Rake 체크 출력에 오류 메시지가 있는지 확인하여 구성 값(특히 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 암호화(보통 636번 포트에서 사용)를 사용 중이라면 ldapsearch 명령에 다음을 포함하십시오:

  • -H 플래그와 포트로 LDAP 서버 FQDN.
  • 완전한 구성된 URI. 
ldapsearch -D "cn=admin,dc=ldap-testing,dc=example,dc=com" \
  -w Password1 \
  -p "ldaps://testing.ldap.com:636" \
  -b "dc=ldap-testing,dc=example,dc=com"

자세한 내용은 공식 ldapsearch 문서를 참조하십시오.

AdFind 사용 (Windows)

AdFind 유틸리티(Windows 기반 시스템)를 사용하여 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 콘솔

경고: Rails 콘솔을 사용하면 데이터를 생성, 읽기, 수정, 삭제하는 것이 매우 쉽습니다. 명령을 정확히 지시한 대로 실행해야 합니다.

Rails 콘솔은 LDAP 문제의 디버그에 도움이 되는 가치 있는 도구입니다. 응용 프로그램과 직접 상호작용하여 명령을 실행하고 GitLab의 응답을 확인할 수 있습니다.

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

디버그 출력 활성화

GitLab이 수행하는 작업과 수행 방법을 보여주는 디버그 출력을 제공합니다. 이 값을 유지하지 않으며 Rails 콘솔 세션에서만 활성화됩니다.

Rails 콘솔에서 디버그 출력을 활성화하려면 rails 콘솔로 이동하고 다음을 실행하세요. 

Rails.logger.level = Logger::DEBUG

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

그룹, 하위 그룹, 구성원 및 요청자와 관련된 오류 메시지를 수집합니다. 이는 웹 인터페이스에 표시되지 않을 수 있는 오류 메시지를 포착합니다. 이는 LDAP 그룹 동기화와 관련된 문제 및 사용자 및 그룹 및 하위 그룹으로의 멤버십에 대한 예기치 않은 동작을 해결하는 데 특히 도움이 됩니다. 

# 그룹 및 하위 그룹 찾기
group = Group.find_by_full_path("부모_그룹")
subgroup = Group.find_by_full_path("부모_그룹/하위_그룹")

# 그룹 및 하위 그룹 오류
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)