From 0e1977cd70d69d83ce13c5aa49c7c98fa24a47a1 Mon Sep 17 00:00:00 2001
From: Brett Dudo <brett@dudo.io>
Date: Sat, 23 Dec 2023 13:06:44 -0800
Subject: [PATCH] Update guard-jwt.md to show .well-known/jwks.json support
 (#159)

Update guard-jwt.md
---
 src/reference/config/guards/guard-jwt.md | 64 +++++++++++++++---------
 1 file changed, 40 insertions(+), 24 deletions(-)

diff --git a/src/reference/config/guards/guard-jwt.md b/src/reference/config/guards/guard-jwt.md
index b5d2df3d..e9698ec6 100644
--- a/src/reference/config/guards/guard-jwt.md
+++ b/src/reference/config/guards/guard-jwt.md
@@ -11,25 +11,39 @@ tag:
 
 Zilla runtime jwt guard.
 
+If using an Identity Provider that exposes a `.well-known/jwks.json` file, simply provide the `issuer` and `audience`. The JWKS will be fetched, remotely.
+
+```yaml {2}
+guards:
+  jwt:
+    type: jwt
+    options:
+      issuer: https://auth.example.com
+      audience: https://api.example.com
+```
+
+Manual configuration is also supported.
+
 ```yaml {2}
-jwt:
-  type: jwt
-  options:
-    issuer: https://auth.example.com
-    audience: https://api.example.com
-    keys:
-      - kty: EC
-        crv: P-256
-        x: MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4
-        y: 4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM
-        use: enc
-        kid: '1'
-      - kty: RSA
-        n: 0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw
-        e: AQAB
-        alg: RS256
-        kid: '2011-04-29'
-    challenge: 30
+guards:
+  jwt:
+    type: jwt
+    options:
+      issuer: https://auth.example.com
+      audience: https://api.example.com
+      keys:
+        - kty: EC
+          crv: P-256
+          x: MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4
+          y: 4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM
+          use: enc
+          kid: '1'
+        - kty: RSA
+          n: 0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw
+          e: AQAB
+          alg: RS256
+          kid: '2011-04-29'
+      challenge: 30
 ```
 
 ## Summary
@@ -48,9 +62,9 @@ Each verified JWT access token has an expiration time, and an optional challenge
 - [options.issuer](#options-issuer)
 - [options.audience](#options-audience)
 - [options.challenge](#options-challenge)
-- [options.keys\*](#options-keys)
-- [keys\[\].kty\*](#keys-kty)
-- [keys\[\].kid\*](#keys-kid)
+- [options.keys](#options-keys)
+- [keys\[\].kty](#keys-kty)
+- [keys\[\].kid](#keys-kid)
 - [keys\[\].n](#keys-n)
 - [keys\[\].e](#keys-e)
 - [keys\[\].alg](#keys-alg)
@@ -107,17 +121,19 @@ Audience claim.
 
 Challenge period (seconds).
 
-### options.keys\*
+### options.keys
 
 > `array` of `object`
 
-### keys[].kty\*
+If not provided, relies on the `issuer` to infer the location of a remote `.well-known/jwks.json` file.
+
+### keys[].kty
 
 > `string`
 
 Key type, e.g. `RSA` , `EC`.
 
-### keys[].kid\*
+### keys[].kid
 
 > `string`