Enabling JWT Authentication

Introduction

You can enable your Hasura DDN instance to use JWTs in just a few steps.

Step 1. Update your AuthConfig

Hasura utilizes an AuthConfig object that allows you to define the configuration for your authentication service. The auth-config.hml file can be found in your globals directory.

You can use Hasura's VS Code extension to scaffold out your AuthConfig object by typing AuthConfig and selecting this object from the list of available options. As you navigate through the skeleton, you can type CTRL+SPACEBAR at any point to reveal options for the different key-value pairs.

Below, we're demonstrating using the BearerAuthorization format with JWKs. However, Hasura DDN supports other methods for both identifying and verifying JWTs.

globals/metadata/auth-config.hml

kind: AuthConfig
version: v2
definition:
  mode:
    jwt:
      claimsConfig:
        namespace:
          claimsFormat: Json
          location: /claims.jwt.hasura.io
      tokenLocation:
        type: BearerAuthorization
      key:
        jwkFromUrl: "https://your-jwk-url.your-service.com"

Other configuration options are available

What we've provided above is a sample configuration. However, there are many options available, which you can learn about here.

Setting audience check

Certain JWT providers (like Firebase) share JWKs between multiple tenants. They use the aud claim of JWT to specify the intended tenant for the JWT. Setting the audience field in the Hasura JWT configuration will make sure that the aud claim from the JWT is also checked during verification. Not doing this check will allow JWTs issued for other tenants to be valid as well.

In these cases, you MUST set the audience field to appropriate value. Failing to do so is a major security vulnerability. Learn how to set this here.

Step 2. Create the claims

Your auth service should include an object with a key of https://hasura.io/jwt/claims in the JWT's claims. Within this, each claim should be prefixed with x-hasura-* and include the relevant information.

Key	Required	Value
x-hasura-default-role	Yes	The role that will be used when the optional x-hasura-role header is not passed
x-hasura-allowed-roles	Yes	A list of allowed roles for the user making the request.
x-hasura-[custom]	No	Where [custom] is any string you wish (e.g., org, user-id, customer). The value can be any JSON value.

As an example, we're including the required claims by stating the default role is user and the list of available roles is limited to user and admin. Additionally, we're passing a custom key of x-hasura-user-id which can be used with permissions when executing queries.

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": false,
  "iat": 1516239022,
  "exp": 1516325422,
  "claims.jwt.hasura.io": {
    "x-hasura-default-role": "user",
    "x-hasura-allowed-roles": ["user", "admin"],
    "x-hasura-user-id": 1234
  }
}

Your auth server will encode this object using a secret and create a token which can then be passed as a header to Hasura or any other service. You can see an example of the above token encoded here.

Step 3. Rebuild your supergraph

Once you've updated your auth-config.hml and updated your claims, you can rebuild your supergraph and test it locally.

For example, from the root of your project, run:

ddn supergraph build local \
  --supergraph supergraph.yaml \
  --env-file .env

Step 4. Make an authenticated request

In the example above, we're using the BearerAuthorization method. As such, as we can make a request to our Hasura DDN instance by including a header with the key-value of Authorization: Bearer <our-encoded-token>. For testing, you can pass this value in the Hasura DDN console's header section.

Next steps

If you're looking for step-by-step help to get started with common authentication providers, check this section of recipes.

Authentication is only part of the puzzle! Hasura DDN empowers you to easily write your access-control rules, commonly known as authorization, using declarative metadata. You can use the values passed in your JWTs to then limit which models and types a user has access to with each request.