From e0778dd013fd82b3a314f76c207c5ab739e3792f Mon Sep 17 00:00:00 2001
From: chdeskur <chdeskur@gmail.com>
Date: Wed, 8 Oct 2025 16:32:28 -0400
Subject: [PATCH] feat: document oauth rbac steps

---
 fern/products/docs/docs.yml                   |  4 +
 .../pages/authentication/set-up-oauth.mdx     | 78 +++++++++++++++++++
 2 files changed, 82 insertions(+)
 create mode 100644 fern/products/docs/pages/authentication/set-up-oauth.mdx

diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml
index f6c1f352e..b885a805f 100644
--- a/fern/products/docs/docs.yml
+++ b/fern/products/docs/docs.yml
@@ -199,6 +199,10 @@ navigation:
       - page: Role based access control (RBAC)
         path: ./pages/authentication/rbac.mdx
         slug: rbac
+      - page: Set up OAuth
+        path: ./pages/authentication/set-up-oauth.mdx
+        hidden: true
+        slug: set-up-oauth
       - page: API key injection
         path: ./pages/api-references/autopopulate-api-key.mdx
       - page: SSO
diff --git a/fern/products/docs/pages/authentication/set-up-oauth.mdx b/fern/products/docs/pages/authentication/set-up-oauth.mdx
new file mode 100644
index 000000000..12f0138dd
--- /dev/null
+++ b/fern/products/docs/pages/authentication/set-up-oauth.mdx
@@ -0,0 +1,78 @@
+---
+title: Set up OAuth
+subtitle: Integrate your OAuth provider with Fern Docs
+---
+
+<Steps>
+<Step title="Create an OAuth client">
+Go to your OAuth provider's dashboard. Create a new **web application** client. This is the client that will be used by Fern to authenticate users with your OAuth provider.
+</Step>
+
+<Step title="Allowlist Fern callbacks">
+You will need to allowlist the following callback in your OAuth provider:
+`https://<your-domain>/api/fern-docs/oauth2/callback`.
+
+Replace `<your-domain>` with whatever domain you are using for your Fern Docs site. If you want to authenticate both your `.docs.buildwithfern.com` and custom domain, you will need to allowlist both.
+</Step>
+
+<Step title="Send OAuth client details to Fern">
+Fern will need the following details to configure OAuth authentication:
+- [ ] Docs domain
+- [ ] Client ID
+- [ ] Client secret
+- [ ] Authorization URL (e.g. `https://<your-oauth-tenant>/oauth2/authorize`)
+- [ ] Token URL (e.g. `https://<your-oauth-tenant>/oauth2/token`)
+- [ ] Scopes (e.g. `openid`, `profile`, `email`)
+- [ ] Issuer URL (e.g. `https://<your-domain>`)
+
+Send these details to support@buildwithfern.com or in your dedicated Slack channel.
+</Step>
+
+<Step title="Wait for Fern to configure OAuth">
+Wait for Fern to configure OAuth. You will receive a notification when the site is ready to use authentication.
+</Step>
+
+<Step title="Add a custom claim to set user roles">
+Add a custom claim to your OAuth provider's token response. This claim will be used to set the user's roles in Fern Docs. The resulting token response should look something like this:
+
+```json {12-15}
+{
+  "iss": "https://your-tenant.us.auth0.com/",
+  "sub": "auth0|507f1f77bcf86cd799439011",
+  "aud": "your_client_id_here",
+  "iat": 1728388800,
+  "exp": 1728475200,
+  "email": "user@example.com",
+  "email_verified": true,
+  "name": "John Doe",
+  "nickname": "johndoe",
+  "picture": "https://s.gravatar.com/avatar/...",
+  "roles": [
+    "custom-role",
+    "user-specific-role"
+  ]
+}
+```
+
+<AccordionGroup>
+<Accordion title="Using Auth0">
+To add a custom claim to Auth0, you need to create a **custom action**. This action will be used to add the custom claim to the token response.
+
+1. Go to the **Actions** tab in the Auth0 dashboard.
+2. Create a **Custom Action**.
+3. Select **Login/Post Login**.
+4. Add logic to set a roles.
+5. Click **Create**.
+6. Add the action to your **Post Login Flow**.
+</Accordion>
+<Accordion title="Using another provider">
+If you are using a different OAuth provider, please reach out to Fern with any questions on setting up a custom claim.
+</Accordion>
+</AccordionGroup>
+</Step>
+
+<Step title="Add roles to your docs">
+See [RBAC](/docs/authentication/rbac#set-up-rbac) for more information on how to add roles to your docs.
+</Step>
+
+</Steps>
\ No newline at end of file