8000 wip · coder/coder@579778e · GitHub
[go: up one dir, main page]
Skip to content

Commit 579778e

Browse files
matifalimatifali
committed
wip
1 parent ad16573 commit 579778e

File tree

Collapse file tree

15 files changed

+587
-100
lines changed

15 files changed

+587
-100
lines changed

‎docs/admin/configure.md

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -187,6 +187,263 @@ To configure Coder behind a corporate proxy, set the environment variables
187187
`HTTP_PROXY` and `HTTPS_PROXY`. Be sure to restart the server. Lowercase values
188188
(e.g. `http_proxy`) are also respected in this case.
189189

190+
## External Authentication
191+
192+
To add an external authentication provider, you'll need to create an OAuth
193+
application. The following providers are supported:
194+
195+
- [GitHub](#github)
196+
- [GitLab](https://docs.gitlab.com/ee/integration/oauth_provider.html)
197+
- [BitBucket](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/)
198+
- [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/oauth?view=azure-devops)
199+
- [Azure DevOps (via Entra ID)](https://learn.microsoft.com/en-us/entra/architecture/auth-oauth2)
200+
201+
The next step is to configure the Coder server to use the OAuth application by
202+
setting the following environment variables:
203+
204+
```env
205+
CODER_EXTERNAL_AUTH_0_ID="<USER_DEFINED_ID>"
206+
CODER_EXTERNAL_AUTH_0_TYPE=<github|gitlab|azure-devops|bitbucket-cloud|bitbucket-server|etc>
207+
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
208+
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
209+
210+
# Optionally, configure a custom display name and icon
211+
CODER_EXTERNAL_AUTH_0_DISPLAY_NAME="Google Calendar"
212+
CODER_EXTERNAL_AUTH_0_DISPLAY_ICON="https://mycustomicon.com/google.svg"
213+
```
214+
215+
The `CODER_EXTERNAL_AUTH_0_ID` environment variable is used for internal
216+
reference. Therefore, it can be set arbitrarily (e.g., `primary-github` for your
217+
GitHub provider).
218+
219+
### GitHub
220+
221+
> If you don't require fine-grained access control, it's easier to configure a
222+
> GitHub OAuth app!
223+
224+
1. [Create a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)
225+
226+
- Set the callback URL to
227+
`https://coder.example.com/external-auth/USER_DEFINED_ID/callback`.
228+
- Deactivate Webhooks.
229+
- Enable fine-grained access to specific repositories or a subset of
230+
permissions for security.
231+
232+
![Register GitHub App](../images/admin/github-app-register.png)
233+
234+
2. Adjust the GitHub App permissions. You can use more or less permissions than
235+
are listed here, this is merely a suggestion that allows users to clone
236+
repositories:
237+
238+
![Adjust GitHub App Permissions](../images/admin/github-app-permissions.png)
239+
240+
| Name | Permission | Description |
241+
| ------------- | ------------ | ------------------------------------------------------ |
242+
| Contents | Read & Write | Grants access to code and commit statuses. |
243+
| Pull requests | Read & Write | Grants access to create and update pull requests. |
244+
| Workflows | Read & Write | Grants access to update files in `.github/workflows/`. |
245+
| Metadata | Read-only | Grants access to metadata written by GitHub Apps. |
246+
| Members | Rad-only | Grabts access to organization members and teams. |
247+
248+
3. Install the App for your organization. You may select a subset of
249+
repositories to grant access to.
250+
251+
![Install GitHub App](../images/admin/github-app-install.png)
252+
253+
```env
254+
CODER_EXTERNAL_AUTH_0_ID="USER_DEFINED_ID"
255+
CODER_EXTERNAL_AUTH_0_TYPE=github
256+
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
257+
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
258+
```
259+
260+
### GitHub Enterprise
261+
262+
GitHub Enterprise requires the following environment variables:
263+
264+
```env
265+
CODER_EXTERNAL_AUTH_0_ID="primary-github"
266+
CODER_EXTERNAL_AUTH_0_TYPE=github
267+
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
268+
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
269+
CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://github.example.com/api/v3/user"
270+
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://github.example.com/login/oauth/authorize"
271+
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/login/oauth/access_token"
272+
```
273+
274+
### Bitbucket Server
275+
276+
Bitbucket Server requires the following environment variables:
277+
278+
```env
279+
CODER_EXTERNAL_AUTH_0_ID="primary-bitbucket-server"
280+
CODER_EXTERNAL_AUTH_0_TYPE=bitbucket-server
281+
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxx
282+
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxx
283+
CODER_EXTERNAL_AUTH_0_AUTH_URL=https://bitbucket.domain.com/rest/oauth2/latest/authorize
284+
```
285+
286+
### Azure DevOps
287+
288+
Azure DevOps requires the following environment variables:
289+
290+
```env
291+
CODER_EXTERNAL_AUTH_0_ID="primary-azure-devops"
292+
CODER_EXTERNAL_AUTH_0_TYPE=azure-devops
293+
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
294+
# Ensure this value is your "Client Secret", not "App Secret"
295+
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
296+
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://app.vssps.visualstudio.com/oauth2/authorize"
297+
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://app.vssps.visualstudio.com/oauth2/token"
298+
```
299+
300+
### Azure DevOps (via Entra ID)
301+
302+
Azure DevOps (via Entra ID) requires the following environment variables:
303+
304+
```env
305+
CODER_EXTERNAL_AUTH_0_ID="primary-azure-devops"
306+
CODER_EXTERNAL_AUTH_0_TYPE=azure-devops-entra
307+
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
308+
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
309+
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://login.microsoftonline.com/<TENANT ID>/oauth2/authorize"
310+
```
311+
312+
> Note: Your app registration in Entra ID requires the `vso.code_write` scope
313+
314+
### GitLab self-managed
315+
316+
GitLab self-managed requires the following environment variables:
317+
318+
```env
319+
CODER_EXTERNAL_AUTH_0_ID="primary-gitlab"
320+
CODER_EXTERNAL_AUTH_0_TYPE=gitlab
321+
# This value is the "Application ID"
322+
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
323+
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
324+
CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://gitlab.company.org/oauth/token/info"
325+
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitlab.company.org/oauth/authorize"
326+
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://gitlab.company.org/oauth/token"
327+
CODER_EXTERNAL_AUTH_0_REGEX=gitlab\.company\.org
328+
```
329+
330+
### Gitea
331+
332+
```env
333+
CODER_EXTERNAL_AUTH_0_ID="gitea"
334+
CODER_EXTERNAL_AUTH_0_TYPE=gitea
335+
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxxx
336+
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
337+
# If self managed, set the Auth URL to your Gitea instance
338+
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://gitea.com/login/oauth/authorize"
339+
```
340+
341+
The Redirect URI for Gitea should be
342+
https://coder.company.org/external-auth/gitea/callback
343+
344+
### Self-managed git providers
345+
346+
Custom authentication and token URLs should be used for self-manage F438 d Git
347+
provider deployments.
348+
349+
```env
350+
CODER_EXTERNAL_AUTH_0_AUTH_URL="https://github.example.com/oauth/authorize"
351+
CODER_EXTERNAL_AUTH_0_TOKEN_URL="https://github.example.com/oauth/token"
352+
CODER_EXTERNAL_AUTH_0_VALIDATE_URL="https://your-domain.com/oauth/token/info"
353+
CODER_EXTERNAL_AUTH_0_REGEX=github\.company\.org
354+
```
355+
356+
> Note: The `REGEX` variable must be set if using a custom git domain.
357+
358+
### JFrog Artifactory
359+
360+
See [this](../admin/integrations/jfrog-artifactory.md) guide on instructions on
361+
how to set up for JFrog Artifactory.
362+
363+
### Custom scopes
364+
365+
Optionally, you can request custom scopes:
366+
367+
```env
368+
CODER_EXTERNAL_AUTH_0_SCOPES="repo:read repo:write write:gpg_key"
369+
```
370+
371+
### Multiple External Providers (enterprise)
372+
373+
Multiple providers are an Enterprise feature. [Learn more](../enterprise.md).
374+
Below is an example configuration with multiple providers.
375+
376+
```env
377+
# Provider 1) github.com
378+
CODER_EXTERNAL_AUTH_0_ID=primary-github
379+
CODER_EXTERNAL_AUTH_0_TYPE=github
380+
CODER_EXTERNAL_AUTH_0_CLIENT_ID=xxxxxx
381+
CODER_EXTERNAL_AUTH_0_CLIENT_SECRET=xxxxxxx
382+
CODER_EXTERNAL_AUTH_0_REGEX=github.com/orgname
383+
384+
# Provider 2) github.example.com
385+
CODER_EXTERNAL_AUTH_1_ID=secondary-github
386+
CODER_EXTERNAL_AUTH_1_TYPE=github
387+
CODER_EXTERNAL_AUTH_1_CLIENT_ID=xxxxxx
388+
CODER_EXTERNAL_AUTH_1_CLIENT_SECRET=xxxxxxx
389+
CODER_EXTERNAL_AUTH_1_REGEX=github.example.com
390+
CODER_EXTERNAL_AUTH_1_AUTH_URL="https://github.example.com/login/oauth/authorize"
391+
CODER_EXTERNAL_AUTH_1_TOKEN_URL="https://github.example.com/login/oauth/access_token"
392+
CODER_EXTERNAL_AUTH_1_VALIDATE_URL="https://github.example.com/api/v3/user"
393+
```
394+
395+
To support regex matching for paths (e.g. github.com/orgname), you'll need to
396+
add this to the
397+
[Coder agent startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/agent#startup_script):
398+
399+
```shell
400+
git config --global credential.useHttpPath true
401+
```
402+
403+
### Kubernetes environment variables
404+
405+
If you deployed Coder with Kubernetes you can set the environment variables in
406+
your `values.yaml` file:
407+
408+
```yaml
409+
coder:
410+
env:
411+
# […]
412+
- name: CODER_EXTERNAL_AUTH_0_ID
413+
value: USER_DEFINED_ID
414+
415+
- name: CODER_EXTERNAL_AUTH_0_TYPE
416+
value: github
417+
418+
- name: CODER_EXTERNAL_AUTH_0_CLIENT_ID
419+
valueFrom:
420+
secretKeyRef:
421+
name: github-primary-basic-auth
422+
key: client-id
423+
424+
- name: CODER_EXTERNAL_AUTH_0_CLIENT_SECRET
425+
valueFrom:
426+
secretKeyRef:
427+
name: github-primary-basic-auth
428+
key: client-secret
429+
```
430+
431+
You can set the secrets by creating a `github-primary-basic-auth.yaml` file and
432+
applying it.
433+
434+
```yaml
435+
apiVersion: v1
436+
kind: Secret
437+
metadata:
438+
name: github-primary-basic-auth
439+
type: Opaque
440+
stringData:
441+
client-secret: xxxxxxxxx
442+
client-id: xxxxxxxxx
443+
```
444+
445+
Make sure to restart the affected pods for the change to take effect.
446+
190447
## Up Next
191448

192449
- [Learn how to upgrade Coder](./upgrade.md).

‎docs/admin/integrations/README.md

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,14 @@ workspaces can include any Terraform resource. See our
77

88
You can host your deployment on almost any infrastructure. To learn how, read our [installation guides](../../install/README.md).
99

10-
The following resources may help as you're deploying Coder.
10+
<children></children>
1111

12-
- [Deploy workspaces on multiple Kubernetes Clusters](./multiple-kube-clusters.md)
12+
<!-- - [Deploy workspaces on multiple Kubernetes Clusters](./multiple-kube-clusters.md)
1313
- [Get workspace build logs from Kubernetes](./kubernetes-logs.md)
14-
- [Track deployment metrics with Prometheus](./prometheus.md)
14+
- [Track deployment metrics with Prometheus](./prometheus.md) -->
15+
16+
The following resources may help as you're deploying Coder.
17+
1518
- [Coder packages: one-click install on cloud providers](https://github.com/coder/packages)
1619
- [Deploy Coder offline](../../install/offline.md)
1720
- [Supported resources (Terraform registry)](https://registry.terraform.io)

‎docs/admin/templates/README.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,9 @@ After learning the basics, use starter templates to import a template with sensi
2121

2222
It's often necessary to extend the template to make it generally useful to end users. Common modifications are:
2323

24-
- Your image(s) (e.g. a Docker image with languages and tools installed)
25-
- Additional parameters (e.g. disk size, instance type, or region)
26-
- Additional IDEs (e.g. JetBrains) or features (e.g. dotfiles, RDP)
24+
- Your image(s) (e.g. a Docker image with languages and tools installed). Docs: [Image management](./extending-templates/image-management.md).
25+
- Additional parameters (e.g. disk size, instance type, or region). Docs: [Template parameters](./extending-templates/parameters.md).
26+
- Additional IDEs (e.g. JetBrains) or features (e.g. dotfiles, RDP). Docs: [Adding IDEs and features](./extending-templates/ides/README.md).
2727

2828
Learn more about the various ways you can [extend your templates](./extending-templates.md).
2929

‎docs/admin/templates/extending-templates/README.md

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,16 @@ Template resources follow the [behavior of Terraform resources](https://develope
3737

3838
A common configuration is a template whose only persistent resource is the home directory. This allows the developer to retain their work while ensuring the rest of their environment is consistently up-to-date on each workspace restart.
3939

40+
When a workspace is deleted, the Coder server essentially runs a
41+
[terraform destroy](https://www.terraform.io/cli/commands/destroy) to remove all
42+
resources associated with the workspace.
43+
44+
> Terraform's
45+
> [prevent-destroy](https://www.terraform.io/language/meta-arguments/lifecycle#prevent_destroy)
46+
> and
47+
> [ignore-changes](https://www.terraform.io/language/meta-arguments/lifecycle#ignore_changes)
48+
> meta-arguments can be used to prevent accidental data loss.
49+
4050
## Coder apps
4151

4252
Additional IDEs, documentation, or services can be associated to your workspace using the [`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app) resource.
@@ -47,6 +57,4 @@ Note that some apps are associated to the agent by default as [`display_apps`](h
4757

4858
Check out our [module registry](https://registry.coder.com/modules) for additional Coder apps from the team and our OSS community.
4959

50-
<children>
51-
52-
</children>
60+
<children></children>

0 commit comments

Comments
 (0)
0