github oauth2 by default docs

hugodutka · hugodutka · commit da04e13623c0 · 2025-02-24T13:30:57.000Z
diff --git a/docs/admin/users/github-auth.md b/docs/admin/users/github-auth.md
@@ -1,5 +1,25 @@
 # GitHub
 
+## Default Configuration
+
+By default, new Coder deployments use a Coder-managed GitHub app to authenticate
+users. We provide it for convenience, allowing you to experiment with Coder without
+setting up your own GitHub OAuth app. However, by using it, you allow the app's 
+admin, Coder the company, to see:
+
+- your GitHub user email
+- your GitHub organization membership
+
+For production deployments, we recommend
+disabling the default and creating your own app.
+
+The default is automatically disabled if you configure your own app as outlined
+below or set:
+
+```env
+CODER_OAUTH2_GITHUB_DEFAULT_PROVIDER=false
+```
+
 ## Step 1: Configure the OAuth application in GitHub
 
 First,
@@ -82,3 +102,16 @@ helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
 > We recommend requiring and auditing MFA usage for all users in your GitHub
 > organizations. This can be enforced from the organization settings page in the
 > "Authentication security" sidebar tab.
+
+## Device Flow
+
+Coder supports
+[device flow](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow)
+for GitHub OAuth. To enable it, set:
+
+```env
+CODER_OAUTH2_GITHUB_DEVICE_FLOW=true
+```
+
+This is optional. We recommend using the standard OAuth flow instead, as it is
+more convenient for end users.
