Understanding JWT tokens with Hasura

A JWT token is used to authorize GraphQL requests to Hasura.

But what is a JWT token, and how does it work?

What is a JWT token?

A JWT token is a string that contains information about a user, such as a user id and user role. When the user makes a GraphQL request to Hasura, the user also sends the JWT token and the GraphQL request. Hasura can then understand who the user is by looking at the JWT token when receiving the GraphQL request.

Encoded JWT token

Decoded JWT token (payload)

The JWT token above includes information about the user id, user default role, and allowed roles.

The key-value pairs starting with x-hasura- are called session variables. The following session variables exist in the JWT token above:

• x-hasura-user-id
• x-hasura-allowed-roles
• x-hasura-default-role

The session variables are used to resolve Hasura permission to make sure the user only has access to the data it should have access to.

What claims must be in the JWT token?

At a minimum, the two session variables x-hasura-default-role and x-hasura-allowed-roles must be part of the JWT token.

What claims can exist in the JWT token?

Any claim prefixed with x-hasura- can exist as a claim in the JWT token.

A popular session variable is x-hasura-user-id.

How is the JWT token sent to Hasura?

The JWT token is sent in the Authorization header together with a GraphQL request. The token is prepended with Bearer in the header.

Here's an example:

Authorization: Bearer ${jwtToken}

How is a JWT token created?

A JWT token is created by an authentication server. A common use case is that a client sends an email and password to the authentication server. The authentication server makes sure that the email and password are correct and send back a JWT token to the client.

Hasura Backend Plus is an authentication server that works out of the box with Hasura to generate JWT tokens.

How can Hasura trust the information in the JWT token?

The JWT token is cryptographically signed with a secret key. That means that anyone with the same secret key can mathematically verify that the JWT token has not been modified since it was created.

The authentication server and Hasura share the same secret key. The authentication server uses the secret key when generating the JWT token, and Hasura verifies the JWT token when receiving it together with GraphQL requests.

If Hasura is unable to verify the JWT token, the GraphQL request fails.

How to store JWT token on the client?

The client's browser should save the JWT token in memory.

Tokens are stored automatically in memory using nhost-js-sdk.

Revoke JWT token

No one can not manually revoke JWT tokens. Instead, each JWT token has an exp field which indicates when the JWT token expires. Usually, JWT tokens expire after a few minutes after being created. The client can use a refresh token to request a new JWT token.

Refresh token

A refresh token's only purpose is to get a new JWT token and a new refresh token. Each refresh token is associated with a user in the database. And before the authentication return, new tokens refresh tokens are stored in the database, and the authentication server always checks the database before

Tokens (both JWT tokens and refresh tokens) are refreshed automatically with nhost-js-sdk.

Conclusion

Now you have a basic understanding of what a JWT token is and how it's used together with Hasura.