synced/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2025-07-12 00:14:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add details on external authentication priority (#17164)

Browse Source 
## Issue

Closes #16875 

Clarify how Coder authentication works with Git providers, particularly
the order of authentication methods used.

## Changes Made

I've updated the External Authentication documentation to:

1. Clarify that Coder first attempts to use external auth provider
tokens when available, and only defaults to SSH authentication if no
tokens are available
2. Add more detailed explanations about both authentication methods
3. Improve the description of how the `coder gitssh` command works with
existing and Coder-generated SSH keys

## Verification

Claude verified that this accurately describes the behavior of the
codebase by reviewing the `gitssh.go` implementation, which shows how
Coder handles SSH authentication as a fallback when external auth is not
available.


[preview](https://coder.com/docs/@16875-git-workspace-auth/admin/external-auth)

<sub>🤖 Generated with https://claude.ai/code</sub>

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Co-authored-by: Ben Potter <me@bpmct.net>
Co-authored-by: M Atif Ali <atif@coder.com>
Co-authored-by: Bruno Quaresma <bruno@coder.com>
Co-authored-by: Kyle Carberry <kyle@coder.com>
Co-authored-by: Cian Johnston <cian@coder.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Jon Ayers <jon@coder.com>
Co-authored-by: Hugo Dutka <hugo@coder.com>
Co-authored-by: Ethan <39577870+ethanndickson@users.noreply.github.com>
Co-authored-by: Michael Smith <throwawayclover@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Sas Swart <sas.swart.cdk@gmail.com>
This commit is contained in:
Edward Angert
2025-04-09 11:16:00 -04:00
committed by GitHub
parent 3f3e2017bd
commit 109e73bf97
1 changed files with 49 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
docs/admin/external-auth.md
View File

@ -71,6 +71,55 @@ Use [`external-auth`](../reference/cli/external-auth.md) in the Coder CLI to acc
coder external-auth access-token <USER_DEFINED_ID>
```
## Git Authentication in Workspaces
Coder provides automatic Git authentication for workspaces through SSH authentication and Git-provider specific env variables.
When performing Git operations, Coder first attempts to use external auth provider tokens if available.
If no tokens are available, it defaults to SSH authentication.
### OAuth (external auth)
For Git providers configured with [external authentication](#configuration), Coder can use OAuth tokens for Git operations.
When Git operations require authentication, and no SSH key is configured, Coder will automatically use the appropriate external auth provider based on the repository URL.
For example, if you've configured a GitHub external auth provider and attempt to clone a GitHub repository, Coder will use the OAuth token from that provider for authentication.
To manually access these tokens within a workspace:
```shell
coder external-auth access-token <USER_DEFINED_ID>
```
### SSH Authentication
Coder automatically generates an SSH key pair for each user that can be used for Git operations.
When you use SSH URLs for Git repositories, for example, `git@github.com:organization/repo.git`, Coder checks for and uses an existing SSH key.
If one is not available, it uses the Coder-generated one.
The `coder gitssh` command wraps the standard `ssh` command and injects the SSH key during Git operations.
This works automatically when you:
1. Clone a repository using SSH URLs
1. Pull/push changes to remote repositories
1. Use any Git command that requires SSH authentication
You must add the SSH key to your Git provider.
#### Add your Coder SSH key to your Git provider
1. View your Coder Git SSH key:
```shell
coder publickey
```
1. Add the key to your Git provider accounts:
- [GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account#adding-a-new-ssh-key-to-your-account)
- [GitLab](https://docs.gitlab.com/user/ssh/#add-an-ssh-key-to-your-gitlab-account)
## Git-provider specific env variables
### Azure DevOps