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. Your AuthConfig object belongs to the supergraph and, as such, lives in the /supergraph subdirectory of a project.

By default, all projects are created with an AuthConfig object that utilizes Hasura DDN's webhook for authentication. However, in production, you will want to use your own custom webhook or JWT service for authentication. The metadata examples below can help you configure your AuthConfig object to use your own custom webhook or JWT service.

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

LSP-assisted authoring

Authentication options can be complex. As your AuthConfig object is written in an HML file, if you're using a compatible editor (such as VS Code with the Hasura extension), LSP-assisted authoring will help you write AuthConfig more efficiently. LSP will provide you with auto-completion, syntax highlighting, and error checking as you create this object.

Metadata structure

AuthConfig

Definition of the authentication configuration used by the API server.

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

AuthConfigV1

Definition of the authentication configuration 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 or JWT.

AuthModeConfig

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

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.

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: /https:~1~1hasura.io~1jwt~1claims
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	string	false
path	JWTClaimsMappingPathEntry	false

JWTClaimsMappingPathEntry

Key	Value	Required	Description
path	string	true	JSON pointer to find the particular claim in the decoded JWT token.
default	string / 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