From 66c83f5194a3d3793f2e1c3c13d561389b918ae7 Mon Sep 17 00:00:00 2001
From: Petri-Johan Last <petri.last@sourcegraph.com>
Date: Wed, 8 Oct 2025 15:25:04 +0200
Subject: [PATCH] Add docs around requiredSsoOrgs

---
 docs/admin/auth/index.mdx        | 30 ++++++++++++++++++++++++++++++
 docs/admin/code_hosts/github.mdx |  2 ++
 2 files changed, 32 insertions(+)

diff --git a/docs/admin/auth/index.mdx b/docs/admin/auth/index.mdx
index 8da3abd89..8c8df7700 100644
--- a/docs/admin/auth/index.mdx
+++ b/docs/admin/auth/index.mdx
@@ -184,6 +184,36 @@ When combined with `"allowSignup": false` or unset, an admin should first create
     }
   ```
 
+**requiredSsoOrgs**
+
+Requires that users have SAML SSO authorization for specific GitHub organizations when authenticating via OAuth. This is useful when your GitHub organizations enforce SAML SSO, and you want to ensure users properly authorize the OAuth application for those organizations during the authentication flow. Not doing so could cause permissions syncing issues.
+
+This setting accepts **GitHub organization IDs** (numeric strings), not organization names.
+
+**Finding your GitHub organization ID:**
+
+You can find your organization ID using the GitHub API:
+
+```bash
+curl -H "Authorization: token YOUR_GITHUB_TOKEN" \
+  https://api.github.com/orgs/YOUR_ORG_NAME
+```
+
+The response will include an `id` field with your organization's numeric ID.
+
+**Example configuration:**
+
+```json
+{
+  "type": "github",
+  "url": "https://github.com",
+  "displayName": "GitHub",
+  "clientID": "replace-with-the-oauth-client-id",
+  "clientSecret": "replace-with-the-oauth-client-secret",
+  "allowSignup": true,
+  "requiredSsoOrgs": ["123456789", "987654321"]
+}
+```
 
 ## GitLab
 
diff --git a/docs/admin/code_hosts/github.mdx b/docs/admin/code_hosts/github.mdx
index 0b0dec4ca..1d6d5af1e 100644
--- a/docs/admin/code_hosts/github.mdx
+++ b/docs/admin/code_hosts/github.mdx
@@ -315,6 +315,8 @@ See [Internal rate limits](/admin/code_hosts/rate_limits#internal-rate-limits).
 
 Prerequisite for configuring repository permission syncing: [Add GitHub as an authentication provider](/admin/auth/#github).
 
+> NOTE: If your GitHub organization enforces SAML SSO, consider configuring [`requiredSsoOrgs`](/admin/auth/#requiredssoOrgs) in your GitHub auth provider to ensure users properly authorize the OAuth application during sign-in. This helps prevent permissions syncing issues caused by tokens that lack SSO authorization.
+
 Then, add or edit the GitHub connection as described above and include the `authorization` field:
 
 ```json