From 2c0f5bb31315eeb7d52bfdfa01663e0df69e6abd Mon Sep 17 00:00:00 2001
From: Michael Webb <28074382+mjfwebb@users.noreply.github.com>
Date: Mon, 27 Nov 2023 13:54:27 +0100
Subject: [PATCH] docs: add section about passing in JWTs (#71)

Co-authored-by: Lidia Zuin <102308961+lidiazuin@users.noreply.github.com>
---
 .../configuration.adoc                        | 45 +++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/modules/ROOT/pages/authentication-and-authorization/configuration.adoc b/modules/ROOT/pages/authentication-and-authorization/configuration.adoc
index d36973e3..ac285fe2 100644
--- a/modules/ROOT/pages/authentication-and-authorization/configuration.adoc
+++ b/modules/ROOT/pages/authentication-and-authorization/configuration.adoc
@@ -127,3 +127,48 @@ type JWT @jwt {
 ====
 The seemingly excessive escaping is required to doubly escape: once for GraphQL and once for `dot-prop`, which is used under the hood to resolve the path.
 ====
+
+== Passing in JWTs
+
+To pass in an encoded JWT, you must use the token field of the context.
+When using Apollo Server, extract the authorization header into the token property of the context as follows:
+
+[source, javascript, indent=0]
+----
+const server = new ApolloServer({
+    schema,
+});
+
+await startStandaloneServer(server, {
+    context: async ({ req }) => ({ token: req.headers.authorization }),
+});
+----
+
+For example, a HTTP request with the following `authorization` header should look like this:
+
+[source]
+----
+POST / HTTP/1.1
+authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJyb2xlcyI6WyJ1c2VyX2FkbWluIiwicG9zdF9hZG1pbiIsImdyb3VwX2FkbWluIl19.IY0LWqgHcjEtOsOw60mqKazhuRFKroSXFQkpCtWpgQI
+content-type: application/json
+----
+
+Alternatively, you can pass a key `jwt` of type `JwtPayload` into the context, which has the following definition:
+
+[source, typescript, indent=0]
+----
+// standard claims https://datatracker.ietf.org/doc/html/rfc7519#section-4.1
+interface JwtPayload {
+    [key: string]: any;
+    iss?: string | undefined;
+    sub?: string | undefined;
+    aud?: string | string[] | undefined;
+    exp?: number | undefined;
+    nbf?: number | undefined;
+    iat?: number | undefined;
+    jti?: string | undefined;
+}
+----
+
+[WARNING]
+_Do not_ pass in the header or the signature.