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:

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:

Other access levels

• Admin secret access
• Unauthenticated / Public access

Next Steps

• Quickstart 3rd party integration tutorials
• See here for info on using JWT mode.
• See here for info on using webhook mode.

JWT and webhook Tutorials

• Webhooks Basics - Learn Tutorial
• JWT Basics - Learn Tutorial