wip

coder · matifali · May 22, 2024 · May 23, 2024 · May 23, 2024 · May 23, 2024
commit 579778e91e6068a81afdc0e440c4acb44e7c99ea
diff --git a/docs/admin/configure.md b/docs/admin/configure.md
@@ -187,6 +187,263 @@ To configure Coder behind a corporate proxy, set the environment variables
 `HTTP_PROXY` and `HTTPS_PROXY`. Be sure to restart the server. Lowercase values
 (e.g. `http_proxy`) are also respected in this case.
 
+## External Authentication
+
+To add an external authentication provider, you'll need to create an OAuth
+application. The following providers are supported:
+
+- [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)
+
+The next step is to configure the Coder server to use the OAuth application by
+setting the following environment variables:
+
+```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
+
+# 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).
+
+### 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)
+
+   - 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)
+
+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:
+
+   ![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       | Rad-only     | Grabts access to organization members and teams.       |
+
+3. 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)
+
+```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:
+
+```env
+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_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"
+```
+
+### Bitbucket Server
+
+Bitbucket Server requires the following environment variables:
+
+```env
+CODER_EXTERNAL_AUTH_0_ID="primary-bitbucket-server"
+CODER_EXTERNAL_AUTH_0_TYPE=bitbucket-server
+CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxx
+CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxx
+CODER_EXTERNAL_AUTH_0_AUTH_URL=https://bitbucket.domain.com/rest/oauth2/latest/authorize
+```
+
+### Azure DevOps
+
+Azure DevOps requires the following environment variables:
+
+```env
+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"
+```
+
+### Azure DevOps (via Entra ID)
+
+Azure DevOps (via Entra ID) 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_CLIENT_ID=xxxxxx
+CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
+CODER_EXTERNAL_AUTH_0_AUTH_URL="https://login.microsoftonline.com/<TENANT ID>/oauth2/authorize"
+```
+
+> Note: Your app registration in Entra ID requires the `vso.code_write` scope
+
+### GitLab self-managed
+
+GitLab self-managed requires the following environment variables:
+
+```env
+CODER_EXTERNAL_AUTH_0_ID="primary-gitlab"
+CODER_EXTERNAL_AUTH_0_TYPE=gitlab
+# This value is the "Application ID"
+CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
+CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
+CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://gitlab.company.org/oauth/token/info"
+CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitlab.company.org/oauth/authorize"
+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"
+```
+
+The Redirect URI for Gitea should be
+https://coder.company.org/external-auth/gitea/callback
+
+### Self-managed git providers
+
+Custom authentication and token URLs should be used for self-managed Git
+provider deployments.
+
+```env
+CODER_EXTERNAL_AUTH_0_AUTH_URL="https://github.example.com/oauth/authorize"
+CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/oauth/token"
+CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://your-domain.com/oauth/token/info"
+CODER_EXTERNAL_AUTH_0_REGEX=github\.company\.org
+```
+
+> Note: The `REGEX` variable must be set if using a custom git domain.
+
+### JFrog Artifactory
+
+See [this](../admin/integrations/jfrog-artifactory.md) guide on instructions on
+how to set up for JFrog Artifactory.
+
+### Custom scopes
+
+Optionally, you can request custom scopes:
+
+```env
+CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"
+```
+
+### Multiple External Providers (enterprise)
+
+Multiple providers are an Enterprise feature. [Learn more](../enterprise.md).
+Below is an example configuration with multiple providers.
+
+```env
+# Provider 1) github.com
+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_REGEX=github.com/orgname
+
+# Provider 2) github.example.com
+CODER_EXTERNAL_AUTH_1_ID=secondary-github
+CODER_EXTERNAL_AUTH_1_TYPE=github
+CODER_EXTERNAL_AUTH_1_CLIENT_ID=xxxxxx
+CODER_EXTERNAL_AUTH_1_CLIENT_SECRET=xxxxxxx
+CODER_EXTERNAL_AUTH_1_REGEX=github.example.com
+CODER_EXTERNAL_AUTH_1_AUTH_URL="https://github.example.com/login/oauth/authorize"
+CODER_EXTERNAL_AUTH_1_TOKEN_URL="https://github.example.com/login/oauth/access_token"
+CODER_EXTERNAL_AUTH_1_VALIDATE_URL="https://github.example.com/api/v3/user"
+```
+
+To support regex matching for paths (e.g. github.com/orgname), you'll need to
+add this to the
+[Coder agent startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script):
+
+```shell
+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.
+
 ## Up Next
 
 - [Learn how to upgrade Coder](./upgrade.md).
diff --git a/docs/admin/integrations/README.md b/docs/admin/integrations/README.md
@@ -7,11 +7,14 @@ workspaces can include any Terraform resource. See our
 
 You can host your deployment on almost any infrastructure. To learn how, read our [installation guides](../../install/README.md).
 
-The following resources may help as you're deploying Coder.
+<children></children>
 
-- [Deploy workspaces on multiple Kubernetes Clusters](./multiple-kube-clusters.md)
+<!-- - [Deploy workspaces on multiple Kubernetes Clusters](./multiple-kube-clusters.md)
 - [Get workspace build logs from Kubernetes](./kubernetes-logs.md)
-- [Track deployment metrics with Prometheus](./prometheus.md)
+- [Track deployment metrics with Prometheus](./prometheus.md) -->
+
+The following resources may help as you're deploying Coder.
+
 - [Coder packages: one-click install on cloud providers](https://github.com/coder/packages)
 - [Deploy Coder offline](../../install/offline.md)
 - [Supported resources (Terraform registry)](https://registry.terraform.io)

diff --git a/docs/admin/templates/README.md b/docs/admin/templates/README.md
@@ -21,9 +21,9 @@ After learning the basics, use starter templates to import a template with sensi
 
 It's often necessary to extend the template to make it generally useful to end users. Common modifications are:
 
-- Your image(s) (e.g. a Docker image with languages and tools installed)
-- Additional parameters (e.g. disk size, instance type, or region)
-- Additional IDEs (e.g. JetBrains) or features (e.g. dotfiles, RDP)
+- Your image(s) (e.g. a Docker image with languages and tools installed). Docs: [Image management](./extending-templates/image-management.md).
+- Additional parameters (e.g. disk size, instance type, or region). Docs: [Template parameters](./extending-templates/parameters.md).
+- Additional IDEs (e.g. JetBrains) or features (e.g. dotfiles, RDP). Docs: [Adding IDEs and features](./extending-templates/ides/README.md).
 
 Learn more about the various ways you can [extend your templates](./extending-templates.md).
 

diff --git a/docs/admin/templates/extending-templates/README.md b/docs/admin/templates/extending-templates/README.md
@@ -37,6 +37,16 @@ Template resources follow the [behavior of Terraform resources](https://develope
 
 A common configuration is a template whose only persistent resource is the home directory. This allows the developer to retain their work while ensuring the rest of their environment is consistently up-to-date on each workspace restart.
 
+When a workspace is deleted, the Coder server essentially runs a
+[terraform destroy](https://www.terraform.io/cli/commands/destroy) to remove all
+resources associated with the workspace.
+
+> Terraform's
+> [prevent-destroy](https://www.terraform.io/language/meta-arguments/lifecycle#prevent_destroy)
+> and
+> [ignore-changes](https://www.terraform.io/language/meta-arguments/lifecycle#ignore_changes)
+> meta-arguments can be used to prevent accidental data loss.
+
 ## Coder apps
 
 Additional IDEs, documentation, or services can be associated to your workspace using the [`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app) resource.
@@ -47,6 +57,4 @@ Note that some apps are associated to the agent by default as [`display_apps`](h
 
 Check out our [module registry](https://registry.coder.com/modules) for additional Coder apps from the team and our OSS community.
 
-<children>
-
-</children>
+<children></children>