From 762c97212464e26cee674baecbd96c2db9efe73e Mon Sep 17 00:00:00 2001
From: "joel@joellee.org" <joel@joellee.org>
Date: Sun, 9 Apr 2023 12:32:44 +0800
Subject: [PATCH] docs: update ssr guide with pkce details

---
 .../guides/auth/server-side-rendering.mdx     | 87 ++++++++++++++-----
 1 file changed, 67 insertions(+), 20 deletions(-)

diff --git a/apps/docs/pages/guides/auth/server-side-rendering.mdx b/apps/docs/pages/guides/auth/server-side-rendering.mdx
index 236cc747db3..d2f510814f0 100644
--- a/apps/docs/pages/guides/auth/server-side-rendering.mdx
+++ b/apps/docs/pages/guides/auth/server-side-rendering.mdx
@@ -57,7 +57,9 @@ like `*` and `**` to allow redirects to different forms of URLs.
 
 </Admonition>
 
-Users can choose between one of two flows:
+Supabase Auth supports two authentication flows: **Implicit** and **PKCE**. The **PKCE** flow is generally preferred when on the server.
+It introduces a few additional steps which guard a against replay and URL capture attacks. Unlike the implicit flow, it also allows users to access the
+`access_token` and `refresh_token` on the server.
 
 <Accordion
   type="default"
@@ -68,13 +70,12 @@ Users can choose between one of two flows:
   className="text-scale-900 dark:text-white"
   >
     <div className="border-b pb-3">
+      <Accordion.Item
+        header={<span className="text-scale-1200">Implicit</span>}
+        id={`ssr-implicit-flow`}
+      >
 
-<Accordion.Item
-                          header={<span className="text-scale-1200">Implicit</span>}
-                          id={`implicit-flow`}
-                        >
-
-These redirect URLs have the following structure:
+When using the implicit flow, a redirect URL will be returned with the following structure:
 ```
 https://yourapp.com/...#access_token=<...>&refresh_token=<...>&...
 ```
@@ -95,22 +96,68 @@ your direct control (such as on GitHub Pages or other freemium hosting
 providers), we want to prevent hosting services from getting access to your
 user's authorization credentials by default. Even if the server is under your
 direct control, `GET` requests and their full URLs are often logged. This
-approach also avoids leaking credentials in request or access logs.
+approach also avoids leaking credentials in request or access logs. If you wish to obtain the
+`access_token` and `refresh_token` on a server, please consider using the PKCE flow.
 </Admonition>
-
-  </Accordion.Item>
-  </div>
-    <div className="border-b pb-3">
-
-<Accordion.Item
-                          header={<span className="text-scale-1200">PKCE</span>}
-                          id={`pkce-flow`}
-                        >
-
-  Test
-  </Accordion.Item>
+      </Accordion.Item>
     </div>
+    <div className="border-b pb-3">
+      <Accordion.Item
+        header={<span className="text-scale-1200">PKCE</span>}
+        id={`ssr-pkce-flow`}
+      >
+        When using the PKCE flow, a redirect URL will be returned with the following structure:
+        ```
+        https://yourapp.com/...?code=<...>
+        ```
+        The `code` can then be exchanged for an access token by calling `exchangeCodeForSession(code)` method.
 
+        As the flow is run server side,  `localStorage` may not be available. You may configure the client library to use a custom storage adapter
+        by setting the `storage` option to an object with the following methods:
+        ```js
+        const customStorageAdapter: SupportedStorage = {
+          getItem: (key) => {
+            if (!supportsLocalStorage()) {
+              return null
+            }
+            return globalThis.localStorage.getItem(key)
+          },
+          setItem: (key, value) => {
+            if (!supportsLocalStorage()) {
+              return
+            }
+            globalThis.localStorage.setItem(key, value)
+          },
+          removeItem: (key) => {
+            if (!supportsLocalStorage()) {
+              return
+            }
+            globalThis.localStorage.removeItem(key)
+          },
+        }
+        ```
+        You may also configure the client library to automatically exchange it for a session after a successful redirect. This can be done by setting the `detectSessionInUrl` option to `true`.
+
+        Putting it all together, your client library initialization may look like this:
+        ```js
+        const supabase = createClient(
+             'https://xyzcompany.supabase.co',
+             'public-anon-key',
+             options: {
+               ...
+               auth: {
+                 ...
+                 detectSessionInUrl: true,
+                 flowType: 'pkce',
+                 storage: customStorageAdapter,
+               }
+               ...
+             }
+        )
+        ```
+        You can read more about the PKCE flow [here](https://oauth.net/2/pkce/)
+      </Accordion.Item>
+    </div>
 </Accordion>
 
 ## Bringing it together