Cluster Single Sign-on (SSO) using JSON Web Tokens (JWTs)

• Configure a cluster for cluster single sign-on using JWTs
• Configure user provisioning (optional)
• Authenticate to your cluster

• Identity Provider (IdP): You must have access to an identity provider that supports JWT tokens, such as Okta, Google, Azure AD, or Keycloak.
• Cluster Settings Access: You must have the ability to update your cluster settings. Refer to .
• SQL User Provisioning:
  • If you are using automatic user provisioning, SQL users will be created automatically on first authentication.
  • If automatic user provisioning is disabled, a SQL user that corresponds with your external identity must be pre-created on the cluster. To create users, you must have access to the .
• (Optional) DB Console JWT Generation: To use the DB Console to generate JWTs (instead of obtaining them directly from your IdP), you must have your cluster pre-configured for OIDC/SSO authentication for DB Console. Use the guide to set this up.
• (Optional) JWT Authorization: To enable automatic role synchronization based on IdP group claims, see .

​

Configure your cluster for SSO

​

Cluster Settings

​

Update your cluster settings

1. In your IdP, find:
   • The issuer name, which can be found in the iss field of a JWT.
   • The issuer’s OpenID configuration endpoint, which is typically published at https://{ issuer URL }/.well-known/openid-configuration. The issuer URL is the domain portion of the configuration endpoint. From the full endpoint, you can find the issuer URL, and vice versa. For example, the issuer URL for CockroachDB CockroachDB Cloud is https://cockroachlabs.cloud and the configuration endpoint is https://cockroachlabs.cloud/.well-known/openid-configuration. The configuration endpoint for Google Cloud is https://accounts.google.com and the configuration endpoint is https://accounts.google.com/.well-known/openid-configuration. If you omit the .well-known/openid-configuration portion, it is appended automatically.
   • The public signing key your issuer uses to sign JWTs. Your cluster will reject JWTs that are not signed by this key. Fetch the public signing key from the configuration endpoint. For example:
     curl --silent https://accounts.google.com/.well-known/openid-configuration | jq .jwks_uri | xargs curl
     
     {
       "keys": [
         {
           "alg": "RS256",
           "use": "sig",
           "e": "AQAB",
           "kty": "RSA",
           "kid": "7c0b6913fe13820a333399ace426e70535a9a0bf",
           "n": "lWXY0XOj_ikSIDIvGOhfuRhQJAAj6BWsbbZ6P-PXRclzV32-QLB4GZHPPcH37Lou5pQsTQPvTETAfCLnglIRSbP8x1zA5tUakRlm5RiGF4kcWh5k60x8u0Uslx-d6EueKuY-KLHUVDuMULlHkYAScIdYnXz-Cnr6PFZj8RQezzdPVPH53Q8a_Z9b-vpGzsMS5gszITb-72OQNokojXdPVctl5WzSx-JnWbJxPiwHx_dSWgmTnyiYrZLqrqfampGdroaamtIXy0W8CAe0uCqcD1LunpfX-Q-RD1IycxnEaXSuUKhNhCcxtHWrozEyeD23Zja2WlcvHdYuTzyrvrvS9Q"
         },
         {
           "kid": "6f7254101f56e41cf35c9926de84a2d552b4c6f1",
           "e": "AQAB",
           "alg": "RS256",
           "use": "sig",
           "n": "oUriU8GqbRw-avcMn95DGW1cpZR1IoM6L7krfrWvLSSCcSX6Ig117o25Yk7QWBiJpaPV0FbP7Y5-DmThZ3SaF0AXW-3BsKPEXfFfeKVc6vBqk3t5mKlNEowjdvNTSzoOXO5UIHwsXaxiJlbMRalaFEUm-2CKgmXl1ss_yGh1OHkfnBiGsfQUndKoHiZuDzBMGw8Sf67am_Ok-4FShK0NuR3-q33aB_3Z7obC71dejSLWFOEcKUVCaw6DGVuLog3x506h1QQ1r0FXKOQxnmqrRgpoHqGSouuG35oZve1vgCU4vLZ6EAgBAbC0KL35I7_0wUDSMpiAvf7iZxzJVbspkQ",
           "kty": "RSA"
         }
       ]
     }
     
2. Enable JWT SQL authentication for your cluster:
   SET CLUSTER SETTING server.jwt_authentication.enabled = true;
   
3. Add your IdP’s issuer URL to your cluster’s list of accepted token issuers. If you have already configured , the issuer URL must match the value of server.oidc_authentication.provider_url.
   SET CLUSTER SETTING server.jwt_authentication.issuers.configuration = 'https://cockroachlabs.cloud';
   
4. Configure your cluster’s audience, which is your cluster’s ID (or JSON array of IDs) in your IdP. The audience is a mechanism for limiting the clients that can obtain JWTs from your IdP. If you have already configured , the issuer URL must match the value of server.oidc_authentication.client_id. Many third-party token issuers, including GCP and Azure, default to creating tokens with a generic default audience. We recommend limiting the scope of access tokens if possible. By extension, if your provider allows you to specify scopes or permissions on the token, we recommend configuring the scopes or permissions to be as restrictive as possible.
   SET CLUSTER SETTING server.jwt_authentication.audience = '984901724939-njig7lkv7k724rbv2hllvr4of8ul7th7.apps.googleusercontent.com';
   
5. Configure the field in the JWT that contains the email address that corresponds to a SQL user.
   SET CLUSTER SETTING server.jwt_authentication.claim = 'email';
   
6. Add your IdP’s public signing key, which you found previously, to your cluster’s list of acceptable signing JSON web keys (JWKS). Your cluster will reject JWTs that are not signed by a signing key that is listed in server.jwt_authentication.jwks. If you want to enable automatic fetching of signing keys instead of configuring static signing keys, skip this step. IdPs such as Google rotate their signing keys periodically. You must update your cluster with a new signing key before the previous one expires, or your SQL clients will be unable to connect with cluster SSO. We recommend updating this cluster setting with the current key daily to avoid this scenario. Alternatively, you can enable server.jwt_authentication.jwks_auto_fetch.enabled to automatically fetch signing keys from the issuer instead of maintaining a static list of signing keys. If server.jwt_authentication.jwks_auto_fetch.enabled is enabled, then server.jwt_authentication.jwks is ignored. By default, CockroachDB Advanced clusters are configured with CockroachDB CockroachDB Cloud’s public key, so that CockroachDB CockroachDB Cloud can serve as an IdP. This is required for . When modifying this cluster setting, do not omit the CockroachDB CockroachDB Cloud public key from the key set, or SSO with ccloud will no longer work. The public key for CockroachDB can be found at https://cockroachlabs.cloud/.well-known/openid-configuration. Replace the full contents of keys with the list of keys you found previously.
   SET CLUSTER SETTING server.jwt_authentication.jwks = '{
     "keys": [
       {
         ...
       }
     ]
   }';
   

1. Set your Identity Map. Refer to Identity Map configuration.
   SET CLUSTER SETTING
     server.identity_map.configuration = 'https://accounts.google.com /^(.*)@cockroachlabs\.com$ \1';
   
2. Enable token generation. This will also enable the Token Generation button to appear in the DB Console.
   SET CLUSTER SETTING
     server.oidc_authentication.generate_cluster_sso_token.enabled = true;
   
3. Configure how the user’s identity will be displayed by setting server.oidc_authentication.generate_cluster_sso_toke.use_token to either id_token or access_token, depending on the structure of the JWTs issued by your IdP.
   SET CLUSTER SETTING
     server.oidc_authentication.generate_cluster_sso_token.use_token = id_token;
   

​

How CockroachDB determines the SQL username from a JWT

1. server.jwt_authentication.claim determines which field to use to identify the external user. This must match a SQL user via the identity map.
2. server.identity_map.configuration maps that claim (along with the token’s issuer) to a SQL username.

​

Identity Map configuration

• https://accounts.google.com /^(.*)@cockroachlabs\.com$ \1 Maps every cockroachlabs email to a SQL user with the same username. That is, the part of the email address to the left of the @). For example, docs@cockroachlabs.com becomes docs.
• https://accounts.google.com 1232316645658094244789 roach Maps a single external identity with the hard-coded ID to the roach.
• https://accounts.google.com /^([9-0]*)$ gcp_\1 Maps each GCP-provisioned service account to a SQL user named gcp_{ GCP user ID }. For example, gcp_1234567 for a service account with ID 1234567.

​

Configure user provisioning

​

Enable user provisioning

SET CLUSTER SETTING security.provisioning.jwt.enabled = true;

​

How it works

1. A user presents a valid JWT token during authentication.
2. If the user doesn’t exist in CockroachDB, the user is created automatically.
3. The user is tagged with the PROVISIONSRC role option: jwt_token:<issuer, where <issuer is the JWT issuer URL.
4. If is also enabled, roles are synchronized immediately after user creation.

​

Auditing provisioned users

SHOW ROLES;

  username  |                       options                        | member_of
------------+------------------------------------------------------+-----------
  alice     | {PROVISIONSRC=jwt_token:https://auth.example.com}    | {developers}
  bob       | {PROVISIONSRC=jwt_token:https://auth.example.com}    | {admins}

​

Security considerations

• Validate JWT issuers carefully: Ensure server.jwt_authentication.issuers.configuration only includes trusted issuers, as any valid JWT from these issuers can create new users.
• Monitor provisioned users: Regularly review automatically created users to ensure only authorized users are being provisioned.
• Combine with JWT authorization: Consider enabling to automatically grant appropriate roles to provisioned users based on their IdP group memberships.
• Password management: Provisioned users cannot change their own passwords, as authentication is managed through the IdP.

​

Authenticate to your cluster

1. Obtain JWTs directly from your IdP: Use your identity provider’s API or SDK to generate JWT tokens (e.g., via Okta APIs, Google OAuth, Azure AD). This is the primary method and requires only the JWT authentication cluster settings configured above.
2. Generate JWTs via DB Console: If you have configured, users can obtain JWT tokens through the DB Console UI.

​

Authenticate using DB Console-generated JWTs

1. Obtain a token. Go to your cluster’s DB Console and click the Generate JWT auth token for cluster SSO button
2. Use the token in place of a password in your database connection string.
   cockroach sql --url "postgresql://{SQL_USERNAME}:{JWT_TOKEN}@{CLUSTER_HOST}:26257?options=--crdb:jwt_auth_enabled=true" --certs-dir={CLUSTER_CERT_DIR}
   
   Welcome to the cockroach SQL interface...
   

​

What’s Next?

• Learn more about in CockroachDB.
• This Cockroach Labs blog post covers and provides further resources for a variety of auth token-issuing use cases, including using Okta and Google Cloud Platform to issue tokens.

​

See also