mirror of https://github.com/coder/coder.git
chore(docs): make external auth docs easier to follow (#12970)
* add additional context to github external auth provider documentation * Apply suggestions from code review Co-authored-by: Kyle Carberry <kyle@carberry.com> * Update docs/admin/external-auth.md * fmt * fmt --------- Co-authored-by: Kyle Carberry <kyle@carberry.com>
This commit is contained in:
parent
3d7740bd32
commit
b40f54f603
|
@ -25,16 +25,12 @@ 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)
|
||||
|
||||
Example callback URL:
|
||||
`https://coder.example.com/external-auth/primary-github/callback`. Use an
|
||||
arbitrary ID for your provider (e.g. `primary-github`).
|
||||
|
||||
Set the following environment variables to
|
||||
[configure the Coder server](./configure.md):
|
||||
The next step is to [configure the Coder server](./configure.md) to use the
|
||||
OAuth application by setting the following environment variables:
|
||||
|
||||
```env
|
||||
CODER_EXTERNAL_AUTH_0_ID="primary-github"
|
||||
CODER_EXTERNAL_AUTH_0_TYPE=github|gitlab|azure-devops|bitbucket-cloud|bitbucket-server|<name of service e.g. jfrog>
|
||||
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
|
||||
|
||||
|
@ -43,11 +39,22 @@ 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).
|
||||
|
||||
### 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)
|
||||
to enable fine-grained access to specific repositories, or a subset of
|
||||
permissions for security.
|
||||
|
||||
- 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)
|
||||
|
||||
|
@ -69,6 +76,13 @@ CODER_EXTERNAL_AUTH_0_DISPLAY_ICON="https://mycustomicon.com/google.svg"
|
|||
|
||||
![Install GitHub App](../images/admin/github-app-install.png)
|
||||
|
||||
```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:
|
||||
|
@ -204,6 +218,50 @@ add this to the
|
|||
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
|
||||
|
|
Loading…
Reference in New Issue