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 ID는 삭제되지 않습니다.
해당 사용자가 SCIM 앱에 다시 추가되면:

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

그 날짜 이전에 SCIM에 의해 제거된 사용자의 SAML ID는 삭제됩니다.
이 문제를 해결하기 위해 사용자는 기존 GitLab.com 계정에 SAML 링크를 추가해야 합니다.

자체 관리형 GitLab

자체 관리형 GitLab 인스턴스의 경우, 해당 인스턴스의 관리자는 대신에 사용자 ID를 직접 추가할 수 있습니다. 이는 관리자가 여러 ID를 재추가해야 할 경우 시간을 절약할 수 있습니다.

사용자가 로그인할 수 없음

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

  • 사용자가 SCIM 앱에 추가되었는지 확인합니다.
  • User is not linked to a SAML account 오류가 발생하는 경우, 사용자는 이미 GitLab에 존재할 가능성이 높습니다. 사용자가 SCIM과 SAML ID 연동 지침을 따르도록 하세요.
    또는 자체 관리형 관리자가 사용자 ID를 추가할 수 있습니다.
  • GitLab에 저장된 Identity (extern_uid) 값은 id 또는 externalId가 변경될 때마다 SCIM에 의해 업데이트됩니다. 사용자는 GitLab 식별자(extern_uid)와 제공자가 보내는 ID가 일치하지 않는 한 로그인할 수 없습니다.
    예를 들어, SAML이 보내는 NameId와 일치해야 합니다. 이 값은 SCIM이 사용자를 id에 따라 일치시키는 데도 사용되며, id 또는 externalId 값이 변경될 때마다 SCIM에 의해 업데이트됩니다.
  • GitLab.com에서는 SCIM id 및 SCIM externalId가 SAML NameId와 동일한 값으로 설정되어야 합니다. 디버깅 도구를 사용하여 SAML 응답 추적하고, SAML 문제 해결 정보를 통해 오류를 확인할 수 있습니다.

사용자의 SAML NameId가 SCIM externalId와 일치하는지 여부 확인

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

  • 관리자는 관리자 영역을 사용하여 사용자의 SCIM ID 나열할 수 있습니다.
  • 그룹 소유자는 그룹 SAML SSO 설정 페이지에서 각 사용자에 대해 저장된 ID의 목록을 볼 수 있습니다.
  • SCIM API를 사용하여 GitLab이 사용자에게 저장한 extern_uid를 수동으로 검색하고, SAML API에서 각 사용자의 값을 비교할 수 있습니다.
  • 사용자가 SAML 트레이서를 사용하고 extern_uid를 SAML NameId로 반환된 값과 비교하도록 하세요.

SCIM extern_uid와 SAML NameId 불일치

값이 변경되었거나 다른 필드에 매핑할 필요가 있는 경우, 다음은 동일한 필드에 매핑되어야 합니다:

  • extern_Id
  • NameId

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

SCIM ID 공급자가 사용하는 필드를 수정할 경우 주의해야 합니다. 일반적으로 extern_Id입니다.

ID 공급자는 이 업데이트를 수행하도록 구성되어야 합니다.

경우에 따라 ID 공급자가 업데이트를 수행할 수 없는 경우가 있습니다. 예를 들어 사용자를 조회할 수 없는 경우입니다.

GitLab은 이러한 ID를 사용하여 사용자를 조회합니다.

ID 공급자가 이러한 필드의 현재 값을 모르는 경우, 해당 공급자는 중복 사용자를 생성하거나 예상되는 작업을 완료하지 못할 수 있습니다.

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

  • 사용자가 링크를 해제하고 다시 연결하도록 하십시오. 이는 SAML 인증 실패: 사용자가 이미 사용되고 있습니다 섹션을 기반으로 합니다.

  • 프로비저닝이 켜진 상태에서 SCIM 응용 프로그램에서 모든 사용자를 제거하여 모두 동시에 연결 해제할 수 있습니다.

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

  • SAML API 또는 SCIM API를 사용하여 사용자가 저장한 extern_uid를 수동으로 수정하여 SAML NameId 또는 SCIM externalId와 일치시키십시오.

다음 사항을 하지 않아야 합니다:

  • 잘못된 값으로 업데이트하지 마십시오. 이는 사용자가 로그인할 수 없게 만듭니다.
  • 잘못된 사용자에게 값을 할당하지 마십시오. 이는 사용자가 잘못된 계정으로 로그인하게 만듭니다.

또한 사용자의 기본 이메일은 SCIM ID 공급자의 이메일과 일치해야 합니다.

SCIM 앱 변경

SCIM 앱이 변경되면:

  • 사용자는 SAML 앱 변경 섹션의 지침을 따를 수 있습니다.
  • ID 공급자의 관리자는:
    1. SCIM 앱에서 사용자를 제거할 수 있습니다. 이렇게 하면:
      • GitLab.com에서는 모든 제거된 사용자가 그룹에서 제거됩니다.
      • GitLab 자체 관리에서는 사용자가 차단됩니다.
    2. 새로운 SCIM 앱에 대해 동기화를 켜서 기존 사용자 링크를 생성할 수 있습니다.

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

Tier: Premium, Ultimate

Offering: GitLab.com

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

이 그룹에 대한 구성원의 이메일 주소는 허용되지 않습니다

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

구성원의 이메일 주소는 이 그룹에 허용되지 않습니다. 관리자에게 확인하십시오.

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

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

  • 사용자 계정의 이메일 도메인을 허용된 도메인 목록에 추가합니다.

  • 모든 도메인을 제거하여 도메인별 그룹 액세스 제한 기능을 비활성화합니다.

SCIM 요청에 대한 Rails 로그 검색

Tier: Premium, Ultimate Offering: GitLab.com

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

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

관련 로그 항목에서 json.params.value는 GitLab이 수신하는 SCIM 매개변수의 값을 보여줍니다. 이 값을 사용하여 아이덴티티 제공자의 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 아이덴티티가 있으며, SCIM 아이덴티티가 active: false로 설정된 경우입니다. 이를 해결하려면:

  1. 선택 사항. SCIM을 처음 구성할 때 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 주소로 그룹 액세스를 제한할 때 발생하는 알려진 문제입니다.

이 문제를 해결하기 위해, 그룹 SCIM API를 사용하여

단일 SCIM 프로비저닝된 사용자 업데이트

를 통해 사용자의 active 상태를 false로 설정하세요.

Azure Active Directory

다음 문제 해결 정보는 Azure Active Directory를 통해 프로비저닝된 SCIM에 대해 특별히 제공됩니다.

내 SCIM 구성 확인하기

다음 사항을 확인하세요:

  • externalId의 일치 우선순위는 1입니다.
  • externalId에 대한 SCIM 값은 SAML 값인 NameId와 일치해야 합니다.

다음 SCIM 매개변수가 정상적인 값인지 검토하세요:

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

연결 테스트 시 invalid credentials 오류

연결 테스트 시 다음과 같은 오류가 발생할 수 있습니다:

You appear to have entered invalid credentials. Please confirm
you are using the correct information for an administrative account

Tenant URL 및 secret token이 올바른 경우, 그룹 경로에

유효하지 않은 JSON 기본형으로 간주될 수 있는 문자가 포함되어 있는지 확인하세요 (예: .).

그룹 경로에서 이러한 문자를 제거하거나 URL 인코딩하면 일반적으로 오류가 해결됩니다.

(Field) can't be blank 동기화 오류

프로비저닝의 감사 이벤트를 확인할 때 때때로

Namespace can't be blank, Name can't be blank, and User can't be blank. 오류를 볼 수 있습니다.

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

해결 방법으로는 다른 매핑을 시도하세요:

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

name.formatted 대상 속성으로 변경하세요.

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에 대한 정보는 다음 문서를 참조하세요:

self-managed GitLab 인스턴스의 경우, Okta가 연결할 수 있도록 GitLab이 공개적으로 사용 가능해야 합니다. 필요 시, 방화벽에서

Okta IP 주소에 대한 액세스를 허용 할 수 있습니다.