mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +08:00
docs: update external auth to better explain process (#16027)
- adds to @ChristopherJTrent's PR #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>
This commit is contained in:
Edward Angert
co-authored by
Christopher Trent
Muhammad Atif Ali
Christopher Trent
Muhammad Atif Ali
parent
8fb7832b27
commit
ee1829ba71
+132
-88
@@ -1,100 +1,70 @@
|
||||
# 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)
|
||||
|
||||
The next step is to configure the Coder server to use the OAuth application by
|
||||
setting the following environment variables:
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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:
|
||||
|
||||
|
||||
|
||||
| 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.
|
||||
|
||||
|
||||
|
||||
```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
|
||||
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.
|
||||
|
||||
GitHub Enterprise requires the following environment variables:
|
||||
### Workspace CLI
|
||||
|
||||
```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"
|
||||
Use [`external-auth`](../reference/cli/external-auth.md) in the Coder CLI to access a token within the workspace:
|
||||
|
||||
```shell
|
||||
coder external-auth <USER_DEFINED_ID> access-token
|
||||
```
|
||||
|
||||
## Bitbucket Server
|
||||
## Git-provider specific env variables
|
||||
|
||||
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
|
||||
|
||||
Azure DevOps requires the following environment variables:
|
||||
|
||||
@@ -108,7 +78,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:
|
||||
|
||||
@@ -122,7 +92,62 @@ CODER_EXTERNAL_AUTH_0_AUTH_URL="https://login.microsoftonline.com/<TENANT ID>/oa
|
||||
|
||||
> Note: Your app registration in Entra ID requires the `vso.code_write` scope
|
||||
|
||||
## GitLab self-managed
|
||||
### 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
|
||||
|
||||
<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="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"
|
||||
```
|
||||
|
||||
### 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
|
||||
### JFrog Artifactory
|
||||
|
||||
```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"
|
||||
```
|
||||
Visit the [JFrog Artifactory](../admin/integrations/jfrog-artifactory.md) guide for instructions on how to set up for JFrog Artifactory.
|
||||
|
||||
The Redirect URI for Gitea should be
|
||||
`https://coder.company.org/external-auth/gitea/callback`.
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
1. Adjust the GitHub app permissions. You can use more or fewer permissions than
|
||||
are listed here, this example allows users to clone
|
||||
repositories:
|
||||
|
||||
|
||||
|
||||
| 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.
|
||||
|
||||
|
||||
|
||||
## Multiple External Providers
|
||||
|
||||
<blockquote class="info">
|
||||
|
||||
+25
-27
@@ -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
|
||||
```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
|
||||
```
|
||||
# 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)
|
||||
|
||||
Reference in New Issue
Block a user