diff --git a/docs/cloud/guides/security/01_cloud_access_management/07b_scim-setup.md b/docs/cloud/guides/security/01_cloud_access_management/07b_scim-setup.md index eea74cdbc5c..fd9fef660d5 100644 --- a/docs/cloud/guides/security/01_cloud_access_management/07b_scim-setup.md +++ b/docs/cloud/guides/security/01_cloud_access_management/07b_scim-setup.md @@ -22,7 +22,7 @@ SCIM provisioning is in private preview. ClickHouse Cloud supports SCIM 2.0 (System for Cross-domain Identity Management) for automated user and group lifecycle management. Once connected to your identity provider, every user you assign to the ClickHouse Cloud application is automatically created in your organization with the right role, profile updates flow through automatically, and removing a user from your IdP removes their access — no manual invites, no orphaned accounts. -This guide walks through setting up SCIM provisioning end-to-end with **Okta**. The ClickHouse Cloud SCIM endpoint follows SCIM 2.0 (RFC 7644), but authentication is supported only via Basic Auth, and Okta is the only identity provider we've tested against. Other SCIM 2.0 IdPs may work if they can authenticate using Basic Auth, but they're not officially supported today. +This guide walks through setting up SCIM provisioning end-to-end with **Okta**. The ClickHouse Cloud SCIM endpoint follows SCIM 2.0 (RFC 7644). Okta authenticates using Basic Auth, which is what this guide uses. If your identity provider is Microsoft Entra ID, follow the [SCIM provisioning with Entra ID](/cloud/security/scim-setup-entra) guide instead. ## Before you begin {#before-you-begin} @@ -65,13 +65,13 @@ Copy it — you'll paste it into Okta later. ### Generate a SCIM access token {#generate-scim-token} -Locate the `Create an API key` section and choose an expiration date. +Locate the `Generate new key` section and choose an expiration date. :::tip Plan for rotation We recommend setting an expiry of 12 months and adding a calendar reminder. ClickHouse Cloud supports up to two active SCIM tokens at once so you can rotate without downtime: generate the new token, swap Okta over, confirm provisioning still works, then revoke the old token. ::: -Click `Generate key`. The token is shown **once**, as a key (prefixed `scim_`) and a secret. Copy both immediately and store them in a secure secrets manager — they can't be retrieved later. If you lose them, revoke the token and generate a new one. +Click `Generate new key`. The token is shown **once**, as a key (prefixed `scim_`) and a secret. Copy both immediately and store them in a secure secrets manager — they can't be retrieved later. If you lose them, revoke the token and generate a new one. ![Generate a new SCIM API key](/images/cloud/security/scim-okta/scim-okta-07.png) @@ -276,7 +276,7 @@ Tokens can't be recovered. In **Organization settings → SAML and SCIM settings Yes. SCIM creates the user accounts, but ClickHouse Cloud authenticates them through SAML. Set up [SAML SSO](/cloud/security/saml-setup) first. **Does SCIM work with Microsoft Entra ID, OneLogin, or other SCIM 2.0 IdPs?** -Officially, no — Okta is the only IdP we've tested and support today. The endpoint follows SCIM 2.0 (RFC 7644), but authentication is restricted to Basic Auth, so any IdP that can't authenticate over Basic Auth won't work. Other Basic-Auth-capable SCIM 2.0 IdPs may work in practice, but we make no guarantees. +Microsoft Entra ID is also supported — see [SCIM provisioning with Entra ID](/cloud/security/scim-setup-entra). The endpoint follows SCIM 2.0 (RFC 7644) and accepts either Basic Auth (used by Okta) or a bearer token (used by Entra ID). Other SCIM 2.0 IdPs may work in practice if they can authenticate one of these ways, but Okta and Entra ID are the IdPs we've tested and support today. **How quickly do changes in Okta show up in ClickHouse Cloud?** Most operations propagate within a few seconds. Bulk changes (large group push) can take longer depending on size, but Okta retries automatically on transient errors. diff --git a/docs/cloud/guides/security/01_cloud_access_management/07c_scim-setup-entra.md b/docs/cloud/guides/security/01_cloud_access_management/07c_scim-setup-entra.md new file mode 100644 index 00000000000..95b2e90c2de --- /dev/null +++ b/docs/cloud/guides/security/01_cloud_access_management/07c_scim-setup-entra.md @@ -0,0 +1,284 @@ +--- +sidebar_label: 'SCIM provisioning with Entra ID' +slug: /cloud/security/scim-setup-entra +title: 'SCIM provisioning with Microsoft Entra ID' +description: 'How to set up SCIM provisioning between Microsoft Entra ID and ClickHouse Cloud' +doc_type: 'guide' +keywords: ['ClickHouse Cloud', 'SCIM', 'provisioning', 'Entra ID', 'Azure AD', 'Microsoft', 'SSO', 'SAML', 'identity provider', 'IdP', 'user management'] +--- + +import EnterprisePlanFeatureBadge from '@theme/badges/EnterprisePlanFeatureBadge' +import PrivatePreviewBadge from '@theme/badges/PrivatePreviewBadge'; + +# SCIM provisioning with Microsoft Entra ID + + + +:::note +SCIM provisioning is in private preview. +::: + + + +ClickHouse Cloud supports SCIM 2.0 (System for Cross-domain Identity Management) for automated user and group lifecycle management. Once connected to your identity provider, every user you assign to the ClickHouse Cloud application is automatically created in your organization with the right role, profile updates flow through automatically, and removing a user from your IdP removes their access — no manual invites, no orphaned accounts. + +This guide walks through setting up SCIM provisioning end-to-end with **Microsoft Entra ID** (formerly Azure Active Directory). The ClickHouse Cloud SCIM endpoint follows SCIM 2.0 (RFC 7644). Entra ID authenticates to the endpoint using a long-lived bearer token, which you assemble from the SCIM token key and secret generated in the ClickHouse Cloud Console. + +:::tip Using Okta instead? +If your identity provider is Okta, follow the [SCIM provisioning with Okta](/cloud/security/scim-setup) guide. The ClickHouse Cloud side is identical; only the IdP configuration differs. +::: + +## Before you begin {#before-you-begin} + +You'll need: + +- The **Admin** role in your ClickHouse Cloud organization. +- [SAML SSO](/cloud/security/saml-setup) already configured between Entra ID and ClickHouse Cloud. SCIM creates the user accounts; those accounts sign in through SAML, so SSO must be working first. +- Access to the **Microsoft Entra admin center** with at least the **Application Administrator** (or **Cloud Application Administrator**) role, with permission to configure provisioning on the enterprise application. +- A list of the roles you want to assign through SCIM (for example: Admins, Developers, Read-only). Decide this up front — you'll create matching groups in Entra ID. + +## How SCIM works with ClickHouse Cloud {#how-scim-works} + +1. An admin in Entra ID assigns a user — directly or through a group — to the ClickHouse Cloud enterprise application. +2. Entra ID's provisioning service calls the ClickHouse Cloud SCIM endpoint over HTTPS, authenticated with a bearer token you generate. +3. ClickHouse Cloud creates the user in your organization and assigns roles based on Entra ID group membership. +4. The user signs in to ClickHouse Cloud through your existing SAML SSO flow. +5. Profile changes, group changes, and deactivation in Entra ID propagate to ClickHouse Cloud automatically. + +## Configure SCIM on your ClickHouse Cloud organization {#configure-clickhouse-cloud} + + + +### Enable SCIM {#enable-scim-provisioning} + +Sign in to **ClickHouse Cloud Console** as an organization admin and open **Organization settings → SAML and SCIM settings → SCIM Configuration**. + +Click `Enable SCIM`. SCIM is unlocked once SAML SSO is connected — if the option is greyed out, finish your SAML setup first. + +A **SCIM endpoint URL** is generated, in the form: + +```plaintext +https://api.clickhouse.cloud/v1/organizations//scim +``` + +Copy it — you'll paste it into Entra ID later as the **Tenant URL**. + +### Generate a SCIM access token {#generate-scim-token} + +Locate the `Generate new key` section and choose an expiration date. + +:::tip Plan for rotation +We recommend setting an expiry of 12 months and adding a calendar reminder. ClickHouse Cloud supports up to two active SCIM tokens at once so you can rotate without downtime: generate the new token, swap Entra ID over, confirm provisioning still works, then revoke the old token. +::: + +Click `Generate new key`. The token is shown **once**, as a key (prefixed `scim_`) and a secret. Copy both immediately and store them in a secure secrets manager — they can't be retrieved later. If you lose them, revoke the token and generate a new one. + +You'll combine the key and secret into a single bearer token for Entra ID in the form: + +```plaintext +: +``` + +Specifically, the token **key** (starting with `scim_`), a colon, then the token **secret**, with no spaces. Entra ID sends this value as an `Authorization: Bearer` header on every request. + +### Define the role mapping {#define-role-mapping} + +From the SCIM Configuration panel, click **Map roles in "Users and roles"** (or navigate directly via **Users and roles → Roles**). + +SCIM groups bind to ClickHouse Cloud roles by name, with a few rules to keep in mind: + +- **You can't map a SCIM group to a predefined system role.** SCIM mappings apply only to custom roles. If you need to expose a system-level capability through SCIM, create a custom role that wraps the permissions you want. +- **Matching names auto-link.** If a custom role has the same name as the incoming SCIM group, ClickHouse Cloud links them automatically — no manual mapping needed. +- **To use a different role name than the group name**, create the custom role with the role name you want, then set its **SCIM group** field to the name of the SCIM group it should bind to. +- **Unmapped groups create new roles.** If Entra ID pushes a group that doesn't match an existing role name and isn't referenced by any role's `SCIM group` field, ClickHouse Cloud creates a new custom role with that group's name. You can then grant it the permissions you want. + + + +## Configure provisioning in Microsoft Entra ID {#configure-entra} + + + +### Open your ClickHouse Cloud enterprise application {#open-clickhouse-cloud-app} + +Open the **Microsoft Entra ID** overview and, under **Manage** in the left-hand menu, select **Enterprise applications**. Open the application you created when you set up SAML SSO for ClickHouse Cloud. + +If you haven't created the enterprise application yet, follow the [SAML SSO setup guide](/cloud/security/saml-setup#configure-azure-microsoft-saml) first — with SAML-based SSO, the same enterprise application is used for both single sign-on and SCIM provisioning. + +### Set the provisioning mode and credentials {#connect-entra-scim} + +In the application's left sidebar, select **Provisioning**, then click `Get started` (or `Provisioning` → `Edit provisioning`). + +Set **Provisioning Mode** to `Automatic`. Under **Admin Credentials**, fill in: + +- **Tenant URL** — the SCIM endpoint URL from the ClickHouse Cloud Console (the `.../scim` URL). +- **Secret Token** — your SCIM credentials joined with a colon, in the form `:`. Entra ID sends this as an `Authorization: Bearer` header. + +Click `Test Connection`. Entra ID makes a test call to the SCIM endpoint; you should see a success notification. If it fails, jump to [Troubleshooting](#troubleshooting). + +Click `Save`. + +### Configure attribute mappings {#map-user-attributes} + +After saving credentials, expand the **Mappings** section. Entra ID shows two mapping sets: + +- **Provision Microsoft Entra ID Users** +- **Provision Microsoft Entra ID Groups** + +Open **Provision Microsoft Entra ID Users** and confirm the attribute mappings line up with what ClickHouse Cloud expects. + +By default, Entra ID maps `userName` from `userPrincipalName`. **Edit this mapping so that `userName` is sourced from `mail` instead.** Click the `userName` row, change the **Source attribute** to `mail`, and save. + +Set the **Matching precedence** so that `userName` is the primary matching attribute. You can remove unsupported mappings; anything outside the SCIM standard set is ignored on the ClickHouse Cloud side. + +:::warning Match the email used for SAML SSO +The value that flows into `userName` **must** match the email address each user signs in with through SAML SSO. SCIM creates the account and SAML authenticates it, so if the SCIM `userName` and the SAML assertion's email don't match, the user is provisioned but can't sign in. Map `userName` from whichever attribute (`mail` here) carries the same email your SAML configuration sends. +::: + +The remaining rows below come mapped by default — double-check that each is in place: + +| Microsoft Entra ID attribute | ClickHouse Cloud (SCIM) attribute | Required | +|---|---|---| +| `mail` | `emails[type eq "work"].value` | **Yes** — must match `userName` | +| `givenName` | `name.givenName` | Recommended | +| `surname` | `name.familyName` | Recommended | +| `displayName` | `displayName` | Recommended — shown in the ClickHouse Cloud UI | +| `Switch([IsSoftDeleted], ...)` | `active` | **Yes** — drives deactivation | + +Open **Provision Microsoft Entra ID Groups** and confirm `displayName` maps to `displayName` and `members` maps to `members` — group display name is what binds to your ClickHouse Cloud role. + +:::warning Email casing matters +Make sure the value that flows into `userName` and the value that flows into the primary email use the same casing. ClickHouse Cloud normalises emails to lowercase; mismatches between the two fields can cause provisioning failures. +::: + +### Set the provisioning scope {#configure-provisioning-behavior} + +Expand the **Settings** section: + +- Set **Scope** to `Sync only assigned users and groups`. This limits provisioning to the users and groups you explicitly assign to the application in the next step. +- Leave **Provisioning Status** `Off` for now — you'll turn it on after assigning your test users. + +Click `Save`. + +### Assign groups and users {#push-groups-and-assign-users} + +This is where roles get applied automatically. + +**Create groups in Entra ID.** For each role mapping you set up earlier, create or identify an Entra ID group with the **exact same display name**. For example, if your mapping says `ClickHouse-Admins → Admin`, create a group called `ClickHouse-Admins` in Entra ID. + +**Assign groups to the application.** In the enterprise application, go to **Users and groups → Add user/group**, select your role group, and assign it. Repeat for each role group. Because the application's provisioning scope is set to *assigned users and groups*, only these groups (and their members) are provisioned. + +:::note Group provisioning requires the right Entra ID licensing +Provisioning groups (not just their members) requires Microsoft Entra ID P1 or higher. With group provisioning, the group itself is created in ClickHouse Cloud and bound to the matching role by display name. +::: + +**Assign users.** You have two options: + +- **Via groups (recommended).** Add users to the Entra ID groups you assigned to the application. They'll be provisioned to ClickHouse Cloud and assigned the matching role automatically. +- **Directly.** Assign individual users to the application under **Users and groups**. They'll be provisioned with the **Default role** unless they're also a member of an assigned group. + +Group-based assignment is cleaner for ongoing management — when someone changes role, you only update group membership. + +### Turn on provisioning {#turn-on-provisioning} + +Return to **Provisioning**, set **Provisioning Status** to `On`, and click `Save`. + +Entra ID runs provisioning on a recurring cycle (approximately every 40 minutes). To provision a specific user immediately — useful for testing — use **Provisioning → Provision on demand**, search for the user, and run a single provisioning operation. + + + +## Test the integration {#test-the-integration} + +Once provisioning is on, use **Provision on demand** to push one or two test users right away rather than waiting for the next cycle. Then return to **Settings → Users and roles** in the ClickHouse Cloud Console to confirm that synchronised users have appeared with the expected roles. + +Run through this short test plan with one or two test users **before** you assign your whole team. If a step doesn't take effect, use **Provision on demand** to force a sync, then check the [Troubleshooting](#troubleshooting) section. + +| # | Action in Entra ID | Expected result in ClickHouse Cloud | +|---|---|---| +| 1 | Add a test user to the `ClickHouse-Admins` group and run **Provision on demand** | User appears in **Settings → Members** with role **Admin** | +| 2 | The test user signs in to ClickHouse Cloud via SSO | They land on the dashboard with admin access | +| 3 | Update the user's first name in Entra ID and re-provision | Updated name appears in **Members** | +| 4 | Move the user from `ClickHouse-Admins` to `ClickHouse-Read-only` and re-provision | Their role changes to **Read-only** | +| 5 | Unassign the user from the application (or disable the account in Entra ID) | User is removed from the organization; further sign-in attempts fail | + +If any step fails, fix the underlying issue before continuing — symptoms usually compound. + +:::tip Where to look for SCIM errors in Entra ID +SCIM errors surface in the application's **Provisioning → View provisioning logs** screen (also available under **Identity → Monitoring & health → Provisioning logs**). Each entry shows the request, the target, and the error returned by ClickHouse Cloud verbatim — start there. +::: + +## Best practices for production {#best-practices} + +**Rotate tokens regularly.** Set a calendar reminder for SCIM token rotation. Recommended cadence: every 12 months, or immediately whenever an admin who knew the token leaves the company. ClickHouse Cloud allows two active tokens per organization specifically so you can rotate without breaking provisioning — generate the new token, update the **Secret Token** in Entra ID, confirm with **Test Connection**, then revoke the old token. + +**Use groups, not direct assignments.** Direct user assignment to the application works, but quickly becomes hard to audit. Driving assignment through Entra ID groups means access reviews and role changes happen in one place. + +**Review the audit log.** Every SCIM action — user created, user deactivated, profile updated — is recorded in the ClickHouse Cloud audit log. See [Audit logging](/cloud/security/audit-logging). Check the log periodically, especially after large provisioning bursts. + +**Set a sensible default role.** If an Entra ID user gets assigned to the application but isn't in any assigned group, they're created with the **Default role**. Pick the most restrictive role that still lets the user accomplish *something*, so misconfigurations fail safely. + +**Avoid SCIM and manual invites at the same time.** Once SCIM is on, manage membership through Entra ID — don't also send manual invites for the same users. Mixing the two paths leads to confusion about who is the source of truth and can produce duplicates. + +**Account for the provisioning cycle.** Entra ID syncs on a recurring cycle (roughly every 40 minutes), so routine changes aren't instant. Use **Provision on demand** when you need a change to land immediately, and monitor **Provisioning logs** for persistent failures. + +## Troubleshooting {#troubleshooting} + +### "Test connection" fails in Entra ID {#test-credentials-fails} + +- Confirm SCIM is **enabled** in the ClickHouse Cloud Console. +- Confirm the **Tenant URL** in Entra ID exactly matches the SCIM endpoint URL shown in the Cloud Console — the organization id must be correct. +- Confirm the **Secret Token** is in the form `:` — the key (starting with `scim_`), a colon, then the secret, with no leading or trailing whitespace, and no `Bearer` prefix (Entra ID adds that automatically). +- If you've rotated tokens, make sure you're using the **new** key and secret, not the previous pair. + +### Users get created but have no permissions {#users-no-permissions} + +- Check that you've added a row under **Map roles in "Users and roles"** for the role you expect. +- Check that the Entra ID group name **exactly** matches the SCIM group name in the mapping, including capitalisation and hyphens. +- If your design intentionally provisions some users without a group, confirm the **Default role** is set. + +### Users or groups aren't provisioning at all {#nothing-provisioning} + +- Confirm **Provisioning Status** is `On`. +- Confirm **Scope** is set to `Sync only assigned users and groups` and that the users/groups are actually assigned to the application under **Users and groups**. +- Remember the cycle runs roughly every 40 minutes — use **Provision on demand** to test a single user immediately. +- Provisioning groups (rather than just their members) requires Microsoft Entra ID P1 or higher. + +### Duplicate user in the member list {#duplicate-user} + +Usually caused by inconsistent email casing between Entra ID and an earlier manual invite. Remove the duplicate from the Members list, then unassign and reassign the user in Entra ID (or re-run **Provision on demand**) to provision fresh. + +### Group provisioning fails with a name mismatch {#group-display-name} + +The group display name in Entra ID doesn't match a configured mapping in ClickHouse Cloud. Either rename the Entra ID group or add a mapping under **Map roles in "Users and roles"** from the SCIM Configuration panel (or via **Users and roles → Roles**). + +### Deactivated users still show as members {#deactivated-users-remaining} + +Deactivation propagates on the next provisioning cycle. To force it immediately, use **Provision on demand** for that user. If the user is still a member afterwards, check **Provisioning → View provisioning logs** for an error on the disable operation. + +### I rotated the SCIM token and now Entra ID is failing {#token-rotation-issue} + +Check that you updated the **Secret Token** on the correct enterprise application in Entra ID, in the form `:`. After updating, click `Test Connection` to confirm. Once provisioning is back to healthy, revoke the old token in the ClickHouse Cloud Console. + +### I lost the SCIM token {#lost-token} + +Tokens can't be recovered. In **Organization settings → SAML and SCIM settings → SCIM Configuration** in the ClickHouse Cloud Console, revoke the lost token and generate a new one, then update the **Secret Token** in Entra ID. + +## Frequently asked questions {#faq} + +**Do I need SAML SSO before I can use SCIM?** +Yes. SCIM creates the user accounts, but ClickHouse Cloud authenticates them through SAML. Set up [SAML SSO](/cloud/security/saml-setup) first. + +**Can I use the same enterprise application for SAML and SCIM?** +Yes. With SAML-based SSO, a single Entra ID enterprise application handles both single sign-on and SCIM provisioning. + +**Why is the Secret Token formatted as `key:secret`?** +Entra ID authenticates by sending the Secret Token as an `Authorization: Bearer` header. The ClickHouse Cloud SCIM endpoint expects the bearer value to be your token key and secret joined by a colon. + +**How quickly do changes in Entra ID show up in ClickHouse Cloud?** +Entra ID provisions on a recurring cycle of roughly 40 minutes. For an immediate update, use **Provision on demand** for the specific user. + +**Where do I get help if I'm stuck?** +Open a support ticket from the ClickHouse Cloud Console (**Help → Contact support**) and include: + +- your organization id, +- the name (and object id) of your Entra ID enterprise application, and +- a screenshot of the failing entry from **Provisioning → View provisioning logs**. diff --git a/docs/cloud/guides/security/01_cloud_access_management/index.md b/docs/cloud/guides/security/01_cloud_access_management/index.md index 5fede9b7394..1ee020f57c5 100644 --- a/docs/cloud/guides/security/01_cloud_access_management/index.md +++ b/docs/cloud/guides/security/01_cloud_access_management/index.md @@ -18,5 +18,6 @@ This section contains detailed guides for managing access in ClickHouse Cloud | [Manage SQL console role assignments](/cloud/guides/sql-console/manage-sql-console-role-assignments) | An administrator's guide to managing SQL console users | | [Manage database users](/cloud/security/manage-database-users) | An administrator's guide to managing database users | | [SAML SSO setup](/cloud/security/saml-setup) | An administrator's guide to configuring and troubleshooting SAML integrations | -| [SCIM provisioning with Okta](/cloud/security/scim-setup) | An administrator's guide to automating user and group lifecycle with SCIM | +| [SCIM provisioning with Okta](/cloud/security/scim-setup) | An administrator's guide to automating user and group lifecycle with SCIM and Okta | +| [SCIM provisioning with Entra ID](/cloud/security/scim-setup-entra) | An administrator's guide to automating user and group lifecycle with SCIM and Microsoft Entra ID | | [Common access management queries](/cloud/security/common-access-management-queries) | Detailed examples of setting up and verifying database permissions | diff --git a/styles/ClickHouse/Headings.yml b/styles/ClickHouse/Headings.yml index ef4bcc1437a..75cda69e9c9 100644 --- a/styles/ClickHouse/Headings.yml +++ b/styles/ClickHouse/Headings.yml @@ -69,6 +69,7 @@ exceptions: - EDOT - Elastic Agent - Emmet + - Entra ID - FAQ - Filebeat - Frequently Asked Questions