> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Okta를 통한 SCIM 프로비저닝 > Okta와 ClickHouse Cloud 간 SCIM 프로비저닝을 설정하는 방법 export const PrivatePreviewBadge = () => { return
{'Private preview in ClickHouse Cloud'}
; }; export const EnterprisePlanFeatureBadge = ({feature = 'This feature', support = false, linking_verb_are = false}) => { return
Enterprise plan feature

{feature} {linking_verb_are ? 'are' : 'is'} available in the Enterprise plan. {support ? `Contact support to enable this feature.` : 'To upgrade, visit the plans page in the cloud console.'}

; }; export const Image = ({img, alt, size}) => { return {alt} ; }; 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](/ko/cloud/security/saml-setup)가 이미 구성되어 있어야 합니다. 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 구성하기
### SCIM 활성화 조직 관리자로 **ClickHouse Cloud 콘솔**에 로그인한 후 **조직 설정 → SAML 및 SCIM 설정 → SCIM 구성**을 엽니다. 조직 설정에서 SCIM 구성 탭으로 이동 `Enable SCIM`을 클릭합니다. SAML SSO가 연결되면 SCIM이 활성화됩니다. 옵션이 회색으로 비활성화되어 있으면 먼저 SAML 설정을 완료하십시오. Enable SCIM 전환 다음 형식의 **SCIM endpoint URL**이 생성됩니다. ```plaintext theme={null} https://api.clickhouse.cloud/v1/organizations//scim ``` 복사해 두십시오. 나중에 Okta에 붙여 넣어야 합니다. ### SCIM 액세스 토큰 생성 `Create an API key` 섹션을 찾아 만료 날짜를 선택합니다. **토큰 교체를 미리 계획하십시오.** 만료 기간은 12개월로 설정하고 캘린더 알림을 추가하는 것이 좋습니다. ClickHouse Cloud는 동시에 최대 2개의 활성 SCIM 토큰을 지원하므로 중단 없이 교체할 수 있습니다. 새 토큰을 생성하고, Okta를 새 토큰으로 전환하고, 프로비저닝이 계속 작동하는지 확인한 다음, 기존 토큰을 철회하십시오. `Generate key`를 클릭합니다. 토큰은 키(`scim_` 접두사 포함)와 시크릿 형태로 **한 번만** 표시됩니다. 둘 다 즉시 복사하여 안전한 시크릿 관리자에 저장하십시오. 나중에 다시 확인할 수 없습니다. 분실한 경우 해당 토큰을 철회하고 새로 생성하십시오. 새 SCIM API Key 생성 ### 역할 매핑 정의 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 애플리케이션 구성하기
### Okta에서 ClickHouse Cloud 애플리케이션 열기 **Okta Admin Console**에서 **Applications → Applications**로 이동한 후, ClickHouse Cloud용 SAML SSO를 설정할 때 생성한 애플리케이션을 검색합니다. 해당 애플리케이션을 엽니다. 아직 SAML 애플리케이션을 만들지 않았다면 먼저 [SAML SSO 설정 가이드](/ko/cloud/security/saml-setup)를 따르십시오. SCIM 프로비저닝은 동일한 애플리케이션에서 구성합니다. **General** 탭에서 **App Settings** 섹션을 찾아 `Edit`를 클릭하십시오. **Provisioning** 아래에서 `SCIM`을 선택한 다음 `Save`를 클릭하십시오. Okta 애플리케이션 설정에서 프로비저닝 모드를 SCIM으로 설정 이제 애플리케이션에 **Provisioning** 탭이 표시됩니다. 이제 애플리케이션에 Provisioning 탭이 표시됨 ### SCIM 엔드포인트에 Okta 연결 애플리케이션의 **Provisioning** 탭을 열고 `Edit`를 클릭합니다. 양식을 다음과 같이 입력합니다. * **SCIM connector base URL** — 앞서 확인한 SCIM 엔드포인트 URL입니다. * **사용자용 고유 식별자 필드** — `userName`. * **지원되는 프로비저닝 작업** — 다음 항목을 모두 선택합니다. * 새 사용자 가져오기 및 프로필 업데이트 * 새 사용자 Push * 프로필 업데이트 Push * 그룹 Push * 그룹 가져오기 * **인증 모드** — `Basic Auth`. * **Username** — SCIM 토큰 **key**입니다(`scim_`로 시작). * **Password** — SCIM 토큰 **secret**입니다. SCIM connector URL을 입력하고 고유 식별자를 userName으로 설정합니다 SCIM 인증용 API 자격 증명을 입력합니다 `Test Connector Configuration`을 클릭합니다. 녹색 확인 표시가 나타나야 합니다. 실패하면 [문제 해결](#troubleshooting)로 이동하십시오. SCIM 연결을 테스트합니다 `Save`를 클릭합니다. ### Provisioning 동작 구성 계속해서 **Provisioning** 탭에서 왼쪽 사이드바의 `To App`을 클릭합니다. `Edit`를 클릭한 후 다음 항목을 활성화합니다: | 설정 | 작업 | 설명 | | ---------------------- | ------- | ----------------------------------------------------- | | Create Users | Enable | Okta에서 할당되면 ClickHouse Cloud에 새 사용자를 생성합니다 | | Update User Attributes | Enable | 프로필 변경 사항(이름, 이메일 등)을 자동으로 푸시합니다 | | Deactivate Users | Enable | Okta에서 할당이 해제되거나 비활성화되면 ClickHouse Cloud에서 사용자를 제거합니다 | | Sync Password | Disable | 사용되지 않습니다 — 로그인은 비밀번호가 아니라 SAML을 통해 처리됩니다 | 사용자에 대한 SCIM 프로비저닝 작업 활성화 `Save`를 클릭한 다음 애플리케이션의 **Sign On** / **Provisioning** 탭으로 돌아가 설정이 적용되었는지 확인합니다. 프로비저닝 설정을 저장하고 Sign On 탭으로 돌아가기 ### 사용자 속성 매핑 Okta와 ClickHouse Cloud는 사용자 필드의 매핑 방식에 대해 동일하게 설정되어 있어야 합니다. **Provisioning** 탭에서 `To App`을 클릭하고 애플리케이션의 **Attribute Mappings**를 검토하십시오. Okta SAML 애플리케이션의 기본값은 보통 그대로 사용해도 되지만, 아래 표를 확인하십시오. | Okta 속성 | ClickHouse Cloud (SCIM) 속성 | 필수 | | ----------------- | -------------------------- | ------------------------------- | | `userName` | `userName` | **예** — 고유 식별자이자 기본 이메일로 사용됩니다 | | `email` (primary) | `emails[primary].value` | **예** — `userName`와 일치해야 합니다 | | `firstName` | `name.givenName` | 권장 | | `lastName` | `name.familyName` | 권장 | | `displayName` | `displayName` | 권장 — ClickHouse Cloud UI에 표시됩니다 | | `externalId` | `externalId` | 권장 — 대조 시 정확도를 높여 줍니다 | 부서, 관리자, 위치와 같은 선택적 속성도 추가할 수 있습니다. ClickHouse Cloud는 이를 사용자 프로필에 저장하지만 현재는 권한에 사용하지 않습니다. SCIM 표준 항목에 포함되지 않은 값은 ClickHouse Cloud 측에서 무시됩니다. **이메일의 대소문자는 중요합니다.** Okta `userName`과 `email`이 동일한 대소문자를 사용하도록 하십시오. ClickHouse Cloud는 이메일을 소문자로 정규화하므로, 두 필드의 대소문자가 일치하지 않으면 테스트가 실패할 수 있습니다. ### 그룹 푸시 및 사용자 할당 이 단계에서 역할이 자동으로 적용됩니다. **Okta에서 그룹을 생성합니다.** 앞서 설정한 각 역할 매핑마다 **정확히 동일한 표시 이름**을 사용하는 Okta 그룹을 생성하거나 기존 그룹을 확인합니다. 예를 들어 매핑이 `ClickHouse-Admins → Admin`이라면, Okta에서 `ClickHouse-Admins`라는 그룹을 생성합니다. Okta에서 새 그룹 생성 방금 생성한 그룹을 열고 `Assign people`을 클릭해 구성원을 추가합니다. 그룹에서 Assign people 클릭 사용자를 그룹에 할당 그런 다음 동일한 그룹에 SCIM 애플리케이션도 연결하여 역할 멤버십과 애플리케이션 액세스가 동기화된 상태로 유지되도록 합니다. 그룹에 애플리케이션 할당 **그룹을 Push합니다.** 애플리케이션의 **Provisioning** 탭에서 `Push Groups → Find groups by name`을 클릭하고 그룹을 검색한 다음 `Save`를 클릭합니다. 각 역할 그룹에 대해 이 과정을 반복합니다. Provisioning이 완료되면 각 그룹의 **Push Status**가 \*\*Active (Pushed)\*\*로 표시되어야 합니다. 애플리케이션의 Push Groups 탭에서 이름으로 Group Push 설정 **사용자를 할당합니다.** 두 가지 방법이 있습니다. * **그룹을 통해(권장).** 방금 Push한 Okta 그룹에 사용자를 추가합니다. 그러면 ClickHouse Cloud에 프로비저닝되고, 해당 역할이 자동으로 할당됩니다. * **직접 할당.** 애플리케이션의 **Assignments** 탭에서 `Assign → Assign to People`을 클릭하고 개별 사용자를 선택합니다. Push된 그룹에도 속해 있지 않다면 **Default role**로 프로비저닝됩니다. 그룹 기반 할당 방식이 지속적인 관리에 더 깔끔합니다. 사용자의 역할이 바뀌면 그룹 멤버십만 업데이트하면 됩니다.
## 통합 테스트
Provisioning 구성을 마치면 ClickHouse Cloud 콘솔의 **Settings → Users and roles**로 돌아가 동기화된 사용자가 예상한 역할로 표시되는지 확인합니다. Users and roles에서 사용자 동기화 확인 전체 팀을 할당하기 **전**에 테스트 사용자 1\~2명으로 이 간단한 테스트 계획을 진행하십시오. 각 단계는 몇 초 안에 성공해야 합니다. 그렇지 않다면 Okta Tasks 큐와 [Troubleshooting](#troubleshooting) 섹션을 확인하십시오. | # | Okta에서 수행할 작업 | ClickHouse Cloud에서의 예상 결과 | | - | ----------------------------------------------------- | -------------------------------------------- | | 1 | 테스트 사용자를 `ClickHouse-Admins` Okta 그룹에 추가 | 사용자가 **Settings → Members**에 역할 **관리자**로 표시됨 | | 2 | 테스트 사용자가 SSO를 통해 ClickHouse Cloud에 로그인 | 관리자 권한으로 dashboard에 접속함 | | 3 | Okta에서 사용자의 이름을 업데이트 | 몇 초 안에 업데이트된 이름이 **Members**에 표시됨 | | 4 | 사용자를 `ClickHouse-Admins`에서 `ClickHouse-Read-only`로 이동 | 역할이 **읽기 전용**으로 변경됨 | | 5 | 애플리케이션에서 사용자 할당을 해제(또는 Okta에서 비활성화) | 사용자가 조직에서 제거되며, 이후 로그인 시도는 실패함 | 어느 단계에서든 실패하면 계속 진행하기 전에 근본 원인을 해결하십시오. 증상은 대개 연쇄적으로 악화됩니다. **Okta에서 SCIM 오류를 확인할 위치.** SCIM 오류는 애플리케이션으로 필터링한 **Reports → System Log**와 애플리케이션의 **Provisioning → View Logs** 화면에 표시됩니다. ClickHouse Cloud가 반환한 오류 메시지가 그대로 표시되므로, 먼저 그 내용을 확인하십시오.
## 운영 환경을 위한 모범 사례
**토큰을 정기적으로 교체하세요.** SCIM 토큰 교체를 위한 캘린더 알림을 설정하십시오. 권장 주기는 12개월마다 1회이며, 토큰을 알고 있던 관리자가 회사를 떠나는 경우에는 즉시 교체하는 것이 좋습니다. ClickHouse Cloud는 조직마다 활성 토큰 2개를 허용하므로 Provisioning을 중단하지 않고 토큰을 교체할 수 있습니다. **직접 할당 대신 그룹을 사용하세요.** 사용자를 애플리케이션에 직접 할당해도 동작하지만, 금방 감사하기 어려워집니다. Okta 그룹을 통해 할당을 관리하면 액세스 검토와 역할 변경을 한곳에서 처리할 수 있습니다. **감사 로그를 검토하세요.** 사용자 생성, 사용자 비활성화, 프로필 업데이트 등 모든 SCIM 작업은 ClickHouse Cloud 감사 로그에 기록됩니다. [감사 로깅](/ko/cloud/security/audit-logging)을 참조하십시오. 특히 대규모 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](/ko/cloud/security/saml-setup)를 설정하십시오. **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 로그에서 실패한 작업 또는 테스트의 스크린샷.