AuthConfig

Introduction

The AuthConfig object is used to define the authentication configuration used by the API. With Hasura, you can utilize either webhooks or JWTs for authentication. The AuthConfig object belongs to the supergraph and can be defined once across your supergraph in any subgraph of your choice using one of the following modes:

Mode	Description
noAuth	This is enabled by default and allows you to connect to your API without any authentication. It is not recommended for production.
JWT	This allows you to use JWTs for authentication.
Webhook	This allows you to use a custom webhook for authentication.

You can learn more about Hasura's approach to using existing authentication systems in the authentication section.

How AuthConfig works

Lifecycle

By default, all projects are created with an AuthConfig object in the globals subgraph in a noAuth mode that doesn't use any auth service and doesn't allow setting session variables with API requests. Meaning that your API is, by default, fully public and exposed if deployed live.

However, you would want update the AuthConfig to use a custom webhook or JWT service for authentication to restrict access to your API and make use of Hasura's powerful authorization features. The metadata examples below can help you configure your AuthConfig object to use your own custom webhook or JWT service.

An AuthConfig object is required to be defined in the supergraph metadata. If not defined, any attempted builds will not be successful.

To make an update AuthConfig available in your supergraph, after updating your metadata, you'll need to create a new build using the CLI.

Examples

Each example below offers numerous customizations. However, we've provided a basic example for each mode to get you started. Check the reference table for more information on each field.

noAuth

An AuthConfig for noAuth mode:

kind: AuthConfig
version: v2
definition:
  mode:
    noAuth:
      role: admin
      sessionVariables: {}

Field	Description	Reference
role	The role to be assumed while running the engine in noAuth mode.	Role
sessionVariables	Static session variables that will be used while running the engine without authentication. This is helpful when you want to test requests using particular session variables, such as x-hasura-user-id with a non-admin role.	SessionVariables

JWT

An AuthConfig for JWT mode:

kind: AuthConfig
version: v2
definition:
  mode:
    jwt:
      claimsConfig:
        namespace:
          claimsFormat: Json
          location: /claims.jwt.hasura.io
      tokenLocation:
        type: BearerAuthorization
      key:
        fixed:
          algorithm: HS256
          key:
            valueFromEnv: AUTH_SECRET

Field	Description	Reference
claimsConfig	Configuration to describe how and where the engine should look for the claims within the decoded token. You can vary the format and location of the claims.	JWTClaimsConfig
tokenLocation	Specifies the source of the JWT authentication token and how it should be parsed.	JWTTokenLocation
key	Configuration for the JWT key, specifying how the incoming JWT will be verified and decoded. In this example, we've used a fixed key that's stored as an environment variable in our root-level .env file that is also mapped to the subgraph.yaml in our /globals directory.	JWTKey

Webhook

An AuthConfig for Webhook mode:

kind: AuthConfig
version: v2
definition:
  mode:
    webhook:
      url: http://auth_hook:3050/validate-request
      method: Post

Field	Description	Reference
url	The URL of the authentication webhook that will be called to validate authentication.	AuthHookConfig
method	The HTTP method (Get or Post) that will be used to make the request to the auth hook.	AuthHookMethod

---

Metadata structure

AuthConfig

Definition of the authentication configuration used by the API server.

One of the following values:

Value	Description
AuthConfig1	Definition of the authentication configuration v1, used by the API server.
AuthConfig2	Definition of the authentication configuration v2, used by the API server.

AuthConfig2

Definition of the authentication configuration v2, used by the API server.

Key	Value	Required	Description
kind	AuthConfig	true
version	v2	true
definition	AuthConfigV2	true	Definition of the authentication configuration v2, used by the API server.

AuthConfigV2

Definition of the authentication configuration v2, used by the API server.

Key	Value	Required	Description
mode	AuthModeConfig	true

AuthConfig1

Definition of the authentication configuration v1, used by the API server.

Key	Value	Required	Description
kind	AuthConfig	true
version	v1	true
definition	AuthConfigV1	true	Definition of the authentication configuration v1, used by the API server.

AuthConfigV1

Definition of the authentication configuration v1, used by the API server.

Key	Value	Required	Description
allowRoleEmulationBy	Role / null	false
mode	AuthModeConfig	true	The configuration for the authentication mode to use - webhook, JWT or NoAuth.

AuthModeConfig

The configuration for the authentication mode to use - webhook, JWT or NoAuth.

Must have exactly one of the following fields:

Key	Value	Required	Description
webhook	AuthHookConfig	false	The configuration of the authentication webhook.
jwt	JWTConfig	false	JWT config according to which the incoming JWT will be verified and decoded to extract the session variable claims.
noAuth	NoAuthConfig	false	Configuration used when running engine without authentication

NoAuthConfig

Configuration used when running engine without authentication

Key	Value	Required	Description
role	Role	true	role to assume whilst running the engine
sessionVariables	SessionVariables	true	static session variables to use whilst running the engine

Example:

role: admin
sessionVariables:
  x-hasura-user-id: '100'

SessionVariables

static session variables to use whilst running the engine

Key	Value	Required	Description
<customKey>		false	JSON value of a session variable

JWTConfig

JWT config according to which the incoming JWT will be verified and decoded to extract the session variable claims.

Key	Value	Required	Description
audience	[string] / null	false	Optional validation to check that the aud field is a member of the audience received, otherwise will throw error.
issuer	string / null	false	Optional validation to check that the iss field is a member of the iss received, otherwise will throw error.
allowedSkew	integer / null	false	Allowed leeway (in seconds) to the exp validation to account for clock skew.
claimsConfig	JWTClaimsConfig	true	Claims config. Either specified via claims_mappings or claims_namespace_path
tokenLocation	JWTTokenLocation	true	Source of the JWT authentication token.
key	JWTKey	true	Mode according to which the JWT auth is configured.

Example:

audience: null
issuer: null
allowedSkew: null
claimsConfig:
  namespace:
    claimsFormat: Json
    location: /claims.jwt.hasura.io
tokenLocation:
  type: BearerAuthorization
key:
  fixed:
    algorithm: HS256
    key:
      value: token

JWTKey

JWT key configuration according to which the incoming JWT will be decoded.

Must have exactly one of the following fields:

Key	Value	Required	Description
fixed	JWTKeyConfig	false	JWT Secret config according to which the incoming JWT will be decoded.
jwkFromUrl	string	false

JWTKeyConfig

JWT Secret config according to which the incoming JWT will be decoded.

Key	Value	Required	Description
algorithm	JWTAlgorithm	true	The algorithm used to decode the JWT.
key	EnvironmentValue	true	The key to use for decoding the JWT.

EnvironmentValue

Either a literal string or a reference to a Hasura secret

Must have exactly one of the following fields:

Key	Value	Required	Description
value	string	false
valueFromEnv	string	false

JWTAlgorithm

The algorithm used to decode the JWT.

One of the following values:

Value	Description
HS256	HMAC using SHA-256
HS384	HMAC using SHA-384
HS512	HMAC using SHA-512
ES256	ECDSA using SHA-256
ES384	ECDSA using SHA-384
RS256	RSASSA-PKCS1-v1_5 using SHA-256
RS384	RSASSA-PKCS1-v1_5 using SHA-384
RS512	RSASSA-PKCS1-v1_5 using SHA-512
PS256	RSASSA-PSS using SHA-256
PS384	RSASSA-PSS using SHA-384
PS512	RSASSA-PSS using SHA-512
EdDSA	Edwards-curve Digital Signature Algorithm (EdDSA)

JWTTokenLocation

Source of the Authorization token

One of the following values:

Value	Description
JWTBearerAuthorizationLocation	Get the bearer token from the Authorization header.
JWTCookieLocation	Get the token from the Cookie header under the specified cookie name.
JWTHeaderLocation	Custom header from where the header should be parsed from.

JWTHeaderLocation

Custom header from where the header should be parsed from.

Key	Value	Required	Description
type	Header	true
name	string	true

JWTCookieLocation

Get the token from the Cookie header under the specified cookie name.

Key	Value	Required	Description
type	Cookie	true
name	string	true

JWTBearerAuthorizationLocation

Get the bearer token from the Authorization header.

Key	Value	Required	Description
type	BearerAuthorization	true

JWTClaimsConfig

Config to describe how/where the engine should look for the claims within the decoded token.

Must have exactly one of the following fields:

Key	Value	Required	Description
locations	JWTClaimsMap	false	Can be used when Hasura claims are not all present in the single object, but individual claims are provided a JSON pointer within the decoded JWT and optionally a default value.
namespace	JWTClaimsNamespace	false	Used when all of the Hasura claims are present in a single object within the decoded JWT.

JWTClaimsNamespace

Used when all of the Hasura claims are present in a single object within the decoded JWT.

Key	Value	Required	Description
claimsFormat	JWTClaimsFormat	true	Format in which the Hasura claims will be present.
location	string	true	Pointer to lookup the Hasura claims within the decoded claims.

JWTClaimsFormat

Format in which the Hasura claims will be present.

One of the following values:

Value	Description
Json	Claims will be in the JSON format.
StringifiedJson	Claims will be in the Stringified JSON format.

JWTClaimsMap

Can be used when Hasura claims are not all present in the single object, but individual claims are provided a JSON pointer within the decoded JWT and optionally a default value.

Key	Value	Required	Description
x-hasura-default-role	JWTClaimsMappingEntry	true	JSON pointer to lookup the default role within the decoded JWT.
x-hasura-allowed-roles	JWTClaimsMappingEntry	true	JSON pointer to lookup the allowed roles within the decoded JWT.

JWTClaimsMappingEntry

JSON pointer to lookup the default role within the decoded JWT.

Must have exactly one of the following fields:

Key	Value	Required	Description
literal	Role	false
path	JWTClaimsMappingPathEntry	false	Entry to lookup the Hasura claims at the specified JSON Pointer

JWTClaimsMappingPathEntry

Entry to lookup the Hasura claims at the specified JSON Pointer

Key	Value	Required	Description
path	string	true	JSON pointer to find the particular claim in the decoded JWT token.
default	Role / null	false	Default value to be used when no value is found when looking up the value using the path.

AuthHookConfig

The configuration of the authentication webhook.

Key	Value	Required	Description
url	string	true	The URL of the authentication webhook.
method	AuthHookMethod	true	The HTTP method to be used to make the request to the auth hook.

Example:

url: http://auth_hook:3050/validate-request
method: Post

AuthHookMethod

The HTTP method to be used to make the request to the auth hook.

Value: Get / Post

Role

Value: string