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.

server.jwt_authentication.audience

The ID of your cluster as specified by the IdP, or a JSON array of such names. One of the audience values here must match the audience claim of an access token, or it will be rejected.

Configure your cluster's identity mapping

server.identity_map.configuration

Format: <external issuer> <external user ID> <SQL username>

Specifies mapping of subject names to SQL usernames, for each allowed IdP. For example, a configuration of:

https://accounts.google.com /^([9-0]*)$ gcp_\1

would yield a mapping where the SQL username for each GCP-provisioned service account would be gcp_{user ID}, e.g. gcp_1234567 for a service account with ID 1234567.

Authenticate to your cluster with your JWT token

To provision SQL cluster access for application users or service accounts, you must provision JWT tokens. There are many ways to do this, which are beyond the scope of this tutorial.

For example, your Google Cloud Platform organization can serve as token issuer, as described here in the GCP docs on issuing tokens to service accounts. This blog post discusses using GCP to authenticate issue tokens.

Once you have a valid JWT auth token (with issuer and audience matching the values configured in your cluster settings) from your IdP, you may use it to connect to your cluster's SQL interface.

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?

• Read about SSO to CockroachDB clusters using JWT in the CockroachDB blog.
• Learn more about Authentication in CockroachDB.

Was this helpful?