configuring-sso-and-scim

What this skill does

# Configuring SSO and SCIM

Configures Single Sign-On (SSO) and SCIM 2.0 provisioning for CockroachDB across four distinct layers:

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

## Prerequisites

- **Console SSO/SCIM:** Organization Admin + `ccloud` CLI
- **DB Console/SQL SSO:** Cluster admin role + Advanced or Enterprise plan (DB Console SSO not on Standard/Basic)
- **LDAP/AD:** Self-hosted only (not available on CockroachDB Cloud)
- **SCIM 2.0:** Enterprise plan required

## Configuration Decisions

Before proceeding, determine which layers the user needs. Ask which of the following apply, then follow only the relevant Parts below.

**Decision 1 — Cloud Console SSO:**
- **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

**Decision 2 — DB Console SSO:**
- **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

**Decision 3 — SQL/Cluster SSO method:**
- **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

**Decision 4 — SCIM 2.0 provisioning:**
- **Enable:** Automates user lifecycle (create/update/deactivate) between IdP and Cloud Console. Requires Enterprise plan
- **Skip:** Manage Cloud Console users manually

## Steps

### Part 1: Cloud Console SSO

Cloud Console SSO enables SAML or OIDC authentication for the CockroachDB Cloud web console.

#### 1.1 Check Current SSO Configuration

Check SSO status in the Cloud Console UI (Organization Settings > Authentication).

#### 1.2a Configure SAML SSO

Follow this section if the user selected **SAML** in Decision 1.

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

See [configuration steps reference](references/configuration-steps.md) for IdP-specific SAML instructions (Okta, Azure AD).

#### 1.2b Configure OIDC SSO

Follow this section if the user selected **OIDC** in Decision 1.

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

See [configuration steps reference](references/configuration-steps.md) for IdP-specific OIDC instructions (Okta, Azure AD, Google Workspace).

#### 1.3 Test SSO Login

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.4 Enforce SSO (Disable Password Login)

After verifying SSO works:

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)

### Part 2: DB Console SSO (OIDC)

> **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.

DB Console SSO uses OIDC to authenticate users to the CockroachDB DB Console web interface.

#### 2.1 Check Current DB Console SSO Configuration

```sql
SHOW CLUSTER SETTING server.oidc_authentication.enabled;
SHOW CLUSTER SETTING server.oidc_authentication.provider_url;
SHOW CLUSTER SETTING server.oidc_authentication.client_id;
```

#### 2.2 Configure DB Console SSO

```sql
-- Enable OIDC authentication for the DB Console
SET CLUSTER SETTING server.oidc_authentication.enabled = true;

-- Set the OIDC provider URL (your IdP's discovery endpoint)
SET CLUSTER SETTING server.oidc_authentication.provider_url = 'https://your-idp.example.com';

-- Set the client ID registered in your IdP
SET CLUSTER SETTING server.oidc_authentication.client_id = '<client-id>';

-- Set the client secret
SET CLUSTER SETTING server.oidc_authentication.client_secret = '<client-secret>';

-- Configure the claim field used for username mapping
SET CLUSTER SETTING server.oidc_authentication.claim_json_key = 'email';

-- Configure the principal regex (extract username from claim)
SET CLUSTER SETTING server.oidc_authentication.principal_regex = '^([^@]+)';
```

See [configuration steps reference](references/configuration-steps.md) for IdP-specific DB Console SSO setup (Okta, Azure AD).

#### 2.3 Test DB Console SSO

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

### Part 3: SQL/Cluster SSO (JWT)

SQL/Cluster SSO uses JWT tokens from an IdP to authenticate SQL client connections. This is separate from DB Console SSO (Part 2) — it authenticates `cockroach sql` and application connections, not the web UI.

#### 3.1 Check Current JWT SSO Configuration

```sql
SHOW CLUSTER SETTING server.jwt_authentication.enabled;
SHOW CLUSTER SETTING server.jwt_authentication.issuers.configuration;
SHOW CLUSTER SETTING server.jwt_authentication.jwks_auto_fetch.enabled;
```

#### 3.2 Configure JWT Authentication

```sql
-- Enable JWT authentication for SQL connections
SET CLUSTER SETTING server.jwt_authentication.enabled = true;

-- Configure the JWT issuer(s)
-- Format: JSON object with issuer URL and audience
SET CLUSTER SETTING server.jwt_authentication.issuers.configuration = '{
  "issuers": [
    {
      "issuer": "https://your-idp.example.com",
      "audience": "<client-id>"
    }
  ]
}';

-- Enable automatic JWKS fetching (recommended)
SET CLUSTER SETTING server.jwt_authentication.jwks_auto_fetch.enabled = true;

-- Configure the claim used for SQL username mapping
SET CLUSTER SETTING server.jwt_authentication.claim = 'email';
```

See [configuration steps reference](references/configuration-steps.md) for IdP-specific JWT configuration (Okta, Azure AD, Google).

#### 3.3 Configure Identity Mapping

Map IdP identities (e.g., email addresses) to SQL usernames:

```sql
-- Map [email protected] -> user (strip domain)
SET CLUSTER SETTING server.identity_map.configuration = '
crdb /^(.*)@example\.com$ \1
';
```

#### 3.4 Enable Auto User Provisioning (Optional)

Auto-provision SQL users when they first authenticate via JWT:

```sql
SET CLUSTER SETTING security.pr