Skip to main content
Version: v2.x

Authentication

Introduction

Authentication verifies the identity of a user.

Hasura GraphQL Engine utilizes session variables, with specific user, role, organization and any other information you may need to determine the data access rights of the user.

With these session variables you are able to construct permission rules which are added per table, role, and database operation in order to provide extremely granular access control.

Actual authentication is handled outside Hasura. Ie: the responsibility for generating session variables is delegated to your (new or existing) authentication service in order to provide you with the greatest flexibility and range of options for your authentication needs.

Hasura authentication can be configured via JSON web tokens (JWT) or a webhook service and can be integrated with any other provider you choose (e.g. Auth0, Firebase Auth, AWS Cognito, a custom solution, etc) in order to verify the user and set session variables that then control access to data.

Full admin level and unauthenticated access can also be configured.

In JWT mode, session variables are provided to Hasura Engine in the payload of the JWT token. In webhook mode, the session variables are provided in JSON format back to Hasura Engine in the body of a successful request to the webhook endpoint.

Your authentication service is required to pass, at least, a user's role information in the form of the session variable X-Hasura-Role. More often than not, you'll also need to pass other information for your particular access control use cases, like X-Hasura-User-Id or X-Hasura-Org-Id, in order to build your permission rules.

The specific content of the GraphQL request is then processed with the session variables against the permissions defined by you in the Hasura Engine to build a single optimized query to the database with restricted access for that user role.

The two Hasura authentication options

Hasura supports two options for authentication configuration:

1. JWT

Your auth service issues JWTs (JSON Web Tokens) to your client app, which, when sent as part of the request are then verified and decoded by the Hasura Engine to get session variables to use when evaluating permissions.

Here's how a GraphQL query is processed in JWT mode:

Authentication using JWT

2. Webhook

Your auth service exposes a webhook endpoint that is used to authenticate all incoming requests and to respond with session variables to use when evaluating permissions on Hasura Engine.

Here's how a GraphQL request is processed in webhook mode:

Authentication using webhooks

Other access levels

Next Steps

JWT and webhook Tutorials