Skip to main content
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.
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.
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. This is what each part of the sync reads, and the roles CockroachDB Cloud accepts for it at organization scope: 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

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 and 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.
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.
CockroachDB Cloud shows the API key secret only once, when you create it. Copy it now and store it securely.
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. 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: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.
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. 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.