> ## Documentation Index > Fetch the complete documentation index at: https://docs.oleria.com/llms.txt > Use this file to discover all available pages before exploring further. # CockroachDB Cloud > Connect a CockroachDB Cloud organization with a service account API key so Oleria can discover users, groups, built-in roles and their scopes, service accounts, API keys, and audit log activity. CockroachDB Cloud is a managed distributed SQL database platform. Connect your CockroachDB Cloud organization to Oleria to see who and what can act on its control plane, which built-in roles they hold and at what scope, and what they do with that access. Oleria reads the CockroachDB Cloud API and its SCIM API for one organization per connection. ## What Oleria discovers * **Users**, with their name, email, active state, creation date, and the roles they hold directly or through groups. Users with **Organization Admin** at organization scope, directly or through a group, are flagged as admins. Users provisioned by your identity provider are marked as such. Last activity comes from the audit log (see below). * **Groups** and their members, including service accounts and nested groups. Groups pushed by your identity provider show as synced groups. Groups created in CockroachDB Cloud show as custom groups. * **Roles**: the 14 built-in CockroachDB Cloud roles, such as **Organization Admin**, **Cluster Admin**, **Folder Admin**, and **Auditor**. Each assignment records its scope: the whole organization, a folder, or a cluster, with the folder or cluster name when Oleria can read it. Roles held by groups appear on the group. Users and service accounts with no other role show **Organization Member**, the default role that adds no permissions. * **Non-human identities**: * Service accounts, with their roles, description, creation date, and the user who created them when the creator matches exactly one user. * API keys, each linked to the service account it belongs to. An API key carries all of its service account's roles, so it inherits that account's admin flag. * Service-account credentials (JWT-bearer public keys), with their expiration date and whether they're active, disabled, or expired, each linked to its service account. * Federated workload identities from JWT issuers, such as a CI pipeline whose tokens CockroachDB Cloud accepts. Each identity records the issuer, audience, and the token identity it matches, and is linked to the users and service accounts it can act as. A pattern-based token identity is shown once, not expanded. An identity is flagged as an admin when it can act as an Organization Admin. When its mapping builds the CockroachDB identity from the token (for example `\1@example.com`), it has no links, and it's flagged as an admin if that template could name an Organization Admin. * **Activity** from the organization audit log. Oleria maps each of the audit log's roughly 121 action types, such as logins, failed logins, role grants and removals, API key and service account changes, SSO and MFA policy changes, and cluster and network settings. Events are attributed to the user or service account that performed them, with the source IP address. Oleria uses this data for access reviews, dormant account detection, over-privileged user flagging, and NHI discovery, refreshed on Oleria's [regular sync schedule](/integrations/overview.md#sync-model). > [!NOTE] > > This is a governance integration. Clusters and folders appear only as the scope of a role assignment. Oleria doesn't discover clusters, folders, databases, or SQL users as resources. ## Prerequisites * The **Organization Admin** role in your CockroachDB Cloud organization, to create a service account and assign its role. * Admin access on the Oleria platform to add a new integration. * For full user details and groups, **Cloud Organization SSO** enabled in CockroachDB Cloud. Oleria reads users and groups through SCIM, which needs it. See [Without Cloud Organization SSO](#without-cloud-organization-sso). One Oleria integration covers one CockroachDB Cloud organization. To connect several organizations, create a service account and API key in each one and add a separate integration for each. ### Permissions Oleria needs CockroachDB Cloud API keys get their permissions from the roles of their service account. Assign the service account one of these roles at **organization** scope, directly or through a group. A role assigned at folder or cluster scope doesn't count, and Oleria refuses a key whose service account holds neither role at organization scope. **Cluster Admin** alone isn't enough, because it can't read users, groups, or the audit log. | Role | Use it for | | :- | :- | | **Organization Admin** (`ORG_ADMIN`) | Sync and every [remediation action](#remediation-actions). | | **Auditor** (`AUDITOR`) | Read-only sync. Remediation actions aren't available. **Auditor** is a Limited Access role, not enabled by default. To enroll your organization, contact your Cockroach Labs account team. | This is what each part of the sync reads, and the roles CockroachDB Cloud accepts for it at organization scope: | What Oleria reads | Roles that can read it | If it can't be read | | :- | :- | :- | | Users (SCIM) | `ORG_ADMIN` or `AUDITOR`, and Cloud Organization SSO | Without SSO, users are read from role assignments with ID and roles only. See [Without Cloud Organization SSO](#without-cloud-organization-sso). | | Service accounts | `ORG_ADMIN`, `CLUSTER_ADMIN`, or `AUDITOR` | Oleria refuses the connection. | | Role assignments | `ORG_ADMIN`, `CLUSTER_ADMIN`, `FOLDER_ADMIN`, or `AUDITOR` | Oleria refuses the connection. | | Groups and their members | `ORG_ADMIN` or `AUDITOR`, and Cloud Organization SSO | No groups are collected, and the integration's **Capabilities** tab shows **Read groups** as not enabled. | | API keys | `ORG_ADMIN`, `CLUSTER_ADMIN`, or `AUDITOR` | No API keys are collected. The rest of the sync continues. | | Service-account credentials | `ORG_ADMIN`, `CLUSTER_ADMIN`, or `AUDITOR`, and the Limited Access service-account credentials feature | No credentials are collected. The rest of the sync continues. | | JWT issuers and their identity maps | `ORG_ADMIN` or `AUDITOR`, and the Limited Access JWT issuers feature | No federated workload identities are collected. The rest of the sync continues. | | Audit log | `ORG_ADMIN` or `AUDITOR`, and the Limited Access audit log feature | No activity is collected, and users and service accounts have no last activity date. | | Folder and cluster names | Any role that can list folders and clusters, including `AUDITOR` | Role scopes show the folder or cluster ID without its name. | **Organization Admin** or **Auditor** covers every row. The Limited Access features are enabled by your Cockroach Labs account team. When one isn't enabled, Oleria skips that data and keeps syncing the rest. ## Create a service account and API key > [!NOTE] > > The exact location of these settings can change over time. If the steps below don't match what you see, refer to CockroachDB's [managing access](https://www.cockroachlabs.com/docs/cockroachcloud/managing-access) and [Cloud API](https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api) documentation. **1. Create a service account** In the CockroachDB Cloud Console, go to **Access Management** -> **Service Accounts** and create a service account for Oleria, for example `oleria`. Use a service account dedicated to Oleria. Oleria never removes this account's admin roles or disables it or its keys, and it tags the account's own audit log entries as Oleria activity. **2. Assign a role at organization scope** Assign the service account **Organization Admin** at organization scope for sync and remediation, or **Auditor** at organization scope for read-only sync. See [Permissions Oleria needs](#permissions-oleria-needs). > [!WARNING] > > **Organization Admin** can manage every user, service account, and role assignment in the organization. Treat its API key as an admin credential. **3. Create an API key** Create an API key for the service account and copy its secret. The secret starts with `CCDB1_`. You'll paste it into Oleria in the next section. > [!WARNING] > > CockroachDB Cloud shows the API key secret only once, when you create it. Copy it now and store it securely. > [!TIP] > > CockroachDB Cloud limits the API to 10 requests per second for each service account. The limit is shared by everything that uses the same service account, which is another reason to keep one dedicated to Oleria. ### Without Cloud Organization SSO SCIM needs Cloud Organization SSO. If SSO isn't enabled, Oleria still connects and syncs, with less user and group data: * Users are read from role assignments. Each user shows its ID and roles only, without a name or email, and is always shown as enabled. * No groups are collected. * The user and group remediation actions use SCIM, so Oleria shows them as unavailable: **Disable user accounts**, **Enable user accounts**, **Delete user**, **Create user**, **Add user to group**, **Remove user from group**, and **Create group**. **Add user to role**, **Remove user from role**, and **Disable NHI accounts** still work. To get full user and group data, [enable Cloud Organization SSO](https://www.cockroachlabs.com/docs/cockroachcloud/cloud-org-sso). Oleria picks it up on the next sync. ## Connect CockroachDB Cloud to Oleria **1. Open the integration** Go to your Oleria workspace, select **Integrations**, then select the **CockroachDB Cloud** tile. **2. Complete the connection form** Fill in the connection form: | Field | Notes | | :- | :- | | API key secret | Required. The secret of the service account's API key. It starts with `CCDB1_`. | You don't need to enter an organization. Oleria finds the organization the key belongs to. **3. Save the integration** Select **Authenticate**. Oleria checks that the key authenticates and can read your organization's users and role assignments 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 CockroachDB Cloud organization. After the first sync completes, you can review the discovered users, groups, roles, non-human identities, and activity in your Oleria workspace. > [!NOTE] > > If you rotate the API key, edit the integration in Oleria and enter the new **API key secret**, then select **Update**. To keep the stored key while editing, leave **API key secret** empty. The new key must belong to the same CockroachDB Cloud organization: Oleria refuses a key from another organization. To connect a different organization, add a new integration. ## Remediation actions Oleria can take these actions in CockroachDB Cloud when the integration's service account holds **Organization Admin** at organization scope, directly or through a group. Until it does, Oleria shows the actions as missing permissions. Before every change, Oleria reads the target's current state. If the target is already in the requested state, nothing changes and there's nothing to revert. Oleria never undoes someone else's change: a revert runs only while the target is still as the action left it. Otherwise Oleria skips the revert and the revert result says why. | Action | What it does | Revert | | :- | :- | :- | | Disable user accounts | Deactivates the user. Oleria doesn't change the user's roles or group memberships. | Reactivates the user, while they're still deactivated. | | Enable user accounts | Reactivates a deactivated user. | Deactivates the user again, while they're still active. | | Add user to group | Adds a user or service account to a group. | Removes the member, while they're still in the group. | | Remove user from group | Removes a user or service account from a group. | Adds the member back, while they're still out of the group. | | Add user to role | Grants a built-in role to a user or service account at organization scope. A cluster or folder role granted at organization scope applies to every cluster or folder in the organization. | Removes the grant, while it's still in place. | | Remove user from role | Removes the role from a user or service account at every scope where they hold it directly: organization, folder, and cluster. A role held through a group stays, and Oleria reports which groups still grant it. | Re-adds only the scopes this action removed and that are still missing. | | Disable NHI accounts: API key | Deletes the API key. | Not supported - a deleted key can't be restored. Create a new key instead. | | Disable NHI accounts: service-account credential | Deletes the credential. | Not supported - a deleted credential can't be restored. Register a new one instead. | | Disable NHI accounts: service account | Replaces the service account's roles with **Organization Member** only, which grants no permissions. The service account and its keys remain, but they can no longer do anything. A service account that already holds no other role isn't changed. | Restores the service account's previous roles, while it still holds only **Organization Member**. | | Delete user | Deletes the user from the organization. | Not supported - re-invite or re-provision the user. | | Create user | Creates a user with the email you provide as their sign-in name, active unless you choose otherwise, and optionally adds them to groups. If an active user with that email already exists, nothing changes and the groups aren't applied. If the existing user is deactivated, the action fails: use **Enable user accounts** instead. | Deletes the user the action created, while their sign-in name is unchanged. | | Create group | Creates a group with the name you provide. If a group with that name already exists, nothing changes. | Deletes the group the action created, but only if it still has its name, has no members, and holds no roles, directly or through a parent group. | The role and group actions accept users and service accounts. An API key or credential holds its service account's roles, so act on the service account instead. **Organization Member** can't be granted or removed, because every member of the organization holds it. A few safeguards apply: * Oleria won't disable or delete the API key the integration uses, its service account, or that service account's other keys and credentials. It also won't remove that service account from a group, or remove its **Organization Admin** or **Cluster Admin** role. Doing so would disconnect the integration. * Oleria won't deactivate, delete, or take a role or group away from the last active user who holds both **Organization Admin** and **Cluster Admin** at organization scope. CockroachDB Cloud requires at least one such user to remain. * Oleria won't disable a service account that inherits roles from a group, because replacing its own roles wouldn't remove that access. Remove it from those groups first. * Oleria never claims a create it can't confirm. If CockroachDB Cloud doesn't answer a create request and a user or group with that name then exists, the action fails without claiming it, because someone else, such as your identity provider, may have created it. Reverting that action deletes nothing. * Changes to a group that your identity provider manages can be overwritten on its next push. Oleria notes this in the action result. ## Troubleshooting ### Connection fails because the API key was rejected **Symptom:** When you select **Authenticate**, Oleria reports that CockroachDB Cloud rejected the API key secret. **Cause:** CockroachDB Cloud didn't accept the key. The secret is incomplete or mistyped, or the key or its service account was deleted. **Fix:** 1. Check that the API key still exists on the service account in the CockroachDB Cloud Console. 2. Copy the full secret, starting with `CCDB1_`. If you no longer have it, create a new API key, because CockroachDB Cloud shows a secret only once. 3. Enter the secret in Oleria and select **Authenticate** again. ### Connection fails because the key belongs to a different organization **Symptom:** When you edit the integration, Oleria reports that the API key belongs to a different CockroachDB Cloud organization than the one the integration is connected to. **Cause:** An integration stays tied to the organization it was first connected to. The new key was created in another organization. **Fix:** Create the API key on a service account in the organization the integration is connected to. To connect the other organization, add a new integration instead. ### Connection fails because the service account is missing a role **Symptom:** When you select **Authenticate**, Oleria reports that the service account holds neither Organization Admin nor Auditor at organization scope, or that it can't read service accounts or role grants, and names the roles to assign. **Cause:** The service account doesn't hold **Organization Admin** or **Auditor** at organization scope, directly or through a group. A role assigned at folder or cluster scope doesn't count, and **Cluster Admin** alone isn't enough. An existing integration whose service account loses these roles also fails its next connection check and sync. **Fix:** Assign the service account **Organization Admin** or **Auditor** at organization scope, then select **Authenticate** again. You don't need a new API key, because the key carries its service account's roles. ### Remediation actions are refused **Symptom:** Actions show as missing permissions, or fail because Oleria can't identify the integration's own service account. **Cause:** Either the service account doesn't hold **Organization Admin** at organization scope, or Oleria can't read the integration's own API key and service account. Oleria refuses to act until it knows which key and service account it connects with, so it can't disable them by mistake. It identifies its key from the secret, which must be a complete `CCDB1_` API key secret. **Fix:** Assign the service account **Organization Admin** at organization scope. If the actions still fail, edit the integration and enter the full API key secret again. ## Known limitations * **MFA, SSO enforcement, authentication methods, and password age aren't available.** The CockroachDB Cloud API doesn't expose them, so Oleria reports these fields as unavailable, not as disabled. Changes to MFA enforcement, SSO, and sign-in methods still appear in activity. * **Sessions can't be revoked.** The CockroachDB Cloud API has no way to end a user's sessions, so the revoke sessions action isn't offered. * **Groups need SCIM.** Without Cloud Organization SSO, no groups are collected and users have only their ID and roles. If SSO was turned off after groups held roles, a group that still holds a role can't be told apart from a user and shows as one. * **Disabling a service account removes its roles.** CockroachDB Cloud has no disabled state for service accounts, API keys, or credentials. **Disable NHI accounts** reduces a service account to **Organization Member** and deletes API keys and credentials. * **Last activity covers 30 days.** Oleria uses the newest successful audit log entry a user or service account performed in the last 30 days. It needs the audit log feature. API keys and credentials have no last-used date. Service accounts that share a name get no last activity date, because audit entries name the service account rather than its ID. * **Activity targets the organization.** Audit entries don't identify the object that changed in a form Oleria can read, so every event is recorded against the organization. The entry's details are kept with the event, with any API key secret redacted. * **Federated identities are read-only.** Oleria shows which users and service accounts a JWT issuer's identity map lets a workload act as, but **Disable NHI accounts** doesn't apply to them. To revoke one, edit the issuer's identity map in CockroachDB Cloud. A mapping that uses a regex capture group, or that names an identity Oleria can't match to exactly one user or service account, is kept in the identity's details without a link. * **API key creators aren't known.** A service account's creator is shown only when it matches exactly one user. API keys and credentials have no creator. * **Pending invitations aren't discovered.** CockroachDB Cloud has no API to list them. Invitation events still appear in activity. * **Clusters, folders, databases, and SQL users aren't discovered.** Oleria reads the organization's control plane. SQL users and the grants inside each cluster aren't inventoried. Cluster and SQL user events still appear in activity. * **API keys only.** Oleria authenticates with a service account API key. OAuth isn't supported. ## Contact us For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.