hasura/graphql-engine
1
0
Fork 0
mirror of https://github.com/hasura/graphql-engine.git synced 2024-09-11 10:46:25 +03:00
Code Issues Projects Releases Wiki Activity

docs: add dex info for google sso

Browse Source 
[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:
Rob Dominguez 2023-05-26 10:51:56 -05:00 committed by hasura-bot
parent 4dec50ba5b
commit b63046f4a8
2 changed files with 316 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

316
docs/docs/enterprise/sso/google-workspace.mdx Normal file
View 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
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB