Cluster Single Sign-on (SSO) using a JSON web token (JWT)

On this page

Cluster Single Sign-On (SSO) allows users to access the SQL interface of a CockroachDB cluster (whether provisioned on CockroachDB Cloud or self-hosted) with the full security of Single Sign-On (SSO), and the convenience of being able to choose from a variety of cloud-based or customer-managed identity providers (IdPs).

This page describes the procedure for accessing a CockroachDB Cloud cluster using the JWT access tokens provided by a customer-managed IdP. This document applies for both CockroachDB self-hosted and CockroachDB Dedicated customers.

You might also be looking for: Cluster Single Sign-on (SSO) using CockroachDB Cloud Console. This is an option for authenticating human users to cloud clusters, but does not work for service accounts or in the context of self-hosted clusters.

Before you begin

For more details and examples, refer to SSO to CockroachDB clusters using JWT in the CockroachDB blog.

• IdP:

  You must have the ability to create identities and issue access tokens formatted using JSON Web Token (JWT).

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

• CockroachDB:

  • Self-Hosted: You must have access to a cluster enabled with a valid CockroachDB Enterprise license.

    See Enterprise Trial –– Get Started for help enabling your cluster with you enterprise license.

  • CockroachDB Cloud: You must have access to a CockroachDB Dedicatedcluster.

  • SQL users/credentials:

    • Your SQL user must have the ability to update cluster settings. This permission is provided by either the admin role or the MODIFYCLUSTERSETTING role option. This is required to designate an IdP as an external token issuer.
    • A SQL user that corresponds with your external identity must be pre-provisioned on the cluster. To provision such users, you must have access to the admin role.

Learn more

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.

Provision a service account

For access to a CockroachDB cluster, an identity in an external IdP must correspond to a SQL user on the target cluster, so creating a service for your cluster entails two steps:

• Create a service account/IAM username with your external IdP (for example, GCP).
• Create a SQL user in your cluster.

The correspondence between IdP identity and SQL username is crucial. This determined by your cluster's identity mapping.

Configure your cluster to accept your external identity provider

In order to authenticate a service account to a CockroachDB Cloud cluster using a JWT issuer, you must update several cluster settings in the server.jwt_authentication namespace, as well as the identity_map.configuration

• enabled: JWT token authentication must be allowed on your cluster.
• jwks: A list of public signing keys for allowed IdPs. You'll need to add your IdP's key.
• issuers: A list of accepted token issuers. You'll need to add your IdP.
• audience: A list of audiences (or targets) for authentication, most relevantly, clusters.

server.jwt_authentication.enabled

Enable or disable Cluster SSO

Required value: true

Check to confirm that JWT authentication is enabled on your cluster. It is enabled by default in CockroachDB Cloud clusters.

server.jwt_authentication.jwks

Add your IdP's public signing key to your cluster's list of accepted signing JSON web keys (JWKS), under the jwks setting. This is a JWK formatted single key or key set, containing the public keys for SSO token issuers/IdPs that will be accepted by your cluster.

By default, your cluster's configuration will contain the CockroachDB Cloud's own public key, allowing CockroachDB Cloud to serve as an IdP. When modifying this cluster setting, you must include the CockroachDB Cloud public key in the key set. Failing to do so will lock out console SSO users and prevent maintenance access by the CockroachDB Cloud managed service, leading to unintended consequences.

For example:

SET CLUSTER SETTING server.jwt_authentication.jwks = '{"keys": [{"alg": "RS256","e": "AQAB","kid": "e34e6c51-917d-4e77-8a8c-812d3aa2d730","kty": "RSA","n": "1Y7D2TssaJeeE_g-6ynRrfhfkI_RyvGOv3AVxnkeF3HvYZwJUp4QMngqsbZ-n_J_cdMlKYiuop8S0PW6lZiCx7kHw872tgvrYycRXLo6QgIO_JqJboG5gsXkf92lO8niGgXllyFuilQajzR9_K8bPIqMoLaoKHnEjULNleK6j7pHWW-MnQ_vs4NmU69Ctn3c_3muCZ5ULZKZ3FozlfFCj1D_HC5gk7hRJe22-VYyaxLgO-DqOCE4EedQW-yTGGIy8inMZ9l1EdoNwfDS0RCDnQad9F-DXqcN0VhSJO6nRgWf8EtFuW1sNAknSb6MiI0QGZt9yIVhd2VUMg9HHqXAEQ","use": "sig"},{"alg": "RS256","e": "AQAB","kid": "c0d742ec-edc6-409e-88c7-57747914c09c","kty": "RSA","n": "qG6aXxmuYM-9z2gD83g6o79kNd4T1d_YsKs9VBRDmtvV3Lep5oVwj1wQ2bqbsWtG8JNFej0yzKi8NB16_yfL9NSMw3be2HF6-zr6aBswTAY31_SxBFGzN-sQq0-x49kqZuWOw2_CGz8Z7ZThlB4GAhfqcztFFps_j1z5kOTrzZSX0yIWY-HSv_gCps1bVKJ-d8HJR_AHGtyAOuGZJjJxwJYyWWQmLEHz4YK-GXz4GRO6oMXMDiZTBJCNTUI1g4XRKezZhEA6MHLtbeuIjeiLo1ZG571nfVbPjidHZPPREnR8LxePYYw3WTTddxtCanCo1G9e3ENW4TKHX-wx1YvkQQ","use": "sig"}]}';

server.jwt_authentication.issuers

Add your IdP's formal issuer name (this must match the issuer field in the JWT itself) to your cluster's list of accepted token issuers.

This field takes a single JWT or JSON array of JWTS. This list must include a given IdP, or the cluster will reject JWTs issued by it.

The default value is CockroachDB Cloud. When modifying this cluster setting, you must include CockroachDB Cloud in the new value. Failing to do so can prevent maintenance access by the CockroachDB Cloud managed service, leading to unintended consequences. It can also break the cluster SSO for human users to this cluster.

Changes to this configuration should be made with utmost care, and access to updating this configuration (granted by the admin role or the MODIFYCLUSTERSETTING role option) should be carefully restricted.