시작하기 전에
- ClickHouse Cloud 조직에서 관리자 역할이 있어야 합니다.
- IdP와 ClickHouse Cloud 간에 SAML SSO가 이미 구성되어 있어야 합니다. SCIM이 사용자 계정을 생성하고, 해당 계정은 SAML을 통해 로그인하므로 SSO가 먼저 정상적으로 작동해야 합니다.
- 애플리케이션 설치 및 Provisioning 구성 권한이 있는 Okta 테넌트의 super-admin 액세스
- SCIM을 통해 할당할 역할 목록(예: Admins, Developers, 읽기 전용). 이 목록은 미리 정해 두십시오. Okta에서 이에 맞는 그룹을 생성하게 됩니다.
SCIM이 ClickHouse Cloud에서 작동하는 방식
- Okta의 관리자가 사용자를 직접 또는 그룹을 통해 ClickHouse Cloud 애플리케이션에 할당합니다.
- Okta는 생성한 토큰으로 인증한 후 HTTPS를 통해 ClickHouse Cloud SCIM 엔드포인트를 호출합니다.
- ClickHouse Cloud는 조직에 사용자를 생성하고 Okta 그룹 멤버십에 따라 역할을 할당합니다.
- 사용자는 기존 SAML SSO 흐름을 통해 ClickHouse Cloud에 로그인합니다.
- Okta에서의 프로필 변경, 그룹 변경, 비활성화는 ClickHouse Cloud에 자동으로 반영됩니다.
ClickHouse Cloud 조직에서 SCIM 구성하기
1
SCIM 활성화
조직 관리자로 ClickHouse Cloud 콘솔에 로그인한 후 조직 설정 → SAML 및 SCIM 설정 → SCIM 구성을 엽니다.
Enable SCIM을 클릭합니다. SAML SSO가 연결되면 SCIM이 활성화됩니다. 옵션이 회색으로 비활성화되어 있으면 먼저 SAML 설정을 완료하십시오.2
SCIM 액세스 토큰 생성
Create an API key 섹션을 찾아 만료 날짜를 선택합니다.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를 클릭하십시오.2
### SCIM 엔드포인트에 Okta 연결
애플리케이션의 Provisioning 탭을 열고 
Edit를 클릭합니다. 양식을 다음과 같이 입력합니다.- SCIM connector base URL — 앞서 확인한 SCIM 엔드포인트 URL입니다.
- 사용자용 고유 식별자 필드 —
userName. - 지원되는 프로비저닝 작업 — 다음 항목을 모두 선택합니다.
- 새 사용자 가져오기 및 프로필 업데이트
- 새 사용자 Push
- 프로필 업데이트 Push
- 그룹 Push
- 그룹 가져오기
- 인증 모드 —
Basic Auth.-
Username — SCIM 토큰 key입니다(
scim_로 시작). -
Password — SCIM 토큰 secret입니다.
-
Username — SCIM 토큰 key입니다(
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 측에서 무시됩니다.
5
그룹 푸시 및 사용자 할당
이 단계에서 역할이 자동으로 적용됩니다.Okta에서 그룹을 생성합니다. 앞서 설정한 각 역할 매핑마다 정확히 동일한 표시 이름을 사용하는 Okta 그룹을 생성하거나 기존 그룹을 확인합니다. 예를 들어 매핑이 
ClickHouse-Admins → Admin이라면, Okta에서 ClickHouse-Admins라는 그룹을 생성합니다.Assign people을 클릭해 구성원을 추가합니다.Push Groups → Find groups by name을 클릭하고 그룹을 검색한 다음 Save를 클릭합니다. 각 역할 그룹에 대해 이 과정을 반복합니다. Provisioning이 완료되면 각 그룹의 Push Status가 **Active (Pushed)**로 표시되어야 합니다.- 그룹을 통해(권장). 방금 Push한 Okta 그룹에 사용자를 추가합니다. 그러면 ClickHouse Cloud에 프로비저닝되고, 해당 역할이 자동으로 할당됩니다.
- 직접 할당. 애플리케이션의 Assignments 탭에서
Assign → Assign to People을 클릭하고 개별 사용자를 선택합니다. Push된 그룹에도 속해 있지 않다면 Default role로 프로비저닝됩니다.
통합 테스트
어느 단계에서든 실패하면 계속 진행하기 전에 근본 원인을 해결하십시오. 증상은 대개 연쇄적으로 악화됩니다.
운영 환경을 위한 모범 사례
토큰을 정기적으로 교체하세요
직접 할당 대신 그룹을 사용하세요
감사 로그를 검토하세요
적절한 기본 역할을 설정하세요
SCIM과 수동 초대를 동시에 사용하지 마세요
실패한 Provisioning 작업을 모니터링하세요
문제 해결
Okta에서 "Test connector configuration"이 실패하는 경우
Okta에서 "Test connector configuration"이 실패하는 경우
- ClickHouse Cloud 콘솔에서 SCIM이 활성화되어 있는지 확인하세요.
- Okta의 기준 URL이 Cloud Console에 표시된 SCIM 엔드포인트 URL과 정확히 일치하는지 확인하세요. 조직 ID가 정확해야 합니다.
- 토큰 key와 시크릿를 앞뒤 공백 없이 붙여넣었는지 확인하세요.
- 토큰을 교체했다면 이전 쌍이 아니라 새 key와 시크릿를 사용하고 있는지 확인하세요.
사용자는 생성되지만 권한이 없는 경우
사용자는 생성되지만 권한이 없는 경우
- 예상한 역할에 대해 Users and roles의 역할 매핑 아래에 행을 추가했는지 확인하세요.
- Okta 그룹 이름이 매핑의 SCIM 그룹 이름과 대소문자, 하이픈까지 포함해 정확히 일치하는지 확인하세요.
- 설계상 일부 사용자를 그룹 없이 프로비저닝하도록 한 경우, 기본 역할이 설정되어 있는지 확인하세요.
멤버 목록에 중복 사용자가 표시되는 경우
멤버 목록에 중복 사용자가 표시되는 경우
대개 Okta와 이전에 수동으로 초대한 계정 간 이메일 대소문자가 일치하지 않을 때 발생합니다. Members 목록에서 중복 항목을 제거한 다음, Okta에서 해당 사용자의 할당을 해제했다가 다시 할당해 새로 프로비저닝하세요.
Group push가 "displayName not recognised"와 함께 실패하는 경우
Group push가 "displayName not recognised"와 함께 실패하는 경우
Okta의 그룹 이름이 ClickHouse Cloud에 구성된 매핑과 일치하지 않습니다. Okta 그룹 이름을 변경하거나, SCIM 구성 패널(또는 Users and roles → Roles 경로)에서 Users and roles의 역할 매핑 아래에 매핑을 추가하세요.
비활성화된 사용자가 여전히 멤버로 표시되는 경우
비활성화된 사용자가 여전히 멤버로 표시되는 경우
Okta에서 deactivation이 반영되기까지 최대 1분이 걸릴 수 있습니다. 몇 분이 지나도 사용자가 여전히 멤버로 남아 있다면, Okta의 Provisioning → View Logs에서 deactivate 작업의 오류를 확인하세요.
SCIM 토큰을 교체한 후 Okta가 실패하는 경우
SCIM 토큰을 교체한 후 Okta가 실패하는 경우
Okta에서 동일한 SCIM 애플리케이션의 자격 증명을 업데이트했는지 확인하세요. 업데이트한 후
Test Connector Configuration을 클릭해 확인하세요. Provisioning 상태가 다시 정상으로 돌아오면 ClickHouse Cloud 콘솔에서 이전 토큰을 철회하세요.SCIM 토큰을 분실한 경우
SCIM 토큰을 분실한 경우
토큰은 복구할 수 없습니다. ClickHouse Cloud 콘솔의 Organization settings → SAML and SCIM settings → SCIM 구성에서 분실한 토큰을 철회하고 새 토큰을 생성한 다음, Okta에서 자격 증명을 업데이트하세요.
자주 묻는 질문
SCIM을 사용하려면 먼저 SAML SSO를 설정해야 합니까?
SCIM을 사용하려면 먼저 SAML SSO를 설정해야 합니까?
예. SCIM은 사용자 계정을 생성하지만, ClickHouse Cloud는 SAML을 통해 이를 인증합니다. 먼저 SAML SSO를 설정하십시오.
SCIM은 Microsoft Entra ID, OneLogin 또는 다른 SCIM 2.0 IdP에서 작동합니까?
SCIM은 Microsoft Entra ID, OneLogin 또는 다른 SCIM 2.0 IdP에서 작동합니까?
공식적으로는 그렇지 않습니다 — 현재 테스트를 거쳐 지원하는 유일한 IdP는 Okta입니다. 엔드포인트는 SCIM 2.0(RFC 7644)을 따르지만, 인증 방식이 Basic Auth로 제한되므로 Basic Auth로 인증할 수 없는 IdP는 사용할 수 없습니다. Basic Auth를 지원하는 다른 SCIM 2.0 IdP도 실제로는 작동할 수 있지만, 이를 보장하지는 않습니다.
Okta의 변경 사항은 얼마나 빨리 ClickHouse Cloud에 반영됩니까?
Okta의 변경 사항은 얼마나 빨리 ClickHouse Cloud에 반영됩니까?
대부분의 작업은 몇 초 내에 반영됩니다. 대량 변경(대규모 그룹 푸시)은 규모에 따라 더 오래 걸릴 수 있지만, 일시적인 오류가 발생하면 Okta가 자동으로 재시도합니다.
하나의 Okta 테넌트에서 여러 ClickHouse Cloud 조직을 Provisioning할 수 있습니까?
하나의 Okta 테넌트에서 여러 ClickHouse Cloud 조직을 Provisioning할 수 있습니까?
예 — 조직마다 고유한 SCIM 엔드포인트 URL과 토큰을 사용해 애플리케이션을 각각 한 번씩 설치하십시오. 필요에 따라 동일한 Okta 그룹을 각 애플리케이션에 푸시하면 됩니다.
진행이 막혔을 때는 어디에서 도움을 받을 수 있습니까?
진행이 막혔을 때는 어디에서 도움을 받을 수 있습니까?
ClickHouse Cloud 콘솔에서 지원 티켓을 여십시오(Help → Contact support). 다음 내용을 포함해야 합니다:
- 조직 ID,
- Okta 애플리케이션 ID,
- Okta 로그에서 실패한 작업 또는 테스트의 스크린샷.