SCIM 프로비저닝 문제 해결

SCIM 프로비저닝 문제 해결 (Troubleshoot SCIM provisioning)

HCP(HashiCorp Cloud Platform)에서 SCIM(시스템 간 아이덴티티 관리) 프로비저닝과 관련한 일반적인 문제의 해결 방법을 설명해 드릴게요. SCIM 프로비저닝에 대한 자세한 내용은 SCIM provisioning 문서를 참고하세요.

출처: 문서

본문

동기화 실패 (Sync failures)

SCIM 동기화 실패는 여러 가지 이유로 발생할 수 있어요. 다음 섹션에서 일반적인 원인과 해결 단계를 설명할게요.

일반적인 원인

  • 잘못된 SCIM 토큰 — SCIM 토큰이 만료됐거나 다시 생성됐을 수 있어요.
  • 네트워크 연결 문제 — 아이덴티티 제공자가 HCP SCIM 엔드포인트에 도달할 수 없어요.
  • SCIM 할당량 초과 — 조직이 사용자, 그룹, 또는 그룹 멤버 수의 최대 한도에 도달했어요.
  • 속성 매핑 오류 — 필수 속성이 누락되었거나 잘못 매핑됐어요.

진단 방법

  1. HCP에서 SCIM 프로비저닝 상태를 확인해요.
    • https://portal.cloud.hashicorp.com에 로그인하고 조직으로 이동해요.
    • Organization settings를 클릭한 다음 SCIM provisioning을 클릭해요.
    • 동기화 상태와 오류 메시지를 검토해요.
  2. 오류 메시지를 확인하려면 아이덴티티 제공자의 프로비저닝 로그를 확인해요.
  3. SCIM 토큰이 유효하고 다시 생성되지 않았는지 확인해요.
  4. 아이덴티티 제공자가 HCP SCIM 엔드포인트에 도달할 수 있는지 확인해요.

해결 단계

  • SCIM 토큰이 유효하지 않다면 HCP에서 새 토큰을 생성하고 아이덴티티 제공자에서 갱신해요.
  • 할당량 한도에 도달했다면 HashiCorp 지원팀에 문의해 한도 상향을 요청해요.
  • 속성 매핑이 잘못됐다면 SCIM 프로비저닝 문서에 따라 아이덴티티 제공자에서 수정해요.
  • 네트워크 연결 문제라면 아이덴티티 제공자가 https://api.cloud.hashicorp.com에 도달할 수 있는지 확인해요.

속성 매핑 오류 (Attribute mapping errors)

속성 매핑 오류는 필수 사용자 또는 그룹 속성이 아이덴티티 제공자에서 누락되었거나 잘못 구성됐을 때 발생해요.

일반적인 속성 문제

  • 필수 속성 누락 — userName, emails, name.givenName, name.familyName 속성이 매핑되지 않았어요.
  • 잘못된 속성 형식 — 속성이 잘못된 SCIM 필드에 매핑됐어요.
  • 지원되지 않는 속성 — 아이덴티티 제공자가 HCP가 지원하지 않는 속성을 보내고 있어요.

프로바이더별 고려 사항

Microsoft Entra ID:

  • 지원되지 않는 기본 속성 매핑을 제거했는지 확인해요.
  • 이메일 식별자가 User principal name 필드가 아니라 Contact information 아래의 Email 필드에서 도출되는지 확인해요.
  • HCP는 Entra ID 전용 Base URL을 생성해요. IdP에 올바른 Base URL을 복사했는지 확인해요. 자세한 내용은 HCP에서 SCIM 프로비저닝 활성화 문서를 참고하세요.

Okta:

  • API 토큰에 Bearer 접두어가 포함되어 있는지 확인해요.
  • Create users, Update User Attributes, Deactivate Users가 활성화되어 있는지 확인해요.

올바른 매핑 확인 방법

  • 아이덴티티 제공자의 속성 매핑을 검토해요.
  • SCIM 프로비저닝 문서의 속성 매핑 표와 비교해요.
  • 모든 필수 속성이 매핑됐는지 확인해요.
  • 지원되지 않는 속성 매핑을 제거해요.

SCIM 할당량 초과 오류 (SCIM quota exceeded errors)

HCP는 최적의 성능을 보장하기 위해 SCIM 프로비저닝에 할당량을 적용해요. 할당량을 초과하면 영향받는 리소스 유형에 대해 SCIM 동기화가 실패해요.

할당량 한도 이해하기

현재 할당량 한도는 HCP 지원 페이지를 참고하세요.

현재 사용량 확인 방법

  1. https://portal.cloud.hashicorp.com에 로그인하고 조직으로 이동해요.
  2. Access control (IAM) 을 클릭해요.
  3. 현재 사용자 수를 확인하려면 Users를, 현재 그룹 수를 확인하려면 Groups를 클릭해요.

한도 증가 지원 요청

조직에 더 높은 한도가 필요하다면 다음 정보와 함께 HashiCorp 지원팀에 문의해요.

  • 조직 ID
  • 현재 할당량 한도
  • 요청하는 할당량 한도
  • 증가에 대한 비즈니스 사유

사용자 또는 그룹이 동기화되지 않음 (User or group not syncing)

특정 사용자나 그룹이 아이덴티티 제공자에서 HCP로 동기화되지 않는다면 다음 문제 해결 단계를 완료해요.

SCIM 활성화 확인

  1. https://portal.cloud.hashicorp.com에 로그인하고 조직으로 이동해요.
  2. Organization settings를 클릭한 다음 SCIM provisioning을 클릭해요.
  3. SCIM 프로비저닝이 활성화되어 있고 상태가 active인지 확인해요.

아이덴티티 제공자 할당 확인

  1. 아이덴티티 제공자에 로그인해요.
  2. HCP 애플리케이션으로 이동해요.
  3. 사용자나 그룹이 애플리케이션에 할당되어 있는지 확인해요.
  4. 할당되어 있지 않다면 할당하고 다음 동기화 주기를 기다려요.

속성 매핑 확인

  • 아이덴티티 제공자에서 사용자나 그룹에 대한 속성 매핑을 검토해요.
  • 모든 필수 속성이 있고 올바르게 형식화되었는지 확인해요.
  • 사용자의 경우 이메일 주소가 유효하고 고유한지 확인해요.

SCIM 프로비저닝 상태 확인

  1. HCP에서 Users 또는 Groups로 이동해요.
  2. 목록에서 사용자나 그룹을 찾아요.
  3. SCIM provisioning 열에서 상태를 확인해요.
  4. IdP가 SCIM으로 사용자나 그룹을 관리하면 상태는 Synced예요. 다른 상태는 HCP에 대한 접근이 IdP를 통해 관리되더라도 해당 사용자나 그룹이 HCP에서 관리되고 있음을 나타내요.

중복 사용자 또는 그룹 (Duplicate users or groups)

SCIM 프로비저닝을 활성화했을 때 기존 HCP 리소스와 충돌하면 중복 사용자나 그룹이 발생할 수 있어요.

충돌 처리 이해하기

SCIM 프로비저닝을 활성화하면 HCP는 아이덴티티 제공자 디렉터리를 확인해 HCP에 이미 있는 사용자나 그룹이 있는지 판단해요.

  • 사용자의 경우 — HCP와 아이덴티티 제공자 양쪽에 같은 이메일 주소의 사용자가 있다면, SCIM은 HCP의 SSO 기반 사용자만 관리해요.
  • 그룹의 경우 — HCP와 아이덴티티 제공자 양쪽에 같은 이름의 그룹이 있다면, 아이덴티티 제공자 그룹이 우선해서 기존 HCP 그룹을 대체해요.

중복이 발생하는 방식

다음 시나리오에서 중복이 발생할 수 있어요.

  • SCIM을 활성화하기 전에 사용자나 그룹이 HCP에 존재했지만 이메일 주소나 이름이 정확히 일치하지 않는 경우
  • SCIM 활성화 후 HCP에서 사용자나 그룹을 수동으로 생성한 경우
  • 여러 아이덴티티 제공자 사용자가 같은 이메일 주소를 가진 경우

해결 단계

  1. HCP에서 중복 사용자나 그룹을 식별해요.
  2. 어떤 사용자나 그룹이 진실 원천(source of truth)이어야 하는지 결정해요.
  3. 아이덴티티 제공자가 진실 원천이어야 한다면 HCP에서 중복을 제거해요.
  4. HCP가 진실 원천이어야 한다면 아이덴티티 제공자에서 중복을 제거해요.
  5. 다음 동기화 주기가 완료될 때까지 기다려요.

토큰 인증 실패 (Token authentication failures)

토큰 인증 실패는 SCIM 토큰이 아이덴티티 제공자에서 유효하지 않거나, 만료됐거나, 잘못 구성됐을 때 발생해요.

토큰 만료

SCIM 토큰은 자동으로 만료되지 않지만 HCP에서 다시 생성할 수 있어요. 토큰을 다시 생성했다면 아이덴티티 제공자에서도 갱신해야 해요.

토큰 재생성 단계

  1. https://portal.cloud.hashicorp.com에 로그인하고 조직으로 이동해요.
  2. Organization settings를 클릭한 다음 SCIM provisioning을 클릭해요.
  3. Generate SCIM token을 클릭해요.
  4. 새 토큰 값을 복사해요.
  5. 아이덴티티 제공자에서 토큰을 갱신해요.

아이덴티티 제공자에서 토큰 갱신

Microsoft Entra ID:

  1. Microsoft Entra 관리 센터에 로그인해요.
  2. HCP 애플리케이션으로 이동해요.
  3. Provisioning을 클릭한 다음 Admin credentials를 클릭해요.
  4. Secret token 필드를 새 토큰으로 갱신해요.
  5. 확인하려면 Test Connection을 클릭해요.
  6. Save를 클릭해요.

Okta:

  1. Okta에 로그인해요.
  2. HCP 애플리케이션으로 이동해요.
  3. Provisioning 탭을 클릭해요.
  4. API Integration 섹션에서 Edit을 클릭해요.
  5. API Token 필드를 Bearer 다음에 새 토큰을 붙여 갱신해요.
  6. 확인하려면 Test API Credentials를 클릭해요.
  7. Save를 클릭해요.

프로바이더별 문제 (Provider-specific issues)

다음 섹션은 지원되는 각 아이덴티티 제공자에 특정한 일반적인 문제를 설명해요.

Microsoft Entra ID

기능 플래그 요구 사항: Microsoft Entra ID는 Base URL에 기능 플래그를 추가해야 해요. 이 플래그를 포함하지 않으면 SCIM 프로비저닝이 실패해요.

  • 해결 방법: Tenant URL 필드의 Base URL 끝에 ?aadOptscim062020을 추가했는지 확인해요. 예: https://api.cloud.hashicorp.com/scim/v2/organizations/YOUR_ORG_ID?aadOptscim062020

지원되지 않는 속성 필드: Microsoft Entra ID에는 HCP가 지원하지 않는 기본 속성 매핑이 포함돼 있어요. 이 매핑을 제거하지 않으면 SCIM 프로비저닝이 실패하거나 예상치 못한 결과가 발생할 수 있어요.

  • 해결 방법: SCIM 프로비저닝 문서에 나열되지 않은 속성 매핑을 모두 제거해요. 사용자와 그룹에 대한 지원되는 속성만 포함해요.

이메일 필드 구성: 각 사용자의 이메일 식별자는 Microsoft Entra ID의 Contact information 아래 Email 필드에서 도출해야 해요. User principal name 필드의 업데이트는 HCP에 반영되지 않아요.

  • 해결 방법: 속성 매핑에서 mail 속성이 emails[type eq 'work'].value에 매핑되어 있는지 확인해요.

Okta

API 통합 요구 사항: Okta는 API Token 필드에서 SCIM 토큰 앞에 Bearer 접두어를 붙여야 해요. 이 접두어를 포함하지 않으면 인증이 실패해요.

  • 해결 방법: API Token 필드에 Bearer 다음에 SCIM 토큰이 포함되어 있는지 확인해요. 예: Bearer your-scim-token-here

프로비저닝 옵션 구성: Okta는 SCIM이 올바르게 동작하려면 특정 프로비저닝 옵션이 활성화되어야 해요. 이 옵션들이 활성화되어 있지 않으면 사용자와 그룹이 동기화되지 않아요.

  • 해결 방법: Provisioning 탭에서 다음 옵션이 활성화되어 있는지 확인해요.
    • Create users
    • Update User Attributes
    • Deactivate Users

Ping ID

일반적인 구성 문제: Ping ID 구성 문제는 일반적으로 잘못된 Base URL 또는 SCIM 토큰 값과 관련돼요.

  • 해결 방법: HCP에서 가져온 Base URL과 SCIM 토큰을 Ping ID 구성에 올바르게 입력했는지 확인해요. 자세한 구성 단계는 Ping ID 문서를 참고하세요.

IBM Verify

일반적인 구성 문제: IBM Verify 구성 문제는 일반적으로 잘못된 Base URL 또는 SCIM 토큰 값과 관련돼요.

  • 해결 방법: HCP에서 가져온 Base URL과 SCIM 토큰을 IBM Verify 구성에 올바르게 입력했는지 확인해요. 자세한 구성 단계는 IBM Verify 지원팀에 문의하거나 IBM Verify 문서를 참고하세요.

지원 받기 (Get support)

이 문서의 문제 해결 단계를 따른 뒤에도 SCIM 프로비저닝 문제가 계속 발생한다면 HashiCorp 지원팀에 문의해요.

지원팀에 문의할 때 다음 정보를 제공해요.

  • HCP 조직 ID
  • 사용 중인 아이덴티티 제공자
  • 문제에 대한 설명
  • HCP 또는 아이덴티티 제공자의 오류 메시지
  • 이미 수행한 문제 해결 단계
  • SCIM 구성 스크린샷 (민감 정보는 가려주세요)

SCIM 프로비저닝에 대한 자세한 내용은 SCIM provisioning 문서를 참고하세요.

더 알아보기 (Learn more)