Skip to content

Commit 11cb1b4

Browse files
paritosh-08paritosh-08
committed
update to AuthConfig v3
1 parent 61c3a7c commit 11cb1b4

File tree

10 files changed

+153
-70
lines changed

10 files changed

+153
-70
lines changed

‎docs/auth/jwt/jwt-configuration.mdx

+73-53
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Example JSON Web Token (JWT) payload configuration definition:
2323

2424
```yaml title="globals/metadata/auth-config.hml"
2525
kind: AuthConfig
26-
version: v2
26+
version: v3
2727
definition:
2828
mode:
2929
jwt:
@@ -135,12 +135,13 @@ your auth provider.
135135

136136
### claimsConfig
137137

138-
You can specify where the engine should look for the claims within the decoded token either with one of `namespace` and `locations` options.
138+
You can specify where the engine should look for the claims within the decoded token either with one of `namespace` and
139+
`locations` options.
139140

140141
#### namespace {#jwt-claims-config-namespace}
141142

142-
The `namespace` option is used when all of the Hasura claims are present in a single object within the decoded JWT.
143-
Our example uses `claims.jwt.hasura.io` in the [Example Decoded Payload](#example-decoded-payload).
143+
The `namespace` option is used when all of the Hasura claims are present in a single object within the decoded JWT. Our
144+
example uses `claims.jwt.hasura.io` in the [Example Decoded Payload](#example-decoded-payload).
144145

145146
```yaml
146147
claimsConfig:
@@ -149,9 +150,11 @@ claimsConfig:
149150
location: /claims.jwt.hasura.io
150151
```
151152

152-
The `location` field indicates the location of the namespace object that uses [RFC 6901 JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) string syntax.
153+
The `location` field indicates the location of the namespace object that uses
154+
[RFC 6901 JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) string syntax.
153155

154-
The `claimsFormat` field indicates whether the Hasura-specific claims are a regular JSON object or a stringified JSON. The following possible values are allowed: `Json`, `StringifiedJson`.
156+
The `claimsFormat` field indicates whether the Hasura-specific claims are a regular JSON object or a stringified JSON.
157+
The following possible values are allowed: `Json`, `StringifiedJson`.
155158

156159
This is required because providers like AWS Cognito only allow strings in the JWT claims.
157160
[See #1176](https://github.com/hasura/graphql-engine/issues/1176).
@@ -190,12 +193,13 @@ If `claimsFormat` is `StringifiedJson` then the JWT claims should look like:
190193

191194
#### locations {#jwt-claims-config-locations}
192195

193-
This `locations` option 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.
194-
In this option, you can indicate:
195-
- a literal value.
196+
This `locations` option can be used when Hasura claims are not all present in the single object, but individual claims
197+
are provided a JSON pointer within the decoded JWT. In this option, you can indicate:
198+
199+
- a literal value.
196200
- or a JSON pointer path for individual claims and an optional default value if the claim doesn't exist.
197201

198-
`x-hasura-default-role` and `x-hasura-allowed-roles` claims are required. Other custom claims are optionally configured.
202+
`x-hasura-default-role` and `x-hasura-allowed-roles` claims are required. Other custom claims are optionally configured.
199203

200204
The literal values should be of type `String`, except for the `x-hasura-allowed-roles` claim which expects a string
201205
array.
@@ -221,12 +225,12 @@ The mapping for `x-hasura-allowed-roles`, `x-hasura-default-role` and `x-hasura-
221225
specified in the `locations` configuration as follows:
222226

223227
```yaml
224-
claimsConfig:
228+
claimsConfig:
225229
locations:
226-
x-hasura-default-role:
230+
x-hasura-default-role:
227231
path:
228232
path: /hasura/all_roles/0
229-
x-hasura-allowed-roles:
233+
x-hasura-allowed-roles:
230234
path:
231235
path: /hasura/all_roles
232236
x-hasura-user-id:
@@ -249,12 +253,12 @@ claimsConfig:
249253
```
250254

251255
```yaml
252-
claimsConfig:
256+
claimsConfig:
253257
locations:
254-
x-hasura-default-role:
258+
x-hasura-default-role:
255259
path:
256260
path: /hasura/all_roles/0
257-
x-hasura-allowed-roles:
261+
x-hasura-allowed-roles:
258262
path:
259263
path: /hasura/all_roles
260264
x-hasura-user-id:
@@ -283,11 +287,11 @@ In the above case, since the `/user/id` doesn't exist in the JWT token, the defa
283287
The corresponding JWT config should be:
284288

285289
```yaml
286-
claimsConfig:
290+
claimsConfig:
287291
locations:
288-
x-hasura-default-role:
292+
x-hasura-default-role:
289293
literal: user
290-
x-hasura-allowed-roles:
294+
x-hasura-allowed-roles:
291295
literal: ["user", "editor"]
292296
x-hasura-user-id:
293297
path:
@@ -299,7 +303,7 @@ value of the `x-hasura-user-id` is a JSON path to the value in the JWT token.
299303

300304
### tokenLocation
301305

302-
Indicates the token location where request header to read the JWT from.
306+
Indicates the token location where request header to read the JWT from.
303307

304308
The following are the possible values:
305309

@@ -308,7 +312,7 @@ The following are the possible values:
308312
In this mode, Hasura expects an `Authorization` header with a `Bearer` token.
309313

310314
```yaml
311-
tokenLocation:
315+
tokenLocation:
312316
type: BearerAuthorization
313317
```
314318

@@ -324,7 +328,7 @@ In the cookie mode, Hasura will try to parse the cookie header with the given co
324328
should be the exact JWT.
325329

326330
```yaml
327-
tokenLocation:
331+
tokenLocation:
328332
type: Cookie
329333
name: cookie_name
330334
```
@@ -340,7 +344,7 @@ Cookie: cookie_name=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWI...
340344
In the custom header mode, Hasura expects a `header_name` header with the exact JWT token value.
341345

342346
```yaml
343-
tokenLocation:
347+
tokenLocation:
344348
type: Header
345349
name: header_name
346350
```
@@ -353,12 +357,12 @@ header_name: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWI...
353357

354358
### key {#jwt-json-key}
355359

356-
This field specifies the JWT key configuration according to which the incoming JWT will be decoded.
357-
You can configure either a `fixed` algorithm key or a remote JWK URL.
360+
This field specifies the JWT key configuration according to which the incoming JWT will be decoded. You can configure
361+
either a `fixed` algorithm key or a remote JWK URL.
358362

359363
#### fixed {#jwt-json-key-fixed}
360364

361-
In this option, you must indicate a JWT key and its algorithm so the engine can decode and verify the JWT token.
365+
In this option, you must indicate a JWT key and its algorithm so the engine can decode and verify the JWT token.
362366

363367
```yaml
364368
key:
@@ -369,10 +373,10 @@ key:
369373
# valueFromEnv: AUTH_JWT_KEY
370374
```
371375

372-
The `algorithm` field specifies the cryptographic signing algorithm which is used to sign the JWTs. Valid values are: `HS256`, `HS384`,
373-
`HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `PS256`, `PS384`, `PS512`, `EdDSA`.
376+
The `algorithm` field specifies the cryptographic signing algorithm which is used to sign the JWTs. Valid values are:
377+
`HS256`, `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `PS256`, `PS384`, `PS512`, `EdDSA`.
374378

375-
The `key` field can be a literal value or an environment variable name.
379+
The `key` field can be a literal value or an environment variable name.
376380

377381
- In the case of a symmetric key (i.e. a HMAC-based key), just the key as is. (e.g. -"abcdef..."). The key must be long
378382
enough for the chosen algorithm, (e.g. for HS256 it must be at least 32 characters long).
@@ -391,7 +395,7 @@ For example:
391395
`https://www.googleapis.com/service_accounts/v1/jwk/[email protected]`.
392396

393397
```yaml
394-
key:
398+
key:
395399
jwkFromUrl: https://www.googleapis.com/service_accounts/v1/jwk/[email protected]
396400
```
397401

@@ -414,9 +418,9 @@ Examples:
414418

415419
```yaml
416420
kind: AuthConfig
417-
version: v2
418-
definition:
419-
mode:
421+
version: v3
422+
definition:
423+
mode:
420424
jwt:
421425
# ...
422426
audience: ["myapp-1234", "myapp-6789"]
@@ -447,9 +451,9 @@ Examples:
447451

448452
```yaml
449453
kind: AuthConfig
450-
version: v2
451-
definition:
452-
mode:
454+
version: v3
455+
definition:
456+
mode:
453457
jwt:
454458
# ...
455459
issuer: https://my-auth-server.com
@@ -476,7 +480,7 @@ will look like:
476480

477481
```yaml
478482
kind: AuthConfig
479-
version: v2
483+
version: v3
480484
definition:
481485
mode:
482486
jwt:
@@ -504,7 +508,7 @@ have the public key.
504508

505509
```yaml
506510
kind: AuthConfig
507-
version: v2
511+
version: v3
508512
definition:
509513
mode:
510514
jwt:
@@ -518,14 +522,17 @@ definition:
518522
fixed:
519523
algorithm: RS512
520524
key:
521-
value: '-----BEGIN PUBLIC KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDdlatRjRjogo3WojgGHFHYLugd\nUWAY9iR3fy4arWNA1KoS8kVw33cJibXr8bvwUAUparCwlvdbH6dvEOfou0/gCFQs\nHUfQrSDv+MuSUMAe8jzKE4qW+jK+xQU9a03GUnKHkkle+Q0pX/g6jXZ7r1/xAK5D\no2kQ+X5xK9cipRgEKwIDAQAB\n-----END PUBLIC KEY-----\n'
525+
value:
526+
'-----BEGIN PUBLIC
527+
KEY-----\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDdlatRjRjogo3WojgGHFHYLugd\nUWAY9iR3fy4arWNA1KoS8kVw33cJibXr8bvwUAUparCwlvdbH6dvEOfou0/gCFQs\nHUfQrSDv+MuSUMAe8jzKE4qW+jK+xQU9a03GUnKHkkle+Q0pX/g6jXZ7r1/xAK5D\no2kQ+X5xK9cipRgEKwIDAQAB\n-----END
528+
PUBLIC KEY-----\n'
522529
```
523530

524531
**Example 2**: public key as X509 certificate:
525532

526533
```yaml
527534
kind: AuthConfig
528-
version: v2
535+
version: v3
529536
definition:
530537
mode:
531538
jwt:
@@ -539,14 +546,17 @@ definition:
539546
fixed:
540547
algorithm: RS512
541548
key:
542-
value: '-----BEGIN CERTIFICATE-----\nMIIDHDCCAgSgAwIBAgIINw9gva8BPPIwDQYJKoZIhvcNAQEFBQAwMTEvMC0GA1UE\nAxMmc2VjdXJldG9rZW4uc3lzdGVtLmdzZXJ2aWNlYWNjb3VudC5jb20wHhcNMTgQt7dIsMTIU9k1SUrFviZOGnmHWtIAw\nmtYBcM9I0f9/ka45JIRp5Y1NKpAMFSShs7Wv0m1JS1kXQHdJsPSmjmDKcwnBe3R/\nTU3foRRywR/3AJRM15FNjTqvUm7TeaW16LkkRoECAwEAAaM4MDYwDAYDVR0TAQH/\nBAIwADAOBgNVHQ8BAf8EBAMCB4AwFgYDVR0lAQH/BAwwCgYIKwYBBQUHAwIwDQYJ\nKoZIhvcNAQEFBQADggEBADfY2DEmc2gb8/pqMNWHYq/nTYfJPpK4VA9A0lFTNeoq\nzmnbGwhKj24X+Nw8trsvkrKxHvCI1alDgBaCyzjGGvgOrh8X0wLtymp1yj6PWwee\nR2ZPdUaB62TCzO0iRv7W6o39ey+mU/FyYRtxF0ecxG2a0KNsIyFkciXUAeC5UVDo\nBNp678/SDDx9Ltuxc6h56a/hpBGf9Yzhr0RvYy3DmjBs6eopiGFmjnOKNxQrZ5t2\n339JWR+yiGEAtoHqk/fINMf1An6Rung1xYowrm4guhCIVi5unAvQ89fq0I6mzPg6\nLhTpeP0o+mVYrBmtYVpDpv0e71cfYowSJCCkod/9YbY=\n-----END CERTIFICATE-----'
549+
value:
550+
'-----BEGIN
551+
CERTIFICATE-----\nMIIDHDCCAgSgAwIBAgIINw9gva8BPPIwDQYJKoZIhvcNAQEFBQAwMTEvMC0GA1UE\nAxMmc2VjdXJldG9rZW4uc3lzdGVtLmdzZXJ2aWNlYWNjb3VudC5jb20wHhcNMTgQt7dIsMTIU9k1SUrFviZOGnmHWtIAw\nmtYBcM9I0f9/ka45JIRp5Y1NKpAMFSShs7Wv0m1JS1kXQHdJsPSmjmDKcwnBe3R/\nTU3foRRywR/3AJRM15FNjTqvUm7TeaW16LkkRoECAwEAAaM4MDYwDAYDVR0TAQH/\nBAIwADAOBgNVHQ8BAf8EBAMCB4AwFgYDVR0lAQH/BAwwCgYIKwYBBQUHAwIwDQYJ\nKoZIhvcNAQEFBQADggEBADfY2DEmc2gb8/pqMNWHYq/nTYfJPpK4VA9A0lFTNeoq\nzmnbGwhKj24X+Nw8trsvkrKxHvCI1alDgBaCyzjGGvgOrh8X0wLtymp1yj6PWwee\nR2ZPdUaB62TCzO0iRv7W6o39ey+mU/FyYRtxF0ecxG2a0KNsIyFkciXUAeC5UVDo\nBNp678/SDDx9Ltuxc6h56a/hpBGf9Yzhr0RvYy3DmjBs6eopiGFmjnOKNxQrZ5t2\n339JWR+yiGEAtoHqk/fINMf1An6Rung1xYowrm4guhCIVi5unAvQ89fq0I6mzPg6\nLhTpeP0o+mVYrBmtYVpDpv0e71cfYowSJCCkod/9YbY=\n-----END
552+
CERTIFICATE-----'
543553
```
544554

545555
**Example 3**: public key published as JWKs:
546556

547557
```yaml
548558
kind: AuthConfig
549-
version: v2
559+
version: v3
550560
definition:
551561
mode:
552562
jwt:
@@ -569,7 +579,7 @@ the public key.
569579

570580
```yaml
571581
kind: AuthConfig
572-
version: v2
582+
version: v3
573583
definition:
574584
mode:
575585
jwt:
@@ -583,14 +593,16 @@ definition:
583593
fixed:
584594
algorithm: Ed25519
585595
key:
586-
value: '-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAG9I+toAAJicilbPt36tiC4wi7E1Dp9rMmfnwdKyVXi0=\n-----END PUBLIC KEY-----'
596+
value:
597+
'-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAG9I+toAAJicilbPt36tiC4wi7E1Dp9rMmfnwdKyVXi0=\n-----END PUBLIC
598+
KEY-----'
587599
```
588600

589601
**Example 2**: public key as X509 certificate:
590602

591603
```yaml
592604
kind: AuthConfig
593-
version: v2
605+
version: v3
594606
definition:
595607
mode:
596608
jwt:
@@ -604,7 +616,10 @@ definition:
604616
fixed:
605617
algorithm: Ed25519
606618
key:
607-
value: '-----BEGIN CERTIFICATE REQUEST-----\nMIIBAzCBtgIBADAnMQswCQYDVQQGEwJERTEYMBYGA1UEAwwPd3d3LmV4YW1wbGUu\nY29tMCowBQYDK2VwAyEA/9DV/InajW02Q0tC/tyr9mCSbSnNP1txICXVJrTGKDSg\nXDBaBgkqhkiG9w0BCQ4xTTBLMAsGA1UdDwQEAwIEMDATBgNVHSUEDDAKBggrBgEF\nBQcDATAnBgNVHREEIDAegg93d3cuZXhhbXBsZS5jb22CC2V4YW1wbGUuY29tMAUG\nAytlcANBAKbTqnTyPcf4ZkVuq2tC108pBGY19VgyoI+PP2wD2KaRz4QAO7Bjd+7S\nljyJoN83UDdtdtgb7aFgb611gx9W4go=\n-----END CERTIFICATE REQUEST-----'
619+
value:
620+
'-----BEGIN CERTIFICATE
621+
REQUEST-----\nMIIBAzCBtgIBADAnMQswCQYDVQQGEwJERTEYMBYGA1UEAwwPd3d3LmV4YW1wbGUu\nY29tMCowBQYDK2VwAyEA/9DV/InajW02Q0tC/tyr9mCSbSnNP1txICXVJrTGKDSg\nXDBaBgkqhkiG9w0BCQ4xTTBLMAsGA1UdDwQEAwIEMDATBgNVHSUEDDAKBggrBgEF\nBQcDATAnBgNVHREEIDAegg93d3cuZXhhbXBsZS5jb22CC2V4YW1wbGUuY29tMAUG\nAytlcANBAKbTqnTyPcf4ZkVuq2tC108pBGY19VgyoI+PP2wD2KaRz4QAO7Bjd+7S\nljyJoN83UDdtdtgb7aFgb611gx9W4go=\n-----END
622+
CERTIFICATE REQUEST-----'
608623
```
609624

610625
#### EC based
@@ -616,7 +631,7 @@ needs to have the public key.
616631

617632
```yaml
618633
kind: AuthConfig
619-
version: v2
634+
version: v3
620635
definition:
621636
mode:
622637
jwt:
@@ -630,15 +645,17 @@ definition:
630645
fixed:
631646
algorithm: ES256
632647
key:
633-
value: '-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEVs/o5+uQbTjL3chynL4wXgUg2R9\nq9UU8I5mEovUf86QZ7kOBIjJwqnzD1omageEHWwHdBO6B+dFabmdT9POxg==\n-----END PUBLIC KEY-----'
648+
value:
649+
'-----BEGIN PUBLIC
650+
KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEVs/o5+uQbTjL3chynL4wXgUg2R9\nq9UU8I5mEovUf86QZ7kOBIjJwqnzD1omageEHWwHdBO6B+dFabmdT9POxg==\n-----END
651+
PUBLIC KEY-----'
634652
```
635653

636654
**Example 2**: public key as X509 certificate:
637655

638-
639656
```yaml
640657
kind: AuthConfig
641-
version: v2
658+
version: v3
642659
definition:
643660
mode:
644661
jwt:
@@ -652,14 +669,17 @@ definition:
652669
fixed:
653670
algorithm: ES256
654671
key:
655-
value: '"-----BEGIN CERTIFICATE-----\nMIIBbjCCARWgAwIBAgIUGn02F6Y6s88dDGmIfwiNxWxDjhswCgYIKoZIzj0EAwIw\nDTELMAkGA1UEBhMCSU4wHhcNMjMwNTI0MTAzNTI4WhcNMjgwNTIyMTAzNTI4WjAN\nMQswCQYDVQQGEwJJTjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABBFbP6OfrkG0\n4y93Icpy+MF4FINkfavVFPCOZhKL1H/OkGe5DgSIycKp8w9aJmoHhB1sB3QTugfn\nRWm5nU/TzsajUzBRMB0GA1UdDgQWBBSaqFjzps1qG+x2DPISjaXTWsTOdDAfBgNV\nHSMEGDAWgBSaqFjzps1qG+x2DPISjaXTWsTOdDAPBgNVHRMBAf8EBTADAQH/MAoG\nCCqGSM49BAMCA0cAMEQCIBDHHWa/uLAVdGFEk82auTmw995+MsRwv52VXLw2Z+ji\nAiAXzOWIcGN8p25uhUN/7v9gEcADGIS4yUiv8gsn/Jk2ow==\n-----END CERTIFICATE-----'
672+
value:
673+
'"-----BEGIN
674+
CERTIFICATE-----\nMIIBbjCCARWgAwIBAgIUGn02F6Y6s88dDGmIfwiNxWxDjhswCgYIKoZIzj0EAwIw\nDTELMAkGA1UEBhMCSU4wHhcNMjMwNTI0MTAzNTI4WhcNMjgwNTIyMTAzNTI4WjAN\nMQswCQYDVQQGEwJJTjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABBFbP6OfrkG0\n4y93Icpy+MF4FINkfavVFPCOZhKL1H/OkGe5DgSIycKp8w9aJmoHhB1sB3QTugfn\nRWm5nU/TzsajUzBRMB0GA1UdDgQWBBSaqFjzps1qG+x2DPISjaXTWsTOdDAfBgNV\nHSMEGDAWgBSaqFjzps1qG+x2DPISjaXTWsTOdDAPBgNVHRMBAf8EBTADAQH/MAoG\nCCqGSM49BAMCA0cAMEQCIBDHHWa/uLAVdGFEk82auTmw995+MsRwv52VXLw2Z+ji\nAiAXzOWIcGN8p25uhUN/7v9gEcADGIS4yUiv8gsn/Jk2ow==\n-----END
675+
CERTIFICATE-----'
656676
```
657677

658678
**Example 3**: public key published as JWKs:
659679

660680
```yaml
661681
kind: AuthConfig
662-
version: v2
682+
version: v3
663683
definition:
664684
mode:
665685
jwt:
@@ -719,7 +739,7 @@ If you are using Firebase and Hasura, use this config:
719739

720740
```yaml
721741
kind: AuthConfig
722-
version: v2
742+
version: v3
723743
definition:
724744
mode:
725745
jwt:

‎docs/auth/jwt/jwt-mode.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ variable. However, Hasura DDN supports other methods for
7373

7474
```yaml title="globals/metadata/auth-config.hml"
7575
kind: AuthConfig
76-
version: v2
76+
version: v3
7777
definition:
7878
mode:
7979
jwt:

‎docs/auth/jwt/tutorials/integrations/1-auth0.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ Update your AuthConfig object to use JWT mode and your
9696

9797
```yaml
9898
kind: AuthConfig
99-
version: v2
99+
version: v3
100100
definition:
101101
mode:
102102
jwt:

‎docs/auth/jwt/tutorials/integrations/2-aws-cognito.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ which you can find on your User pool overview card:
9898

9999
```yaml
100100
kind: AuthConfig
101-
version: v2
101+
version: v3
102102
definition:
103103
mode:
104104
jwt:

0 commit comments

Comments
 (0)