SCIM 문제 해결

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

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

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

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

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

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

해당 날짜부터 SCIM에 의해 비활성화된 사용자는 SAML 신원이 제거되지 않습니다. 사용자가 SCIM 앱에 다시 추가되면:

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

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

자체 관리 GitLab

자체 관리 GitLab 인스턴스의 경우 해당 인스턴스의 관리자는 사용자 신원을 직접 추가할 수 있습니다. 관리자가 여러 신원을 다시 추가해야 하는 경우 시간을 절약할 수 있습니다.

사용자가 로그인할 수 없음

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

  • 사용자가 SCIM 앱에 추가되었는지 확인합니다.
  • User is not linked to a SAML account 오류를 받으면 사용자가 이미 GitLab에 존재할 가능성이 높습니다. 사용자에게 SCIM과 SAML 신원 연결 지침을 따르도록 합니다. 또는 자체 관리하는 관리자는 사용자 신원을 추가할 수 있습니다.
  • GitLab이 저장한 Idenitity (extern_uid) 값은 SCIM이 id 또는 externalId가 변경될 때마다 업데이트됩니다. 사용자는 SAML이 보낸 NameId와 일치하는 경우에만 GitLab 식별자(extern_uid)로 로그인할 수 있습니다. 이 값은 또한 SCIM에서 id를 기준으로 사용자를 일치시키거나 id나 externalId 값이 변경될 때마다 업데이트됩니다.
  • GitLab.com에서는 SCIM id 및 SCIM externalId는 SAML NameId와 동일한 값을 구성해야 합니다. 디버깅 도구를 사용하여 SAML 응답을 추적하고 모든 오류를 SAML 문제 해결 정보와 비교합니다.

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

사용자의 SAML NameId가 SCIM extern_uid와 일치하는지 확인하려면:

  • 관리자는 관리자 영역을 사용하여 사용자의 SCIM 신원을 나열할 수 있습니다.
  • 그룹 소유자는 그룹 SAML SSO 설정 페이지에서 각 사용자의 식별자를 확인할 수 있습니다.
  • SCIM API를 사용하여 사용자에게 저장된 extern_uid를 수동으로 검색하고 SAML API에서 각 사용자의 값과 비교할 수 있습니다.
  • 사용자에게 SAML Tracer를 사용해 extern_uid를 비교하고 SAML NameId로 반환된 값과 비교하도록 합니다.

불일치하는 SCIM extern_uid 및 SAML NameId

값이 변경된 경우 또는 다른 필드로 매핑해야 하는 경우 다음이 동일한 필드에 매핑되어야 합니다:

  • extern_Id
  • NameId

SCIM extern_uid가 SAML NameId와 일치하지 않는 경우 SCIM extern_uid를 업데이트하여 사용자가 로그인할 수 있도록 해야 합니다.

여러분의 SCIM 식별 공급자에서 이 업데이트를 수행하도록 구성해야 합니다. 어떤 경우에는 식별 공급자가 업데이트를 수행할 수 없을 수 있습니다. 예를 들어 사용자 조회가 실패할 때입니다.

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

값을 일치하도록 변경하려면 다음 중 하나를 수행할 수 있습니다:

  • 사용자가 기존의 SAML 인증 실패: 사용자가 이미 사용 중 섹션에 따라 자신을 연결 해제 및 다시 연결

  • 프로비저닝이 켜져 있는 상태에서 SCIM 앱에서 모든 사용자를 제거하여 모든 사용자를 동시에 연결 해제하십시오.

    경고: 이렇게 하면 모든 사용자의 상위 그룹 및 하위 그룹에서 역할이 구성된 기본 멤버십 역할로 재설정됩니다.

  • 사용자에게 저장된 extern_uid를 SAML NameId 또는 SCIM externalId와 일치하도록 수동으로 수정하기 위해 SAML API 또는 SCIM API를 사용합니다.

다음을 수행하지 마십시오:

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

또한, 사용자의 주 이메일은 SCIM 식별 공급자에서의 이메일과 일치해야 합니다.

SCIM 앱 변경

SCIM 앱이 변경된 경우:

  • 사용자는 SAML 앱 변경 섹션의 지침을 따를 수 있습니다.
  • 식별 공급자의 관리자는 다음을 수행할 수 있습니다:
    1. SCIM 앱에서 사용자를 제거합니다.
      • GitLab.com에선 그룹에서 제거된 모든 사용자를 제거합니다.
      • GitLab 자체 관리에선 사용자를 차단합니다.
    2. 새로운 SCIM 앱에 대해 동기화를 켜기하여 기존 사용자 연결을 수행합니다.

SCIM 앱이 "사용자가 이미 존재합니다","status":409 오류를 반환함

Tier: 프리미엄, 얼티메이트 Offering: GitLab.com

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

이 그룹에 대해 허용되지 않은 회원 이메일 주소

SCIM 프로비저닝은 HTTP 상태 412 및 다음 오류 메시지와 함께 실패할 수 있습니다: 

이 그룹에 대해 회원의 이메일 주소가 허용되지 않았습니다. 관리자에게 문의하세요.

이 오류는 다음 두 가지 조건이 모두 참일 때 발생합니다:

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

SCIM 요청을 위한 Rails 로그 검색

Tier: 프리미엄, 얼티메이트 Offering: GitLab.com

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

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

관련 로그 항목에서 json.params.value는 GitLab에서 받은 SCIM 파라미터의 값을 보여줍니다. 이러한 값들을 사용하여 의도한대로 식별 공급자의 SCIM 앱에서 구성된 SCIM 파라미터가 GitLab에 통신되는지 확인합니다.

예를 들어 이러한 값들을 사용하여 특정한 세부정보로 계정이 프로비저닝된 이유에 대한 확실한 소스로 사용할 수 있습니다. 이 정보는 계정이 SCIM 앱 구성과 일치하지 않는 세부정보로 프로비저닝된 경우에 도움이 될 수 있습니다.

SCIM 로그의 회원 이메일 주소가 연결되지 않은 오류

GitLab.com에서 SCIM 사용자를 프로비저닝하려고 하면 GitLab은 해당 이메일 주소를 가진 사용자가 이미 존재하는지 확인합니다. 다음의 오류 메시지를 볼 수 있습니다 다음과 같이:

  • 사용자가 존재하지만 SAML ID가 연결되어 있지 않음.
  • 사용자가 존재하고 SAML ID가 있으며, SCIM ID가 active: false로 설정되어 있음. 
회원의 이메일 주소가 SAML 계정에 연결되지 않았거나 비활성화되었습니다.

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

이는 영향을 받는 최종 사용자가 계정에 올바르게 액세스할 수 없게 만들 수 있습니다.

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

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

오류가 계속되는 경우, 사용자가 이미 존재하고 SAML 및 SCIM ID가 둘 다 active: false로 설정되어 있을 가능성이 가장 높습니다. 이 문제를 해결하려면:

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

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

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

    이 정보가 일치하지 않는 경우, GitLab 지원팀에 문의하십시오.

  5. API를 사용하여 SCIM 프로비저닝된 사용자의 active 값을 true로 업데이트합니다.
  6. 업데이트가 상태 코드 204를 반환하면, 사용자가 SAML SSO를 사용하여 로그인을 시도하세요.

비활성화 작업에 대한 403 Forbidden 응답

만약 IP 주소별로 그룹 액세스 제한을 하고 있다면, SCIM 해제 프로비저닝이 다음과 같은 오류 응답으로 실패할 수 있습니다: 

{"message":"403 Forbidden"}

이는 IP 주소별 그룹 액세스 제한을 하는 경우에 알려진 문제입니다.

이 문제를 해결하려면, Group SCIM API를 사용하여 단일 SCIM 프로비저닝된 사용자를 업데이트하여 사용자의 active 상태를 false로 설정하세요.

Azure Active Directory

다음의 문제 해결 정보는 특히 Azure Active Directory를 통해 SCIM 프로비저닝된 경우에 해당됩니다.

내 SCIM 구성이 올바른지 확인

다음 사항을 확인하세요:

  • externalId의 매칭 우선순위가 1임.
  • externalId의 SCIM 값이 NameId의 SAML 값과 일치하는지 확인합니다.

합리적인 값을 위한 다음 SCIM 파라미터를 검토하세요:

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

연결 테스트 시 유효하지 않은 자격 증명 오류

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

유효하지 않은 자격 증명이 입력된 것으로 보입니다. 관리 권한 계정에 대한 올바른 정보를 사용하는지 확인하십시오.

테넌트 URL과 시크릿 토큰이 올바른 경우에도, 그룹 경로에 .과 같은 JSON 기본 요소로 간주될 수 있는 문자가 포함되어있는지 확인하세요. 이러한 문자를 제거하거나 URL 인코딩하면 일반적으로 오류가 해결됩니다.

(필드)를(을) 비워둘 수 없습니다 동기화 오류

프로비저닝의 감사 이벤트를 확인할 때, 때로는 Namespace를(을) 비워둘 수 없음, Name을(를) 비워둘 수 없음, User를(을) 비워둘 수 없음. 오류가 표시됩니다.

이 오류는 모든 필수 필드(예: 이름 및 성)가 모든 사용자에 대해 존재하지 않기 때문에 발생할 수 있습니다.

이를 해결하기 위해 대체 매핑을 시도해 보세요:

  1. Azure 매핑 지침을 따르세요.
  2. name.formatted 대상 속성 항목을 삭제하세요.
  3. displayName 소스 속성을 name.formatted 대상 속성으로 변경하세요.

소스 및 대상 시스템 그룹 '그룹 이름'에서 항목을 일치시키지 못했습니다 오류

Azure에서 그룹 프로비저닝은 ‘그룹 이름’에 해당하는 항목을 일치시키지 못하면 소스 및 대상 시스템 그룹 '그룹 이름'에서 항목을 일치시키지 못했습니다 오류가 발생할 수 있습니다. 오류 응답에는 GitLab URL https://gitlab.com/users/sign_in의 HTML 결과가 포함될 수 있습니다.

이 오류는 그룹 프로비저닝이 활성화되었지만 GitLab SCIM 통합에서 지원하지 않거나 필요하지 않기 때문에 발생하는 것으로, 오류를 제거하려면 Azure 구성 안내서의 지침을 따라서 Azure Active Directory 그룹을 AppName에 동기화하는 옵션을 해제하세요.

Okta

다음 해결책 정보는 Okta를 통해 SCIM으로 프로비저닝된 것에만 해당됩니다.

API SCIM 자격 증명을 테스트할 때 인증 오류: null 메시지

Okta SCIM 애플리케이션에서 API 자격 증명을 테스트하는 중에 다음과 같은 오류가 발생할 수 있습니다: 

인증 오류: null

Okta는 사용자를 프로비저닝하거나 비프로비저닝하기 위해 GitLab 인스턴스에 연결할 수 있어야 합니다.

Okta SCIM 애플리케이션에서 SCIM 베이스 URL이 올바르며 유효한 GitLab SCIM API 엔드포인트 URL을 가리키도록 되어 있는지 확인하세요. 이 URL에 대한 정보는 다음 문서에서 찾을 수 있습니다:

자체 관리 GitLab 인스턴스의 경우, Okta가 연결할 수 있도록 GitLab이 공개적으로 접근 가능한지 확인하세요. 필요한 경우 방화벽에서 Okta IP 주소에 액세스 권한을 허용할 수 있습니다.