diff --git a/docs/admin/external-auth.md b/docs/admin/external-auth.md index bbb479ecf2d00..ee6510d751a44 100644 --- 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="" 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 +# 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" "" { + 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 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//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 + +
+ +If you don't require fine-grained access control, it's easier to [configure a GitHub OAuth app](#configure-a-github-oauth-app). + +
```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//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
diff --git a/docs/admin/setup/index.md b/docs/admin/setup/index.md index 9429db6cfebac..9af914125a75e 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 @@ -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 > 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 @@ -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)