docs: update external auth to better explain process (coder#16027)

EdwardAngert · ChristopherJTrent · matifali · web-flow · commit ee1829ba7171 · 2025-01-07T15:10:16.000-05:00
- adds to @ChristopherJTrent's PR coder#15970 > Adds more information on how to add external auth, including docker-compose and docker CLI examples and terraform code for template integration. - general edits and improvements to the external-auth doc [preview](https://coder.com/docs/@15970-external-auth-update/admin/external-auth) --------- Co-authored-by: Christopher Trent <ChristopherJTrent@outlook.com> Co-authored-by: Muhammad Atif Ali <me@matifali.dev>
diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md
@@ -1,88 +1,98 @@
 # External Authentication
 
+Coder supports external authentication via OAuth2.0. This allows enabling any OAuth provider as well as integrations with Git providers,
+such as GitHub, GitLab, and Bitbucket.
+
+External authentication can also be used to integrate with external services
+like JFrog Artifactory and others.
+
 To add an external authentication provider, you'll need to create an OAuth
-application. The following providers are supported:
+application. The following providers have been tested and work with Coder:
 
-- [GitHub](#github)
-- [GitLab](https://docs.gitlab.com/ee/integration/oauth_provider.html)
-- [BitBucket](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/)
 - [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)
+- [BitBucket](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/)
+- [GitHub](#github)
+- [GitLab](https://docs.gitlab.com/ee/integration/oauth_provider.html)
+
+If you have experience with a provider that is not listed here, please
+[file an issue](https://github.com/coder/internal/issues/new?title=request%28docs%29%3A+external-auth+-+request+title+here%0D%0A&labels=["customer-feedback","docs"]&body=doc%3A+%5Bexternal-auth%5D%28https%3A%2F%2Fcoder.com%2Fdocs%2Fadmin%2Fexternal-auth%29%0D%0A%0D%0Aplease+enter+your+request+here%0D%0A)
 
-The next step is to configure the Coder server to use the OAuth application by
-setting the following environment variables:
+## Configuration
+
+After you create an OAuth application, set environment variables to configure the Coder server to use it:
 
 ```env
 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
+CODER_EXTERNAL_AUTH_0_CLIENT_ID=<OAuth app client ID>
+CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=<OAuth app client secret>
 
-# Optionally, configure a custom display name and icon
+# Optionally, configure a custom display name and icon:
 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).
+reference. Set it with a value that helps you identify it. For example, you can use `CODER_EXTERNAL_AUTH_0_ID="primary-github"` for your
+GitHub provider.
 
-## GitHub
+Add the following code to any template to add a button to the workspace setup page which will allow you to authenticate with your provider:
 
-> If you don't require fine-grained access control, it's easier to configure a
-> GitHub OAuth app!
+```tf
+data "coder_external_auth" "<github|gitlab|azure-devops|bitbucket-cloud|bitbucket-server|other>" {
+    id = "<USER_DEFINED_ID>"
+}
 
-1. [Create a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)
+# GitHub Example (CODER_EXTERNAL_AUTH_0_ID="primary-github")
+# makes a GitHub authentication token available at data.coder_external_auth.github.access_token
+data "coder_external_auth" "github" {
+   id = "primary-github"
+}
 
-   - 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)
+Inside your Terraform code, you now have access to authentication variables. Reference the documentation for your chosen provider for more information on how to supply it with a token.
 
-2. Adjust the GitHub App permissions. You can use more or less permissions than
-   are listed here, this is merely a suggestion that allows users to clone
-   repositories:
+### Workspace CLI
 
-   ![Adjust GitHub App Permissions](../images/admin/github-app-permissions.png)
+Use [`external-auth`](../reference/cli/external-auth.md) in the Coder CLI to access a token within the workspace:
 
-   | Name          | Permission   | Description                                            |
-   |---------------|--------------|--------------------------------------------------------|
-   | Contents      | Read & Write | Grants access to code and commit statuses.             |
-   | Pull requests | Read & Write | Grants access to create and update pull requests.      |
-   | Workflows     | Read & Write | Grants access to update files in `.github/workflows/`. |
-   | Metadata      | Read-only    | Grants access to metadata written by GitHub Apps.      |
-   | Members       | Read-only    | Grants access to organization members and teams.       |
+```shell
+coder external-auth <USER_DEFINED_ID> access-token
+```
 
-3. Install the App for your organization. You may select a subset of
-   repositories to grant access to.
+## Git-provider specific env variables
 
-   ![Install GitHub App](../images/admin/github-app-install.png)
+### Azure DevOps
+
+Azure DevOps requires the following environment variables:
 
 ```env
-CODER_EXTERNAL_AUTH_0_ID="USER_DEFINED_ID"
-CODER_EXTERNAL_AUTH_0_TYPE=github
+CODER_EXTERNAL_AUTH_0_ID="primary-azure-devops"
+CODER_EXTERNAL_AUTH_0_TYPE=azure-devops
 CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
+# Ensure this value is your "Client Secret", not "App Secret"
 CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
+CODER_EXTERNAL_AUTH_0_AUTH_URL="https://app.vssps.visualstudio.com/oauth2/authorize"
+CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://app.vssps.visualstudio.com/oauth2/token"
 ```
 
-## GitHub Enterprise
+### Azure DevOps (via Entra ID)
 
-GitHub Enterprise requires the following environment variables:
+Azure DevOps (via Entra ID) requires the following environment variables:
 
 ```env
-CODER_EXTERNAL_AUTH_0_ID="primary-github"
-CODER_EXTERNAL_AUTH_0_TYPE=github
+CODER_EXTERNAL_AUTH_0_ID="primary-azure-devops"
+CODER_EXTERNAL_AUTH_0_TYPE=azure-devops-entra
 CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
 CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
-CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://github.example.com/api/v3/user"
-CODER_EXTERNAL_AUTH_0_AUTH_URL="https://github.example.com/login/oauth/authorize"
-CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token"
+CODER_EXTERNAL_AUTH_0_AUTH_URL="https://login.microsoftonline.com/<TENANT ID>/oauth2/authorize"
 ```
 
-## Bitbucket Server
+> Note: Your app registration in Entra ID requires the `vso.code_write` scope
+
+### Bitbucket Server
 
 Bitbucket Server requires the following environment variables:
 
@@ -94,35 +104,50 @@ CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxx
 CODER_EXTERNAL_AUTH_0_AUTH_URL=https://bitbucket.domain.com/rest/oauth2/latest/authorize
 ```
 
-## Azure DevOps
+### Gitea
 
-Azure DevOps requires the following environment variables:
+```env
+CODER_EXTERNAL_AUTH_0_ID="gitea"
+CODER_EXTERNAL_AUTH_0_TYPE=gitea
+CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxxx
+CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
+# If self managed, set the Auth URL to your Gitea instance
+CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitea.com/login/oauth/authorize"
+```
+
+The Redirect URI for Gitea should be
+`https://coder.company.org/external-auth/gitea/callback`.
+
+### GitHub
+
+<blockquote class="admonition tip">
+
+If you don't require fine-grained access control, it's easier to [configure a GitHub OAuth app](#configure-a-github-oauth-app).
+
+</blockquote>
 
 ```env
-CODER_EXTERNAL_AUTH_0_ID="primary-azure-devops"
-CODER_EXTERNAL_AUTH_0_TYPE=azure-devops
+CODER_EXTERNAL_AUTH_0_ID="USER_DEFINED_ID"
+CODER_EXTERNAL_AUTH_0_TYPE=github
 CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
-# Ensure this value is your "Client Secret", not "App Secret"
 CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
-CODER_EXTERNAL_AUTH_0_AUTH_URL="https://app.vssps.visualstudio.com/oauth2/authorize"
-CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://app.vssps.visualstudio.com/oauth2/token"
 ```
 
-## Azure DevOps (via Entra ID)
+### GitHub Enterprise
 
-Azure DevOps (via Entra ID) requires the following environment variables:
+GitHub Enterprise requires the following environment variables:
 
 ```env
-CODER_EXTERNAL_AUTH_0_ID="primary-azure-devops"
-CODER_EXTERNAL_AUTH_0_TYPE=azure-devops-entra
+CODER_EXTERNAL_AUTH_0_ID="primary-github"
+CODER_EXTERNAL_AUTH_0_TYPE=github
 CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
 CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
-CODER_EXTERNAL_AUTH_0_AUTH_URL="https://login.microsoftonline.com/<TENANT ID>/oauth2/authorize"
+CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://github.example.com/api/v3/user"
+CODER_EXTERNAL_AUTH_0_AUTH_URL="https://github.example.com/login/oauth/authorize"
+CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token"
 ```
 
-> Note: Your app registration in Entra ID requires the `vso.code_write` scope
-
-## GitLab self-managed
+### GitLab self-managed
 
 GitLab self-managed requires the following environment variables:
 
@@ -138,21 +163,11 @@ CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.company.org/oauth/token"
 CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.company\.org
 ```
 
-## Gitea
-
-```env
-CODER_EXTERNAL_AUTH_0_ID="gitea"
-CODER_EXTERNAL_AUTH_0_TYPE=gitea
-CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxxx
-CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
-# If self managed, set the Auth URL to your Gitea instance
-CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitea.com/login/oauth/authorize"
-```
+### JFrog Artifactory
 
-The Redirect URI for Gitea should be
-`https://coder.company.org/external-auth/gitea/callback`.
+Visit the [JFrog Artifactory](../admin/integrations/jfrog-artifactory.md) guide for instructions on how to set up for JFrog Artifactory.
 
-## Self-managed git providers
+## Self-managed Git providers
 
 Custom authentication and token URLs should be used for self-managed Git
 provider deployments.
@@ -166,10 +181,6 @@ CODER_EXTERNAL_AUTH_0_REGEX=github\.company\.org
 
 > Note: The `REGEX` variable must be set if using a custom git domain.
 
-## JFrog Artifactory
-
-Visit the [JFrog Artifactory](../admin/integrations/jfrog-artifactory.md) guide for instructions on how to set up for JFrog Artifactory.
-
 ## Custom scopes
 
 Optionally, you can request custom scopes:
@@ -178,6 +189,39 @@ Optionally, you can request custom scopes:
 CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"
 ```
 
+## OAuth provider
+
+### 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)
+
+   - 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)
+
+1. Adjust the GitHub app permissions. You can use more or fewer permissions than
+   are listed here, this example allows users to clone
+   repositories:
+
+   ![Adjust GitHub App Permissions](../images/admin/github-app-permissions.png)
+
+   | Name          | Permission   | Description                                            |
+   |---------------|--------------|--------------------------------------------------------|
+   | Contents      | Read & Write | Grants access to code and commit statuses.             |
+   | Pull requests | Read & Write | Grants access to create and update pull requests.      |
+   | Workflows     | Read & Write | Grants access to update files in `.github/workflows/`. |
+   | Metadata      | Read-only    | Grants access to metadata written by GitHub Apps.      |
+   | Members       | Read-only    | Grants access to organization members and teams.       |
+
+1. Install the App for your organization. You may select a subset of
+   repositories to grant access to.
+
+   ![Install GitHub App](../images/admin/github-app-install.png)
+
 ## Multiple External Providers
 
 <blockquote class="info">
diff --git a/docs/admin/setup/index.md b/docs/admin/setup/index.md
@@ -52,7 +52,7 @@ a wildcard subdomain that resolves to Coder (e.g. `*.coder.example.com`).
 If you are providing TLS certificates directly to the Coder server, either
 
 1. Use a single certificate and key for both the root and wildcard domains.
-2. Configure multiple certificates and keys via
+1. Configure multiple certificates and keys via
    [`coder.tls.secretNames`](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
    in the Helm Chart, or
    [`--tls-cert-file`](../../reference/cli/server.md#--tls-cert-file) and
@@ -78,29 +78,27 @@ working directory prior to step 1.
 
 1. Create the TLS secret in your Kubernetes cluster
 
-```shell
-kubectl create secret tls coder-tls -n <coder-namespace> --key="tls.key" --cert="tls.crt"
-```
+   ```shell
+   kubectl create secret tls coder-tls -n <coder-namespace> --key="tls.key" --cert="tls.crt"
+   ```
 
-> You can use a single certificate for the both the access URL and wildcard
-> access URL. The certificate CN must match the wildcard domain, such as
-> `*.example.coder.com`.
+   You can use a single certificate for the both the access URL and wildcard access URL. The certificate CN must match the wildcard domain, such as `*.example.coder.com`.
 
 1. Reference the TLS secret in your Coder Helm chart values
 
-```yaml
-coder:
-  tls:
-    secretName:
-      - coder-tls
-
-  # Alternatively, if you use an Ingress controller to terminate TLS,
-  # set the following values:
-  ingress:
-    enable: true
-    secretName: coder-tls
-    wildcardSecretName: coder-tls
-```
+   ```yaml
+   coder:
+     tls:
+         secretName:
+         - coder-tls
+
+     # Alternatively, if you use an Ingress controller to terminate TLS,
+     # set the following values:
+     ingress:
+         enable: true
+         secretName: coder-tls
+         wildcardSecretName: coder-tls
+   ```
 
 ## PostgreSQL Database
 
@@ -116,7 +114,7 @@ the PostgreSQL interactive terminal), output the connection URL with the
 following command:
 
 ```console
-coder server postgres-builtin-url
+$ coder server postgres-builtin-url
 psql "postgres://coder@localhost:49627/coder?sslmode=disable&password=feU...yI1"
 ```
 
@@ -126,13 +124,13 @@ To migrate from the built-in database to an external database, follow these
 steps:
 
 1. Stop your Coder deployment.
-2. Run `coder server postgres-builtin-serve` in a background terminal.
-3. Run `coder server postgres-builtin-url` and copy its output command.
-4. Run `pg_dump <built-in-connection-string> > coder.sql` to dump the internal
+1. Run `coder server postgres-builtin-serve` in a background terminal.
+1. Run `coder server postgres-builtin-url` and copy its output command.
+1. Run `pg_dump <built-in-connection-string> > coder.sql` to dump the internal
    database to a file.
-5. Restore that content to an external database with
+1. Restore that content to an external database with
    `psql <external-connection-string> < coder.sql`.
-6. Start your Coder deployment with
+1. Start your Coder deployment with
    `CODER_PG_CONNECTION_URL=<external-connection-string>`.
 
 ## Configuring Coder behind a proxy
@@ -144,7 +142,7 @@ To configure Coder behind a corporate proxy, set the environment variables
 ## External Authentication
 
 Coder supports external authentication via OAuth2.0. This allows enabling
-integrations with git providers, such as GitHub, GitLab, and Bitbucket etc.
+integrations with Git providers, such as GitHub, GitLab, and Bitbucket.
 
 External authentication can also be used to integrate with external services
 like JFrog Artifactory and others.
@@ -154,5 +152,5 @@ more information.
 
 ## Up Next
 
-- [Learn how to setup and manage templates](../templates/index.md)
+- [Setup and manage templates](../templates/index.md)
 - [Setup external provisioners](../provisioners.md)
