Skip to main content
ClickHouse Cloud는 사용자 및 그룹의 수명 주기를 자동으로 관리할 수 있도록 SCIM 2.0(System for Cross-domain Identity Management)을 지원합니다. IdP(Identity Provider)에 연결하면 ClickHouse Cloud 애플리케이션에 할당한 모든 사용자가 적절한 역할로 조직에 자동 생성되고, 프로필 업데이트도 자동으로 반영됩니다. 또한 IdP에서 사용자를 제거하면 해당 사용자의 액세스 권한도 삭제되므로 수동 초대나 미사용 계정이 남지 않습니다. 이 가이드에서는 Microsoft Entra ID(이전 명칭: Azure Active Directory)를 사용하여 SCIM provisioning을 처음부터 끝까지 설정하는 방법을 안내합니다. ClickHouse Cloud SCIM endpoint는 SCIM 2.0(RFC 7644)을 따릅니다. Entra ID는 ClickHouse Cloud 콘솔에서 생성한 SCIM 토큰 key와 시크릿을 조합해 만든 장기 Bearer token으로 endpoint를 인증합니다.
Okta를 사용하시나요?IdP가 Okta인 경우 Okta를 사용한 SCIM provisioning 가이드를 따르십시오. ClickHouse Cloud 측 설정은 동일하며 IdP 구성만 다릅니다.

​
시작하기 전에

다음이 필요합니다.
  • ClickHouse Cloud 조직의 관리자 역할
  • Entra ID와 ClickHouse Cloud 간에 SAML SSO가 이미 구성되어 있어야 합니다. SCIM이 사용자 계정을 생성하고, 해당 계정은 SAML을 통해 로그인하므로 먼저 SSO가 작동해야 합니다.
  • 엔터프라이즈 애플리케이션의 Provisioning을 구성할 권한이 있으며, 최소 Application Administrator(또는 Cloud Application Administrator) 역할이 부여된 Microsoft Entra admin center에 대한 액세스
  • SCIM을 통해 할당할 역할 목록(예: Admins, Developers, Read-only). Entra ID에서 해당 역할에 맞는 그룹을 생성하므로 미리 결정해야 합니다.

​
SCIM이 ClickHouse Cloud와 작동하는 방식

  1. Entra ID 관리자가 사용자에게 직접 또는 그룹을 통해 ClickHouse Cloud 엔터프라이즈 애플리케이션을 할당합니다.
  2. Entra ID의 프로비저닝 서비스가 생성한 Bearer token으로 인증한 후 HTTPS를 통해 ClickHouse Cloud SCIM endpoint를 호출합니다.
  3. ClickHouse Cloud가 organization에 사용자를 생성하고 Entra ID 그룹 멤버십에 따라 역할을 할당합니다.
  4. 사용자가 기존 SAML SSO 흐름을 통해 ClickHouse Cloud에 로그인합니다.
  5. Entra ID에서 프로필이나 그룹이 변경되거나 계정이 비활성화되면 해당 변경 사항이 ClickHouse Cloud에 자동으로 반영됩니다.

​
ClickHouse Cloud 조직에서 SCIM 구성

1

SCIM 활성화

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

SCIM 액세스 토큰 생성

Generate new key 섹션을 찾아 만료일을 선택합니다.
교체 계획 수립만료 기간을 12개월로 설정하고 캘린더 알림을 추가하는 것이 좋습니다. ClickHouse Cloud는 동시에 최대 2개의 활성 SCIM 토큰을 지원하므로 가동 중단 없이 교체할 수 있습니다. 새 토큰을 생성하고 Entra ID를 새 토큰으로 전환한 후 프로비저닝이 계속 작동하는지 확인하고 이전 토큰을 취소하십시오.
Generate new key를 클릭합니다. 토큰은 scim_ 접두사가 붙은 키와 시크릿으로 한 번만 표시됩니다. 즉시 둘 다 복사하여 안전한 시크릿 관리자에 저장하십시오. 나중에 다시 조회할 수 없습니다. 분실한 경우 토큰을 취소하고 새로 생성하십시오.Entra ID에 사용할 단일 Bearer token으로 키와 시크릿을 다음 형식으로 결합합니다.
구체적으로 scim_으로 시작하는 토큰 키, 콜론, 토큰 시크릿 순서이며 공백은 넣지 않습니다. Entra ID는 모든 요청에서 이 값을 Authorization: Bearer header로 전송합니다.
3

역할 매핑 정의

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

​
Microsoft Entra ID에서 Provisioning 구성하기

1

ClickHouse Cloud Enterprise 애플리케이션을 엽니다.

Microsoft Entra ID 개요를 열고 왼쪽 메뉴의 Manage에서 Enterprise applications를 선택합니다. ClickHouse Cloud용 SAML SSO를 설정할 때 만든 애플리케이션을 엽니다.아직 엔터프라이즈 애플리케이션을 만들지 않았다면 먼저 SAML SSO 설정 가이드를 따르십시오. SAML 기반 SSO에서는 싱글 사인온과 SCIM provisioning에 동일한 엔터프라이즈 애플리케이션을 사용합니다.
2

Provisioning 모드 및 자격 증명 설정

애플리케이션 왼쪽 사이드바에서 Provisioning을 선택한 다음 Get started(또는 Provisioning → Edit provisioning)를 클릭합니다.Provisioning Mode를 Automatic으로 설정합니다. Admin Credentials에서 다음 정보를 입력합니다.
  • Tenant URL — ClickHouse Cloud Console의 SCIM endpoint URL(.../scim URL)입니다.
  • Secret Token — <scim-key>:<scim-secret> 형식으로 콜론(:)으로 연결한 SCIM 자격 증명입니다. Entra ID는 이를 Authorization: Bearer header로 전송합니다.
Test Connection을 클릭합니다. Entra ID가 SCIM endpoint에 테스트 요청을 보내며, 성공 알림이 표시됩니다. 실패하면 Troubleshooting으로 이동합니다.Save를 클릭합니다.
3

속성 매핑 구성

자격 증명을 저장한 후 Mappings 섹션을 확장하십시오. Entra ID에는 두 개의 매핑 세트가 표시됩니다.
  • Provision Microsoft Entra ID Users
  • Provision Microsoft Entra ID Groups
Provision Microsoft Entra ID Users를 열고 속성 매핑이 ClickHouse Cloud에서 예상하는 방식과 일치하는지 확인하십시오.기본적으로 Entra ID는 userPrincipalName의 값을 userName에 매핑합니다. 중요한 점은 특정 속성 이름이 아니라 SAML SSO에서 사용자를 로그인시키는 데 사용하는 이메일 주소와 동일한 이메일 주소를 가진 속성에서 userName을 가져와야 한다는 것입니다. 일부 테넌트에서는 userPrincipalName이 이미 해당 이메일이므로 변경할 필요가 없지만, 다른 테넌트에서는 이메일이 mail에 있으므로 userName의 소스를 mail로 변경해야 합니다. 소스를 변경하려면 userName 행을 클릭하고 Source attribute를 올바른 속성으로 설정한 후 저장하십시오.userName이 프라이머리 일치 속성이 되도록 Matching precedence를 설정하십시오. 지원되지 않는 매핑은 제거할 수 있습니다. SCIM 표준 세트에 포함되지 않은 항목은 ClickHouse Cloud 측에서 무시됩니다.
SAML SSO에 사용하는 이메일과 일치시켜야 합니다userName에 전달되는 값은 각 사용자가 SAML SSO를 통해 로그인할 때 사용하는 이메일 주소와 반드시 일치해야 합니다. SCIM은 계정을 생성하고 SAML은 이를 인증하므로, SCIM userName과 SAML 어설션의 이메일이 일치하지 않으면 SAML은 로그인 시 SCIM에서 관리되지 않는 별도의 새 사용자를 생성합니다. 그 결과 중복된 비관리 계정이 남게 됩니다. SAML 구성에서 전송하는 이메일과 동일한 이메일이 포함된 속성(userPrincipalName, mail 또는 다른 속성)에서 userName을 매핑하십시오.
아래의 나머지 행은 기본적으로 매핑되어 있습니다. 각 항목이 올바르게 설정되어 있는지 다시 확인하십시오.Provision Microsoft Entra ID Groups를 열고 displayName이 displayName에, members가 members에 매핑되는지 확인하십시오. 그룹 표시 이름이 ClickHouse Cloud 역할에 연결됩니다.
이메일 대소문자가 중요합니다userName에 전달되는 값과 프라이머리 이메일에 전달되는 값이 동일한 대소문자를 사용하는지 확인하십시오. ClickHouse Cloud는 이메일을 소문자로 정규화하므로 두 필드의 값이 일치하지 않으면 프로비저닝이 실패할 수 있습니다.
4

Provisioning 범위 설정

설정 섹션을 펼치세요.
  • 범위를 Sync only assigned users and groups로 설정하세요. 이렇게 하면 다음 단계에서 애플리케이션에 명시적으로 할당하는 사용자 및 그룹으로 프로비저닝이 제한됩니다.
  • 지금은 프로비저닝 상태를 Off로 유지하세요. 테스트 사용자를 할당한 후에 켜면 됩니다.
Save를 클릭하세요.
5

그룹 및 사용자 할당

여기에서 역할이 자동으로 할당됩니다.Entra ID에서 그룹을 만드십시오. 앞서 설정한 각 역할 매핑에 대해 표시 이름이 정확히 동일한 Entra ID 그룹을 만들거나 기존 그룹을 확인하십시오. 예를 들어 매핑이 ClickHouse-Admins → Admin인 경우 Entra ID에서 ClickHouse-Admins라는 그룹을 만드십시오.애플리케이션에 그룹을 할당하십시오. 엔터프라이즈 애플리케이션에서 Users and groups → Add user/group으로 이동해 역할 그룹을 선택한 후 할당하십시오. 각 역할 그룹에 대해 반복하십시오. 애플리케이션의 프로비저닝 범위가 assigned users and groups로 설정되어 있으므로 이 그룹들과 해당 구성원만 프로비저닝됩니다.
그룹 프로비저닝에는 적절한 Entra ID 라이선스가 필요합니다구성원뿐 아니라 그룹 자체도 프로비저닝하려면 Microsoft Entra ID P1 이상이 필요합니다. 그룹 프로비저닝을 사용하면 그룹 자체가 ClickHouse Cloud에 생성되고, 표시 이름을 기준으로 일치하는 역할에 연결됩니다.
사용자를 할당하십시오. 다음 두 가지 방법이 있습니다.
  • 그룹을 통해(권장). 애플리케이션에 할당한 Entra ID 그룹에 사용자를 추가하십시오. 사용자는 ClickHouse Cloud에 프로비저닝되며 일치하는 역할이 자동으로 할당됩니다.
  • 직접 할당. Users and groups에서 개별 사용자를 애플리케이션에 할당하십시오. 할당된 그룹의 구성원이 아닌 경우 기본 역할로 프로비저닝됩니다.
역할이 변경될 때 그룹 구성원만 업데이트하면 되므로, 지속적인 관리에는 그룹 기반 할당이 더 간편합니다.
6

프로비저닝 활성화

Provisioning으로 돌아가 Provisioning Status를 On으로 설정한 후 Save를 클릭합니다.Entra ID는 약 40분마다 프로비저닝을 실행합니다. 테스트 등의 목적으로 특정 사용자를 즉시 프로비저닝하려면 Provisioning → Provision on demand에서 사용자를 검색한 후 한 번의 프로비저닝 작업을 실행합니다.

​
통합 테스트

프로비저닝이 활성화되면 다음 주기를 기다리지 말고 Provision on demand를 사용해 테스트 사용자 한두 명을 즉시 프로비저닝하십시오. 그런 다음 ClickHouse Cloud 콘솔의 Settings → Users and roles로 돌아가 동기화된 사용자에게 예상한 역할이 부여되었는지 확인하십시오. 전체 팀을 할당하기 전에 테스트 사용자 한두 명으로 이 간단한 테스트 계획을 실행하십시오. 단계가 적용되지 않으면 Provision on demand를 사용해 동기화를 강제한 후 문제 해결 섹션을 확인하십시오. 어느 단계에서든 실패하면 계속 진행하기 전에 근본 원인을 해결하십시오. 일반적으로 문제가 연쇄적으로 발생합니다.
Entra ID에서 SCIM 오류를 확인할 위치SCIM 오류는 애플리케이션의 Provisioning → View provisioning logs 화면(Identity → Monitoring & health → Provisioning logs에서도 확인 가능)에 표시됩니다. 각 항목에는 요청, 대상 및 ClickHouse Cloud에서 반환한 오류가 원문 그대로 표시되므로, 여기서 먼저 확인하십시오.

​
프로덕션 환경 모범 사례

​
토큰을 정기적으로 교체하십시오

SCIM 토큰 교체 일정을 캘린더에 등록하십시오. 권장 주기는 12개월마다 또는 토큰을 알고 있던 관리자가 퇴사한 직후입니다. ClickHouse Cloud에서는 프로비저닝이 중단되지 않도록 조직당 활성 토큰 2개를 허용합니다. 새 토큰을 생성하고 Entra ID에서 시크릿 토큰을 업데이트한 후 Test Connection으로 확인하고, 기존 토큰을 취소하십시오.

​
직접 할당 대신 그룹 사용

사용자를 애플리케이션에 직접 할당할 수도 있지만, 곧 감사가 어려워질 수 있습니다. Entra ID 그룹을 통해 할당하면 액세스 검토와 역할 변경을 한 곳에서 관리할 수 있습니다.

​
감사 로그 검토

사용자 생성, 사용자 비활성화, 프로필 업데이트 등 모든 SCIM 작업은 ClickHouse Cloud 감사 로그에 기록됩니다. 감사 로깅을 참조하십시오. 특히 대규모 프로비저닝 작업 후에는 로그를 정기적으로 확인하십시오.

​
적절한 기본 역할 설정

Entra ID 사용자가 애플리케이션에 할당되었지만 할당된 그룹에 속하지 않은 경우 기본 역할로 생성됩니다. 사용자가 최소한의 작업은 수행할 수 있도록 하되, 가능한 한 가장 제한적인 역할을 선택하여 구성 오류가 발생해도 안전하게 처리되도록 하십시오.

​
SCIM과 수동 초대를 동시에 사용하지 마십시오

SCIM을 활성화한 후에는 Entra ID를 통해 멤버십을 관리하고, 동일한 사용자에게 수동 초대를 보내지 마십시오. 두 방식을 함께 사용하면 어떤 시스템이 기준인지 혼란이 생기고 중복 항목이 발생할 수 있습니다.

​
Provisioning 주기를 고려하십시오

Entra ID는 약 40분마다 반복적으로 동기화되므로 일반적인 변경 사항은 즉시 적용되지 않습니다. 변경 사항을 즉시 반영해야 할 때는 Provision on demand를 사용하고, 지속적으로 발생하는 실패는 Provisioning logs에서 모니터링하십시오.

​
문제 해결

  • ClickHouse Cloud 콘솔에서 SCIM이 활성화되어 있는지 확인하십시오.
  • Entra ID의 테넌트 URL이 Cloud Console에 표시된 SCIM endpoint URL과 정확히 일치하는지 확인하십시오. 조직 ID가 정확해야 합니다.
  • 시크릿 토큰이 <scim-key>:<scim-secret> 형식인지 확인하십시오. scim_으로 시작하는 키, 콜론, 시크릿 순서여야 합니다. 앞뒤 공백이나 Bearer 접두사를 포함하지 마십시오(Entra ID가 자동으로 추가합니다).
  • 토큰을 교체한 경우 이전 키와 시크릿 쌍이 아닌 새 키와 시크릿을 사용하고 있는지 확인하십시오.
  • 예상한 역할에 대해 Users and roles의 역할 매핑 아래에 행을 추가했는지 확인하십시오.
  • Entra ID 그룹 이름이 대소문자와 하이픈을 포함하여 매핑의 SCIM 그룹 이름과 정확히 일치하는지 확인하십시오.
  • 일부 사용자를 그룹 없이 의도적으로 프로비저닝하도록 설계했다면 기본 역할이 설정되어 있는지 확인하십시오.
  • 프로비저닝 상태가 On인지 확인하십시오.
  • 범위가 Sync only assigned users and groups로 설정되어 있고, 사용자/그룹이 Users and groups 아래에서 애플리케이션에 실제로 할당되어 있는지 확인하십시오.
  • 프로비저닝 사이클은 약 40분마다 실행됩니다. 단일 사용자를 즉시 테스트하려면 Provision on demand를 사용하십시오.
  • 구성원뿐 아니라 그룹 자체를 프로비저닝하려면 Microsoft Entra ID P1 이상이 필요합니다.
일반적으로 Entra ID와 이전 수동 초대 간 이메일 주소의 대소문자가 일치하지 않아 발생합니다. Members 목록에서 중복 사용자를 제거한 다음, Entra ID에서 사용자의 할당을 해제했다가 다시 할당하거나 Provision on demand를 다시 실행하여 새로 프로비저닝하십시오.
Entra ID의 그룹 표시 이름이 ClickHouse Cloud에 구성된 매핑과 일치하지 않습니다. Entra ID 그룹 이름을 변경하거나 SCIM 구성 패널의 Users and roles의 역할 매핑 아래에 매핑을 추가하십시오(또는 Users and roles → Roles를 통해 추가).
비활성화는 다음 프로비저닝 사이클에 반영됩니다. 즉시 적용하려면 해당 사용자에 대해 Provision on demand를 사용하십시오. 이후에도 사용자가 구성원으로 남아 있으면 Provisioning → View provisioning logs에서 비활성화 작업 관련 오류를 확인하십시오.
Entra ID의 올바른 엔터프라이즈 애플리케이션에서 시크릿 토큰을 <scim-key>:<scim-secret> 형식으로 업데이트했는지 확인하십시오. 업데이트한 후 Test Connection을 클릭하여 확인하십시오. 프로비저닝이 다시 정상 상태가 되면 ClickHouse Cloud 콘솔에서 이전 토큰을 해지하십시오.
토큰은 복구할 수 없습니다. ClickHouse Cloud 콘솔의 Organization settings → SAML and SCIM settings → SCIM 구성에서 분실한 토큰을 해지하고 새 토큰을 생성한 다음, Entra ID에서 시크릿 토큰을 업데이트하십시오.

​
자주 묻는 질문

예. SCIM은 사용자 계정을 생성하지만, ClickHouse Cloud는 SAML을 통해 사용자를 인증합니다. 먼저 SAML SSO를 설정하십시오.
예. SAML 기반 SSO에서는 하나의 Entra ID 엔터프라이즈 애플리케이션이 싱글 사인온과 SCIM provisioning을 모두 처리합니다.
Entra ID는 Secret Token을 Authorization: Bearer 헤더로 전송하여 인증합니다. ClickHouse Cloud SCIM endpoint는 베어러 값으로 콜론으로 연결된 토큰 키와 시크릿을 기대합니다.
Entra ID는 약 40분 간격으로 프로비저닝을 수행합니다. 즉시 업데이트하려면 특정 사용자에 대해 Provision on demand를 사용하십시오.
ClickHouse Cloud 콘솔에서 지원 티켓을 열고(Help → Contact support) 다음 정보를 포함하십시오.
  • 조직 ID,
  • Entra ID 엔터프라이즈 애플리케이션의 이름(및 객체 ID), 그리고
  • Provisioning → View provisioning logs에서 실패한 항목의 스크린샷.
마지막 수정일 2026년 8월 14일