draft SSO docs #8409

taroface · 2020-09-15T21:08:42Z

Note: Admin UI screenshot is pending new login page & SSO button design.

cockroach-teamcity · 2020-09-15T21:08:49Z

This change is

cockroach-teamcity · 2020-09-15T21:12:04Z

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/cbab572a09a8d558af82078dbf6084859700505d/

Edited pages:

taroface · 2020-09-21T17:11:29Z

@dhartunian Friendly ping for review!

ericharmeling · 2020-10-06T21:33:46Z

@taroface

I don't think this closes #7984

dhartunian

Apologies for the immense delay.

Reviewed 3 of 3 files at r1.
Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @taroface)

v20.2/sso.md, line 20 at r1 (raw file):

- An external OAuth 2.0 identity provider
- A callback URL to redirect the user to the CockroachDB cluster

In theory the URL is "available" if the user can access the Admin UI since it's part of that server. It's a pre-requisite but wondering if it can be omitted.

v20.2/sso.md, line 30 at r1 (raw file):

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. CockroachDB matches the information passed in the callback query to a registered SQL user.

Before this step, there's an exchange of a "code" for an "id_token". Not visible to user but wondering if it's worth pointing out. The callback query does not actually contain any user data, just the code.

v20.2/sso.md, line 43 at r1 (raw file):

| `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/callback'

/oidc/v1/callback

v20.2/sso.md, line 51 at r1 (raw file):

- `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/callback`.

Technically the path can be anything if it's on their proxy, the key is that it routes to the /oidc/v1/callback URL on the CRDB nodes. Probably not worth complicating this section though.

Either way, it's now version prefixed with oidc/v1.

v20.2/sso.md, line 53 at r1 (raw file):

- `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/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 is added by default and should not be included.

The openid scope is now required to be included, there's a validation that will check for its presence. Default value is just "openid" now

v20.2/sso.md, line 71 at r1 (raw file):

	<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 URL for the Admin UI to the list of **Authorized Javascript origins**. On a local cluster, this will be `https://localhost:8080`. For details on how to determine this URL on a production cluster, see [Admin UI access](admin-ui-overview.html#admin-ui-access).

I don't think this is necessary. Only the authorized redirect URIs are needed. I tested locally with removing the "localhost" from the JS origins and things still worked.

v20.2/sso.md, line 105 at r1 (raw file):

	{% include copy-clipboard.html %}
	~~~ sql
	> SET CLUSTER SETTING server.oidc_authentication.redirect_url = 'https://localhost:8080/oidc/callback';

oidc/v1/callback

v20.2/sso.md, line 114 at r1 (raw file):

	{% include copy-clipboard.html %}
	~~~ sql
	> SET CLUSTER SETTING server.oidc_authentication.scopes = 'email';

openid email

taroface

Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @dhartunian)

v20.2/sso.md, line 20 at r1 (raw file):