Skip to main content

Authentication using JWTs

important

Using SuperTokens with Hasura requires you to host your own API layer that uses our Backend SDK. If you do not want to host your own server you can use a serverless environment (AWS Lambda for example) to achieve this.

1) Complete the quick setup#

Follow the quick setup guide to setup SuperTokens

2) Enable the JWT feature#

import SuperTokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";

SuperTokens.init({
    supertokens: {
        connectionURI: "..."
    },
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init({
            jwt: {
                enable: true,
            },
        })
    ]
});
info

To learn more about using JWTs with SuperTokens refer to this page.

3) Add custom claims to the JWT#

caution

Hasura requires claims to be set in a specific way, read the official documentation to know more.

import SuperTokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";

SuperTokens.init({
    supertokens: {
        connectionURI: "...",
    },
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: [
        Session.init({
            jwt: {
                enable: true,
            },
            override: {
                functions: function (originalImplementation) {
                    return {
                        ...originalImplementation,
                        createNewSession: async function (input) {
                            input.accessTokenPayload = {
                                ...input.accessTokenPayload,
                                "https://hasura.io/jwt/claims": {
                                    "x-hasura-user-id": input.userId,
                                    "x-hasura-default-role": "user",
                                    "x-hasura-allowed-roles": ["user"],
                                }
                            };

                            return originalImplementation.createNewSession(input);
                        },
                    };
                }
            },
        })
    ]
});

4) Configure Hasura environment variables#

info

Read the official documentation to know about setting the JWT secret environment variable on Hasura

To use JWT based authentication, Hasura requires setting environment variables when configuring your app. With SuperTokens this can be done in 2 ways:

Using the JWKS endpoint#

When configuring Hasura, you can set the jwk_url property.

{
    "jwk_url": "{apiDomain}/{apiBasePath}/jwt/jwks.json"
}

You can get the jwks URL for your backend by using the method explained here

Using a key string#

Hasura let's you provide a PEM string in the configuration. Refer to this page to know how to get a public key as a string, you can then use that key string in the Hasura config:

{
    "type": "RS256",
    "key": "CERTIFICATE_STRING",
}

5) Making requests to Hasura#

a) Getting the JWT on the frontend#

Refer to this page to know how to read the JWT

b) Making HTTP requests#

import axios from "axios";

async function makeRequest() {
  let url = "...";
  let jwt = "..."; // Refer to step 5.a
  let response = await axios.get(url, {
    headers: {
      "Authorization": `Bearer ${jwt}`,
    },
  });
}

During Local development#

If you are using Hasura cloud and testing your backend APIs in your local environment, JWT verification will fail because Hasura will not be able to query the JWKS endpoint (because the cloud can not query your local environment i.e localhost, 127.0.0.1).

To solve this problem you will need to expose your locally hosted backend APIs to the internet. For example you can use ngrok:

  • Configure Hasura to use the {ngrokURL}/{apiBasePath}/jwt/jwks.json as the JWKS endpoint (explained in step 4)
  • Configure SuperTokens to use {ngrokURL}/{apiBasePath} as the custom issuer URL (refer to this page to know more)
Which frontend SDK do you use?
supertokens-web-js / mobile
supertokens-auth-react