Docs: Hasura EE console SSO

PR-URL: https://github.com/hasura/graphql-engine-mono/pull/8355
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Rob Dominguez <24390149+robertjdominguez@users.noreply.github.com>
GitOrigin-RevId: 065de606fffcd2d3d1a18b9cb739bd1168ad9a77

docs/docs/deployment/graphql-engine-flags/reference.mdx

@@ -892,6 +892,19 @@ The port on which `graphql-engine` should be served.
 | **Default**         | **CE, Enterprise Edition**: `8080` <br />**Cloud**: managed by Hasura Cloud |
 | **Supported in**    | CE, Enterprise Edition                                                      |
 
+### Single Sign-on Providers
+
+List of third-party identity providers to enable Single Sign-on authentication for the console.
+
+|                     |                                                                                                                                                                                                                                                                                                                      |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Flag**            | `--sso-providers <JSON_CONFIG>`                                                                                                                                                                                                                                                                                      |
+| **Env var**         | `HASURA_GRAPHQL_SSO_PROVIDERS`                                                                                                                                                                                                                                                                                       |
+| **Accepted values** | JSON array of objects (containing identity provider configs and the JWK used for verification)                                                                                                                                                                                                                       |
+| **Default**         | `null`                                                                                                                                                                                                                                                                                                               |
+| **Example**         | `[{\"client_id\": \"<client-id-from-idp>\", \"name\": \"<display-name>\", \"scope\": \"openid\", \"authorization_url\": \"<login-url>\", \"request_token_url\": \"<request-token-url>\", \"admin_roles\": [\"admin\"], \"jwt_secret\": {\"type\": \"RS256\", \"jwk_url\": \"https://...\", \"issuer\": \"myapp\"}}]` |
+| **Supported in**    | EE                                                                                                                                                                                                                                                                                                                   |
+
 ### Streaming Queries Multiplexed Batch Size
 
 Multiplexed [streaming queries](/subscriptions/postgres/streaming/index.mdx) are split into batches of the specified

docs/docs/enterprise/sso/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Enable SSO",
+  "position": 5
+}

docs/docs/enterprise/sso/azure-ad.mdx

@@ -0,0 +1,191 @@
+---
+sidebar_label: Azure Active Directory
+description: Azure Active Directory SSO tutorial for Hasura Enterprise Edition
+title: 'EE: Azure AD SSO'
+keywords:
+  - hasura
+  - console
+  - docs
+  - enterprise
+  - single sign on
+  - SSO
+  - SAML
+  - Azure
+sidebar_position: 3
+---
+
+import Thumbnail from '@site/src/components/Thumbnail';
+
+# Console SSO with Azure Active Directory
+
+<div className="badge badge--primary heading-badge">Available on: Self-hosted Enterprise</div>
+
+## Prerequisites
+
+This tutorial will help you set up Single Sign-on (SSO) for the Hasura Console with Azure Active Directory. We assume
+that the following prerequisites have been met:
+
+- To deploy Hasura EE, you will need a license key. [Please contact Hasura Sales](mailto:sales@hasura.io) if you do not
+  already have one.
+- An Azure account and your Azure user has the required permissions to register an Azure AD application.
+- You have [Docker](https://docs.docker.com/install/) and [Docker Compose](https://docs.docker.com/compose/install/)
+  working on your machine.
+- Hasura EE service is exposed at `http://localhost:8080`
+- Dex service is exposed at `http://localhost:5556`
+
+## Get started
+
+If you are new to Hasura GraphQL Engine, let's go through the [Quickstart](/getting-started/docker-simple.mdx) to help
+you get up and running quickly with the Hasura GraphQL Engine and a Postgres database running as Docker containers using
+Docker Compose. You also need to [configure the EE license key](/enterprise/upgrade-ce-to-ee.mdx) to enable Enterprise
+features.
+
+## Configuring Azure AD application
+
+Register an application for both OAuth and SAML SSO login, then add a single-page application with the following
+callback URLs:
+
+- `http://localhost:8080/console/oauth2/callback`
+- `http://localhost:5556/dex/callback`
+
+:::info Implicit and hybrid flows
+
+The ID tokens (used for implicit and hybrid flows) option must be checked.
+
+:::
+
+<Thumbnail src="/img/enterprise/sso-azure-register-app.jpg" alt="Register Azure AD application" />
+
+The authorized user must have the `admin` role in claims. To do this you need to create the role in `App roles` tab.
+Head back to `Enterprise applications` -> `<Your app>` -> `Users and groups` and assign the app role to the user.
+
+<Thumbnail src="/img/enterprise/sso-azure-create-admin-role.jpg" alt="Create admin role" />
+
+<Thumbnail src="/img/enterprise/sso-azure-assign-role.jpg" alt="Azure AD assign role" />
+
+Finally, go to `App registrations` -> `<Your app>` -> `Overview` -> `Endpoints` to get the required configuration
+endpoints.
+
+<Thumbnail src="/img/enterprise/sso-azure-endpoints.jpg" alt="Azure AD endpoints" />
+
+## OAuth 2.0 configuration
+
+Hasura EE can handle the OAuth authorization flow directly. You only need to configure via
+[--sso-providers](/deployment/graphql-engine-flags/reference.mdx#single-sign-on-providers) argument
+(`HASURA_GRAPHQL_SSO_PROVIDERS`).
+
+```json
+[
+  {
+    "client_id": "<Application (client) ID>",
+    "name": "Azure OAuth2 Login",
+    // OAuth 2.0 authorization endpoint (v2)
+    "authorization_url": "https://login.microsoftonline.com/<client-id>/oauth2/v2.0/authorize",
+    // OAuth 2.0 token endpoint (v2)
+    "request_token_url": "https://login.microsoftonline.com/<client-id>/oauth2/v2.0/token",
+    "scope": "openid offline_access",
+    "admin_roles": ["admin"],
+    "jwt_secret": {
+      "type": "RS256",
+      // you can get jwt secret information in the OpenID Connect metadata document endpoint
+      // https://login.microsoftonline.com/<client-id>/v2.0/.well-known/openid-configuration
+      "jwk_url": "https://login.microsoftonline.com/<Directory (tenant) ID>/discovery/v2.0/keys",
+      "issuer": "https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0",
+      "claims_map": {
+        "x-hasura-allowed-roles": { "path": "$.roles" },
+        "x-hasura-default-role": { "path": "$.roles[0]" }
+      }
+    }
+  }
+]
+```
+
+After configuring the variable, reload the Hasura GraphQL Engine service and browse the Console page to verify.
+
+## SAML configuration
+
+You need to add the [Dex](https://github.com/dexidp/dex) service to docker-compose with
+[SAML 2.0](https://dexidp.io/docs/connectors/saml/) connector configuration to proxy the Azure SAML login connector.
+
+```yaml
+# docker-compose.yaml
+services:
+  dex:
+    image: dexidp/dex
+    volumes:
+      - ./dex/config.docker.yaml:/etc/dex/config.docker.yaml
+      - ./dex/saml-ca.pem:/etc/dex/saml-ca.pem:ro
+    ports:
+      - '5556:5556'
+```
+
+```yaml
+# ./dex/config.docker.yaml
+issuer: http://localhost:5556/dex
+
+storage:
+  type: memory
+
+web:
+  http: 0.0.0.0:5556
+  allowedOrigins: ['*']
+
+staticClients:
+  - id: hasura-app
+    redirectURIs:
+      - 'http://localhost:8080/console/oauth2/callback'
+    name: 'Hasura App'
+    public: true
+
+connectors:
+  - type: saml
+    id: saml
+    name: SAML
+    config:
+      # SAML-P sign-on endpoint
+      ssoURL: https://login.microsoftonline.com/<Directory (tenant) ID>/saml2
+      ca: /path/to/saml-ca.pem
+      redirectURI: http://localhost:5556/dex/callback
+      usernameAttr: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
+      emailAttr: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
+      groupsAttr: http://schemas.microsoft.com/ws/2008/06/identity/claims/role
+      entityIssuer: spn:<client-id>
+```
+
+The `saml-ca.pem` file can be downloaded on the Azure portal UI if you create the SAML enterprise application directly.
+However, if you create the application through App registrations, you can copy the certificate in the
+`Federation metadata document` into the `saml-ca.pem` file.
+
+<Thumbnail src="/img/enterprise/sso-azure-saml-ca.jpg" alt="Azure AD SAML Certificate" />
+
+```
+-----BEGIN PRIVATE KEY-----
+<paste here>
+-----END PRIVATE KEY-----
+```
+
+Finally, add the provider config to the `HASURA_GRAPHQL_SSO_PROVIDERS` variables.
+
+```json
+[
+  {
+    "client_id": "example-app",
+    "name": "Dex SAML Login",
+    "authorization_url": "http://127.0.0.1:5556/dex/auth",
+    "request_token_url": "http://localhost:5556/dex/token",
+    "scope": "openid offline_access groups",
+    "admin_roles": ["admin"],
+    "jwt_secret": {
+      "type": "RS256",
+      // use the internal docker service alias of dex
+      // because hge fetches the secret inside the docker network
+      "jwk_url": "http://dex:5556/dex/keys",
+      "issuer": "http://localhost:5556/dex",
+      "claims_map": {
+        "x-hasura-allowed-roles": { "path": "$.groups" },
+        "x-hasura-default-role": { "path": "$.groups[0]" }
+      }
+    }
+  }
+]
+```

docs/docs/enterprise/sso/config.mdx

@@ -0,0 +1,178 @@
+---
+sidebar_label: Configuration
+description: 'Single sign-on (SSO) configuration for Hasura Enterprise Edition'
+title: 'EE: SSO configuration'
+keywords:
+  - hasura
+  - console
+  - docs
+  - enterprise
+  - single sign on
+  - SSO
+  - SAML
+sidebar_position: 2
+---
+
+import Thumbnail from '@site/src/components/Thumbnail';
+
+# Single Sign-on Configuration
+
+<div className="badge badge--primary heading-badge">Available on: Self-hosted Enterprise</div>
+
+## Configuration
+
+### Configuring the identity provider
+
+Create a new service provider on your identity provider with the following configuration:
+
+1. Configure the allowed origin, CORS to be where the Hasura Console is hosted.
+2. Set the callback URL to `http(s)://<hasura-domain>/console/oauth2/callback`.
+3. Ensure the ID token option is enabled.
+4. Add `"x-hasura-allowed-roles": ["admin"]` and `"x-hasura-default-role": "admin"` into the JWT custom claims. The JWT
+   payload should follow the [Hasura JWT spec](/auth/authentication/jwt.mdx#example-decoded-payload).
+
+Once created, note the client ID, login URL, request token URL, and JWT secret.
+
+### Configuring Hasura Enterprise
+
+Set the [`--sso-providers`](/deployment/graphql-engine-flags/reference.mdx#single-sign-on-providers) argument
+(`HASURA_GRAPHQL_SSO_PROVIDERS`) which takes a list of SSO provider objects.
+
+```json
+[
+  {
+    "client_id": "<client-id-from-idp>",
+    "name": "<display-name>",
+    "scope": "openid",
+    "authorization_url": "<login-url>",
+    "request_token_url": "<request-token-url>",
+    "admin_roles": ["admin"],
+    "jwt_secret": {
+      "type": "RS256",
+      "jwk_url": "https://...",
+      "issuer": "myapp"
+    }
+  }
+]
+```
+
+- `client_id`: Client ID of the identity application.
+- `name`: Display name of the SSO button in the login page of the Hasura Console.
+- `scope`: The OAuth scope. It must contain `openid` so the identity provider can return the JWT `id_token` from the
+  request token endpoint.
+- `authorization_url`: The authorization URL that the browser redirects to from the Console.
+- `request_token_url`: URL the Console uses to get the ID token using the authorization code.
+- `admin_roles`: By default, the role should be `admin` in the token issued by IdP so that Console access is provided.
+  But, if you have a configuration where the `admin` role is used for something else, set this key to indicate which
+  roles should be treated as admin. This is an array of strings.
+- `jwt_secret`: JWT secret the server uses to verify the JWT signature. It follows the
+  [JWT secret configuration](https://hasura.io/docs/latest/auth/authentication/jwt/#configure-hasura-jwt-mode).
+
+## Other protocols
+
+You can use any OpenID Connect compliant middleware service such as [Dex](https://github.com/dexidp/dex) that acts as a
+portal to other identity providers. Hasura talks to the middleware to authorize and verify signatures without caring
+about how the middleware handles external providers. Dex supports [SAML 2.0](https://dexidp.io/docs/connectors/saml/),
+[LDAP](https://dexidp.io/docs/connectors/ldap/) protocols, as well as identity providers like GitHub, Google, and Active
+Directory.
+
+### SAML configuration
+
+#### Configuring the identity provider
+
+Create a new service provider on your SAML identity provider with the following configuration:
+
+1. Configure the callback URL to be `http(s)://<dex-url>/callback`.
+2. Note the sign-on endpoint, entity ID, and issuer.
+3. Download the CA certificate.
+4. Note the XML attribute paths of username, email, and roles so Dex can map those attributes to JWT custom claims. You
+   can find them in the Federation metadata document.
+
+#### Configuring Dex
+
+Create a config file with a static client and a SAML connector.
+
+```yaml
+# The default Dex base URL is http://localhost:5556/dex
+# However the /dex path is removed in the helm chart
+issuer: http(s)://<dex-url>
+
+storage:
+  type: memory
+
+# Configuration for the HTTP endpoints.
+web:
+  http: 0.0.0.0:5556
+  allowedOrigins: ['*']
+
+staticClients:
+  - id: hasura-app
+    redirectURIs:
+      - 'http(s)://<hasura-url>/console/oauth2/callback'
+    name: 'Hasura App'
+    public: true
+
+connectors:
+  - type: saml
+    id: saml
+    name: SAML
+    config:
+      ssoURL: <SAML sign-on endpoint>
+      # CA to use when validating the signature of the SAML response.
+      ca: /path/to/saml-ca.pem
+
+      # CA's can also be provided inline as a base64'd blob.
+      #
+      # caData: ( RAW base64'd PEM encoded CA )
+
+      # To skip signature validation, uncomment the following field. This should
+      # only be used during testing and may be removed in the future.
+      #
+      # insecureSkipSignatureValidation: true
+
+      redirectURI: http(s)://<dex-url>/callback
+      # Name of attributes in the returned assertions to map to ID token claims.
+      usernameAttr: name
+      emailAttr: email
+      # groups are required to be mapped with x-hasura-allowed-roles
+      groupsAttr: groups
+
+      # Optional: Manually specify dex's Issuer value.
+      #
+      # When provided dex will include this as the Issuer value during AuthnRequest.
+      # It will also override the redirectURI as the required audience when evaluating
+      # AudienceRestriction elements in the response.
+      entityIssuer: http(s)://<dex-url>/callback
+
+      # Optional: Issuer value expected in the SAML response.
+      # ssoIssuer: https://login.microsoftonline.com/4bc01d1d-5a16-4d79-b651-5a5b592aeb57/v2.0
+```
+
+### Configuring Hasura Enterprise
+
+Set the environment variable `HASURA_GRAPHQL_SSO_PROVIDERS` to talk to Dex.
+
+```json
+[
+  {
+    "client_id": "hasura-app",
+    "name": "SAML Login",
+    "scope": "openid offline_access groups",
+    "authorization_url": "http(s)://<dex-url>/auth",
+    "request_token_url": "http(s)://<dex-url>/token",
+    "admin_roles": ["admin"],
+    "jwt_secret": {
+      "type": "RS256",
+      "jwk_url": "http(s)://<dex-url>/keys",
+      "issuer": "http(s)://<dex-url>",
+      "claims_map": {
+        "x-hasura-allowed-roles": { "path": "$.groups" },
+        "x-hasura-default-role": { "path": "$.groups[0]" }
+      }
+    }
+  }
+]
+```
+
+The `groups` scope is required to enable the `groups` field in the JWT claims. You also need to set the `claims_map` to
+map the `groups` field to `x-hasura-allowed-roles` and `x-hasura-default-role`.

docs/docs/enterprise/sso/index.mdx

@@ -0,0 +1,43 @@
+---
+sidebar_label: 'SSO'
+sidebar_position: 5
+description: 'Enable single sign-on (SSO) on Console for Hasura Enterprise Edition'
+title: 'EE: Enable Console SSO'
+keywords:
+  - hasura
+  - console
+  - docs
+  - enterprise
+  - single sign on
+  - SSO
+  - SAML
+slug: index
+---
+
+import Thumbnail from '@site/src/components/Thumbnail';
+
+# Enable Single Sign-on
+
+<div className="badge badge--primary heading-badge">Available on: Self-hosted Enterprise</div>
+
+## Introduction
+
+With Hasura Enterprise Edition, you can enable SSO (Single Sign-On) on the Hasura Console with your identity management
+system through the [OAuth 2.0](https://oauth.net) / [OpenID Connect](https://openid.net/connect) protocol.
+
+<Thumbnail src="/img/enterprise/sso-animated-demo.gif" alt="Console SSO demo" />
+
+:::info Note
+
+We only support the [Proof Key for Code Exchange](https://oauth.net/2/pkce/) extension to prevent CSRF and authorization
+code injection attacks.
+
+:::
+
+## Guides
+
+To get started, either use our general configuration guide or follow the specific instructions for your identity
+provider:
+
+- [Single Sign-on configuration](/enterprise/sso/config.mdx)
+- [Enable Azure AD Single Sign-on](/enterprise/sso/azure-ad.mdx)