1. Cloud Console SSO — SAML or OIDC for the CockroachDB Cloud web console
2. DB Console SSO — OIDC for the DB Console web UI (Advanced/Enterprise only)
3. SQL/Cluster SSO — JWT-based or LDAP/AD authentication for SQL client connections
4. SCIM 2.0 — Automated user provisioning on the Cloud Console

• Enabling centralized identity management via an IdP (Okta, Azure AD, Google Workspace, etc.)
• Meeting compliance requirements for SSO-only authentication
• Automating user provisioning and deprovisioning to prevent orphaned accounts
• Setting up SSO for SQL authentication to eliminate database-level passwords
• Configuring LDAP/AD authentication for self-hosted clusters in on-prem or hybrid environments
• Responding to a security audit finding about missing SSO or SCIM configuration

• Cloud Console role: Organization Admin (for Console SSO and SCIM)
• SQL access: Cluster admin role (for DB Console SSO and SQL/Cluster SSO)
• Identity Provider (IdP): Configured and operational — Okta, Azure AD, Google Workspace, PingOne, or other SAML/OIDC-compatible provider
• ccloud CLI authenticated (

  ccloud auth login

  ) — for Cloud Console SSO/SCIM
• DB Console SSO: Advanced or Enterprise plan required (not available on Standard or Basic)
• SCIM: Enterprise plan required for SCIM 2.0
• LDAP/AD: Self-hosted CockroachDB cluster required (LDAP is not available on CockroachDB Cloud)

ccloud auth whoami

• SAML: Best for enterprise IdPs with existing SAML infrastructure (Okta, Azure AD, PingOne)
• OIDC: Simpler setup, supports Google Workspace and modern IdPs natively
• Skip: Not needed

• Enable (OIDC): SSO for the DB Console web UI. Requires Advanced or Enterprise plan — not available on Standard or Basic
• Skip: Not needed or plan does not support it

• JWT-based: Cloud-native approach using JWT tokens for SQL client connections. Works on both CockroachDB Cloud and self-hosted clusters
• LDAP/AD: Direct directory authentication against Active Directory or OpenLDAP. Self-hosted only (not available on CockroachDB Cloud)
• Skip: Not needed

• Enable: Automates user lifecycle (create/update/deactivate) between IdP and Cloud Console. Requires Enterprise plan
• Skip: Manage Cloud Console users manually

1. Navigate to Organization Settings > Authentication in the Cloud Console
2. Select SAML as the SSO provider type
3. Configure the SAML connection:
   • Enter the IdP metadata URL or upload the metadata XML
   • Copy the CockroachDB Cloud ACS URL and Entity ID to your IdP
   • Map IdP attributes to CockroachDB Cloud user fields (email, name)
4. In your IdP, create a SAML 2.0 application:
   • Set the Single sign-on URL to the CockroachDB Cloud ACS URL
   • Set the Audience URI (SP Entity ID) to the CockroachDB Cloud Entity ID
   • Set Name ID format to Email Address
   • Map attributes:

     email

     ,

     firstName

     ,

     lastName

5. Assign users or groups to the SAML application in the IdP

1. Navigate to Organization Settings > Authentication in the Cloud Console
2. Select OIDC as the SSO provider type
3. Configure the OIDC connection:
   • Enter the OIDC discovery URL from your IdP (e.g.,

     https://accounts.google.com/.well-known/openid-configuration

     )
   • Enter the Client ID and Client Secret from your IdP
   • Configure the redirect URI in the IdP to point to CockroachDB Cloud
4. In your IdP, create an OIDC/OAuth 2.0 application:
   • Set Sign-in redirect URI to the CockroachDB Cloud redirect URI
   • Grant scopes:

     openid

     ,

     profile

     ,

     email

5. Assign users or groups to the OIDC application in the IdP

1. Open a new browser session (or incognito window)
2. Navigate to the CockroachDB Cloud Console login page
3. Select Sign in with SSO
4. Verify redirect to IdP, authenticate, and redirect back to Cloud Console

1. Navigate to Organization Settings > Authentication
2. Enable Require SSO to disable password-based login
3. Confirm a break-glass admin account exists (see Safety Considerations)

This configures SSO for the DB Console web UI only, NOT for SQL client connections. SQL client SSO is configured separately in Part 3 (JWT) or Part 4 (LDAP/AD).

Prerequisite: Advanced or Enterprise plan required. DB Console SSO is not available on Standard or Basic plans.

1. Open the DB Console URL in a browser
2. Click Log in with OIDC
3. Authenticate with your IdP
4. Verify you are logged into the DB Console

WARNING — HBA first-match-wins: HBA rules are evaluated top-to-bottom. The first matching rule is used. A rule like

host all all all ldap ...

matches ALL users from ALL addresses and will prevent password fallback for any user. Always scope LDAP rules to specific users or roles to avoid locking out admin accounts.

host all all all ldap

-- Configure HBA for LDAP authentication scoped to specific users
-- The 'root' user and other admin users keep password auth
SET CLUSTER SETTING server.host_based_authentication.configuration = '
host all root all password
host all admin_user all password
host all all all ldap "ldapserver=ldap.example.com" "ldapport=389" "ldapbasedn=dc=example,dc=com" "ldapsearchattribute=uid" "ldapsearchfilter=(objectClass=inetOrgPerson)" "ldapbinddn=cn=readonly,dc=example,dc=com" "ldapbindpasswd=<bind-password>"
host all all all password
';

• ldapserver

  — LDAP server hostname

• ldapport

  — LDAP server port (389 for LDAP, 636 for LDAPS)

• ldapbasedn

  — Base DN for user search

• ldapsearchattribute

  — Attribute matching the SQL username (e.g.,

  uid

  for OpenLDAP,

  sAMAccountName

  for AD)

• ldapsearchfilter

  — Required. LDAP filter to narrow the user search (e.g.,

  (objectClass=inetOrgPerson)

  )

• ldapbinddn

  — DN of the service account used for LDAP bind/search

• ldapbindpasswd

  — Password for the bind DN service account

Important: Each HBA option must be quoted as

"key=value"

(the entire key=value pair in one set of quotes).

Skip this section if the user does not need automated user provisioning or does not have an Enterprise plan.

1. Navigate to Organization Settings > Authentication > SCIM in the Cloud Console
2. Enable the SCIM 2.0 endpoint
3. Copy the SCIM base URL and Bearer token for IdP configuration

1. Add a new SCIM provisioning integration
2. Enter the SCIM base URL from step 5.2
3. Enter the Bearer token for authentication
4. Configure provisioning actions:
   • Create users — New IdP users are created in CockroachDB Cloud
   • Update user attributes — Name and email changes sync
   • Deactivate users — Removed IdP users are deactivated in CockroachDB Cloud
5. Assign users or groups to the SCIM integration

1. Create a test user in your IdP and assign them to the SCIM integration
2. Check the Cloud Console — the user should appear within a few minutes
3. Remove the test user from the IdP SCIM assignment
4. Verify the user is deactivated in the Cloud Console

1. Use the break-glass account: Log in with the pre-configured password-based admin account
2. Disable SSO enforcement: Navigate to Organization Settings > Authentication and disable "Require SSO"
3. If no break-glass account exists: Contact CockroachDB Cloud support to disable SSO enforcement for your organization

• Verify the JWT issuer configuration in

  server.jwt_authentication.issuers.configuration

• Check that the JWT token has not expired
• Verify that

  server.jwt_authentication.jwks_auto_fetch.enabled

  is

  true

• Inspect the token contents:

  echo '<token>' | cut -d. -f2 | base64 -d | jq .

• Verify the

  aud

  (audience) claim in the token matches the configured audience

• The issuer URL in the token does not match

  server.jwt_authentication.issuers.configuration

• Re-check the issuer URL matches exactly (trailing slashes matter)

• The

  server.oidc_authentication.principal_regex

  does not match the claim value from the token
• Test the regex against the actual claim value:

SHOW CLUSTER SETTING server.oidc_authentication.principal_regex;
-- Common patterns:
-- Email -> username (strip domain): '^([^@]+)'
-- Full email as username: '^(.+)$'

• CockroachDB uses Go's

  regexp

  syntax (no lookaheads/lookbehinds)
• Test at https://regex101.com/ with the "Golang" flavor

• Verify

  ldapbinddn

  and

  ldapbindpasswd

  are correct
• Check that the bind service account has read access to the user search base
• Test with:

  ldapsearch -H ldap://ldap.example.com -D "cn=readonly,dc=example,dc=com" -W -b "dc=example,dc=com" "(uid=testuser)"

• Verify

  ldapbasedn

  includes the OU where the user resides
• Check that

  ldapsearchattribute

  matches the login attribute (

  uid

  for OpenLDAP,

  sAMAccountName

  for AD)
• Check that

  ldapsearchfilter

  is set — without it, LDAP user search will fail

• This happens when an overly broad HBA rule like

  host all all all ldap ...

  is the first rule and the LDAP server is unreachable, or the LDAP config is wrong
• Fix: Ensure

  root

  and admin users have explicit

  password

  rules BEFORE any

  ldap

  rule
• Recovery: Connect as

  root

  using client certificate auth (bypasses HBA) and fix the HBA configuration

• Verify network connectivity from CockroachDB nodes to the LDAP server
• For LDAPS, ensure the CA certificate is configured via

  server.ldap_authentication.domain.custom_ca

• Check firewall rules for port 389 (LDAP) or 636 (LDAPS)

• Azure AD tokens include an

  aud

  claim that must match the configured audience
• For JWT SQL SSO: ensure the audience in

  server.jwt_authentication.issuers.configuration

  matches
• For DB Console OIDC: ensure

  server.oidc_authentication.client_id

  matches

• For single-tenant: use

  https://login.microsoftonline.com/<tenant-id>/v2.0

  as the issuer
• For multi-tenant: use

  https://login.microsoftonline.com/common/v2.0

  (requires additional validation)

1. Before enforcing SSO, ensure at least one organization admin account uses password authentication
2. Document the break-glass account credentials in a secure vault (e.g., 1Password, HashiCorp Vault)
3. Test the break-glass account periodically to ensure it still works
4. For SQL SSO (JWT or LDAP), keep at least one SQL user with password authentication as a fallback

• host all all all ldap ...

  as the first rule will force ALL users through LDAP — including

  root

• If the LDAP server goes down, ALL authentication fails (including admin access)
• Always place password rules for

  root

  and admin users BEFORE LDAP rules

undefined

1. Log in with the break-glass admin account
2. Navigate to Organization Settings > Authentication
3. Disable Require SSO to re-enable password login

1. Navigate to Organization Settings > Authentication > SCIM
2. Disable the SCIM endpoint
3. Remove the SCIM integration from your IdP

• IdP configuration steps

• auditing-cloud-cluster-security — Run a full security posture audit
• enforcing-password-policies — Strengthen password policies as an alternative to SSO
• managing-tls-certificates — Certificate-based authentication as an alternative to SSO

• Cloud Console SSO
• DB Console SSO
• Cluster SSO (JWT)
• SCIM Provisioning
• Cluster Settings
• HBA Configuration
• JWT Authentication
• LDAP Authentication
• Authentication Reference