• 사용자가 제거된 후 추가되지 않음
  • Self-Managed GitLab
• 사용자가 로그인할 수 없음
• 사용자의 SAML NameId가 SCIM externalId와 일치하는지 확실하지 않음
• 불일치하는 SCIM extern_uid 및 SAML NameId
• SCIM 앱 변경
• SCIM 앱이 "User has already been taken","status":409 오류를 반환함
• 구성된 그룹의 사용자 이메일 주소가 허용되지 않음
• SCIM 요청을 위한 Rails 로그 검색
• SCIM 로그에서 멤버 이메일 주소가 연결되지 않은 오류
• 비활성화 동작에 대한 403 금지 응답
• Azure Active Directory
  • SCIM 구성이 올바른지 확인
  • 연결 테스트 시 invalid credentials 오류
  • Failed to match an entry in the source and target systems Group 'Group-Name' 오류
• Okta
  • API SCIM 자격 증명을 테스트할 때 Error authenticating: null 메시지

SCIM 문제 해결

이 섹션에는 발생할 수 있는 문제에 대한 가능한 해결책이 포함되어 있습니다.

사용자가 제거된 후 추가되지 않음

사용자를 제거하면 그룹에서 제거되지만 계정이 삭제되지는 않습니다(자세한 내용은 액세스 제거 참조).

사용자가 SCIM 앱에 다시 추가되면 GitLab은 사용자가 이미 존재하기 때문에 새로운 사용자를 생성하지 않습니다.

2023년 8월 11일부터 skip_saml_identity_destroy_during_scim_deprovision 피처 플래그가 활성화되었습니다.

해당 날짜 이후 SCIM에 의해 해제된 사용자의 경우, 사용자의 SAML 식별 정보가 제거되지 않습니다. 해당 사용자가 SCIM 앱에 다시 추가되면:

• 그들의 SCIM 식별 정보 active 속성이 true로 설정됩니다.
• 그들은 SSO를 사용하여 로그인할 수 있습니다.

해당 날짜 이전에 SCIM에 의해 해제된 사용자의 경우, 그들의 SAML 식별 정보가 파기됩니다. 이 문제를 해결하려면 사용자가 기존 GitLab.com 계정에 SAML을 연결해야 합니다.

Self-Managed GitLab

Self-Managed GitLab 인스턴스의 경우, 해당 인스턴스의 관리자는 사용자 식별 정보를 직접 추가할 수 있습니다. 이렇게 할 경우, 관리자가 여러 사용자 식별 정보를 다시 추가해야 하는 경우 시간을 절약할 수 있습니다.

사용자가 로그인할 수 없음

사용자가 로그인할 수 없는 문제에 대한 가능한 해결책은 다음과 같습니다:

• 사용자가 SCIM 앱에 추가되었는지 확인합니다.
• User is not linked to a SAML account 오류 메시지를 받은 경우, 사용자가 이미 GitLab에 존재할 가능성이 있습니다. 사용자가 SCIM 및 SAML 식별 정보 링크 지침을 따를 수 있습니다. 또는 Self-Managed 관리자는 사용자 식별 정보를 추가할 수 있습니다.
• GitLab이 저장한 Identity (extern_uid) 값은 SCIM이 id 또는 externalId가 변경될 때마다 업데이트됩니다. 사용자는 SAML에 의해 전송된 ID와 일치하는 방법으로 로그인할 때까지 사용자가 로그인하지 못합니다. 이 값은 또한 SCIM에 의해 사용자의 id에 따라 매칭되며, id 또는 externalId 값이 변경될 때마다 SCIM에 의해 업데이트됩니다.
• GitLab.com에서는 SCIM id와 SCIM externalId를 SAML NameId와 동일한 값으로 구성해야 합니다. SAML 응답을 디버깅 도구를 사용하여 추적하고, 발생한 오류를 SAML 문제 해결 정보와 비교합니다.

사용자의 SAML NameId가 SCIM externalId와 일치하는지 확실하지 않음

사용자의 SAML NameId가 그들의 SCIM externalId와 일치하는지 확인하려면 다음을 수행할 수 있습니다:

• 관리자는 Admin Area를 사용하여 사용자의 SCIM 식별 정보 디렉터리을 확인할 수 있습니다.
• 그룹 소유자는 그룹 SAML SSO 설정 페이지에서 각 사용자의 식별자 디렉터리을 볼 수 있습니다.
• SCIM API를 사용하여 매뉴얼으로 GitLab이 사용자에 대해 저장한 extern_uid를 검색하고 SAML API에서 각 사용자의 값과 비교할 수 있습니다.
• 사용자에게 SAML 추적 도구를 사용하도록 하고, extern_uid를 SAML NameId로 반환된 값과 비교할 수 있습니다.

불일치하는 SCIM extern_uid 및 SAML NameId

값이 변경되었거나 다른 필드로 매핑해야 하는 경우, 다음이 동일한 필드와 매핑되어야 합니다:

• externalId
• NameId

GitLab의 extern_uid가 SAML의 NameId와 일치하지 않는 경우, 사용자의 로그인을 활성화하기 위해 GitLab의 extern_uid를 업데이트해야 합니다.

SCIM 식별 제공자에서 이 업데이트를 수행하도록 구성해야 합니다. 사용자 조회가 실패하는 경우와 같이 식별 제공자가 업데이트를 수행할 수 없는 경우가 있습니다.

GitLab은 이러한 ID를 사용하여 사용자를 조회합니다. 식별 제공자가 이러한 필드의 현재 값들을 알지 못하는 경우, 해당 제공자는 중복 사용자를 생성하거나 기대한 작업을 완료하지 못할 수 있습니다.

매핑된 식별자 값을 변경하려면 다음 중 하나를 수행할 수 있습니다:

• 사용자에게 SAML authentication failed: User has already been taken 섹션을 기반으로 자신을 unlink하고 다시 링크하도록 함.

• SCIM 앱에서 모든 사용자를 동시에 unlink하여 제공이 켜져 있는 동안 모든 사용자를 삭제함.

  이렇게 하면 모든 사용자의 최상위 그룹 및 하위 그룹에서의 역할이 구성된 기본 멤버십 역할로 재설정됩니다.
• SAML API 또는 SCIM API를 사용하여 매뉴얼으로 사용자에게 저장된 extern_uid를 SAML NameId 또는 SCIM externalId와 일치하도록 수정할 수 있습니다.

다음은 수행해서는 안 되는 작업입니다:

• 잘못된 값으로 업데이트하면 사용자가 로그인할 수 없게됩니다.
• 잘못된 사용자에게 값을 할당하면 사용자가 잘못된 계정에 로그인하게 됩니다.

또한, 사용자의 기본 이메일은 SCIM 식별 제공자의 이메일과 일치해야 합니다.

SCIM 앱 변경

SCIM 앱을 변경할 때:

• 사용자는 SAML 앱 변경 섹션의 지침을 따를 수 있습니다.
• 식별 제공자의 관리자는 다음을 수행할 수 있습니다:
  1. SCIM 앱에서 사용자를 제거합니다. 이렇게 하면:
     • GitLab.com에서 그룹에서 제거된 모든 사용자가 제거됩니다.
     • GitLab Self-Managed에서 사용자가 차단됩니다.
  2. 새 SCIM 앱에 대한 동기화를 켜서 기존 사용자를 링크합니다.

SCIM 앱이 "User has already been taken","status":409 오류를 반환함

SAML 또는 SCIM 구성 또는 제공자를 변경하면 다음과 같은 문제가 발생할 수 있습니다:

• SAML 및 SCIM 식별 정보 불일치. 이 문제를 해결하려면:
  1. 사용자의 SAML NameId가 SCIM extern_uid와 일치함을 확인합니다(unsure if user’s SAML NameId matches the SCIM externalId 참조).
  2. 불일치하는 SCIM extern_uid 및 SAML NameId를 업데이트하거나 수정합니다.
• GitLab과 식별 제공자 SCIM 앱 간의 SCIM 식별 정보 불일치. 이 문제를 해결하려면:
  1. 사용자의 extern_uid를 GitLab에 저장한 SCIM API를 사용하여 사용자의 extern_uid과 SCIM 앱에서의 사용자 externalId를 비교합니다.
  2. 동일한 SCIM API를 사용하여 GitLab.com에서 사용자의 SCIM extern_uid를 업데이트합니다.

구성된 그룹의 사용자 이메일 주소가 허용되지 않음

SCIM 프로비저닝에 HTTP 상태 412 및 다음 오류 메시지가 표시될 수 있습니다:

The member's email address is not allowed for this group. Check with your administrator.

이 오류는 다음의 경우에 발생합니다:

• 그룹에 대한 도메인별 액세스 제한이 구성되어 있습니다.
• 프로비저닝되는 사용자 계정의 이메일 도메인이 허용되지 않는 경우 발생합니다.

이 문제를 해결하려면 다음 중 하나를 수행할 수 있습니다:

• 사용자 계정의 이메일 도메인을 허용되는 도메인 디렉터리에 추가합니다.
• 도메인별 액세스 제한 기능을 비활성화하여 모든 도메인을 제거합니다.

SCIM 요청을 위한 Rails 로그 검색

GitLab.com 관리자는 api_json.log에서 pubsub-rails-inf-gprd-* 인덱스를 사용하여 Kibana에서 SCIM 요청을 검색할 수 있습니다. 내부 그룹 SCIM API에 기반한 다음 필터를 사용합니다:

• json.path: /scim/v2/groups/<group-path>
• json.params.value: <externalId>

관련 로그 항목에서 json.params.value는 GitLab이 수신하는 SCIM 매개변수의 값을 보여줍니다. 이러한 값을 사용하여 식별 공급자의 SCIM 앱 구성에서 GitLab으로 의도된대로 통신되는지 확인합니다.

예를 들어, 특정 세부 정보로 계정이 제공된 이유에 대한 명확한 소스로 이러한 값들을 사용합니다. 이 정보는 계정이 SCIM 앱 구성과 일치하지 않는 세부 정보로 SCIM으로 제공된 경우에 도움이 될 수 있습니다.

SCIM 로그에서 멤버 이메일 주소가 연결되지 않은 오류

GitLab.com에서 SCIM 사용자를 제공하려고 시도할 때, GitLab은 해당 이메일 주소를 가진 사용자가 이미 존재하는지 확인합니다. 다음과 같은 오류 메시지가 표시될 수 있습니다.

• 사용자는 존재하지만 SAML 식별이 연결되지 않은 경우
• 사용자가 존재하고 SAML 식별이 있으며 SCIM 식별이 active: false로 설정된 경우

멤버의 이메일 주소가 SAML 계정에 연결되지 않았거나 비활성화된
SCIM 식별이 있습니다.

이 오류 메시지는 상태 412와 함께 반환됩니다.

이로 인해 해당 종단 사용자가 계정에 올바르게 액세스할 수 없을 수 있습니다.

첫 번째 해결책은 다음과 같습니다:

1. 종단 사용자가 기존의 GitLab.com 계정에 SAML을 연결합니다.
2. 사용자가 이 작업을 수행한 후에, 식별 공급자에서 SCIM 동기화를 시작합니다. SCIM 동기화가 동일한 오류 없이 완료되면, GitLab은 성공적으로 SCIM 식별을 기존 사용자 계정에 연결했으며 사용자는 이제 SAML SSO를 사용하여 로그인할 수 있어야 합니다.

오류가 지속되는 경우, 사용자는 아마도 이미 존재하며 SAML과 SCIM 식별이 모두 active: false로 설정된 것입니다. 이를 해결하려면 다음을 수행합니다:

1. 선택 사항. SCIM 구성을 처음으로 설정할 때 SCIM 토큰을 저장하지 않은 경우, 새 토큰을 생성합니다. 새 SCIM 토큰을 생성하는 경우, 식별 공급자의 SCIM 구성에서 토큰을 반드시 업데이트해야 합니다. 그렇지 않으면 SCIM이 작동을 중지합니다.
2. SCIM 토큰을 찾습니다.
3. API를 사용하여 단일 SCIM 제공 사용자를 가져옵니다.

4. 반환된 정보를 확인하여 다음 사항을 확인합니다:

   • 사용자의 식별자(id) 및 이메일이 식별 공급자가 보내는 것과 일치하는지
   • active가 false로 설정되어 있는지

   이러한 정보 중 어느 것이라도 일치하지 않으면 GitLab Support에 문의합니다.

5. API를 사용하여 SCIM 제공 사용자의 active 값을 true로 업데이트합니다.
6. 업데이트가 상태 코드 204를 반환하면 사용자로부터 SAML SSO로 로그인 시도를 요청합니다.

비활성화 동작에 대한 403 금지 응답

만약 IP 주소에 의한 그룹 액세스 제한을 설정한 경우, SCIM 해제가 다음과 같은 오류 응답으로 실패할 수 있습니다.

{"message":"403 Forbidden"}

이는 IP 주소에 의한 그룹 액세스 제한을 설정했을 때의 알려진 문제입니다.

이 문제를 해결하기 위해, Group SCIM API를 사용하여 사용자의 active 상태를 false로 설정해 단일 SCIM 제공 사용자를 업데이트합니다.

Azure Active Directory

다음 문제 해결 정보는 특히 Azure Active Directory를 통해 SCIM 제공된 경우에 해당됩니다.

SCIM 구성이 올바른지 확인

다음을 확인하세요:

• externalId의 일치 우선 순위가 1입니다.
• externalId의 SCIM 값이 NameId의 SAML 값과 일치합니다.

합리적인 값에 대해 다음 SCIM 매개변수를 검토합니다:

• userName
• displayName
• emails[type eq "work"].value

연결 테스트 시 invalid credentials 오류

연결을 테스트하는 동안 다음과 같은 오류가 발생할 수 있습니다:

유효하지 않은 자격 증명을 입력한 것으로 보입니다. 관리 계정에 대한 올바른 정보를 사용했는지 확인하세요

Tenant URL 및 secret token이 올바른 경우, 그룹 경로에 JSON 기본 요소로 간주 될 수 있는 문자가 포함되어 있는지 확인하세요(.와 같은). 그룹 경로에서 이러한 문자를 제거하거나 URL 인코드하면 일반적으로 이 오류가 해결됩니다.

Failed to match an entry in the source and target systems Group 'Group-Name' 오류

Azure에서 그룹 제공이 Failed to match an entry in the source and target systems Group 'Group-Name' 오류로 실패할 수 있습니다. 오류 응답에는 GitLab URL https://gitlab.com/users/sign_in의 HTML 결과가 포함될 수 있습니다.

이 오류는 무해하며, 그룹 제공이 활성화되었지만 GitLab SCIM 통합에서는 해당되지 않으며 필요하지 않기 때문에 발생합니다. 이 오류를 제거하려면 Azure 구성 가이드의 지침을 따라 Azure Active Directory 그룹을 AppName에 동기화 비활성화합니다.

Okta

다음 문제 해결 정보는 특히 Okta를 통해 SCIM 제공된 경우에 해당됩니다.

API SCIM 자격 증명을 테스트할 때 Error authenticating: null 메시지

Okta SCIM 앱에서 API 자격 증명을 테스트하는 동안 다음과 같은 오류가 발생할 수 있습니다:

Error authenticating: null

Okta는 사용자를 제공하거나 제공을 해제하려면 GitLab 인스턴스에 연결할 수 있어야 합니다.

Okta SCIM 앱에서 SCIM Base URL이 올바르게 GitLab의 유효한 SCIM API 엔드포인트 URL을 가리키는지 확인하세요. 이 URL에 대한 정보를 찾으려면 GitLab.com 그룹이나 자체 호스팅 GitLab 인스턴스에 대해 다음 문서를 참조하세요.

자체 호스팅 GitLab 인스턴스에서는 Okta가 연결되도록 GitLab이 공개적으로 사용 가능한지 확인하세요. 필요한 경우 방화벽에서 Okta IP 주소에 대한 액세스 허용할 수 있습니다.