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.
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"
What we've provided above is a sample configuration. However, there are many options available, which you can learn about here.
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 value you wish (e.g., org , user-id , customer ). |
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.
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.