메인 콘텐츠로 건너뛰기
SCIM Provisioning은 비공개 프리뷰입니다.
ClickHouse Cloud는 사용자와 그룹의 수명 주기를 자동으로 관리할 수 있도록 SCIM 2.0(System for Cross-domain Identity Management)을 지원합니다. IdP(Identity Provider)에 연결하면 ClickHouse Cloud 애플리케이션에 할당한 모든 사용자가 조직에 자동으로 생성되고 적절한 역할이 부여됩니다. 또한 프로필 업데이트도 자동으로 반영되며, IdP에서 사용자를 제거하면 해당 사용자의 접근 권한도 함께 제거됩니다 — 수동으로 초대할 필요도 없고, 고아 계정이 남을 일도 없습니다. 이 가이드에서는 Okta를 사용해 SCIM Provisioning을 처음부터 끝까지 설정하는 방법을 설명합니다. ClickHouse Cloud SCIM endpoint는 SCIM 2.0(RFC 7644)을 따르지만 authentication은 Basic Auth를 통해서만 지원되며, 테스트를 거친 IdP(Identity Provider)는 Okta뿐입니다. 다른 SCIM 2.0 IdP도 Basic Auth로 authentication할 수 있다면 작동할 수 있지만, 현재는 공식 지원 대상이 아닙니다.

​
시작하기 전에

다음이 필요합니다.
  • ClickHouse Cloud 조직에서 관리자 역할이 있어야 합니다.
  • IdP와 ClickHouse Cloud 간에 SAML SSO가 이미 구성되어 있어야 합니다. SCIM이 사용자 계정을 생성하고, 해당 계정은 SAML을 통해 로그인하므로 SSO가 먼저 정상적으로 작동해야 합니다.
  • 애플리케이션 설치 및 Provisioning 구성 권한이 있는 Okta 테넌트의 super-admin 액세스
  • SCIM을 통해 할당할 역할 목록(예: Admins, Developers, 읽기 전용). 이 목록은 미리 정해 두십시오. Okta에서 이에 맞는 그룹을 생성하게 됩니다.

​
SCIM이 ClickHouse Cloud에서 작동하는 방식

  1. Okta의 관리자가 사용자를 직접 또는 그룹을 통해 ClickHouse Cloud 애플리케이션에 할당합니다.
  2. Okta는 생성한 토큰으로 인증한 후 HTTPS를 통해 ClickHouse Cloud SCIM 엔드포인트를 호출합니다.
  3. ClickHouse Cloud는 조직에 사용자를 생성하고 Okta 그룹 멤버십에 따라 역할을 할당합니다.
  4. 사용자는 기존 SAML SSO 흐름을 통해 ClickHouse Cloud에 로그인합니다.
  5. Okta에서의 프로필 변경, 그룹 변경, 비활성화는 ClickHouse Cloud에 자동으로 반영됩니다.

​
ClickHouse Cloud 조직에서 SCIM 구성하기

1

​
SCIM 활성화

조직 관리자로 ClickHouse Cloud 콘솔에 로그인한 후 조직 설정 → SAML 및 SCIM 설정 → SCIM 구성을 엽니다.Enable SCIM을 클릭합니다. SAML SSO가 연결되면 SCIM이 활성화됩니다. 옵션이 회색으로 비활성화되어 있으면 먼저 SAML 설정을 완료하십시오.다음 형식의 SCIM endpoint URL이 생성됩니다.
복사해 두십시오. 나중에 Okta에 붙여 넣어야 합니다.
2

​
SCIM 액세스 토큰 생성

Create an API key 섹션을 찾아 만료 날짜를 선택합니다.
토큰 교체를 미리 계획하십시오. 만료 기간은 12개월로 설정하고 캘린더 알림을 추가하는 것이 좋습니다. ClickHouse Cloud는 동시에 최대 2개의 활성 SCIM 토큰을 지원하므로 중단 없이 교체할 수 있습니다. 새 토큰을 생성하고, Okta를 새 토큰으로 전환하고, 프로비저닝이 계속 작동하는지 확인한 다음, 기존 토큰을 철회하십시오.
Generate key를 클릭합니다. 토큰은 키(scim_ 접두사 포함)와 시크릿 형태로 한 번만 표시됩니다. 둘 다 즉시 복사하여 안전한 시크릿 관리자에 저장하십시오. 나중에 다시 확인할 수 없습니다. 분실한 경우 해당 토큰을 철회하고 새로 생성하십시오.
3

​
역할 매핑 정의

SCIM 구성 패널에서 역할 매핑을 클릭합니다(또는 Users and roles → Roles로 직접 이동합니다).SCIM 그룹은 이름을 기준으로 ClickHouse Cloud 역할에 연결되며, 다음 규칙을 염두에 두어야 합니다.
  • SCIM 그룹은 미리 정의된 시스템 역할에 매핑할 수 없습니다. SCIM 매핑은 사용자 지정 역할에만 적용됩니다. SCIM을 통해 시스템 수준 기능을 노출해야 한다면, 필요한 권한을 포함하는 사용자 지정 역할을 생성하십시오.
  • 이름이 일치하면 자동으로 연결됩니다. 사용자 지정 역할의 이름이 들어오는 SCIM 그룹 이름과 같으면 ClickHouse Cloud가 자동으로 연결하므로 수동 매핑이 필요하지 않습니다.
  • 그룹 이름과 다른 역할 이름을 사용하려면 원하는 역할 이름으로 사용자 지정 역할을 생성한 다음, 해당 역할의 SCIM group 필드를 연결할 SCIM 그룹 이름으로 설정하십시오.
  • 매핑되지 않은 그룹은 새 역할을 생성합니다. Okta가 기존 역할 이름과 일치하지 않고 어떤 역할의 SCIM group 필드에서도 참조되지 않는 그룹을 푸시하면, ClickHouse Cloud는 해당 그룹 이름으로 새 사용자 지정 역할을 생성합니다. 그런 다음 원하는 권한을 부여할 수 있습니다.

​
Okta에서 ClickHouse Cloud 애플리케이션 구성하기

1

​
Okta에서 ClickHouse Cloud 애플리케이션 열기

Okta Admin Console에서 Applications → Applications로 이동한 후, ClickHouse Cloud용 SAML SSO를 설정할 때 생성한 애플리케이션을 검색합니다. 해당 애플리케이션을 엽니다.아직 SAML 애플리케이션을 만들지 않았다면 먼저 SAML SSO 설정 가이드를 따르십시오. SCIM 프로비저닝은 동일한 애플리케이션에서 구성합니다.General 탭에서 App Settings 섹션을 찾아 Edit를 클릭하십시오. Provisioning 아래에서 SCIM을 선택한 다음 Save를 클릭하십시오.이제 애플리케이션에 Provisioning 탭이 표시됩니다.
2

​
SCIM 엔드포인트에 Okta 연결

애플리케이션의 Provisioning 탭을 열고 Edit를 클릭합니다. 양식을 다음과 같이 입력합니다.
  • SCIM connector base URL — 앞서 확인한 SCIM 엔드포인트 URL입니다.
  • 사용자용 고유 식별자 필드 — userName.
  • 지원되는 프로비저닝 작업 — 다음 항목을 모두 선택합니다.
    • 새 사용자 가져오기 및 프로필 업데이트
    • 새 사용자 Push
    • 프로필 업데이트 Push
    • 그룹 Push
    • 그룹 가져오기
  • 인증 모드 — Basic Auth.
    • Username — SCIM 토큰 key입니다(scim_로 시작).
    • Password — SCIM 토큰 secret입니다.
Test Connector Configuration을 클릭합니다. 녹색 확인 표시가 나타나야 합니다. 실패하면 문제 해결로 이동하십시오.Save를 클릭합니다.
3

​
Provisioning 동작 구성

계속해서 Provisioning 탭에서 왼쪽 사이드바의 To App을 클릭합니다. Edit를 클릭한 후 다음 항목을 활성화합니다:Save를 클릭한 다음 애플리케이션의 Sign On / Provisioning 탭으로 돌아가 설정이 적용되었는지 확인합니다.
4

​
사용자 속성 매핑

Okta와 ClickHouse Cloud는 사용자 필드의 매핑 방식에 대해 동일하게 설정되어 있어야 합니다. Provisioning 탭에서 To App을 클릭하고 애플리케이션의 Attribute Mappings를 검토하십시오. Okta SAML 애플리케이션의 기본값은 보통 그대로 사용해도 되지만, 아래 표를 확인하십시오.부서, 관리자, 위치와 같은 선택적 속성도 추가할 수 있습니다. ClickHouse Cloud는 이를 사용자 프로필에 저장하지만 현재는 권한에 사용하지 않습니다. SCIM 표준 항목에 포함되지 않은 값은 ClickHouse Cloud 측에서 무시됩니다.
이메일의 대소문자는 중요합니다. Okta userName과 email이 동일한 대소문자를 사용하도록 하십시오. ClickHouse Cloud는 이메일을 소문자로 정규화하므로, 두 필드의 대소문자가 일치하지 않으면 테스트가 실패할 수 있습니다.
5

​
그룹 푸시 및 사용자 할당

이 단계에서 역할이 자동으로 적용됩니다.Okta에서 그룹을 생성합니다. 앞서 설정한 각 역할 매핑마다 정확히 동일한 표시 이름을 사용하는 Okta 그룹을 생성하거나 기존 그룹을 확인합니다. 예를 들어 매핑이 ClickHouse-Admins → Admin이라면, Okta에서 ClickHouse-Admins라는 그룹을 생성합니다.방금 생성한 그룹을 열고 Assign people을 클릭해 구성원을 추가합니다.그런 다음 동일한 그룹에 SCIM 애플리케이션도 연결하여 역할 멤버십과 애플리케이션 액세스가 동기화된 상태로 유지되도록 합니다.그룹을 Push합니다. 애플리케이션의 Provisioning 탭에서 Push Groups → Find groups by name을 클릭하고 그룹을 검색한 다음 Save를 클릭합니다. 각 역할 그룹에 대해 이 과정을 반복합니다. Provisioning이 완료되면 각 그룹의 Push Status가 **Active (Pushed)**로 표시되어야 합니다.사용자를 할당합니다. 두 가지 방법이 있습니다.
  • 그룹을 통해(권장). 방금 Push한 Okta 그룹에 사용자를 추가합니다. 그러면 ClickHouse Cloud에 프로비저닝되고, 해당 역할이 자동으로 할당됩니다.
  • 직접 할당. 애플리케이션의 Assignments 탭에서 Assign → Assign to People을 클릭하고 개별 사용자를 선택합니다. Push된 그룹에도 속해 있지 않다면 Default role로 프로비저닝됩니다.
그룹 기반 할당 방식이 지속적인 관리에 더 깔끔합니다. 사용자의 역할이 바뀌면 그룹 멤버십만 업데이트하면 됩니다.

​
통합 테스트

Provisioning 구성을 마치면 ClickHouse Cloud 콘솔의 Settings → Users and roles로 돌아가 동기화된 사용자가 예상한 역할로 표시되는지 확인합니다. 전체 팀을 할당하기 전에 테스트 사용자 1~2명으로 이 간단한 테스트 계획을 진행하십시오. 각 단계는 몇 초 안에 성공해야 합니다. 그렇지 않다면 Okta Tasks 큐와 Troubleshooting 섹션을 확인하십시오. 어느 단계에서든 실패하면 계속 진행하기 전에 근본 원인을 해결하십시오. 증상은 대개 연쇄적으로 악화됩니다.
Okta에서 SCIM 오류를 확인할 위치. SCIM 오류는 애플리케이션으로 필터링한 Reports → System Log와 애플리케이션의 Provisioning → View Logs 화면에 표시됩니다. ClickHouse Cloud가 반환한 오류 메시지가 그대로 표시되므로, 먼저 그 내용을 확인하십시오.

​
운영 환경을 위한 모범 사례

토큰을 정기적으로 교체하세요. SCIM 토큰 교체를 위한 캘린더 알림을 설정하십시오. 권장 주기는 12개월마다 1회이며, 토큰을 알고 있던 관리자가 회사를 떠나는 경우에는 즉시 교체하는 것이 좋습니다. ClickHouse Cloud는 조직마다 활성 토큰 2개를 허용하므로 Provisioning을 중단하지 않고 토큰을 교체할 수 있습니다. 직접 할당 대신 그룹을 사용하세요. 사용자를 애플리케이션에 직접 할당해도 동작하지만, 금방 감사하기 어려워집니다. Okta 그룹을 통해 할당을 관리하면 액세스 검토와 역할 변경을 한곳에서 처리할 수 있습니다. 감사 로그를 검토하세요. 사용자 생성, 사용자 비활성화, 프로필 업데이트 등 모든 SCIM 작업은 ClickHouse Cloud 감사 로그에 기록됩니다. 감사 로깅을 참조하십시오. 특히 대규모 Provisioning이 한꺼번에 수행된 후에는 로그를 주기적으로 확인하십시오. 적절한 기본 역할을 설정하세요. Okta 사용자가 애플리케이션에 할당되었지만 푸시된 어떤 그룹에도 속하지 않으면 기본 역할로 생성됩니다. 잘못된 구성에도 안전하게 대응할 수 있도록, 사용자가 최소한의 작업은 수행할 수 있으면서도 가장 제한적인 역할을 선택하십시오. SCIM과 수동 초대를 동시에 사용하지 마세요. SCIM을 활성화한 후에는 Okta를 통해 멤버십을 관리하고, 동일한 사용자에게 수동 초대를 함께 보내지 마십시오. 두 방식을 혼용하면 어느 쪽이 기준 정보인지 혼란이 생기고 중복이 발생할 수 있습니다. 실패한 Provisioning 작업을 모니터링하세요. Okta는 실패한 Provisioning 호출을 재시도하지만, 결국 이를 Tasks 큐에 보류합니다. IT 팀이 이미 모니터링하는 대시보드에 이 큐를 추가하거나, Okta의 웹훅 또는 이메일 알림을 사용해 지속적인 실패를 감지하십시오.

​
문제 해결

​
Okta에서 “커넥터 구성 테스트”가 실패합니다

  • ClickHouse Cloud 콘솔에서 SCIM이 활성화되어 있는지 확인하세요.
  • Okta의 기준 URL이 Cloud Console에 표시된 SCIM 엔드포인트 URL과 정확히 일치하는지 확인하세요 — 조직 ID가 정확해야 합니다.
  • 토큰 키와 시크릿을 앞뒤 공백 없이 붙여넣었는지 확인하세요.
  • 토큰을 교체했다면 이전 쌍이 아니라 새 키와 시크릿을 사용하고 있는지 확인하세요.

​
사용자가 생성되지만 권한이 없습니다

  • 예상한 역할에 대해 “Users and roles”의 역할 매핑 아래에 행이 추가되어 있는지 확인하세요.
  • Okta 그룹 이름이 대소문자와 하이픈까지 포함해 매핑에 있는 SCIM 그룹 이름과 정확히 일치하는지 확인하세요.
  • 설계상 일부 사용자를 그룹 없이 의도적으로 프로비저닝하는 경우 기본 역할이 설정되어 있는지 확인하세요.

​
멤버 목록에 중복 사용자 표시

일반적으로 Okta와 이전에 수동으로 보낸 초대 간 이메일 대소문자 표기가 일치하지 않을 때 발생합니다. Members 목록에서 중복 항목을 제거한 다음, Okta에서 해당 사용자 할당을 해제했다가 다시 할당하여 새로 프로비저닝하십시오.

​
그룹 푸시가 “displayName not recognised” 오류로 실패합니다

Okta의 그룹 이름이 ClickHouse Cloud에 구성된 매핑과 일치하지 않습니다. Okta 그룹 이름을 변경하거나 SCIM 구성 패널의 역할 매핑에서 매핑을 추가하십시오(또는 Users and roles → Roles를 통해 추가할 수 있습니다).

​
비활성화된 사용자가 여전히 구성원으로 표시됩니다

Okta에서 비활성화 상태가 반영되기까지 최대 1분이 걸릴 수 있습니다. 몇 분이 지나도 사용자가 여전히 구성원으로 남아 있으면, 비활성화 작업에서 오류가 발생했는지 Okta의 Provisioning → View Logs에서 확인하십시오.

​
SCIM 토큰을 교체한 후 Okta가 작동하지 않습니다

Okta에서 동일한 SCIM 애플리케이션의 자격 증명을 업데이트했는지 확인하세요. 업데이트한 후 Test Connector Configuration을 클릭해 확인하십시오. Provisioning 상태가 다시 녹색으로 돌아오면 ClickHouse Cloud 콘솔에서 이전 토큰을 무효화하십시오.

​
SCIM 토큰을 분실했습니다

토큰은 복구할 수 없습니다. ClickHouse Cloud 콘솔의 조직 설정 → SAML 및 SCIM 설정 → SCIM 구성에서 분실한 토큰을 해지하고 새 토큰을 생성한 다음, Okta의 자격 증명을 업데이트하십시오.

​
자주 묻는 질문

SCIM을 사용하려면 먼저 SAML SSO를 설정해야 합니까? 예. SCIM은 사용자 계정을 생성하지만, ClickHouse Cloud는 SAML을 통해 이를 인증합니다. 먼저 SAML SSO를 설정하십시오. SCIM은 Microsoft Entra ID, OneLogin 또는 다른 SCIM 2.0 IdP에서 작동합니까? 공식적으로는 그렇지 않습니다 — 현재 테스트를 거쳐 지원하는 유일한 IdP는 Okta입니다. endpoint는 SCIM 2.0(RFC 7644)을 따르지만, 인증 방식이 Basic Auth로 제한되므로 Basic Auth로 인증할 수 없는 IdP는 사용할 수 없습니다. Basic Auth를 지원하는 다른 SCIM 2.0 IdP도 실제로는 작동할 수 있지만, 이를 보장하지는 않습니다. Okta의 변경 사항은 얼마나 빨리 ClickHouse Cloud에 반영됩니까? 대부분의 작업은 몇 초 내에 반영됩니다. 대량 변경(대규모 그룹 푸시)은 규모에 따라 더 오래 걸릴 수 있지만, 일시적인 오류가 발생하면 Okta가 자동으로 재시도합니다. 하나의 Okta 테넌트에서 여러 ClickHouse Cloud 조직을 Provisioning할 수 있습니까? 예 — 조직마다 고유한 SCIM endpoint URL과 token을 사용해 애플리케이션을 각각 한 번씩 설치하십시오. 필요에 따라 동일한 Okta 그룹을 각 애플리케이션에 푸시하면 됩니다. 진행이 막혔을 때는 어디에서 도움을 받을 수 있습니까? ClickHouse Cloud 콘솔에서 지원 티켓을 여십시오(Help → Contact support). 다음 내용을 포함해야 합니다:
  • 조직 ID,
  • Okta 애플리케이션 ID,
  • Okta 로그에서 실패한 작업 또는 테스트의 스크린샷.
마지막 수정일 2026년 6월 12일