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

제거된 사용자를 다시 추가할 수 없음#

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

사용자가 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 Self-Managed#

GitLab Self-Managed의 경우 해당 인스턴스의 관리자는 대신 사용자 아이덴티티를 직접 추가할 수 있습니다. 관리자가 여러 아이덴티티를 다시 추가해야 하는 경우 시간을 절약할 수 있습니다.

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

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

• 사용자가 SCIM 앱에 추가되었는지 확인합니다.
• User is not linked to a SAML account 오류가 발생하면 사용자가 이미 GitLab에 존재할 가능성이 있습니다. 사용자에게 SCIM 및 SAML 아이덴티티 연결 지침을 따르도록 안내하세요. 또는 셀프 매니지드 관리자가 사용자 아이덴티티를 추가할 수 있습니다.
• GitLab에 저장된 아이덴티티(extern_uid) 값은 id 또는 externalId가 변경될 때마다 SCIM에 의해 업데이트됩니다. SAML의 NameId와 같이 공급자가 보낸 ID와 로그인 방법의 GitLab 식별자(extern_uid)가 일치하지 않으면 사용자가 로그인할 수 없습니다. 이 값은 SCIM에서도 id의 사용자를 매칭하는 데 사용되며, id 또는 externalId 값이 변경될 때마다 SCIM에 의해 업데이트됩니다.
• GitLab.com에서 SCIM id와 SCIM externalId는 SAML NameId와 동일한 값으로 구성되어야 합니다. 디버깅 도구를 사용하여 SAML 응답을 추적하고 SAML 문제 해결 정보에 대한 오류를 확인할 수 있습니다.

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

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

• 관리자는 관리자 영역을 사용하여 사용자의 SCIM 아이덴티티 목록을 볼 수 있습니다.
• 그룹 오너는 그룹 SAML SSO 설정 페이지에서 사용자 목록과 각 사용자에 대해 저장된 식별자를 볼 수 있습니다.
• 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를 업데이트해야 합니다.

일반적으로 extern_Id인 SCIM ID 공급자가 사용하는 필드를 수정하는 경우 주의하세요. ID 공급자가 이 업데이트를 수행하도록 구성되어야 합니다. 사용자 조회가 실패하는 경우와 같이 ID 공급자가 업데이트를 수행할 수 없는 경우가 있습니다.

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

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

• SAML 인증 실패: 사용자가 이미 사용됨 섹션을 기반으로 사용자가 연결을 해제하고 다시 연결하도록 합니다.

• 프로비저닝이 켜져 있는 동안 SCIM 앱에서 모든 사용자를 제거하여 모든 사용자의 연결을 동시에 해제합니다.

  [!warning] 이렇게 하면 최상위 그룹 및 서브그룹의 모든 사용자 역할이 구성된 기본 멤버십 역할로 재설정됩니다.

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

다음은 금지됩니다:

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

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

SCIM 앱 변경#

SCIM 앱이 변경될 때:

• 사용자는 SAML 앱 변경 섹션의 지침을 따를 수 있습니다.
• ID 공급자의 관리자는 다음을 수행할 수 있습니다:
  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와 일치하는지 확인.
  2. 일치하지 않는 SCIM extern_uid 및 SAML NameId 업데이트 또는 수정.
• GitLab과 ID 공급자 SCIM 앱 간의 SCIM 아이덴티티 불일치. 이 문제를 해결하려면:
  1. SCIM API를 사용합니다. 이는 GitLab에 저장된 사용자의 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 관리자는 Kibana의 pubsub-rails-inf-gprd-* 인덱스에서 api_json.log를 사용하여 SCIM 요청을 검색할 수 있습니다. 내부 그룹 SCIM API를 기반으로 다음 필터를 사용하세요:

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

관련 로그 항목에서 json.params.value는 GitLab이 받는 SCIM 매개변수 값을 보여줍니다. 이 값을 사용하여 ID 공급자의 SCIM 앱에 구성된 SCIM 매개변수가 의도한 대로 GitLab에 전달되는지 확인하세요.

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

SCIM 로그의 멤버 이메일 주소가 연결되지 않음 오류#

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

• 사용자가 존재하지만 SAML 아이덴티티가 연결되어 있지 않습니다.
• 사용자가 존재하고 SAML 아이덴티티가 있으며, 그리고 active: false로 설정된 SCIM 아이덴티티가 있습니다.
• 사용자가 존재하지만 연결된 최상위 그룹의 멤버가 아니고 SAML SSO 강제가 활성화되어 있습니다.

The member's email address is not linked to a SAML account or has an inactive
SCIM identity.

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

이로 인해 영향을 받는 최종 사용자가 계정에 올바르게 액세스하지 못할 수 있습니다.

첫 번째 해결 방법은:

1. 최종 사용자에게 기존 GitLab.com 계정에 SAML 연결을 안내합니다.
2. 사용자가 이 작업을 완료한 후 ID 공급자에서 SCIM 동기화를 시작합니다. 동일한 오류 없이 SCIM 동기화가 완료되면 GitLab이 기존 사용자 계정에 SCIM 아이덴티티를 성공적으로 연결한 것이며, 이제 사용자가 SAML SSO를 사용하여 로그인할 수 있어야 합니다.

오류가 지속되면 사용자가 이미 존재하고 SAML 및 SCIM 아이덴티티 모두 가지고 있으며, active: false로 설정된 SCIM 아이덴티티가 있을 가능성이 높습니다. 이를 해결하려면:

1. 선택 사항. SCIM을 처음 구성할 때 SCIM 토큰을 저장하지 않은 경우 새 토큰을 생성하세요. 새 SCIM 토큰을 생성하는 경우 ID 공급자의 SCIM 구성에서 토큰을 반드시 업데이트해야 합니다. 그렇지 않으면 SCIM이 작동하지 않습니다.

2. SCIM 토큰을 찾습니다.

3. API를 사용하여 단일 SCIM 프로비저닝된 사용자를 가져옵니다.

4. 반환된 정보를 확인합니다:

   • 사용자의 식별자(id)와 이메일이 ID 공급자가 보내는 것과 일치합니다.
   • active가 false로 설정되어 있습니다.

   이 정보 중 하나라도 일치하지 않으면 GitLab 지원에 문의하세요.

5. API를 사용하여 SCIM 프로비저닝된 사용자의 active 값을 true로 업데이트합니다.

6. 업데이트가 상태 코드 204를 반환하면 사용자에게 SAML SSO를 사용하여 로그인하도록 안내합니다.

Azure Active Directory#

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

SCIM 구성이 올바른지 확인#

다음을 확인하세요:

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

다음 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 기본 URL이 올바르고 유효한 GitLab SCIM API 엔드포인트 URL을 가리키는지 확인하세요. 다음 URL에 대한 정보를 찾으려면 다음 문서를 확인하세요:

• GitLab.com 그룹.
• GitLab Self-Managed.

GitLab Self-Managed의 경우 Okta가 연결할 수 있도록 인스턴스가 공개적으로 사용 가능한지 확인하세요. 필요한 경우 방화벽에서 Okta IP 주소에 대한 액세스를 허용할 수 있습니다.