SCIM provisioning with Okta
SCIM is available in the Enterprise plan. To upgrade, visit the plans page in the cloud console.
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.
Before you begin
You'll need:
- The Admin role in your ClickHouse Cloud organization.
- SAML SSO already configured between your IdP and ClickHouse Cloud. SCIM creates the user accounts; those accounts sign in through SAML, so SSO must be working first.
- Super-admin access to your Okta tenant, with permission to install applications and configure provisioning.
- 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 Okta.
How SCIM works with ClickHouse Cloud
- An admin in Okta assigns a user — directly or through a group — to the ClickHouse Cloud application.
- Okta calls the ClickHouse Cloud SCIM endpoint over HTTPS, authenticated with a token you generate.
- ClickHouse Cloud creates the user in your organization and assigns roles based on Okta group membership.
- The user signs in to ClickHouse Cloud through your existing SAML SSO flow.
- Profile changes, group changes, and deactivation in Okta propagate to ClickHouse Cloud automatically.
Configure SCIM on your ClickHouse Cloud organization
Enable SCIM
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:
Copy it — you'll paste it into Okta later.
Generate a SCIM access token
Locate the Create an API key section and choose an expiration date.
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.
Define the 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 Okta pushes a group that doesn't match an existing role name and isn't referenced by any role's
SCIM groupfield, ClickHouse Cloud creates a new custom role with that group's name. You can then grant it the permissions you want.
Configure the ClickHouse Cloud application in Okta
Open your ClickHouse Cloud application in Okta
In the Okta Admin Console, go to Applications → Applications and search for the application you created when you set up SAML SSO for ClickHouse Cloud. Open it.
If you haven't created the SAML application yet, follow the SAML SSO setup guide first — SCIM provisioning is configured on the same application.
On the General tab, find the App Settings section and click Edit. Under Provisioning, select SCIM, then click Save.
The application now shows a Provisioning tab.
Connect Okta to the SCIM endpoint
Open the Provisioning tab of the application and click Edit. Fill in the form:
- SCIM connector base URL — the SCIM endpoint URL from earlier.
- Unique identifier field for users —
userName. - Supported provisioning actions — select all of the following:
- Import New Users and Profile Updates
- Push New Users
- Push Profile Updates
- Push Groups
- Import Groups
- Authentication Mode —
Basic Auth.- Username — the SCIM token key (it starts with
scim_). - Password — the SCIM token secret.
- Username — the SCIM token key (it starts with
Click Test Connector Configuration. You should see a green confirmation. If it fails, jump to Troubleshooting.
Click Save.
Configure provisioning behavior
Still on the Provisioning tab, click To App in the left sidebar. Click Edit and enable:
| Setting | Action | What it does |
|---|---|---|
| Create Users | Enable | Creates new users in ClickHouse Cloud when assigned in Okta |
| Update User Attributes | Enable | Pushes profile changes (name, email, etc.) automatically |
| Deactivate Users | Enable | Removes a user from ClickHouse Cloud when unassigned or deactivated in Okta |
| Sync Password | Disable | Not used — sign-in goes through SAML, not passwords |
Click Save, then return to the application's Sign On / Provisioning tabs to confirm the settings are in place.
Map user attributes
Okta and ClickHouse Cloud need to agree on how user fields line up. On the Provisioning tab, click To App and review the Attribute Mappings for your application. The defaults from the Okta SAML application are usually fine — verify the table below:
| Okta attribute | ClickHouse Cloud (SCIM) attribute | Required |
|---|---|---|
userName | userName | Yes — used as the unique identifier and primary email |
email (primary) | emails[primary].value | Yes — must match userName |
firstName | name.givenName | Recommended |
lastName | name.familyName | Recommended |
displayName | displayName | Recommended — shown in the ClickHouse Cloud UI |
externalId | externalId | Recommended — improves accuracy when reconciling |
You can add optional attributes such as department, manager, and location — ClickHouse Cloud stores them on the user profile but doesn't use them for permissions today. Anything outside the SCIM standard set is ignored on the ClickHouse Cloud side.
Make sure your Okta userName and email use the same casing. ClickHouse Cloud normalises emails to lowercase; mismatches between the two fields can cause test failures.
Push groups and assign users
This is where roles get applied automatically.
Create groups in Okta. For each role mapping you set up earlier, create or identify an Okta group with the exact same display name. For example, if your mapping says ClickHouse-Admins → Admin, create a group called ClickHouse-Admins in Okta.
Open the group you just created and click Assign people to add a member to it.
Then attach the SCIM application to the same group so role membership and app access stay in sync.
Push the groups. On the application's Provisioning tab, click Push Groups → Find groups by name, search for your group, and click Save. Repeat for each role group. Each one should show Push Status: Active (Pushed) once provisioned.
Assign users. You have two options:
- Via groups (recommended). Add users to the Okta groups you just pushed. They'll be provisioned to ClickHouse Cloud and assigned the matching role automatically.
- Directly. On the application's Assignments tab, click
Assign → Assign to Peopleand select individual users. They'll be provisioned with the Default role unless they're also in a pushed group.
Group-based assignment is cleaner for ongoing management — when someone changes role, you only update group membership.
Test the integration
Once provisioning is configured, 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. Each step should succeed within a few seconds; if it doesn't, check the Okta Tasks queue and the Troubleshooting section.
| # | Action in Okta | Expected result in ClickHouse Cloud |
|---|---|---|
| 1 | Add a test user to the ClickHouse-Admins Okta group | 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 Okta | Updated name appears in Members within seconds |
| 4 | Move the user from ClickHouse-Admins to ClickHouse-Read-only | Their role changes to Read-only |
| 5 | Unassign the user from the application (or deactivate in Okta) | User is removed from the organization; further sign-in attempts fail |
If any step fails, fix the underlying issue before continuing — symptoms usually compound.
Okta surfaces SCIM errors in Reports → System Log filtered by your application, and on the application's Provisioning → View Logs screen. The error message returned by ClickHouse Cloud is shown verbatim — start there.
Best practices for production
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.
Use groups, not direct assignments. Direct user assignment to the application works, but quickly becomes hard to audit. Driving assignment through Okta 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. Check the log periodically, especially after large provisioning bursts.
Set a sensible default role. If an Okta user gets assigned to the application but isn't in any pushed 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 Okta — 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.
Monitor for failed provisioning tasks. Okta retries failed provisioning calls but eventually parks them in the Tasks queue. Add this queue to the dashboards your IT team already monitors, or use Okta's webhook or email alerting to flag persistent failures.
Troubleshooting
"Test connector configuration" fails in Okta
- Confirm SCIM is enabled in the ClickHouse Cloud Console.
- Confirm the base URL in Okta exactly matches the SCIM endpoint URL shown in the Cloud Console — the organization id must be correct.
- Confirm the token key and secret are pasted without leading or trailing whitespace.
- 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
- Check that you've added a row under Map roles in "Users and roles" for the role you expect.
- Check that the Okta 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.
Duplicate user in the member list
Usually caused by inconsistent email casing between Okta and an earlier manual invite. Remove the duplicate from the Members list, then unassign and reassign the user in Okta to provision fresh.
Group push fails with "displayName not recognised"
The group name in Okta doesn't match a configured mapping in ClickHouse Cloud. Either rename the Okta 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
It can take up to a minute for Okta to propagate a deactivation. If the user is still a member after several minutes, check Okta's Provisioning → View Logs for an error on the deactivate task.
I rotated the SCIM token and now Okta is failing
Check that you updated the credentials on the same SCIM application in Okta. After updating, click Test Connector Configuration to confirm. Once provisioning is back to green, revoke the old token in ClickHouse Cloud Console.
I lost the SCIM 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 credentials in Okta.
Frequently asked questions
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 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.
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.
Can I provision multiple ClickHouse Cloud organizations from a single Okta tenant? Yes — install the application once per organization, with its own SCIM endpoint URL and token. Push the same Okta groups to each application as needed.
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, your Okta application id, and a screenshot of the failing task or test from the Okta logs.
