From b40f54f603f34ed0148fc1442007fca24edf4268 Mon Sep 17 00:00:00 2001
From: Frederik Dudzik <5946811+doodzik@users.noreply.github.com>
Date: Sat, 20 Apr 2024 12:26:53 -0400
Subject: [PATCH] chore(docs): make external auth docs easier to follow
 (#12970)

* add additional context to github external auth provider documentation

* Apply suggestions from code review

Co-authored-by: Kyle Carberry <kyle@carberry.com>

* Update docs/admin/external-auth.md

* fmt

* fmt

---------

Co-authored-by: Kyle Carberry <kyle@carberry.com>
---
 docs/admin/external-auth.md | 78 ++++++++++++++++++++++++++++++++-----
 1 file changed, 68 insertions(+), 10 deletions(-)

diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md
index 2f785c5c51..f281afe0d7 100644
--- a/docs/admin/external-auth.md
+++ b/docs/admin/external-auth.md
@@ -25,16 +25,12 @@ application. The following providers are supported:
 - [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops)
 - [Azure DevOps (via Entra ID)](https://learn.microsoft.com/en-us/entra/architecture/auth-oauth2)
 
-Example callback URL:
-`https://coder.example.com/external-auth/primary-github/callback`. Use an
-arbitrary ID for your provider (e.g. `primary-github`).
-
-Set the following environment variables to
-[configure the Coder server](./configure.md):
+The next step is to [configure the Coder server](./configure.md) to use the
+OAuth application by setting the following environment variables:
 
 ```env
-CODER_EXTERNAL_AUTH_0_ID="primary-github"
-CODER_EXTERNAL_AUTH_0_TYPE=github|gitlab|azure-devops|bitbucket-cloud|bitbucket-server|<name of service e.g. jfrog>
+CODER_EXTERNAL_AUTH_0_ID="<USER_DEFINED_ID>"
+CODER_EXTERNAL_AUTH_0_TYPE=<github|gitlab|azure-devops|bitbucket-cloud|bitbucket-server|etc>
 CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
 CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
 
@@ -43,11 +39,22 @@ CODER_EXTERNAL_AUTH_0_DISPLAY_NAME="Google Calendar"
 CODER_EXTERNAL_AUTH_0_DISPLAY_ICON="https://mycustomicon.com/google.svg"
 ```
 
+The `CODER_EXTERNAL_AUTH_0_ID` environment variable is used for internal
+reference. Therefore, it can be set arbitrarily (e.g., `primary-github` for your
+GitHub provider).
+
 ### GitHub
 
+> If you don't require fine-grained access control, it's easier to configure a
+> GitHub OAuth app!
+
 1. [Create a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)
-   to enable fine-grained access to specific repositories, or a subset of
-   permissions for security.
+
+   - Set the callback URL to
+     `https://coder.example.com/external-auth/USER_DEFINED_ID/callback`.
+   - Deactivate Webhooks.
+   - Enable fine-grained access to specific repositories or a subset of
+     permissions for security.
 
    ![Register GitHub App](../images/admin/github-app-register.png)
 
@@ -69,6 +76,13 @@ CODER_EXTERNAL_AUTH_0_DISPLAY_ICON="https://mycustomicon.com/google.svg"
 
    ![Install GitHub App](../images/admin/github-app-install.png)
 
+```env
+CODER_EXTERNAL_AUTH_0_ID="USER_DEFINED_ID"
+CODER_EXTERNAL_AUTH_0_TYPE=github
+CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
+CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
+```
+
 ### GitHub Enterprise
 
 GitHub Enterprise requires the following environment variables:
@@ -204,6 +218,50 @@ add this to the
 git config --global credential.useHttpPath true
 ```
 
+### Kubernetes environment variables
+
+If you deployed Coder with Kubernetes you can set the environment variables in
+your `values.yaml` file:
+
+```yaml
+coder:
+  env:
+    # […]
+    - name: CODER_EXTERNAL_AUTH_0_ID
+      value: USER_DEFINED_ID
+
+    - name: CODER_EXTERNAL_AUTH_0_TYPE
+      value: github
+
+    - name: CODER_EXTERNAL_AUTH_0_CLIENT_ID
+      valueFrom:
+        secretKeyRef:
+          name: github-primary-basic-auth
+          key: client-id
+
+    - name: CODER_EXTERNAL_AUTH_0_CLIENT_SECRET
+      valueFrom:
+        secretKeyRef:
+          name: github-primary-basic-auth
+          key: client-secret
+```
+
+You can set the secrets by creating a `github-primary-basic-auth.yaml` file and
+applying it.
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: github-primary-basic-auth
+type: Opaque
+stringData:
+  client-secret: xxxxxxxxx
+  client-id: xxxxxxxxx
+```
+
+Make sure to restart the affected pods for the change to take effect.
+
 ## Require git authentication in templates
 
 If your template requires git authentication (e.g. running `git clone` in the