draft SSO docs

_includes/sidebar-data-v20.2.json

@@ -642,6 +642,12 @@
                 "urls": [
                   "/${VERSION}/gssapi_authentication.html"
                 ]
+              },
+              {
+                "title": "Single Sign-on",
+                "urls": [
+                  "/${VERSION}/sso.html"
+                ]
               }
             ]
           },

v20.2/authentication.md

@@ -40,7 +40,7 @@ To set up a secure cluster without using an existing certificate authority, you'
 
 ### Client authentication
 
-CockroachDB offers three methods for client authentication:
+CockroachDB offers four methods for client authentication:
 
 - **Client certificate and key authentication**, which is available to all users. To ensure the highest level of security, we recommend only using client certificate and key authentication.
 
@@ -68,6 +68,8 @@ CockroachDB offers three methods for client authentication:
 
    Note that the client still needs the CA certificate to validate the nodes' certificates.
 
+- [**Single sign-on authentication**](sso.html), which is available to [Enterprise users](enterprise-licensing.html) to grant access to the Admin UI.
+
 - [**GSSAPI authentication**](gssapi_authentication.html), which is available to [Enterprise users](enterprise-licensing.html).
 
 ### Using `cockroach cert` or `openssl` commands

v20.2/sso.md

@@ -0,0 +1,151 @@
+---
+title: Single Sign-on (Enterprise)
+summary: Implement single sign-on (SSO) for Admin UI access.
+toc: true
+---
+
+Single sign-on (SSO) allows a CockroachDB user to access the Admin UI in a secure cluster via an external identity provider. When SSO is configured and enabled, the [Admin UI login page](admin-ui-overview.html#admin-ui-access) will display an OAuth login button in addition to the password access option.
+
+CockroachDB supports SSO via [OpenID Connect (OIDC)](https://openid.net/connect/), an authentication layer built on top of OAuth 2.0.
+
+{{site.data.alerts.callout_info}}
+SSO authentication is an [enterprise-only](enterprise-licensing.html) feature.
+{{site.data.alerts.end}}
+
+{% include {{ page.version.version }}/misc/experimental-warning.md %}
+
+## Requirements
+
+- An external OAuth 2.0 identity provider
+
+## Login flow
+
+This SSO implementation uses the [authorization code grant type](https://tools.ietf.org/html/rfc6749#section-4.1) to authenticate a user.
+
+1. A user opens the Admin UI and clicks on the OAuth login button. 
+1. The user is redirected to an external identity provider.
+1. The user successfully authenticates with the provider, completing the OAuth flow.
+1. The user is redirected to the CockroachDB cluster via a callback URL.
+1. The authorization code in the callback query is exchanged for an [ID Token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken).
+1. CockroachDB matches the ID Token to a registered SQL user.
+1. CockroachDB creates a web session for the SQL user.
+1. The user is redirected to the [Admin UI Cluster Overview](admin-ui-cluster-overview-page.html).
+
+## Cluster settings
+
+The following OIDC [cluster settings](cluster-settings.html) are used to configure and enable SSO.
+
+| Cluster Setting | Example Value
+|-----------------|------
+| `server.oidc_authentication.enabled` | true
+| `server.oidc_authentication.client_id` | '32789079457-g3hdfw8cbw85obi5cb525hsceaqf69unn.apps.googleusercontent.com'
+| `server.oidc_authentication.client_secret` | '6Q_jmRMgrPNOc_mN91boe-9EP'
+| `server.oidc_authentication.redirect_url` | 'https://localhost:8080/oidc/v1/callback'
+| `server.oidc_authentication.provider_url` | 'https://accounts.google.com'
+| `server.oidc_authentication.scopes` | 'openid profile email'
+| `server.oidc_authentication.claim_json_key` | 'email'
+| `server.oidc_authentication.principal_regex` | '^([^@]+)@[^@]+$'
+| `server.oidc_authentication.autologin` | true
+
+- `enabled` is a Boolean that enables or disables SSO.
+- `client_id` and `client_secret` are generated by the external identity provider.
+- `redirect_url` specifies the callback URL that redirects the user to CockroachDB after a successful authentication. This can be the address of a node in the cluster or the address of a load balancer that routes traffic to the nodes. The path must be appended with `/oidc/v1/callback`.
+- `provider_url` specifies the OAuth issuer identifier. Ensure that the URL does not have a terminating `/`. For more information, see the [OIDC specification](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig). Note that CockroachDB appends the required `/.well-known/openid-configuration` by default. You do not need to include it.
+- `scopes` is a space-delimited list of the [OAuth scopes](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) being requested for an Access Token. The `openid` scope must be included.
+- `claim_json_key` is the key of the field to be extracted from the external identity provider's [ID Token](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) and mapped to a SQL user. This field is likely to be a [standard claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) such as `email` from which a username is extracted via `principal_regex`.
+- `principal_regex` is a regular expression applied to the field specified by `claim_json_key`. It is used to extract an identifier that can be mapped to a SQL user. For example:
+	- `^([^@]+)@[^@]+$` matches any email address (defined as a string containing one `@` sign) and extracts a username from the string to the left of `@`.
+	- `^(.+)$` maps the claim directly to a principal.
+- `autologin` is a Boolean. When `true`, upon loading the Admin UI login page, the browser will automatically initiate the OIDC authentication process by redirecting to `/oidc/v1/login` instead of waiting for the user to log in manually or click the OIDC login button.
+
+## Example (Google OAuth 2.0)
+
+These steps demonstrate how to enable SSO authentication for the Admin UI on a [local secure cluster](secure-a-cluster.html) using [Google's OAuth 2.0](https://developers.google.com/identity/protocols/oauth2) implementation.
+
+1. Open the [Credentials page](https://console.developers.google.com/apis/credentials) for your account at Google APIs.
+
+1. Click **+ CREATE CREDENTIALS** and select **OAuth client ID**. Specify a **web application** from the pulldown menu.
+
+1. Note the *client ID* and *client secret* of the OAuth 2.0 client. You can find these in the modal that appears after you create the client, or in the details view for the client:
+
+	<img src="{{ 'images/v20.2/google-oidc-client.png' | relative_url }}" alt="Google OAuth 2.0 client details" style="border:1px solid #eee;max-width:100%" />
+
+1. Add the callback URL to the list of **Authorized redirect URIs**. On a local cluster, this will be `https://localhost:8080/oidc/v1/callback`. You will later set `server.oidc_authentication.redirect_url` to the same value. 
+
+1. Open a SQL shell to the cluster on node 1:
+
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ cockroach sql --certs-dir=certs --host=localhost:26257
+    ~~~
+
+1. Specify the client ID and client secret you obtained earlier:
+
+	{% include copy-clipboard.html %}
+	~~~ sql
+	> SET CLUSTER SETTING server.oidc_authentication.client_id = '\<client id\>';
+	~~~
+
+	{% include copy-clipboard.html %}
+	~~~ sql
+	> SET CLUSTER SETTING server.oidc_authentication.client_secret = '\<client secret\>';
+	~~~
+
+1. Specify the OAuth issuer identifier:
+
+	{% include copy-clipboard.html %}
+	~~~ sql
+	> SET CLUSTER SETTING server.oidc_authentication.provider_url = 'https://accounts.google.com';
+	~~~
+
+1. Specify the callback URL to redirect the user to the CockroachDB cluster:
+
+	{% include copy-clipboard.html %}
+	~~~ sql
+	> SET CLUSTER SETTING server.oidc_authentication.redirect_url = 'https://localhost:8080/oidc/v1/callback';
+	~~~
+
+1. Specify the following values to obtain an OIDC identifier that will be mapped to a SQL user.
+
+	Request the `openid` and `email` scopes from the Access Token:
+
+	{% include copy-clipboard.html %}
+	~~~ sql
+	> SET CLUSTER SETTING server.oidc_authentication.scopes = 'openid email';
+	~~~
+
+	Specify the `email` field from the ID Token:
+
+	{% include copy-clipboard.html %}
+	~~~ sql
+	> SET CLUSTER SETTING server.oidc_authentication.claim_json_key = 'email';
+	~~~
+
+	Use a regular expression that will extract a username from `email` that you can match to a SQL user. For example, `'^([^@]+)@cockroachlabs\.com$'` extracts the characters that precede `@cockroachlabs.com` in the email address.
+
+	{% include copy-clipboard.html %}
+	~~~ sql
+	> SET CLUSTER SETTING server.oidc_authentication.principal_regex = '^([^@]+)@cockroachlabs.com$';
+	~~~
+
+1. [Create a SQL user](create-user.html#create-a-user) that will log into the Admin UI. The SQL username you specify must match the identifier obtained in the previous step. For example, a user with the email address `[email protected]` will need the SQL username `maxroach`:
+
+    {% include copy-clipboard.html %}
+    ~~~ sql
+    > CREATE USER maxroach;
+    ~~~
+
+1. Finally, enable OIDC authentication:
+
+	{% include copy-clipboard.html %}
+	~~~ sql
+	> SET CLUSTER SETTING server.oidc_authentication.enabled = true;
+	~~~
+
+	When the user [accesses the Admin UI](admin-ui-overview.html#admin-ui-access), they will be able to log in with their Google account.
+
+	<img src="{{ 'images/v20.2/admin_ui_login_sso.png' | relative_url }}" alt="CockroachDB Admin UI Single Sign-on" style="border:1px solid #eee;max-width:50%" />
+
+{{site.data.alerts.callout_info}}
+You can optionally enable the [`server.oidc_authentication.autologin` cluster setting](#cluster-settings) to automatically log in an authenticated user who visits the Admin UI.
+{{site.data.alerts.end}}