mirror of
https://github.com/coder/coder.git
synced 2025-07-13 21:36:50 +00:00
docs: restructure docs (#14421)
Closes #13434 Supersedes #14182 --------- Co-authored-by: Ethan <39577870+ethanndickson@users.noreply.github.com> Co-authored-by: Ethan Dickson <ethan@coder.com> Co-authored-by: Ben Potter <ben@coder.com> Co-authored-by: Stephen Kirby <58410745+stirby@users.noreply.github.com> Co-authored-by: Stephen Kirby <me@skirby.dev> Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
This commit is contained in:
Muhammad Atif Ali
committed by
GitHub
GitHub
parent
288df75686
commit
419eba5fb6
@ -1,21 +1,5 @@
|
||||
# External Authentication
|
||||
|
||||
Coder integrates with Git and OpenID Connect to automate away the need for
|
||||
developers to authenticate with external services within their workspace.
|
||||
|
||||
## Git Providers
|
||||
|
||||
When developers use `git` inside their workspace, they are prompted to
|
||||
authenticate. After that, Coder will store and refresh tokens for future
|
||||
operations.
|
||||
|
||||
<video autoplay playsinline loop>
|
||||
<source src="https://github.com/coder/coder/blob/main/site/static/external-auth.mp4?raw=true" type="video/mp4">
|
||||
Your browser does not support the video tag.
|
||||
</video>
|
||||
|
||||
## Configuration
|
||||
|
||||
To add an external authentication provider, you'll need to create an OAuth
|
||||
application. The following providers are supported:
|
||||
|
||||
@ -25,8 +9,8 @@ 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](./configure.md) to use the
|
||||
OAuth application by setting the following environment variables:
|
||||
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>"
|
||||
@ -43,7 +27,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).
|
||||
|
||||
### GitHub
|
||||
## GitHub
|
||||
|
||||
> If you don't require fine-grained access control, it's easier to configure a
|
||||
> GitHub OAuth app!
|
||||
@ -84,7 +68,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:
|
||||
|
||||
@ -98,7 +82,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"
|
||||
```
|
||||
|
||||
### Bitbucket Server
|
||||
## Bitbucket Server
|
||||
|
||||
Bitbucket Server requires the following environment variables:
|
||||
|
||||
@ -110,7 +94,7 @@ 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:
|
||||
|
||||
@ -124,7 +108,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:
|
||||
|
||||
@ -138,7 +122,7 @@ 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
|
||||
## GitLab self-managed
|
||||
|
||||
GitLab self-managed requires the following environment variables:
|
||||
|
||||
@ -154,7 +138,7 @@ CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.company.org/oauth/token"
|
||||
CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.company\.org
|
||||
```
|
||||
|
||||
### Gitea
|
||||
## Gitea
|
||||
|
||||
```env
|
||||
CODER_EXTERNAL_AUTH_0_ID="gitea"
|
||||
@ -168,7 +152,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
|
||||
|
||||
### Self-managed git providers
|
||||
## Self-managed git providers
|
||||
|
||||
Custom authentication and token URLs should be used for self-managed Git
|
||||
provider deployments.
|
||||
@ -182,12 +166,12 @@ CODER_EXTERNAL_AUTH_0_REGEX=github\.company\.org
|
||||
|
||||
> Note: The `REGEX` variable must be set if using a custom git domain.
|
||||
|
||||
### JFrog Artifactory
|
||||
## JFrog Artifactory
|
||||
|
||||
See [this](https://coder.com/docs/guides/artifactory-integration#jfrog-oauth)
|
||||
guide on instructions on how to set up for JFrog Artifactory.
|
||||
See [this](../admin/integrations/jfrog-artifactory.md) guide on instructions on
|
||||
how to set up for JFrog Artifactory.
|
||||
|
||||
### Custom scopes
|
||||
## Custom scopes
|
||||
|
||||
Optionally, you can request custom scopes:
|
||||
|
||||
@ -195,10 +179,11 @@ Optionally, you can request custom scopes:
|
||||
CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"
|
||||
```
|
||||
|
||||
### Multiple External Providers (enterprise) (premium)
|
||||
## Multiple External Providers (enterprise) (premium)
|
||||
|
||||
Multiple providers are an [Enterprise feature](https://coder.com/pricing). Below
|
||||
is an example configuration with multiple providers.
|
||||
Multiple providers are an Enterprise feature.
|
||||
[Learn more](https://coder.com/pricing#compare-plans). Below is an example
|
||||
configuration with multiple providers.
|
||||
|
||||
```env
|
||||
# Provider 1) github.com
|
||||
@ -206,7 +191,7 @@ 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
|
||||
CODER_EXTERNAL_AUTH_0_REGEX=github.com/org
|
||||
|
||||
# Provider 2) github.example.com
|
||||
CODER_EXTERNAL_AUTH_1_ID=secondary-github
|
||||
@ -219,128 +204,10 @@ CODER_EXTERNAL_AUTH_1_TOKEN_URL="https://github.example.com/login/oauth/access_t
|
||||
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
|
||||
To support regex matching for paths (e.g. github.com/org), 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.
|
||||
|
||||
## Require git authentication in templates
|
||||
|
||||
If your template requires git authentication (e.g. running `git clone` in the
|
||||
[startup_script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script)),
|
||||
you can require users authenticate via git prior to creating a workspace:
|
||||
|
||||
|
||||
|
||||
### Native git authentication will auto-refresh tokens
|
||||
|
||||
<blockquote class="info">
|
||||
<p>
|
||||
This is the preferred authentication method.
|
||||
</p>
|
||||
</blockquote>
|
||||
|
||||
By default, the coder agent will configure native `git` authentication via the
|
||||
`GIT_ASKPASS` environment variable. Meaning, with no additional configuration,
|
||||
external authentication will work with native `git` commands.
|
||||
|
||||
To check the auth token being used **from inside a running workspace**, run:
|
||||
|
||||
```shell
|
||||
# If the exit code is non-zero, then the user is not authenticated with the
|
||||
# external provider.
|
||||
coder external-auth access-token <external-auth-id>
|
||||
```
|
||||
|
||||
Note: Some IDE's override the `GIT_ASKPASS` environment variable and need to be
|
||||
configured.
|
||||
|
||||
**VSCode**
|
||||
|
||||
Use the
|
||||
[Coder](https://marketplace.visualstudio.com/items?itemName=coder.coder-remote)
|
||||
extension to automatically configure these settings for you!
|
||||
|
||||
Otherwise, you can manually configure the following settings:
|
||||
|
||||
- Set `git.terminalAuthentication` to `false`
|
||||
- Set `git.useIntegratedAskPass` to `false`
|
||||
|
||||
### Hard coded tokens do not auto-refresh
|
||||
|
||||
If the token is required to be inserted into the workspace, for example
|
||||
[GitHub cli](https://cli.github.com/), the auth token can be inserted from the
|
||||
template. This token will not auto-refresh. The following example will
|
||||
authenticate via GitHub and auto-clone a repo into the `~/coder` directory.
|
||||
|
||||
```hcl
|
||||
data "coder_external_auth" "github" {
|
||||
# Matches the ID of the external auth provider in Coder.
|
||||
id = "github"
|
||||
}
|
||||
|
||||
resource "coder_agent" "dev" {
|
||||
os = "linux"
|
||||
arch = "amd64"
|
||||
dir = "~/coder"
|
||||
env = {
|
||||
GITHUB_TOKEN : data.coder_external_auth.github.access_token
|
||||
}
|
||||
startup_script = <<EOF
|
||||
if [ ! -d ~/coder ]; then
|
||||
git clone https://github.com/coder/coder
|
||||
fi
|
||||
EOF
|
||||
}
|
||||
```
|
||||
|
||||
See the
|
||||
[Terraform provider documentation](https://registry.terraform.io/providers/coder/coder/latest/docs/data-sources/external_auth)
|
||||
for all available options.
|
||||
|
||||
Reference in New Issue
Block a user