From 2db695bc86e14877f2f50cd14854d27e4a931bfd Mon Sep 17 00:00:00 2001 From: Christopher Trent Date: Fri, 3 Jan 2025 07:08:50 -0800 Subject: [PATCH 01/11] docs: update external auth to better explain process (#15970) Reference #15968 Adds more information on how to add external auth, including docker-compose and docker CLI examples and terraform code for template integration. --------- Co-authored-by: Muhammad Atif Ali --- docs/admin/external-auth.md | 32 +++++++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index d859467aa6d7a..87b7e81121da0 100644 --- a/docs/admin/external-auth.md +++ b/docs/admin/external-auth.md @@ -12,21 +12,47 @@ application. The following providers are supported: The next step is to configure the Coder server to use the OAuth application by setting the following environment variables: +## Configuration + ```env CODER_EXTERNAL_AUTH_0_ID="" CODER_EXTERNAL_AUTH_0_TYPE= -CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx -CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx +CODER_EXTERNAL_AUTH_0_CLIENT_ID= +CODER_EXTERNAL_AUTH_0_CLIENT_SECRET= # 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). +You can now add the following code to any template. This will add a button to the workspace setup page which will allow you to authenticate with your provider. + +```tf +data "coder_external_auth" "" { + id = "" +} + +# Github Example (CODER_EXTERNAL_AUTH_0_ID="github-auth") +# makes a github authentication token available at data.coder_external_auth.github.access_token +data "coder_external_auth" "github" { + id = "github-auth" +} + +``` + +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. + +### Workspace CLI +An access token can be accessed within the workspace by using + +``` +coder external-auth access-token +``` + + ## GitHub > If you don't require fine-grained access control, it's easier to configure a From 096326d019523dccf71b680d5540ce675014e0f8 Mon Sep 17 00:00:00 2001 From: EdwardAngert Date: Fri, 3 Jan 2025 17:27:52 +0000 Subject: [PATCH 02/11] make lint/fmt --- docs/admin/external-auth.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index 9b7f32b36eedb..010a637348419 100644 --- a/docs/admin/external-auth.md +++ b/docs/admin/external-auth.md @@ -24,6 +24,7 @@ CODER_EXTERNAL_AUTH_0_CLIENT_SECRET= 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). @@ -32,7 +33,7 @@ You can now add the following code to any template. This will add a button to th ```tf data "coder_external_auth" "" { - id = "" + id = "" } # Github Example (CODER_EXTERNAL_AUTH_0_ID="github-auth") @@ -46,13 +47,13 @@ data "coder_external_auth" "github" { 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. ### Workspace CLI + An access token can be accessed within the workspace by using -``` +```shell coder external-auth access-token ``` - ## GitHub > If you don't require fine-grained access control, it's easier to configure a From 85b8e363cf4f066743bf97d7d545f0d432296d1f Mon Sep 17 00:00:00 2001 From: EdwardAngert Date: Fri, 3 Jan 2025 17:34:19 +0000 Subject: [PATCH 03/11] md alignment --- docs/admin/setup/index.md | 52 +++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 27 deletions(-) diff --git a/docs/admin/setup/index.md b/docs/admin/setup/index.md index 9429db6cfebac..c6c85ff02ec0c 100644 --- 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 --key="tls.key" --cert="tls.crt" -``` + ```shell + kubectl create secret tls coder-tls -n --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 @@ -115,7 +113,7 @@ If you are using the built-in PostgreSQL deployment and need to use `psql` (aka the PostgreSQL interactive terminal), output the connection URL with the following command: -```console +```shell 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 > 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 > 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 < coder.sql`. -6. Start your Coder deployment with +1. Start your Coder deployment with `CODER_PG_CONNECTION_URL=`. ## Configuring Coder behind a proxy @@ -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) From cc0939a15c6a1707036b4bbfc3e008876ff0c782 Mon Sep 17 00:00:00 2001 From: EdwardAngert Date: Fri, 3 Jan 2025 17:35:33 +0000 Subject: [PATCH 04/11] external-auth intro from setup/index --- docs/admin/external-auth.md | 6 ++++++ docs/admin/setup/index.md | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index 010a637348419..5104f22110859 100644 --- a/docs/admin/external-auth.md +++ b/docs/admin/external-auth.md @@ -1,5 +1,11 @@ # External Authentication +Coder supports external authentication via OAuth2.0. This allows enabling +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: diff --git a/docs/admin/setup/index.md b/docs/admin/setup/index.md index c6c85ff02ec0c..7300033e19f29 100644 --- a/docs/admin/setup/index.md +++ b/docs/admin/setup/index.md @@ -142,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. From e84811c0273b31ff2dbd7a38e2fe2748fe715139 Mon Sep 17 00:00:00 2001 From: EdwardAngert Date: Mon, 6 Jan 2025 18:50:24 +0000 Subject: [PATCH 05/11] abc git providers --- docs/admin/external-auth.md | 127 ++++++++++++++++++------------------ 1 file changed, 63 insertions(+), 64 deletions(-) diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index 1d286f0398824..61b9ece50f158 100644 --- a/docs/admin/external-auth.md +++ b/docs/admin/external-auth.md @@ -15,11 +15,10 @@ 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) -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="" CODER_EXTERNAL_AUTH_0_TYPE= @@ -35,7 +34,7 @@ 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). -You can now add the following code to any template. This will add a button to the workspace setup page which will allow you to authenticate with your provider. +You can now add the following code to any template. This will add a button to the workspace setup page which will allow you to authenticate with your provider: ```tf data "coder_external_auth" "" { @@ -50,7 +49,7 @@ data "coder_external_auth" "github" { ``` -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. +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. ### Workspace CLI @@ -60,6 +59,60 @@ An access token can be accessed within the workspace by using coder external-auth access-token ``` +## 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//oauth2/authorize" +``` + +> Note: Your app registration in Entra ID requires the `vso.code_write` scope + +## 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 +``` + +## 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`. + ## GitHub > If you don't require fine-grained access control, it's easier to configure a @@ -75,8 +128,8 @@ coder external-auth access-token ![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 +2. 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) @@ -115,46 +168,6 @@ 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//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: @@ -171,21 +184,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. @@ -199,10 +202,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: From b1f32b5f32a722100c434231458a407a6568e5a0 Mon Sep 17 00:00:00 2001 From: EdwardAngert Date: Mon, 6 Jan 2025 19:22:26 +0000 Subject: [PATCH 06/11] git providers to tabs --- docs/admin/external-auth.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index 61b9ece50f158..758498b7267e2 100644 --- a/docs/admin/external-auth.md +++ b/docs/admin/external-auth.md @@ -59,7 +59,11 @@ An access token can be accessed within the workspace by using coder external-auth access-token ``` -## Azure DevOps +## Git-provider specific env variables + +
+ +### Azure DevOps Azure DevOps requires the following environment variables: @@ -73,7 +77,7 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://app.vssps.visualstudio.com/oauth2/author CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://app.vssps.visualstudio.com/oauth2/token" ``` -## Azure DevOps (via Entra ID) +### Azure DevOps (via Entra ID) Azure DevOps (via Entra ID) requires the following environment variables: @@ -87,7 +91,7 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://login.microsoftonline.com//oa > Note: Your app registration in Entra ID requires the `vso.code_write` scope -## Bitbucket Server +### Bitbucket Server Bitbucket Server requires the following environment variables: @@ -99,7 +103,7 @@ CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxx CODER_EXTERNAL_AUTH_0_AUTH_URL=https://bitbucket.domain.com/rest/oauth2/latest/authorize ``` -## Gitea +### Gitea ```env CODER_EXTERNAL_AUTH_0_ID="gitea" @@ -113,7 +117,7 @@ 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 +### GitHub > If you don't require fine-grained access control, it's easier to configure a > GitHub OAuth app! @@ -154,7 +158,7 @@ CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx ``` -## GitHub Enterprise +### GitHub Enterprise GitHub Enterprise requires the following environment variables: @@ -168,7 +172,7 @@ 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" ``` -## GitLab self-managed +### GitLab self-managed GitLab self-managed requires the following environment variables: @@ -184,11 +188,11 @@ CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.company.org/oauth/token" CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.company\.org ``` -## JFrog Artifactory +### JFrog Artifactory 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. @@ -202,6 +206,8 @@ CODER_EXTERNAL_AUTH_0_REGEX=github\.company\.org > Note: The `REGEX` variable must be set if using a custom git domain. +
+ ## Custom scopes Optionally, you can request custom scopes: From 1af84ed03e2a294c7f1bbe70c5c8acb07f040907 Mon Sep 17 00:00:00 2001 From: EdwardAngert Date: Mon, 6 Jan 2025 19:29:32 +0000 Subject: [PATCH 07/11] Revert "git providers to tabs" This reverts commit b1f32b5f32a722100c434231458a407a6568e5a0. --- docs/admin/external-auth.md | 24 +++++++++--------------- 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index 758498b7267e2..61b9ece50f158 100644 --- a/docs/admin/external-auth.md +++ b/docs/admin/external-auth.md @@ -59,11 +59,7 @@ An access token can be accessed within the workspace by using coder external-auth access-token ``` -## Git-provider specific env variables - -
- -### Azure DevOps +## Azure DevOps Azure DevOps requires the following environment variables: @@ -77,7 +73,7 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://app.vssps.visualstudio.com/oauth2/author CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://app.vssps.visualstudio.com/oauth2/token" ``` -### Azure DevOps (via Entra ID) +## Azure DevOps (via Entra ID) Azure DevOps (via Entra ID) requires the following environment variables: @@ -91,7 +87,7 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://login.microsoftonline.com//oa > Note: Your app registration in Entra ID requires the `vso.code_write` scope -### Bitbucket Server +## Bitbucket Server Bitbucket Server requires the following environment variables: @@ -103,7 +99,7 @@ CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxx CODER_EXTERNAL_AUTH_0_AUTH_URL=https://bitbucket.domain.com/rest/oauth2/latest/authorize ``` -### Gitea +## Gitea ```env CODER_EXTERNAL_AUTH_0_ID="gitea" @@ -117,7 +113,7 @@ 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 +## GitHub > If you don't require fine-grained access control, it's easier to configure a > GitHub OAuth app! @@ -158,7 +154,7 @@ CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx ``` -### GitHub Enterprise +## GitHub Enterprise GitHub Enterprise requires the following environment variables: @@ -172,7 +168,7 @@ 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" ``` -### GitLab self-managed +## GitLab self-managed GitLab self-managed requires the following environment variables: @@ -188,11 +184,11 @@ CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.company.org/oauth/token" CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.company\.org ``` -### JFrog Artifactory +## JFrog Artifactory 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. @@ -206,8 +202,6 @@ CODER_EXTERNAL_AUTH_0_REGEX=github\.company\.org > Note: The `REGEX` variable must be set if using a custom git domain. -
- ## Custom scopes Optionally, you can request custom scopes: From 178245435dd3e528bf2ab30380a645a00b0483b8 Mon Sep 17 00:00:00 2001 From: EdwardAngert Date: Mon, 6 Jan 2025 19:58:50 +0000 Subject: [PATCH 08/11] parent heading to git providers --- docs/admin/external-auth.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index 61b9ece50f158..2e351b1028827 100644 --- a/docs/admin/external-auth.md +++ b/docs/admin/external-auth.md @@ -59,7 +59,9 @@ An access token can be accessed within the workspace by using coder external-auth access-token ``` -## Azure DevOps +## Git-provider specific env variables + +### Azure DevOps Azure DevOps requires the following environment variables: @@ -73,7 +75,7 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://app.vssps.visualstudio.com/oauth2/author CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://app.vssps.visualstudio.com/oauth2/token" ``` -## Azure DevOps (via Entra ID) +### Azure DevOps (via Entra ID) Azure DevOps (via Entra ID) requires the following environment variables: @@ -87,7 +89,7 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://login.microsoftonline.com//oa > Note: Your app registration in Entra ID requires the `vso.code_write` scope -## Bitbucket Server +### Bitbucket Server Bitbucket Server requires the following environment variables: @@ -99,7 +101,7 @@ CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxx CODER_EXTERNAL_AUTH_0_AUTH_URL=https://bitbucket.domain.com/rest/oauth2/latest/authorize ``` -## Gitea +### Gitea ```env CODER_EXTERNAL_AUTH_0_ID="gitea" @@ -113,7 +115,7 @@ 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 +### GitHub > If you don't require fine-grained access control, it's easier to configure a > GitHub OAuth app! @@ -154,7 +156,7 @@ CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx ``` -## GitHub Enterprise +### GitHub Enterprise GitHub Enterprise requires the following environment variables: @@ -168,7 +170,7 @@ 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" ``` -## GitLab self-managed +### GitLab self-managed GitLab self-managed requires the following environment variables: @@ -184,7 +186,7 @@ CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.company.org/oauth/token" CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.company\.org ``` -## JFrog Artifactory +### JFrog Artifactory Visit the [JFrog Artifactory](../admin/integrations/jfrog-artifactory.md) guide for instructions on how to set up for JFrog Artifactory. From db03ea0f903d01735ac93a99ea1a31e320f0151c Mon Sep 17 00:00:00 2001 From: EdwardAngert Date: Mon, 6 Jan 2025 21:27:34 +0000 Subject: [PATCH 09/11] highlight oauth provider in intro --- docs/admin/external-auth.md | 72 ++++++++++++++++++++----------------- 1 file changed, 39 insertions(+), 33 deletions(-) diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index 2e351b1028827..35dd48dc9b1d7 100644 --- a/docs/admin/external-auth.md +++ b/docs/admin/external-auth.md @@ -1,7 +1,6 @@ # External Authentication -Coder supports external authentication via OAuth2.0. This allows enabling -integrations with Git providers, such as GitHub, GitLab, and Bitbucket. +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. @@ -34,7 +33,7 @@ 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). -You can now add the following code to any template. This will add a button to the workspace setup page which will allow you to authenticate with your provider: +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: ```tf data "coder_external_auth" "" { @@ -53,7 +52,7 @@ Inside your Terraform code, you now have access to authentication variables. Ref ### Workspace CLI -An access token can be accessed within the workspace by using +Use `coder external-auth` to access a token within the workspace: ```shell coder external-auth access-token @@ -117,37 +116,11 @@ The Redirect URI for Gitea should be ### 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 fewer permissions than - are listed here, this example allows users to clone - repositories: - - ![Adjust GitHub App Permissions](../images/admin/github-app-permissions.png) +If you don't require fine-grained access control, it's easier to [configure a GitHub OAuth app](#configure-a-github-oauth-app). - | 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. | - -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" @@ -212,6 +185,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
From 30a4221aad1834dd3742a5d0dd0b109c0505cbc1 Mon Sep 17 00:00:00 2001 From: EdwardAngert Date: Tue, 7 Jan 2025 19:31:41 +0000 Subject: [PATCH 10/11] inc suggestions from review --- docs/admin/external-auth.md | 13 ++++++++----- docs/admin/setup/index.md | 4 ++-- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index 35dd48dc9b1d7..1e2772922c2c8 100644 --- a/docs/admin/external-auth.md +++ b/docs/admin/external-auth.md @@ -6,13 +6,16 @@ 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) ## Configuration @@ -52,7 +55,7 @@ Inside your Terraform code, you now have access to authentication variables. Ref ### Workspace CLI -Use `coder external-auth` to access a token within the workspace: +Use [`external-auth`](../reference/cli/external-auth.md) in the Coder CLI to access a token within the workspace: ```shell coder external-auth access-token diff --git a/docs/admin/setup/index.md b/docs/admin/setup/index.md index 7300033e19f29..9af914125a75e 100644 --- a/docs/admin/setup/index.md +++ b/docs/admin/setup/index.md @@ -113,8 +113,8 @@ If you are using the built-in PostgreSQL deployment and need to use `psql` (aka the PostgreSQL interactive terminal), output the connection URL with the following command: -```shell -coder server postgres-builtin-url +```console +$ coder server postgres-builtin-url psql "postgres://coder@localhost:49627/coder?sslmode=disable&password=feU...yI1" ``` From 411fb432b6d87696bdb3c44cdaa409233b1e0657 Mon Sep 17 00:00:00 2001 From: EdwardAngert Date: Tue, 7 Jan 2025 20:02:20 +0000 Subject: [PATCH 11/11] add issue link and align example variables --- docs/admin/external-auth.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index 1e2772922c2c8..ee6510d751a44 100644 --- a/docs/admin/external-auth.md +++ b/docs/admin/external-auth.md @@ -1,6 +1,7 @@ # 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. +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. @@ -14,8 +15,8 @@ application. The following providers have been tested and work with Coder: - [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) +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) ## Configuration @@ -27,26 +28,26 @@ CODER_EXTERNAL_AUTH_0_TYPE= CODER_EXTERNAL_AUTH_0_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. 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: ```tf -data "coder_external_auth" "" { +data "coder_external_auth" "" { id = "" } -# Github Example (CODER_EXTERNAL_AUTH_0_ID="github-auth") -# makes a github authentication token available at data.coder_external_auth.github.access_token +# 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 = "github-auth" + id = "primary-github" } ```