Auth0 JWT Integration with Hasura GraphQL engine

In this guide, we will walk through how to set up Auth0 to work with the Hasura GraphQL engine.

Create an Auth0 Application

  • Navigate to the Auth0 dashboard.
  • Click on the Applications menu option on the left and then click the + Create Application button.
  • In the Create Application window, set a name for your application and select Single Page Web Applications (assuming your application is React/Angular/Vue etc).

Configure Auth0 Rules & Callback URLs

In the settings of the application, add appropriate (e.g: http://localhost:3000/callback) URLs as Allowed Callback URLs and Allowed Web Origins. Add domain specific URLs as well for production apps (e.g:

In the dashboard, navigate to Rules. Add the following rules to add our custom JWT claims:

function (user, context, callback) {
  const namespace = "";
  context.idToken[namespace] =
      'x-hasura-default-role': 'user',
      // do some custom logic to decide allowed roles
      'x-hasura-allowed-roles': ['user'],
      'x-hasura-user-id': user.user_id
  callback(null, user, context);

Test auth0 login and generate sample JWTs for testing

You don’t need to integrate your UI with auth0 for testing. You can follow the steps below:

  1. Login to your auth0 app by heading to this URL: https://<auth0-domain><client_id>&protocol=oauth2&response_type=token%20id_token&redirect_uri=<callback_uri>&scope=openid%20profile.
    • Replace <auth0-domain> with your auth0 app domain.
    • Replace <client-id> with your auth0 app client id. Get your client id from the app settings page on the auth0 dashboard.
    • Replace callback_uri with https://localhost:3000/callback or the URL you entered above. Note that this URL doesn’t really need to exist while you are testing.
  2. Once you head to this login page you should see the auth0 login page that you can login with.
Auth0 login page
  1. After successfully logging in, you will be redirected to https://localhost:3000/callback#xxxxxxxx&id_token=yyyyyyy. This page may be a 404 if you don’t have a UI running on localhost:3000.
Auth0 successful callback 404 page
  1. Extract the id_token value from this URL. This is the JWT.
JWT from id_token query param
  1. To test this JWT, and to see if all the Hasura claims are added as per the sections above, let’s test this out with!
JWT debug on

Save this JWT token value so that we can use it later to test authorization using the Hasura console.

Note: In case the above method gives an error, try disabling OIDC Conformant setting ( under Advanced Settings -> OAuth.

Configure Hasura to use Auth0 Keys

Auth0 publishes their JWK under:


But they have a bug where the certificate thumbprint does not match. Hence, currently this URL does not work with Hasura.

Current workaround is to download the X590 certificate from:


And use it in the key field:

      "key": "-----BEGIN CERTIFICATE-----

An easier way to generate the above config is to use the following UI:

The generated config can be used in env HASURA_GRAPHQL_JWT_SECRET or --jwt-secret flag. The config generated from this page can be directly pasted in yaml files and command line arguments as it takes care of escaping new lines.

Add Access Control Rules via Hasura Console

Auth0 is configured and ready to be used in the application. You can now set up access control rules that will automatically get applied whenever a client makes a graphql query with the Auth0 token.

Refer to Access control basics for more information.

To test this out, add an access control rule that uses x-hasura-user-id for the role user. Then make a GraphQL query or a mutation, with the authorization token from the previous step where we generated an Auth0 token.

JWT token used as bearer token on hasura console

You can also use the env variable HASURA_GRAPHQL_UNAUTHORIZED_ROLE or --unauthorized-role flag to set a role for unauthorized users (e.g. anonymous). This will allow you to set permissions for users that are not logged in.

The configured unauthorized role will be used whenever an access token is not present in a request to the GraphQL API.

This can be useful for data that you would like anyone to be able to access and can be configured and restricted just like any other role.