As you may know from various other blog posts found on blog.hasura.io, Hasura supports various types of authentication and in the following blog post I want to lay out what are your authentication options when using Hasura in production.

We will talk about the following things:

Securing GraphQL endpoint
Auth Webhooks
- How to get started with custom webhook
- Setting up Hasura with auth webhook
Auth using JWT
Hasura Permission system

Securing your GraphQL endpoint

When creating a new instance of Hasura engine, you've probably seen Secure your endpoint on top of the console:

This link leads to the docs section describing how to secure your GraphQL endpoint by passing an environment variable HASURA_GRAPHQL_ADMIN_SECRET. Whether you are using Docker, Heroku or anything else, that will be the first step you will do.

So now if you try to access the console, you will get a simple "login" page that will ask you to specify your secret

The name ADMIN_SECRET suggest that if you pass it in your request headers, you will be giving admin permissions to API consumer. That's why it's important that you use it only from server to server interactions such as using it from serverless functions etc.

So that is not an actual authentication. That's just securing your endpoint. Now, what about Authentication and what is the right authentication method for you?

You may want to use Firebase, Auth0, Firebase Functions, Cognito, Your custom auth server, some unknown auth provider e.t.c

So before looking at different Auth implementations and having lots of blog posts links and sample apps down below, let's divide our authentication type to two major types

Auth webhooks

So what is a Webhook? In a nutshell, whenever you set a specific environment variable for Hasura engine, that includes custom URL, all request headers (unless your webhook is configured to use GET) will be passed to this custom URL. In your Auth webhook, you can do whatever you want and it must return either 200 or 401 status codes. Along with 200 status code, you send a bunch of variables prefixed by X-HASURA-* that can be used in Hasura permission system, that we will discuss later on

How we get started with our custom webhook?

Let's look at the case study of passport-js webhook boilerplate example we have available.

We will start by cloning passport-js and following the guide to deploy it on Heroku

Now after it's deployed you can run it with npm start and sending /login or /signup requests and getting back the username and token

curl -H "Content-Type: application/json" \                           
     -d'{"username": "test123456", "password": "test123"}' \
     https://passport-auth-hasura.herokuapp.com/login

and the result will be:

{
  "id": 3,
  "username": "test123456",
  "token": "dd26537df94305f35dca9605b9fade7b"
}%

Now it's time to setup Hasura engine on the database we've just created

docker run -d -p 8081:8080 -e HASURA_GRAPHQL_DATABASE_URL=DATABASE_URL \
-e HASURA_GRAPHQL_ENABLE_CONSOLE=true \
-e HASURA_GRAPHQL_ADMIN_SECRET=secret \
hasura/graphql-engine:v1.0.0-alpha41

When accessing the console you will see the following:

as you can see users table was created when we ran knex migrations when set our passport-js boilerplate, but we want to use it also from our GraphQL API, so make sure you click Track button and now you will be able to query your users:

So how do we log in? And how do we define permissions?

the passport-js example uses LocalStrategy, so a person must authenticate with username and password, as a result, it will return

{
  "id": 3,
  "username": "test123456",
  "token": "dd26537df94305f35dca9605b9fade7b"
}

So how do we structure our client app?

The idea is that we need to try to login similar that how we logged in from the console by hitting the following endpoint https://.herokuapp.com/login

and as a result, get token.
Now we need to pass that token in every request to Hasura as Authorization header like so:

"Authorization": "Bearer dd26537df94305f35dca9605b9fade7b"

Setting up Hasura with auth webhook

Now what is left to do is to configure the webhook env variable and set permissions. To add auth webhook stop our docker container and add HASURA_GRAPHQL_AUTH_HOOK env variable.

docker run -d -p 8081:8080 \
-e HASURA_GRAPHQL_DATABASE_URL=DATABASE_URL \
-e HASURA_GRAPHQL_ENABLE_CONSOLE=true \
-e HASURA_GRAPHQL_ADMIN_SECRET=secret \
-e HASURA_GRAPHQL_AUTH_HOOK=https://<heroku-app-name>.herokuapp.com/webhook \
hasura/graphql-engine:v1.0.0-alpha41

Now what will happen is when you pass Authorization header, it will be passed to custom auth webhook and processed by it.
Let's take a look at passport-js code:

exports.getWebhook = async (req, res, next) => {
  passport.authenticate('bearer', (err, user, info) => {
    if (err) { return handleResponse(res, 401, {'error': err}); }
    if (user) {
      handleResponse(res, 200, {
        'X-Hasura-Role': 'user',
        'X-Hasura-User-Id': `${user.id}`
      });
    } else {
      handleResponse(res, 200, {'X-Hasura-Role': 'anonymous'});
    }
  })(req, res, next);
}

As you can see we pass either anonymous role or user.id.
Now we can set our permissions accordingly in the Permissions tab.

Let's take a look at a different use case - firebase functions auth hook

The idea is the same - return X-Hasura-User-Id and X-Hasura-Role to be used in Hasura permissions system. But specifically in this auth webhook we also validate with firebase that the id_token we've been passed is a correct one

There are other auth-webhooks boilerplate that you can check here.

Let's take a look at auth flow for webhooks

Pass headers to Hasura
Headers are forwarded to your custom auth webhook
response returns 200 or 401.
In case of 200 it has to return X-Hasura-* variables to be used in Hasura Permission system

You can read a bit more about it in docs

Auth using JWT

JSON Web Tokens is an open standard and Hasura supports it out of the box through a configuration option. You need to pass HASURA_GRAPHQL_JWT_SECRET with the following value:

{
  "type": "<standard-JWT-algorithms>",
  "key": "<optional-key-as-string>",
  "jwk_url": "<optional-url-to-refresh-jwks>",
  "claims_namespace": "<optional-key-name-in-claims>",
  "claims_format": "json|stringified_json"
}

standard-JWT-algorithms - Hasura supports HS256, HS384, HS512, RS256, RS384, RS512 algorithms
key - Public key for your JWT encryption.
jwk_url - provider JWK url. This is used for some providers to expire a key.
claims_namespace - by default Hasura engine looks under "https://hasura.io/jwt/claims" namespace to find x-hasura-* prefixed variables encoded in the token. If you pass claims_namespace as part of HASURA_GRAPHQL_JWT_SECRET, then Hasura engine will look for x-hasura- variables under this namespace

For example this:

  "https://hasura.io/jwt/claims": {
    "x-hasura-allowed-roles": ["editor","user", "mod"],
    "x-hasura-default-role": "user",
    "x-hasura-user-id": "1234567890",
    "x-hasura-org-id": "123",
    "x-hasura-custom": "custom-value"
  }

If provided "claims_namespace": "customClaim" to Hasura engine, Hasura engine will expect that after decoding it needs to search in customClaim for all x-hasura-* variables

There are other options described in docs how to use JWT, but in a nutshell, it will look like this:

Any Auth server that returns JWT token have to pass JWT with x-hasura-* claims under either configured or https://hasura.io/jwt/claims namespace.

JWT will be decoded by the engine following configuration provided in HASURA_GRAPHQL_JWT_SECRET and all x-hasura-* claims will be forwarded to Permission system.

Note: x-hasura-default-role and x-hasura-allowed-roles are mandatory

Now let's take a look at the case study of the simplest JWT token use case

Let's go to https://jwt.io/ and choose algorithm as RS256

Let's change Payload data to be:

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true,
  "iat": 1516239022,
    "myAmazingAuth": {
    "x-hasura-allowed-roles": ["editor","user", "mod"],
    "x-hasura-default-role": "user",
    "x-hasura-user-id": "1234567890",
    "x-hasura-org-id": "123",
    "x-hasura-custom": "custom-value"
  }
}

And so ourHASURA_GRAPHQL_JWT_SECRET will be

{
  "type":"RS256",
  "claims_namespace": "myAmazingAuth",
  "key": "copypasted public key"
}

Now we will head to the console and pass our token as Authorization Bearer token.
Our x-hasura-* claims will be extracted from the token and passed to Permissions dialog where you will be able to set roles, and get really granular access even to specific columns. We will talk about Permission system in a bit

Let's take a look at common authentication techniques we can use.

Custom JWT server

You can run your own custom JWT server which will handle token generation along with Hasura custom claims. There is a really great blog post describing that

Server is passport server with jwt and you can check the code here

Auth0

Auth0 uses JWK urls as well as firebase, so there is a cool tool you can use to auto-generate your config for either auth0 or firebase. You can check it here

Also for Auth0 you need to configure custom claims in Rules field under Auth0 dashboard

There is a blog post written about Auth0. You can check it here

Firebase

Firebase also uses JWK so HASURA_GRAPHQL_JWT_SECRET will look like that

{"type":"RS512", "jwk_url": "https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com"}

We also need to add custom claims to Firebase, so we will be able to include X-Hasura-* variables in our encoded token.

There is a great blog post describing the usage of Firebase for authentication.

Cognito

With AWS Cognito there are several steps you need to do to make it work, so even though I won't dive deeper in how to do that in this particular blog post, More detailed blog post will follow. The main idea of using Cognito is similar to Auth0 or Firebase. You need to define custom claims somewhere. For Cognito, you cannot define that in interface, but you can create custom Lambda when generating your token like so:

Our Lambda in this example will be super simple:

exports.handler = (event, context, callback) => {
    event.response = {
        "claimsOverrideDetails": {
            "claimsToAddOrOverride": {
                "https://hasura.io/jwt/claims": JSON.stringify({
                    "x-hasura-allowed-roles": ["anonymous","user", "admin"],
                    "x-hasura-default-role": "anonymous",
                    "x-hasura-user-id": event.request.userAttributes.sub,
                    "x-hasura-role": event.request.userAttributes.sub === "18cc0fe3-ad0b-44f8-a622-fd470c7eeb78" ? "admin": "user",
                    "x-hasura-custom": "custom-value"
                })
            }
        }
    }
    callback(null, event)
}

That's how we add custom claims. Now you can notice that we pass our claims as stringified JSON. This is done because Cognito does not support nested custom claims. Also, you can see that I am checking for specific user if its and admin or not and if it is I return an admin role.

On Hasura side when setting HASURA_GRAPHQL_JWT_SECRET I need to pass jwk_url as well as claims_format as stringified JSON

{
"type":"RS256",
"jwk_url": "https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/jwks.json",
"claims_format": "stringified_json"
}

And that's basically it. Your Cognito token will be decoded and passed to Hasura permission system

Hasura Permission System

Hasura has a really granular method of evaluating permissions. In sections above, I laid out different methods of authenticating with Hasura and while these methods were different from the other all of them result in the same outcome. X-Hasura-* variables are passed to Hasura permission system.

The first layer of permissions is roles. Roles are defined based on x-hasura-default-role and x-hasura-allowed-roles variables passed to the permission system.

Second layer is custom checks based on x-hasura-user-id or any other custom variable passed to permission system

As you can see in this example, we are checking post content to be "custom_value" and only if it is, we enable user to select fields. What it will mean is that user will be able to see posts only when posts content is equal to "custom value"

Alternatively, we can set something like that:

And that will mean that user will be able to see only his/her posts.

Summary

As you can see from the summary above, Hasura supports lots of different Authentication techniques and is aligned with best practices in industry. In addition to that Hasura permissions system gives you a really granular level of access control used, which is a must in production apps.

Blog

Hasura Authentication Explained

Vladimir Novick