What Oleria discovers
Once connected, Oleria continuously discovers and maps the following from your ClickHouse Cloud organization:- Accounts - every member of the organization, with name, email, join date, and assigned roles. Pending invitations appear as disabled accounts that carry the roles the invitation will grant, so outstanding access is visible before anyone accepts it.
- Roles - the system roles (such as Admin) and your custom roles, which accounts hold each one, and each role’s permissions. Oleria marks an account as an administrator when it holds the Admin role or a role with
control-plane:organization:manage. - Non-human identities (NHIs) - every organization API key as an API token, with its state, expiration date, last use, IP allow list, and assigned roles. Each key also appears as a credential, linked to the member or key that created it when the audit log records the creation.
- Activity - organization audit log events, such as member and role changes, API key creation and changes, SAML and approved-domain changes, and service and organization setting changes. Events are attributed to the member or API key that performed them.
Prerequisites
- The Admin role in your ClickHouse Cloud organization, to create a custom role and an API key.
- Admin access on the Oleria platform to add a new integration.
Permissions Oleria needs
ClickHouse Cloud API keys get their permissions from the roles assigned to them. Assign the key a custom role with these permissions:
For a read-only sync,
view, view-api-keys, and view-activities are enough. Roles and who holds them still appear, but without their permission detail, and the integration’s Capabilities tab shows Read roles as not enabled because ClickHouse Cloud lists roles only for keys with manage. Remediation actions aren’t available. A key that holds manage has administrative access, so Oleria shows its own API key as an administrative non-human identity.
The Admin system role holds all of these. The Organization API Reader system role (called Org API reader in ClickHouse’s documentation) isn’t enough, because it doesn’t include view-activities or manage.
The ClickHouse Cloud role editor lists permissions by name rather than by ID. control-plane:organization:view is Access organization, and ClickHouse’s audit log documentation calls control-plane:organization:view-activities View audit logs. For the others, pick the permission whose description matches its entry in ClickHouse’s console roles and permissions reference. For example, view-api-keys is described as “View API keys for the organization” and update-api-keys as “Update existing API keys and their permissions”.
Create an API key in ClickHouse Cloud
The exact location of these settings can change over time. If the steps below don’t match what you see, refer to ClickHouse’s custom roles and API key documentation.
1
Create a custom role for Oleria
In the ClickHouse Cloud console, select the name of your organization, then select Users and roles from the menu. Select the Roles tab, then Create new role.Name the role (for example,
Oleria), select Allow, and add the organization permissions from the table above. Select Create role.2
Create an API key
Select API Keys in the left menu, then New API Key. If the organization has no keys yet, use the prompt to create your first one.Name the key (for example,
oleria), assign it the custom role you created, and set an expiration date. Select Generate API Key.If you restrict the key under Allow access to this API Key -> Specific locations, include Oleria’s IP addresses. To get them, contact support@oleria.com.
3
Copy the Key ID and Key secret
Copy the Key ID and Key secret before you leave the page. You’ll paste both into Oleria in the next section.
Connect ClickHouse Cloud to Oleria
1
Find ClickHouse Cloud in Oleria
Go to your Oleria workspace, select Integrations, select the Available tab, and search for ClickHouse Cloud.
2
Complete the connection form
Select the ClickHouse Cloud card and fill in the connection form:
You don’t need to enter an organization or a host. Oleria finds the organization the key belongs to.
3
Save the integration
Select Authenticate. Oleria checks that the key can read your organization’s members before saving the integration.
Verify the integration
Confirm the new instance appears on the Connected tab of your Oleria Integrations page with a status of Healthy. Oleria names the connection after your ClickHouse Cloud organization. After the first sync completes, you can review the discovered accounts, roles, API keys, and activity in your Oleria workspace.If you replace or rotate the API key, edit the integration in Oleria and enter both the new API Key ID and API Key Secret. To keep the current key while editing, leave both fields blank. The new key must belong to the same ClickHouse Cloud organization. To connect a different organization, add a new integration instead.
Remediation actions
Beyond discovery, Oleria can act on ClickHouse Cloud access to remediate risk, using the same API key. Oleria checks that the key has the permissions each action needs before it runs.
Required permissions per action:
- Disable user accounts and Delete user -
control-plane:organization:viewandcontrol-plane:organization:manage. - Add user to role and Remove user from role -
control-plane:organization:view,control-plane:organization:manage,control-plane:organization:view-api-keys, andcontrol-plane:organization:update-api-keys. - Disable NHI accounts -
control-plane:organization:view-api-keysandcontrol-plane:organization:update-api-keys.
- Oleria won’t remove the last member with administrative permissions, or remove a role if that would leave the organization with no administrator.
- Oleria won’t remove an account’s only role. To cut an API key’s access, disable it instead.
- Oleria won’t disable or change the roles of the API key the integration uses. Doing so would disconnect the integration.
- A pending invitation’s roles can’t be changed. Delete the invitation and invite the person again.
- A revert only undoes the change Oleria made. If someone changed the same account or key in ClickHouse Cloud in the meantime, Oleria leaves it as is. A removed member isn’t re-invited if they already rejoined or have a pending invitation.
Known limitations
- Groups aren’t discovered. ClickHouse Cloud has groups only through SCIM, which requires the Enterprise plan and SAML, and each SCIM group maps to a custom role. Oleria shows that access through roles.
- MFA, SSO, and authentication methods aren’t available. The ClickHouse Cloud API doesn’t expose them for members, so Oleria reports these fields as unavailable, not as disabled. Changes to MFA methods and SAML connections still appear in activity.
- Password changes aren’t available. The API and the audit log don’t report when a member changed their password.
- Member last activity is partial. ClickHouse Cloud doesn’t report when a member last signed in, so Oleria uses the newest audit log event the member performed in the last 30 days. Members who only sign in and view data can appear inactive. API keys have an exact last-used time.
- Members are always shown as enabled. ClickHouse Cloud has no disabled state for members. A member removed from your SAML identity provider stays in the organization until someone removes them.
- Database users and roles aren’t discovered. Oleria reads the organization’s control plane. Database users, roles, and grants inside each service aren’t inventoried.
- Services aren’t discovered as resources. Oleria doesn’t inventory services, backups, or ClickPipes. Service events still appear in activity.
- SCIM tokens aren’t discovered. ClickHouse Cloud offers no API to list them.
- System and support activity has no linked account. Audit events performed by ClickHouse system processes or ClickHouse support staff appear without an account.
- API keys only. ClickHouse Cloud API keys authenticate with a Key ID and Key secret. OAuth isn’t supported.