Skip to main content
Version: v2.x

Console SSO with Azure Active Directory

Available on: Self-hosted Enterprise


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 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 and Docker Compose 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 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 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
Implicit and hybrid flows

The ID tokens (used for implicit and hybrid flows) option must be checked.

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.

Create admin role
Azure AD assign role

Finally, go to App registrations -> <Your app> -> Overview -> Endpoints to get the required configuration endpoints.

Azure AD endpoints

OAuth 2.0 configuration

Hasura EE can handle the OAuth authorization flow directly. You only need to configure via --sso-providers argument (HASURA_GRAPHQL_SSO_PROVIDERS).

"client_id": "<Application (client) ID>",
"name": "Azure OAuth2 Login",
// OAuth 2.0 authorization endpoint (v2)
"authorization_url": "<client-id>/oauth2/v2.0/authorize",
// OAuth 2.0 token endpoint (v2)
"request_token_url": "<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
"jwk_url": "<Directory (tenant) ID>/discovery/v2.0/keys",
"issuer": "<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 service to docker-compose with SAML 2.0 connector configuration to proxy the Azure SAML login connector.

# docker-compose.yaml
image: dexidp/dex
- ./dex/config.docker.yaml:/etc/dex/config.docker.yaml
- ./dex/saml-ca.pem:/etc/dex/saml-ca.pem:ro
- '5556:5556'
# ./dex/config.docker.yaml
issuer: http://localhost:5556/dex

type: memory

allowedOrigins: ['*']

- id: hasura-app
- 'http://localhost:8080/console/oauth2/callback'
name: 'Hasura App'
public: true

- type: saml
id: saml
name: SAML
# SAML-P sign-on endpoint
ssoURL:<Directory (tenant) ID>/saml2
ca: /path/to/saml-ca.pem
redirectURI: http://localhost:5556/dex/callback
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.

Azure AD SAML Certificate
<paste here>

Finally, add the provider config to the HASURA_GRAPHQL_SSO_PROVIDERS variables.

"client_id": "example-app",
"name": "Dex SAML Login",
"authorization_url": "",
"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]" }