mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-09-11 10:46:25 +03:00
docs: add dex info for google sso
[DOCS-946]: https://hasurahq.atlassian.net/browse/DOCS-946?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ PR-URL: https://github.com/hasura/graphql-engine-mono/pull/9154 Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> GitOrigin-RevId: b3f75e8dbb1c2f29ed68c45da9cb45f21b057ab1
This commit is contained in:
parent
4dec50ba5b
commit
b63046f4a8
316
docs/docs/enterprise/sso/google-workspace.mdx
Normal file
316
docs/docs/enterprise/sso/google-workspace.mdx
Normal file
@ -0,0 +1,316 @@
|
||||
---
|
||||
sidebar_label: Google Workspace
|
||||
description: Google Workspace SSO tutorial for Hasura Enterprise Edition
|
||||
title: 'EE: Google Workspace SSO'
|
||||
keywords:
|
||||
- hasura
|
||||
- console
|
||||
- docs
|
||||
- enterprise
|
||||
- single sign on
|
||||
- SSO
|
||||
- SAML
|
||||
- google workspace
|
||||
sidebar_position: 4
|
||||
toc_max_heading_level: 2
|
||||
---
|
||||
|
||||
import Thumbnail from '@site/src/components/Thumbnail';
|
||||
|
||||
# Console SSO with Google Workspace
|
||||
|
||||
<div className="badge badge--primary heading-badge">Available on: Self-hosted Enterprise</div>
|
||||
|
||||
## Overview
|
||||
|
||||
SSO can be configured with Google Workspace OAuth2 by setting up [Dex](https://dexidp.io/docs/) as an OAuth2 proxy.
|
||||
Access can be configured for all users of a domain or just for members of certain groups.
|
||||
|
||||
This guide assumes you have a Hasura GraphQL Engine instance running with a valid license key. If you don't have one,
|
||||
you can get a license key via a [30-day free trial](/enterprise/try-hasura-enterprise-edition.mdx) or by contacting the
|
||||
[Hasura team](mailto:sales@hasura.io).
|
||||
|
||||
:::info Supported from
|
||||
|
||||
SSO for Google Workspace is supported from versions `v2.25.0` and above.
|
||||
|
||||
:::
|
||||
|
||||
## Step 1: Configure Hasura
|
||||
|
||||
The table below describes the configuration options for Google Workspace SSO. Hasura GraphQL Engine will expect these
|
||||
values to be set as the value of the
|
||||
[`HASURA_GRAPHQL_SSO_PROVIDERS` environment variable](/deployment/graphql-engine-flags/reference.mdx/#single-sign-on-providers):
|
||||
|
||||
| Key | Example | Description |
|
||||
| ----------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `client_id` | `dex-login` | Any name identifying the Dex client |
|
||||
| `admin_roles` | `hasura-admin@company.com` | X-hasura-roles that should be given admin access to console |
|
||||
| `name` | Google Workspace Login | A display name for this login method on the console |
|
||||
| `authorization_url` | `http://dex-endpoint-from-browser:port/dex/auth` | Endpoint of Dex for auth request, should be reachable from browser |
|
||||
| `request_token_url` | `http://dex-endpoint-from-browser:port/dex/token` | Endpoint of Dex for token request, should be reachable from browser |
|
||||
| `scope` | `openid offline_access groups` | Oauth2 scopes to be used against Dex |
|
||||
| `jwt_secret.type` | `RS256` | Key type Dex is configured with |
|
||||
| `jwt_secret.jwk_url` | `http://dex-endpoint-from-hasura:port/dex/keys` | JWK URL that is published by dex |
|
||||
| `jwt_secret.issuer` | `http://dex-endpoint-from-browser:port/dex` | Issuer that is configured with Dex, same as issuer in Dex configuration, this is typically the endpoint at which Dex can be reached at |
|
||||
| `jwt_secret.claims_map` | `{"x-hasura-allowed-roles": {"path": "$.groups"},"x-hasura-default-role": {"path": "$.groups[0]"}}` | Mapping groups parsed by Dex to roles on Hasura |
|
||||
|
||||
Using the information above as an example, you can configure the `HASURA_GRAPHQL_SSO_PROVIDERS` environment variable as
|
||||
follows:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"client_id": "dex-login",
|
||||
"admin_roles": ["hasura-admin@company.com"],
|
||||
"name": "Google Workspace Login",
|
||||
"authorization_url": "http://127.0.0.1:5556/dex/auth",
|
||||
"request_token_url": "http://127.0.0.1:5556/dex/token",
|
||||
"scope": "openid offline_access groups",
|
||||
"jwt_secret": {
|
||||
"type": "RS256",
|
||||
"jwk_url": "http://127.0.0.1:5556/dex/keys",
|
||||
"issuer": "http://127.0.0.1:5556:5556/dex",
|
||||
"claims_map": {
|
||||
"x-hasura-allowed-roles": {
|
||||
"path": "$.groups"
|
||||
},
|
||||
"x-hasura-default-role": {
|
||||
"path": "$.groups[0]"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
:::info Setting environment variables
|
||||
|
||||
For guidance on setting environment variables or flags for Hasura GraphQL Engine, see
|
||||
[server configuration](/deployment/graphql-engine-flags/index.mdx).
|
||||
|
||||
:::
|
||||
|
||||
## Step 2: Configure Dex
|
||||
|
||||
Your Dex configuration will need the following fields set to enable Google Workspace SSO. You can find a sample
|
||||
configuration file below. This file should be saved in the `/dex` directory of your container.
|
||||
|
||||
### Issuer
|
||||
|
||||
The base path of Dex and the external name of the OpenID Connect service. This is the canonical URL that all clients
|
||||
**must** use to refer to Dex. If a path is provided, Dex's HTTP service will listen at a non-root URL. This is the
|
||||
public URL at which Dex is available.
|
||||
|
||||
Example:
|
||||
|
||||
```plaintext
|
||||
http://dex-domain:5556/dex
|
||||
```
|
||||
|
||||
### Static clients
|
||||
|
||||
This contains the `id` and `redirectURIs`. The `id` will reference the `client_id` in the Hasura configuration. The
|
||||
`redirectURIs` will be the oauth callback URL of Hasura Console, which is at
|
||||
`http(s)://<hasura-endpoint>/console/oauth2/callback`.
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
staticClients:
|
||||
- id: dex-login
|
||||
redirectURIs:
|
||||
- 'http://localhost:8080/console/oauth2/callback'
|
||||
name: 'Dex Login'
|
||||
public: true
|
||||
```
|
||||
|
||||
### Connectors
|
||||
|
||||
The connectors field is an array of objects that define the various connectors being used in the Dex configuration. Each
|
||||
object in the array contains a type field that specifies the type of connector being used. Here, we'll use
|
||||
`type: google` along with a series of fields that are specific to the Google connector.
|
||||
|
||||
```yaml
|
||||
connectors:
|
||||
- type: google
|
||||
id: google
|
||||
name: Google
|
||||
config:
|
||||
issuer: https://accounts.google.com
|
||||
# Connector config values starting with a "$" will read from the environment.
|
||||
# The clientID and clientSecret are obtained through the Google Console.
|
||||
clientID: <YOUR_CLIENT_ID>.apps.googleusercontent.com
|
||||
clientSecret: <YOUR_CLIENT_SECRET>
|
||||
redirectURI: http://127.0.0.1:5556/dex/callback
|
||||
hostedDomains:
|
||||
- company.com
|
||||
groups:
|
||||
- hasura-admin@company.com
|
||||
serviceAccountFilePath: /dex/google-sa.json
|
||||
adminEmail: groups-reader@company.com
|
||||
```
|
||||
|
||||
### Sample configuration file for Dex
|
||||
|
||||
<details>
|
||||
<summary>Click here to see a sample configuration file for Dex.</summary>
|
||||
|
||||
```yaml
|
||||
# The base path of dex and the external name of the OpenID Connect service.
|
||||
# This is the canonical URL that all clients MUST use to refer to dex. If a
|
||||
# path is provided, dex's HTTP service will listen at a non-root URL.
|
||||
# Public URL that dex is available at
|
||||
issuer: http://127.0.0.1:5556/dex
|
||||
|
||||
# The storage configuration determines where dex stores its state. Supported
|
||||
# options include SQL flavors and Kubernetes third party resources.
|
||||
#
|
||||
# See the documentation (https://dexidp.io/docs/storage/) for further information.
|
||||
storage:
|
||||
type: sqlite3
|
||||
config:
|
||||
file: /var/dex/dex.db
|
||||
|
||||
# Configuration for the HTTP endpoints.
|
||||
web:
|
||||
http: 0.0.0.0:5556
|
||||
allowedOrigins: ['*']
|
||||
# Uncomment for HTTPS options.
|
||||
# https: 127.0.0.1:5554
|
||||
# tlsCert: /etc/dex/tls.crt
|
||||
# tlsKey: /etc/dex/tls.key
|
||||
|
||||
# Uncomment this block to enable configuration for the expiration time durations.
|
||||
# Is possible to specify units using only s, m and h suffixes.
|
||||
# expiry:
|
||||
# deviceRequests: "5m"
|
||||
# signingKeys: "6h"
|
||||
# idTokens: "24h"
|
||||
# refreshTokens:
|
||||
# reuseInterval: "3s"
|
||||
# validIfNotUsedFor: "2160h" # 90 days
|
||||
# absoluteLifetime: "3960h" # 165 days
|
||||
|
||||
# Options for controlling the logger.
|
||||
# logger:
|
||||
# level: "debug"
|
||||
# format: "text" # can also be "json"
|
||||
|
||||
oauth2:
|
||||
responseTypes: ['code'] # also allowed are "token" and "id_token"
|
||||
skipApprovalScreen: true
|
||||
#
|
||||
staticClients:
|
||||
- id: dex-login
|
||||
redirectURIs:
|
||||
- 'http://localhost:8080/console/oauth2/callback'
|
||||
name: 'Dex Login'
|
||||
public: true
|
||||
|
||||
connectors:
|
||||
- type: google
|
||||
id: google
|
||||
name: Google
|
||||
config:
|
||||
issuer: https://accounts.google.com
|
||||
# Connector config values starting with a "$" will read from the environment.
|
||||
clientID: <YOUR_CLIENT_ID>
|
||||
clientSecret: <YOUR_CLIENT_SECRET>
|
||||
redirectURI: http://127.0.0.1:5556/dex/callback
|
||||
hostedDomains:
|
||||
- company.com
|
||||
groups:
|
||||
- hasura-admin@company.com
|
||||
serviceAccountFilePath: /dex/google-sa.json
|
||||
adminEmail: shahidh@hasura.io
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## Step 3: Create a Service Account and Key
|
||||
|
||||
To allow Dex to fetch group information from Google, you will need to configure a service account for Dex to use. This
|
||||
account needs Domain-Wide Delegation and permission to access the
|
||||
`https://www.googleapis.com/auth/admin.directory.group.readonly` API scope.
|
||||
|
||||
To get group fetching set up:
|
||||
|
||||
- Follow the [instructions ](https://developers.google.com/admin-sdk/directory/v1/guides/delegation) to set up a service
|
||||
account with Domain-Wide Delegation:
|
||||
- During service account creation, a JSON key file will be created that contains authentication information for the
|
||||
service account. This needs storing in a location accessible by Dex and you will set the `serviceAccountFilePath` to
|
||||
point at it.
|
||||
- When delegating the API scopes to the service account, delegate the
|
||||
`https://www.googleapis.com/auth/admin.directory.group.readonly` scope and only this scope. If you delegate more
|
||||
scopes to the service account, it will not be able to access the API.
|
||||
- Enable the [Admin SDK ](https://console.developers.google.com/apis/library/admin.googleapis.com/).
|
||||
- Add the `serviceAccountFilePath` and `adminEmail` configuration options to your Dex config.
|
||||
- `serviceAccountFilePath` should point to the location of the service account JSON key file.
|
||||
- `adminEmail` should be the email of a Google Workspace user with a minimum of the `Groups Reader (BETA)` Role
|
||||
assigned. The service account you created earlier will impersonate this user when making calls to the admin API. A
|
||||
valid user should be able to retrieve a list of groups when
|
||||
[testing the API ](https://developers.google.com/admin-sdk/directory/v1/reference/groups/list#try-it).
|
||||
|
||||
## Step 4: Update your deployment
|
||||
|
||||
Finally, you'll need to configure your deployment with these changes. Here is a Docker Compose example, with the
|
||||
configuration:
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:15
|
||||
restart: always
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/data
|
||||
ports:
|
||||
- '5432'
|
||||
environment:
|
||||
POSTGRES_PASSWORD: postgrespassword
|
||||
|
||||
hasura-pro:
|
||||
image: hasura/graphql-engine:v2.25.0
|
||||
ports:
|
||||
- '8080:8080'
|
||||
depends_on:
|
||||
- postgres
|
||||
restart: always
|
||||
environment:
|
||||
HASURA_GRAPHQL_EE_LICENSE_KEY: <YOUR_EE_LICENSE_KEY>
|
||||
HASURA_GRAPHQL_ADMIN_SECRET: <YOUR_ADMIN_SECRET>
|
||||
HASURA_GRAPHQL_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres?sslmode=disable
|
||||
HASURA_GRAPHQL_ENABLE_CONSOLE: 'true'
|
||||
HASURA_GRAPHQL_DEV_MODE: 'true'
|
||||
HASURA_GRAPHQL_ENABLED_LOG_TYPES: startup,http-log,webhook-log,websocket-log,query-log
|
||||
HASURA_GRAPHQL_ENABLED_APIS: metadata,graphql,config,metrics
|
||||
HASURA_GRAPHQL_METRICS_SECRET: <YOUR_METRICS_SECRET>
|
||||
HASURA_GRAPHQL_CONSOLE_ASSETS_DIR: /srv/console-assets
|
||||
HASURA_GRAPHQL_SSO_PROVIDERS:
|
||||
'[{"client_id": "dex-login","admin_roles": ["hasura-admin@company.com"], "name": "Dex
|
||||
Login","authorization_url": "http://127.0.0.1:5556/dex/auth","request_token_url":
|
||||
"http://127.0.0.1:5556/dex/token","scope": "openid offline_access groups","jwt_secret": {"type":
|
||||
"RS256","jwk_url": "http://dex:5556/dex/keys","issuer": "http://127.0.0.1:5556/dex","claims_map":
|
||||
{"x-hasura-allowed-roles": { "path": "$.groups" },"x-hasura-default-role": { "path": "$.groups[0]" }}}}]'
|
||||
|
||||
dex:
|
||||
image: dexidp/dex
|
||||
restart: always
|
||||
volumes:
|
||||
- ./dex/config.docker.yaml:/etc/dex/config.docker.yaml
|
||||
- ./dex/google-sa.json:/dex/google-sa.json
|
||||
ports:
|
||||
- '5556:5556'
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
```
|
||||
|
||||
## Step 5: Log in
|
||||
|
||||
At this point, you should see a `Dex Login` option on the Hasura Console. Now, you're ready to log in with your Google
|
||||
Workspace account 🎉
|
||||
|
||||
<Thumbnail src="/img/enterprise/Dex-sso.png" alt="Dex on Hasura Console" width="600px" />
|
BIN
docs/static/img/enterprise/Dex-sso.png
vendored
Normal file
BIN
docs/static/img/enterprise/Dex-sso.png
vendored
Normal file
Binary file not shown.
After Width: | Height: | Size: 18 KiB |
Loading…
Reference in New Issue
Block a user