synced/coder
1
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2025-07-13 21:36:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: restructure docs (#14421)

Browse Source 
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
2024-10-05 08:52:04 -07:00
committed by GitHub
parent 288df75686
commit 419eba5fb6
298 changed files with 5009 additions and 3889 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
docs/admin/users/github-auth.md Normal file
View File

@ -0,0 +1,84 @@
## GitHub
### Step 1: Configure the OAuth application in GitHub
First,
[register a GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/).
GitHub will ask you for the following Coder parameters:
- **Homepage URL**: Set to your Coder deployments
[`CODER_ACCESS_URL`](../../reference/cli/server.md#--access-url) (e.g.
`https://coder.domain.com`)
- **User Authorization Callback URL**: Set to `https://coder.domain.com`
> Note: If you want to allow multiple coder deployments hosted on subdomains
> e.g. coder1.domain.com, coder2.domain.com, to be able to authenticate with the
> same GitHub OAuth app, then you can set **User Authorization Callback URL** to
> the `https://domain.com`
Note the Client ID and Client Secret generated by GitHub. You will use these
values in the next step.
Coder will need permission to access user email addresses. Find the "Account
Permissions" settings for your app and select "read-only" for "Email addresses".
### Step 2: Configure Coder with the OAuth credentials
Navigate to your Coder host and run the following command to start up the Coder
server:
```shell
coder server --oauth2-github-allow-signups=true --oauth2-github-allowed-orgs="your-org" --oauth2-github-client-id="8d1...e05" --oauth2-github-client-secret="57ebc9...02c24c"
```
> For GitHub Enterprise support, specify the
> `--oauth2-github-enterprise-base-url` flag.
Alternatively, if you are running Coder as a system service, you can achieve the
same result as the command above by adding the following environment variables
to the `/etc/coder.d/coder.env` file:
```env
CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05"
CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c"
```
**Note:** To allow everyone to signup using GitHub, set:
```env
CODER_OAUTH2_GITHUB_ALLOW_EVERYONE=true
```
Once complete, run `sudo service coder restart` to reboot Coder.
If deploying Coder via Helm, you can set the above environment variables in the
`values.yaml` file as such:
```yaml
coder:
env:
- name: CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS
value: "true"
- name: CODER_OAUTH2_GITHUB_CLIENT_ID
value: "533...des"
- name: CODER_OAUTH2_GITHUB_CLIENT_SECRET
value: "G0CSP...7qSM"
# If setting allowed orgs, comment out CODER_OAUTH2_GITHUB_ALLOW_EVERYONE and its value
- name: CODER_OAUTH2_GITHUB_ALLOWED_ORGS
value: "your-org"
# If allowing everyone, comment out CODER_OAUTH2_GITHUB_ALLOWED_ORGS and it's value
#- name: CODER_OAUTH2_GITHUB_ALLOW_EVERYONE
# value: "true"
```
To upgrade Coder, run:
```shell
helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
```
> We recommend requiring and auditing MFA usage for all users in your GitHub
> organizations. This can be enforced from the organization settings page in the
> "Authentication security" sidebar tab.

44
docs/admin/users/groups-roles.md Normal file
View File

@ -0,0 +1,44 @@
# Groups and Roles
Groups and roles can be manually assigned in Coder. For production deployments,
these can also be [managed and synced by the identity provider](./idp-sync.md).
## Groups
Groups are logical segmentations of users in Coder and can be used to control
which templates developers can use. For example:
- Users within the `devops` group can access the `AWS-VM` template
- Users within the `data-science` group can access the `Jupyter-Kubernetes`
template
## Roles
Roles determine which actions users can take within the platform.
| | Auditor | User Admin | Template Admin | Owner |
| --------------------------------------------------------------- | ------- | ---------- | -------------- | ----- |
| Add and remove Users | | ✅ | | ✅ |
| Manage groups (enterprise) (premium) | | ✅ | | ✅ |
| Change User roles | | | | ✅ |
| Manage **ALL** Templates | | | ✅ | ✅ |
| View **ALL** Workspaces | | | ✅ | ✅ |
| Update and delete **ALL** Workspaces | | | | ✅ |
| Run [external provisioners](../provisioners.md) | | | ✅ | ✅ |
| Execute and use **ALL** Workspaces | | | | ✅ |
| View all user operation [Audit Logs](../security/audit-logs.md) | ✅ | | | ✅ |
A user may have one or more roles. All users have an implicit Member role that
may use personal workspaces.
### Security notes
A malicious Template Admin could write a template that executes commands on the
host (or `coder server` container), which potentially escalates their privileges
or shuts down the Coder server. To avoid this, run
[external provisioners](../provisioners.md).
In low-trust environments, we do not recommend giving users direct access to
edit templates. Instead, use
[CI/CD pipelines to update templates](../templates/managing-templates/change-management.md)
with proper security scans and code reviews in place.

31
docs/admin/users/headless-auth.md Normal file
View File

@ -0,0 +1,31 @@
# Headless Authentication
Headless user accounts that cannot use the web UI to log in to Coder. This is
useful for creating accounts for automated systems, such as CI/CD pipelines or
for users who only consume Coder via another client/API.
> You must have the User Admin role or above to create headless users.
## Create a headless user
<div class="tabs">
## CLI
```sh
coder users create \
--email="coder-bot@coder.com" \
--username="coder-bot" \
--login-type="none \
```
## UI
Navigate to the `Users` > `Create user` in the topbar
![Create a user via the UI](../../images/admin/users/headless-user.png)
</div>
To make API or CLI requests on behalf of the headless user, learn how to
[generate API tokens on behalf of a user](./sessions-tokens.md#generate-a-long-lived-api-token-on-behalf-of-another-user).

537
docs/admin/users/idp-sync.md Normal file
View File

@ -0,0 +1,537 @@
# IDP Sync (enterprise) (premium)
If your OpenID Connect provider supports group claims, you can configure Coder
to synchronize groups in your auth provider to groups within Coder. To enable
group sync, ensure that the `groups` claim is being sent by your OpenID
provider. You might need to request an additional
[scope](../../reference/cli/server.md#--oidc-scopes) or additional configuration
on the OpenID provider side.
If group sync is enabled, the user's groups will be controlled by the OIDC
provider. This means manual group additions/removals will be overwritten on the
next user login.
There are two ways you can configure group sync:
<div class="tabs">
## Server Flags
First, confirm that your OIDC provider is sending claims by logging in with OIDC
and visiting the following URL with an `Owner` account:
```text
https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
```
You should see a field in either `id_token_claims`, `user_info_claims` or both
followed by a list of the user's OIDC groups in the response. This is the
[claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by
the OIDC provider. See
[Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this.
> Depending on the OIDC provider, this claim may be named differently. Common
> ones include `groups`, `memberOf`, and `roles`.
Next configure the Coder server to read groups from the claim name with the
[OIDC group field](../../reference/cli/server.md#--oidc-group-field) server
flag:
```sh
# as an environment variable
CODER_OIDC_GROUP_FIELD=groups
```
```sh
# as a flag
--oidc-group-field groups
```
On login, users will automatically be assigned to groups that have matching
names in Coder and removed from groups that the user no longer belongs to.
For cases when an OIDC provider only returns group IDs ([Azure AD][azure-gids])
or you want to have different group names in Coder than in your OIDC provider,
you can configure mapping between the two with the
[OIDC group mapping](../../reference/cli/server.md#--oidc-group-mapping) server
flag.
```sh
# as an environment variable
CODER_OIDC_GROUP_MAPPING='{"myOIDCGroupID": "myCoderGroupName"}'
```
```sh
# as a flag
--oidc-group-mapping '{"myOIDCGroupID": "myCoderGroupName"}'
```
Below is an example mapping in the Coder Helm chart:
```yaml
coder:
env:
- name: CODER_OIDC_GROUP_MAPPING
value: >
{"myOIDCGroupID": "myCoderGroupName"}
```
From the example above, users that belong to the `myOIDCGroupID` group in your
OIDC provider will be added to the `myCoderGroupName` group in Coder.
[azure-gids]:
https://github.com/MicrosoftDocs/azure-docs/issues/59766#issuecomment-664387195
## Runtime (Organizations)
> Note: You must have a Premium license with Organizations enabled to use this.
> [Contact your account team](https://coder.com/contact) for more details
For deployments with multiple [organizations](./organizations.md), you must
configure group sync at the organization level. In future Coder versions, you
will be able to configure this in the UI. For now, you must use CLI commands.
First confirm you have the [Coder CLI](../../install/index.md) installed and are
logged in with a user who is an Owner or Organization Admin role. Next, confirm
that your OIDC provider is sending a groups claim by logging in with OIDC and
visiting the following URL:
```text
https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
```
You should see a field in either `id_token_claims`, `user_info_claims` or both
followed by a list of the user's OIDC groups in the response. This is the
[claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by
the OIDC provider. See
[Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this.
> Depending on the OIDC provider, this claim may be named differently. Common
> ones include `groups`, `memberOf`, and `roles`.
To fetch the current group sync settings for an organization, run the following:
```sh
coder organizations settings show group-sync \
--org <org-name> \
> group-sync.json
```
The default for an organization looks like this:
```json
{
"field": "",
"mapping": null,
"regex_filter": null,
"auto_create_missing_groups": false
}
```
Below is an example that uses the `groups` claim and maps all groups prefixed by
`coder-` into Coder:
```json
{
"field": "groups",
"mapping": null,
"regex_filter": "^coder-.*$",
"auto_create_missing_groups": true
}
```
> Note: You much specify Coder group IDs instead of group names. The fastest way
> to find the ID for a corresponding group is by visiting
> `https://coder.example.com/api/v2/groups`.
Here is another example which maps `coder-admins` from the identity provider to
2 groups in Coder and `coder-users` from the identity provider to another group:
```json
{
"field": "groups",
"mapping": {
"coder-admins": [
"2ba2a4ff-ddfb-4493-b7cd-1aec2fa4c830",
"93371154-150f-4b12-b5f0-261bb1326bb4"
],
"coder-users": ["2f4bde93-0179-4815-ba50-b757fb3d43dd"]
},
"regex_filter": null,
"auto_create_missing_groups": false
}
```
To set these group sync settings, use the following command:
```sh
coder organizations settings set group-sync \
--org <org-name> \
< group-sync.json
```
Visit the Coder UI to confirm these changes:
![IDP Sync](../../images/admin/users/organizations/group-sync.png)
</div>
### Group allowlist
You can limit which groups from your identity provider can log in to Coder with
[CODER_OIDC_ALLOWED_GROUPS](https://coder.com/docs/cli/server#--oidc-allowed-groups).
Users who are not in a matching group will see the following error:
![Unauthorized group error](../../images/admin/group-allowlist.png)
## Role sync (enterprise) (premium)
If your OpenID Connect provider supports roles claims, you can configure Coder
to synchronize roles in your auth provider to roles within Coder.
There are 2 ways to do role sync. Server Flags assign site wide roles, and
runtime org role sync assigns organization roles
<div class="tabs">
## Server Flags
First, confirm that your OIDC provider is sending a roles claim by logging in
with OIDC and visiting the following URL with an `Owner` account:
```text
https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
```
You should see a field in either `id_token_claims`, `user_info_claims` or both
followed by a list of the user's OIDC roles in the response. This is the
[claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by
the OIDC provider. See
[Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this.
> Depending on the OIDC provider, this claim may be named differently.
Next configure the Coder server to read groups from the claim name with the
[OIDC role field](../../reference/cli/server.md#--oidc-user-role-field) server
flag:
Set the following in your Coder server [configuration](../setup/index.md).
```env
# Depending on your identity provider configuration, you may need to explicitly request a "roles" scope
CODER_OIDC_SCOPES=openid,profile,email,roles
# The following fields are required for role sync:
CODER_OIDC_USER_ROLE_FIELD=roles
CODER_OIDC_USER_ROLE_MAPPING='{"TemplateAuthor":["template-admin","user-admin"]}'
```
> One role from your identity provider can be mapped to many roles in Coder
> (e.g. the example above maps to 2 roles in Coder.)
## Runtime (Organizations)
> Note: You must have a Premium license with Organizations enabled to use this.
> [Contact your account team](https://coder.com/contact) for more details
For deployments with multiple [organizations](./organizations.md), you can
configure role sync at the organization level. In future Coder versions, you
will be able to configure this in the UI. For now, you must use CLI commands.
First, confirm that your OIDC provider is sending a roles claim by logging in
with OIDC and visiting the following URL with an `Owner` account:
```text
https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
```
You should see a field in either `id_token_claims`, `user_info_claims` or both
followed by a list of the user's OIDC roles in the response. This is the
[claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by
the OIDC provider. See
[Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this.
> Depending on the OIDC provider, this claim may be named differently.
To fetch the current group sync settings for an organization, run the following:
```sh
coder organizations settings show role-sync \
--org <org-name> \
> role-sync.json
```
The default for an organization looks like this:
```json
{
"field": "",
"mapping": null
}
```
Below is an example that uses the `roles` claim and maps `coder-admins` from the
IDP as an `Organization Admin` and also maps to a custom `provisioner-admin`
role.
```json
{
"field": "roles",
"mapping": {
"coder-admins": ["organization-admin"],
"infra-admins": ["provisioner-admin"]
}
}
```
> Note: Be sure to use the `name` field for each role, not the display name. Use
> `coder organization roles show --org=<your-org>` to see roles for your
> organization.
To set these role sync settings, use the following command:
```sh
coder organizations settings set role-sync \
--org <org-name> \
< role-sync.json
```
Visit the Coder UI to confirm these changes:
![IDP Sync](../../images/admin/users/organizations/role-sync.png)
</div>
## Organization Sync (Premium)
> Note: In a future Coder release, this can be managed via the Coder UI instead
> of server flags.
If your OpenID Connect provider supports groups/role claims, you can configure
Coder to synchronize claims in your auth provider to organizations within Coder.
First, confirm that your OIDC provider is sending clainms by logging in with
OIDC and visiting the following URL with an `Owner` account:
```text
https://[coder.example.com]/api/v2/debug/[your-username]/debug-link
```
You should see a field in either `id_token_claims`, `user_info_claims` or both
followed by a list of the user's OIDC groups in the response. This is the
[claim](https://openid.net/specs/openid-connect-core-1_0.html#Claims) sent by
the OIDC provider. See
[Troubleshooting](#troubleshooting-grouproleorganization-sync) to debug this.
> Depending on the OIDC provider, this claim may be named differently. Common
> ones include `groups`, `memberOf`, and `roles`.
Next configure the Coder server to read groups from the claim name with the
[OIDC organization field](../../reference/cli/server.md#--oidc-organization-field)
server flag:
```sh
# as an environment variable
CODER_OIDC_ORGANIZATION_FIELD=groups
```
Next, fetch the corresponding organization IDs using the following endpoint:
```text
https://[coder.example.com]/api/v2/organizations
```
Set the following in your Coder server [configuration](../setup/index.md).
```env
CODER_OIDC_ORGANIZATION_MAPPING='{"data-scientists":["d8d9daef-e273-49ff-a832-11fe2b2d4ab1", "70be0908-61b5-4fb5-aba4-4dfb3a6c5787"]}'
```
> One claim value from your identity provider can be mapped to many
> organizations in Coder (e.g. the example above maps to 2 organizations in
> Coder.)
By default, all users are assigned to the default (first) organization. You can
disable that with:
```env
CODER_OIDC_ORGANIZATION_ASSIGN_DEFAULT=false
```
## Troubleshooting group/role/organization sync
Some common issues when enabling group/role sync.
### General guidelines
If you are running into issues with group/role sync, is best to view your Coder
server logs and enable
[verbose mode](../../reference/cli/index.md#-v---verbose). To reduce noise, you
can filter for only logs related to group/role sync:
```sh
CODER_VERBOSE=true
CODER_LOG_FILTER=".*userauth.*|.*groups returned.*"
```
Be sure to restart the server after changing these configuration values. Then,
attempt to log in, preferably with a user who has the `Owner` role.
The logs for a successful group sync look like this (human-readable):
```sh
[debu] coderd.userauth: got oidc claims request_id=49e86507-6842-4b0b-94d4-f245e62e49f3 source=id_token claim_fields="[aio aud email exp groups iat idp iss name nbf oid preferred_username rh sub tid uti ver]" blank=[]
[debu] coderd.userauth: got oidc claims request_id=49e86507-6842-4b0b-94d4-f245e62e49f3 source=userinfo claim_fields="[email family_name given_name name picture sub]" blank=[]
[debu] coderd.userauth: got oidc claims request_id=49e86507-6842-4b0b-94d4-f245e62e49f3 source=merged claim_fields="[aio aud email exp family_name given_name groups iat idp iss name nbf oid picture preferred_username rh sub tid uti ver]" blank=[]
[debu] coderd: groups returned in oidc claims request_id=49e86507-6842-4b0b-94d4-f245e62e49f3 email=ben@coder.com username=ben len=3 groups="[c8048e91-f5c3-47e5-9693-834de84034ad 66ad2cc3-a42f-4574-a281-40d1922e5b65 70b48175-107b-4ad8-b405-4d888a1c466f]"
```
To view the full claim, the Owner role can visit this endpoint on their Coder
deployment after logging in:
```sh
https://[coder.example.com]/api/v2/debug/[username]/debug-link
```
### User not being assigned / Group does not exist
If you want Coder to create groups that do not exist, you can set the following
environment variable. If you enable this, your OIDC provider might be sending
over many unnecessary groups. Use filtering options on the OIDC provider to
limit the groups sent over to prevent creating excess groups.
```env
# as an environment variable
CODER_OIDC_GROUP_AUTO_CREATE=true
```
```shell
# as a flag
--oidc-group-auto-create=true
```
A basic regex filtering option on the Coder side is available. This is applied
**after** the group mapping (`CODER_OIDC_GROUP_MAPPING`), meaning if the group
is remapped, the remapped value is tested in the regex. This is useful if you
want to filter out groups that do not match a certain pattern. For example, if
you want to only allow groups that start with `my-group-` to be created, you can
set the following environment variable.
```env
# as an environment variable
CODER_OIDC_GROUP_REGEX_FILTER="^my-group-.*$"
```
```shell
# as a flag
--oidc-group-regex-filter="^my-group-.*$"
```
### Invalid Scope
If you see an error like the following, you may have an invalid scope.
```console
The application '<oidc_application>' asked for scope 'groups' that doesn't exist on the resource...
```
This can happen because the identity provider has a different name for the
scope. For example, Azure AD uses `GroupMember.Read.All` instead of `groups`.
You can find the correct scope name in the IDP's documentation. Some IDP's allow
configuring the name of this scope.
The solution is to update the value of `CODER_OIDC_SCOPES` to the correct value
for the identity provider.
### No `group` claim in the `got oidc claims` log
Steps to troubleshoot.
1. Ensure the user is a part of a group in the IDP. If the user has 0 groups, no
`groups` claim will be sent.
2. Check if another claim appears to be the correct claim with a different name.
A common name is `memberOf` instead of `groups`. If this is present, update
`CODER_OIDC_GROUP_FIELD=memberOf`.
3. Make sure the number of groups being sent is under the limit of the IDP. Some
IDPs will return an error, while others will just omit the `groups` claim. A
common solution is to create a filter on the identity provider that returns
less than the limit for your IDP.
- [Azure AD limit is 200, and omits groups if exceeded.](https://learn.microsoft.com/en-us/azure/active-directory/hybrid/connect/how-to-connect-fed-group-claims#options-for-applications-to-consume-group-information)
- [Okta limit is 100, and returns an error if exceeded.](https://developer.okta.com/docs/reference/api/oidc/#scope-dependent-claims-not-always-returned)
## Provider-Specific Guides
Below are some details specific to individual OIDC providers.
### Active Directory Federation Services (ADFS)
> **Note:** Tested on ADFS 4.0, Windows Server 2019
1. In your Federation Server, create a new application group for Coder. Follow
the steps as described
[here.](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/development/msal/adfs-msal-web-app-web-api#app-registration-in-ad-fs)
- **Server Application**: Note the Client ID.
- **Configure Application Credentials**: Note the Client Secret.
- **Configure Web API**: Set the Client ID as the relying party identifier.
- **Application Permissions**: Allow access to the claims `openid`, `email`,
`profile`, and `allatclaims`.
1. Visit your ADFS server's `/.well-known/openid-configuration` URL and note the
value for `issuer`.
> **Note:** This is usually of the form
> `https://adfs.corp/adfs/.well-known/openid-configuration`
1. In Coder's configuration file (or Helm values as appropriate), set the
following environment variables or their corresponding CLI arguments:
- `CODER_OIDC_ISSUER_URL`: the `issuer` value from the previous step.
- `CODER_OIDC_CLIENT_ID`: the Client ID from step 1.
- `CODER_OIDC_CLIENT_SECRET`: the Client Secret from step 1.
- `CODER_OIDC_AUTH_URL_PARAMS`: set to
```console
{"resource":"$CLIENT_ID"}
```
where `$CLIENT_ID` is the Client ID from step 1
([see here](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/overview/ad-fs-openid-connect-oauth-flows-scenarios#:~:text=scope%E2%80%AFopenid.-,resource,-optional)).
This is required for the upstream OIDC provider to return the requested
claims.
- `CODER_OIDC_IGNORE_USERINFO`: Set to `true`.
1. Configure
[Issuance Transform Rules](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/create-a-rule-to-send-ldap-attributes-as-claims)
on your federation server to send the following claims:
- `preferred_username`: You can use e.g. "Display Name" as required.
- `email`: You can use e.g. the LDAP attribute "E-Mail-Addresses" as
required.
- `email_verified`: Create a custom claim rule:
```console
=> issue(Type = "email_verified", Value = "true")
```
- (Optional) If using Group Sync, send the required groups in the configured
groups claim field. See [here](https://stackoverflow.com/a/55570286) for an
example.
### Keycloak
The access_type parameter has two possible values: "online" and "offline." By
default, the value is set to "offline". This means that when a user
authenticates using OIDC, the application requests offline access to the user's
resources, including the ability to refresh access tokens without requiring the
user to reauthenticate.
To enable the `offline_access` scope, which allows for the refresh token
functionality, you need to add it to the list of requested scopes during the
authentication flow. Including the `offline_access` scope in the requested
scopes ensures that the user is granted the necessary permissions to obtain
refresh tokens.
By combining the `{"access_type":"offline"}` parameter in the OIDC Auth URL with
the `offline_access` scope, you can achieve the desired behavior of obtaining
refresh tokens for offline access to the user's resources.

195
docs/admin/users/index.md Normal file
View File

@ -0,0 +1,195 @@
# Users
By default, Coder is accessible via password authentication. For production
deployments, we recommend using an SSO authentication provider with multi-factor
authentication (MFA). It is your responsibility to ensure the auth provider
enforces MFA correctly.
## Configuring SSO
- [OpenID Connect](./oidc-auth.md) (e.g. Okta, KeyCloak, PingFederate, Azure AD)
- [GitHub](./github-auth.md) (or GitHub Enterprise)
## Groups
Multiple users can be organized into logical groups to control which templates
they can use. While groups can be manually created in Coder, we recommend
syncing them from your identity provider.
- [Learn more about Groups](./groups-roles.md)
- [Group & Role Sync](./idp-sync.md)
## Roles
Roles determine which actions users can take within the platform. Typically,
most developers in your organization have the `Member` role, allowing them to
create workspaces. Other roles have administrative capabilities such as
auditing, managing users, and managing templates.
- [Learn more about Roles](./groups-roles.md)
- [Group & Role Sync](./idp-sync.md)
## User status
Coder user accounts can have different status types: active, dormant, and
suspended.
### Active user
An _active_ user account in Coder is the default and desired state for all
users. When a user's account is marked as _active_, they have complete access to
the Coder platform and can utilize all of its features and functionalities
without any limitations. Active users can access workspaces, templates, and
interact with Coder using CLI.
### Dormant user
A user account is set to _dormant_ status when they have not yet logged in, or
have not logged into the Coder platform for the past 90 days. Once the user logs
in to the platform, the account status will switch to _active_.
Dormant accounts do not count towards the total number of licensed seats in a
Coder subscription, allowing organizations to optimize their license usage.
### Suspended user
When a user's account is marked as _suspended_ in Coder, it means that the
account has been temporarily deactivated, and the user is unable to access the
platform.
Only user administrators or owners have the necessary permissions to manage
suspended accounts and decide whether to lift the suspension and allow the user
back into the Coder environment. This level of control ensures that
administrators can enforce security measures and handle any compliance-related
issues promptly.
Similar to dormant users, suspended users do not count towards the total number
of licensed seats.
## Create a user
To create a user with the web UI:
1. Log in as a user admin.
2. Go to **Users** > **New user**.
3. In the window that opens, provide the **username**, **email**, and
**password** for the user (they can opt to change their password after their
initial login).
4. Click **Submit** to create the user.
The new user will appear in the **Users** list. Use the toggle to change their
**Roles** if desired.
To create a user via the Coder CLI, run:
```shell
coder users create
```
When prompted, provide the **username** and **email** for the new user.
You'll receive a response that includes the following; share the instructions
with the user so that they can log into Coder:
```console
Download the Coder command line for your operating system:
https://github.com/coder/coder/releases/latest
Run coder login https://<accessURL>.coder.app to authenticate.
Your email is: email@exampleCo.com
Your password is: <redacted>
Create a workspace coder create !
```
## Suspend a user
User admins can suspend a user, removing the user's access to Coder.
To suspend a user via the web UI:
1. Go to **Users**.
2. Find the user you want to suspend, click the vertical ellipsis to the right,
and click **Suspend**.
3. In the confirmation dialog, click **Suspend**.
To suspend a user via the CLI, run:
```shell
coder users suspend <username|user_id>
```
Confirm the user suspension by typing **yes** and pressing **enter**.
## Activate a suspended user
User admins can activate a suspended user, restoring their access to Coder.
To activate a user via the web UI:
1. Go to **Users**.
2. Find the user you want to activate, click the vertical ellipsis to the right,
and click **Activate**.
3. In the confirmation dialog, click **Activate**.
To activate a user via the CLI, run:
```shell
coder users activate <username|user_id>
```
Confirm the user activation by typing **yes** and pressing **enter**.
## Reset a password
To reset a user's via the web UI:
1. Go to **Users**.
2. Find the user whose password you want to reset, click the vertical ellipsis
to the right, and select **Reset password**.
3. Coder displays a temporary password that you can send to the user; copy the
password and click **Reset password**.
Coder will prompt the user to change their temporary password immediately after
logging in.
You can also reset a password via the CLI:
```shell
# run `coder reset-password <username> --help` for usage instructions
coder reset-password <username>
```
> Resetting a user's password, e.g., the initial `owner` role-based user, only
> works when run on the host running the Coder control plane.
### Resetting a password on Kubernetes
```shell
kubectl exec -it deployment/coder /bin/bash -n coder
coder reset-password <username>
```
## User filtering
In the Coder UI, you can filter your users using pre-defined filters or by
utilizing the Coder's filter query. The examples provided below demonstrate how
to use the Coder's filter query:
- To find active users, use the filter `status:active`.
- To find admin users, use the filter `role:admin`.
- To find users have not been active since July 2023:
`status:active last_seen_before:"2023-07-01T00:00:00Z"`
The following filters are supported:
- `status` - Indicates the status of the user. It can be either `active`,
`dormant` or `suspended`.
- `role` - Represents the role of the user. You can refer to the
[TemplateRole documentation](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#TemplateRole)
for a list of supported user roles.
- `last_seen_before` and `last_seen_after` - The last time a used has used the
platform (e.g. logging in, any API requests, connecting to workspaces). Uses
the RFC3339Nano format.

158
docs/admin/users/oidc-auth.md Normal file
View File

@ -0,0 +1,158 @@
# OpenID Connect
The following steps through how to integrate any OpenID Connect provider (Okta,
Active Directory, etc.) to Coder.
## Step 1: Set Redirect URI with your OIDC provider
Your OIDC provider will ask you for the following parameter:
- **Redirect URI**: Set to `https://coder.domain.com/api/v2/users/oidc/callback`
## Step 2: Configure Coder with the OpenID Connect credentials
Navigate to your Coder host and run the following command to start up the Coder
server:
```shell
coder server --oidc-issuer-url="https://issuer.corp.com" --oidc-email-domain="your-domain-1,your-domain-2" --oidc-client-id="533...des" --oidc-client-secret="G0CSP...7qSM"
```
If you are running Coder as a system service, you can achieve the same result as
the command above by adding the following environment variables to the
`/etc/coder.d/coder.env` file:
```env
CODER_OIDC_ISSUER_URL="https://issuer.corp.com"
CODER_OIDC_EMAIL_DOMAIN="your-domain-1,your-domain-2"
CODER_OIDC_CLIENT_ID="533...des"
CODER_OIDC_CLIENT_SECRET="G0CSP...7qSM"
```
Once complete, run `sudo service coder restart` to reboot Coder.
If deploying Coder via Helm, you can set the above environment variables in the
`values.yaml` file as such:
```yaml
coder:
env:
- name: CODER_OIDC_ISSUER_URL
value: "https://issuer.corp.com"
- name: CODER_OIDC_EMAIL_DOMAIN
value: "your-domain-1,your-domain-2"
- name: CODER_OIDC_CLIENT_ID
value: "533...des"
- name: CODER_OIDC_CLIENT_SECRET
value: "G0CSP...7qSM"
```
To upgrade Coder, run:
```shell
helm upgrade <release-name> coder-v2/coder -n <namespace> -f values.yaml
```
## OIDC Claims
When a user logs in for the first time via OIDC, Coder will merge both the
claims from the ID token and the claims obtained from hitting the upstream
provider's `userinfo` endpoint, and use the resulting data as a basis for
creating a new user or looking up an existing user.
To troubleshoot claims, set `CODER_VERBOSE=true` and follow the logs while
signing in via OIDC as a new user. Coder will log the claim fields returned by
the upstream identity provider in a message containing the string
`got oidc claims`, as well as the user info returned.
> **Note:** If you need to ensure that Coder only uses information from the ID
> token and does not hit the UserInfo endpoint, you can set the configuration
> option `CODER_OIDC_IGNORE_USERINFO=true`.
### Email Addresses
By default, Coder will look for the OIDC claim named `email` and use that value
for the newly created user's email address.
If your upstream identity provider users a different claim, you can set
`CODER_OIDC_EMAIL_FIELD` to the desired claim.
> **Note** If this field is not present, Coder will attempt to use the claim
> field configured for `username` as an email address. If this field is not a
> valid email address, OIDC logins will fail.
### Email Address Verification
Coder requires all OIDC email addresses to be verified by default. If the
`email_verified` claim is present in the token response from the identity
provider, Coder will validate that its value is `true`. If needed, you can
disable this behavior with the following setting:
```env
CODER_OIDC_IGNORE_EMAIL_VERIFIED=true
```
> **Note:** This will cause Coder to implicitly treat all OIDC emails as
> "verified", regardless of what the upstream identity provider says.
### Usernames
When a new user logs in via OIDC, Coder will by default use the value of the
claim field named `preferred_username` as the the username.
If your upstream identity provider uses a different claim, you can set
`CODER_OIDC_USERNAME_FIELD` to the desired claim.
> **Note:** If this claim is empty, the email address will be stripped of the
> domain, and become the username (e.g. `example@coder.com` becomes `example`).
> To avoid conflicts, Coder may also append a random word to the resulting
> username.
## OIDC Login Customization
If you'd like to change the OpenID Connect button text and/or icon, you can
configure them like so:
```env
CODER_OIDC_SIGN_IN_TEXT="Sign in with Gitea"
CODER_OIDC_ICON_URL=https://gitea.io/images/gitea.png
```
To change the icon and text above the OpenID Connect button, see application
name and logo url in [appearance](../setup/appearance.md) settings.
## Disable Built-in Authentication
To remove email and password login, set the following environment variable on
your Coder deployment:
```env
CODER_DISABLE_PASSWORD_AUTH=true
```
## SCIM (enterprise) (premium)
Coder supports user provisioning and deprovisioning via SCIM 2.0 with header
authentication. Upon deactivation, users are
[suspended](./index.md#suspend-a-user) and are not deleted.
[Configure](../setup/index.md) your SCIM application with an auth key and supply
it the Coder server.
```env
CODER_SCIM_AUTH_HEADER="your-api-key"
```
## TLS
If your OpenID Connect provider requires client TLS certificates for
authentication, you can configure them like so:
```env
CODER_TLS_CLIENT_CERT_FILE=/path/to/cert.pem
CODER_TLS_CLIENT_KEY_FILE=/path/to/key.pem
```
### Next steps
- [Group Sync](./idp-sync.md)
- [Groups & Roles](./groups-roles.md)

110
docs/admin/users/organizations.md Normal file
View File

@ -0,0 +1,110 @@
# Organizations (Premium)
> Note: Organizations requires a
> [Premium license](https://coder.com/pricing#compare-plans). For more details,
> [contact your account team](https://coder.com/contact).
Organizations can be used to segment and isolate resources inside a Coder
deployment for different user groups or projects.
## Example
Here is an example of how one could use organizations to run a Coder deployment
with multiple platform teams, all with unique resources:
![Organizations Example](../../images/admin/users/organizations/diagram.png)
## The default organization
All Coder deployments start with one organization called `Coder`.
To edit the organization details, navigate to `Deployment -> Organizations` in
the top bar:
![Organizations Menu](../../images/admin/users/organizations/deployment-organizations.png)
From there, you can manage the name, icon, description, users, and groups:
![Organization Settings](../../images/admin/users/organizations/default-organization.png)
## Additional organizations
Any additional organizations have unique admins, users, templates, provisioners,
groups, and workspaces. Each organization must have at least one
[provisioner](../provisioners.md) as the built-in provisioner only applies to
the default organization.
You can configure [organization/role/group sync](./idp-sync.md) from your
identity provider to avoid manually assigning users to organizations.
## Creating an organization
### Prerequisites
- Coder v2.16+ deployment with Premium license with Organizations enabled
([contact your account team](https://coder.com/contact)) for more details.
- User with `Owner` role
### 1. Create the organization
Within the sidebar, click `New organization` to create an organization. In this
example, we'll create the `data-platform` org.
![New Organization](../../images/admin/users/organizations/new-organization.png)
From there, let's deploy a provisioner and template for this organization.
### 2. Deploy a provisioner
[Provisioners](../provisioners.md) are organization-scoped and are responsible
for executing Terraform/OpenTofu to provision the infrastructure for workspaces
and testing templates. Before creating templates, we must deploy at least one
provisioner as the built-in provisioners are scoped to the default organization.
Using Coder CLI, run the following command to create a key that will be used to
authenticate the provisioner:
```sh
coder provisioner keys create data-cluster-key --org data-platform
Successfully created provisioner key data-cluster! Save this authentication token, it will not be shown again.
< key omitted >
```
Next, start the provisioner with the key on your desired platform. In this
example, we'll start it using the Coder CLI on a host with Docker. For
instructions on using other platforms like Kubernetes, see our
[provisioner documentation](../provisioners.md).
```sh
export CODER_URL=https://<your-coder-url>
export CODER_PROVISIONER_DAEMON_KEY=<key>
coder provisionerd start --org <org-name>
```
### 3. Create a template
Once you've started a provisioner, you can create a template. You'll notice the
"Create Template" screen now has an organization dropdown:
![Template Org Picker](../../images/admin/users/organizations/template-org-picker.png)
### 5. Add members
Navigate to `Deployment->Organizations` to add members to your organization.
Once added, they will be able to see the organization-specific templates.
![Add members](../../images/admin/users/organizations/organization-members.png)
### 6. Create a workspace
Now, users in the data platform organization will see the templates related to
their organization. Users can be in multiple organizations.
![Workspace List](../../images/admin/users/organizations/workspace-list.png)
## Beta
As of v2.16.0, Organizations is in beta. If you encounter any issues, please
[file an issue](https://github.com/coder/coder/issues/new) or contact your
account team.

27
docs/admin/users/password-auth.md Normal file
View File

@ -0,0 +1,27 @@
# Password Authentication
Coder has password authentication enabled by default. The account created during
setup is a username/password account.
## Disable password authentication
To disable password authentication, use the
[`CODER_DISABLE_PASSWORD_AUTH`](../../reference/cli/server.md#--disable-password-auth)
flag on the Coder server.
## Restore the `Owner` user
If you remove the admin user account (or forget the password), you can run the
[`coder server create-admin-user`](../../reference/cli/server_create-admin-user.md)command
on your server.
> Note: You must run this command on the same machine running the Coder server.
> If you are running Coder on Kubernetes, this means using
> [kubectl exec](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_exec/)
> to exec into the pod.
## Reset a user's password
An admin must reset passwords on behalf of users. This can be done in the web UI
in the Users page or CLI:
[`coder reset-password`](../../reference/cli/reset-password.md)

107
docs/admin/users/quotas.md Normal file
View File

@ -0,0 +1,107 @@
# Quotas
Quotas are a mechanism for controlling spend by associating costs with workspace
templates and assigning budgets to users. Users that exceed their budget will be
blocked from launching more workspaces until they either delete their other
workspaces or get their budget extended.
For example: A template is configured with a cost of 5 credits per day, and the
user is granted 15 credits, which can be consumed by both started and stopped
workspaces. This budget limits the user to 3 concurrent workspaces.
Quotas are scoped to [Groups](./groups-roles.md) in Enterprise and
[organizations](./organizations.md) in Premium.
## Definitions
- **Credits** is the fundamental unit representing cost in the quota system.
This integer can be arbitrary, or it can map to your preferred currency.
- **Budget** is the per-user, enforced, upper limit to credit spend.
- **Allowance** is a grant of credits to the budget.
## Establishing Costs
Templates describe their cost through the `daily_cost` attribute in
[`resource_metadata`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/metadata).
Since costs are associated with resources, an offline workspace may consume less
quota than an online workspace.
A common use case is separating costs for a persistent volume and ephemeral
compute:
```hcl
resource "docker_volume" "home_volume" {
name = "coder-${data.coder_workspace_owner.me.name}-${data.coder_workspace.me.name}-root"
}
resource "coder_metadata" "home_volume" {
resource_id = docker_volume.home_volume.id
daily_cost = 10
}
resource "docker_container" "workspace" {
count = data.coder_workspace.me.start_count
image = "codercom/code-server:latest"
...
volumes {
container_path = "/home/coder/"
volume_name = docker_volume.home_volume.name
read_only = false
}
}
resource "coder_metadata" "workspace" {
count = data.coder_workspace.me.start_count
resource_id = docker_container.workspace.id
daily_cost = 20
}
```
When the workspace above is shut down, the `docker_container` and
`coder_metadata` both get deleted. This reduces the cost from 30 credits to 10
credits.
Resources without a `daily_cost` value are considered to cost 0. If the cost was
removed on the `docker_volume` above, the template would consume 0 credits when
it's offline. This technique is good for incentivizing users to shut down their
unused workspaces and freeing up compute in the cluster.
## Establishing Budgets
Each group has a configurable Quota Allowance. A user's budget is calculated as
the sum of their allowances.
![group-settings](../../images/admin/users/quotas/quota-groups.png)
For example:
| Group Name | Quota Allowance |
| ---------- | --------------- |
| Frontend | 10 |
| Backend | 20 |
| Data | 30 |
<br/>
| Username | Groups | Effective Budget |
| -------- | ----------------- | ---------------- |
| jill | Frontend, Backend | 30 |
| jack | Backend, Data | 50 |
| sam | Data | 30 |
| alex | Frontend | 10 |
By default, groups are assumed to have a default allowance of 0.
## Quota Enforcement
Coder enforces Quota on workspace start and stop operations. The workspace build
process dynamically calculates costs, so quota violation fails builds as opposed
to failing the build-triggering operation. For example, the Workspace Create
Form will never get held up by quota enforcement.
![build-log](../../images/admin/quota-buildlog.png)
## Up next
- [Group Sync](./idp-sync.md)
- [Control plane configuration](../setup/index.md)

64
docs/admin/users/sessions-tokens.md Normal file
View File

@ -0,0 +1,64 @@
# API & Session Tokens
Users can generate tokens to make API requests on behalf of themselves.
## Short-Lived Tokens (Sessions)
The [Coder CLI](../../install/cli.md) and [Backstage Plugin](#TODO) use
short-lived token to authenticate. To generate a short-lived session token on
behalf of your account, visit the following URL:
`https://coder.example.com/cli-auth`
### Session Durations
By default, sessions last 24 hours and are automatically refreshed. You can
configure
[`CODER_SESSION_DURATION`](../../reference/cli/server.md#--session-duration) to
change the duration and
[`CODER_DISABLE_SESSION_EXPIRY_REFRESH`](../../reference/cli/server.md#--disable-session-expiry-refresh)
to configure this behavior.
## Long-Lived Tokens (API Tokens)
Users can create long lived tokens. We refer to these as "API tokens" in the
product.
### Generate a long-lived API token on behalf of yourself
<div class="tabs">
#### UI
Visit your account settings in the top right of the dashboard or by navigating
to `https://coder.example.com/settings/account`
Navigate to the tokens page in the sidebar and create a new token:
![Create an API token](../../images/admin/users/create-token.png)
#### CLI
Use the following command:
```sh
coder tokens create --name=my-token --lifetime=720h
```
See the help docs for
[`coder tokens create`](../../reference/cli/tokens_create.md) for more info.
</div>
### Generate a long-lived API token on behalf of another user
Today, you must use the REST API to generate a token on behalf of another user.
You must have the `Owner` role to do this. Use our API reference for more
information:
[Create token API key](https://coder.com/docs/reference/api/users#create-token-api-key)
### Set max token length
You can use the
[`CODER_MAX_TOKEN_LIFETIME`](https://coder.com/docs/reference/cli/server#--max-token-lifetime)
server flag to set the maximum duration for long-lived tokens in your
deployment.