Skip to content

Commit 6e1bc36

Browse files
author
Katie Horne
authored
chore: rewrite/reorg access control docs (coder#827)
1 parent e6b1ee1 commit 6e1bc36

File tree

10 files changed

+126
-84
lines changed

10 files changed

+126
-84
lines changed

‎admin/access-control/index.md

Lines changed: 14 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -7,60 +7,24 @@ The **Authentication** tab allows you to choose how your users log in and gain
77
access to Coder. Currently, you can choose between **Built-In Authentication**
88
and **OpenID Connect**.
99

10-
## Built-In Authentication
10+
## Built-In authentication
1111

12-
Built-in authentication allows you (or any admin) to manually create users who
13-
log in with their email address and temporary password. Coder will ask them to
14-
change their password after they log in the first time.
12+
Built-in authentication, which is the default method, allows you (or any admin)
13+
to manually create users who log in with their email address and temporary
14+
password. Coder will ask them to change their password after they log in the
15+
first time.
1516

16-
## OpenID Connect
17+
## OIDC authentication
1718

18-
The OpenID Connect (OIDC) option allows you to defer identity management to the
19-
OIDC provider of your choice.
19+
The OpenID Connect (OIDC) authentication option allows you to defer identity
20+
management to the OIDC provider of your choice (e.g., Google).
2021

21-
### Set up authentication via OIDC
22+
## Managing authentication to Coder
2223

23-
Before proceeding, you'll need to register a Coder application with your OIDC
24-
Provider. You'll need to provide a domain name for the OIDC token callback; use
25-
`https://coder.my-company.com/oidc/callback`.
24+
To manage the ways that users can login to Coder, see
25+
[Managing authentication](manage.md)
2626

27-
Once you've done this, you'll need to complete the setup process in Coder. On
28-
the Authentication tab, provide the following parameters:
27+
## See also
2928

30-
- **Client ID**: The client ID for the Coder application you registered with the
31-
OIDC provider
32-
- **Client Secret**: The secret assigned to the Coder application you registered
33-
with the OIDC provider
34-
- **Issuer** (e.g., `https://my-idp.com/realm/my-org`): The URL where Coder can
35-
find your OIDC provider's configuration document
36-
37-
If you do not have values for any of these parameters, you can obtain them from
38-
your OIDC provider.
39-
40-
## Disable built-in authentication
41-
42-
You can disable built-in authentication as an option for accessing Coder if you
43-
have OIDC configured.
44-
45-
![Login page with built-in authentication
46-
disabled](../../assets/admin/disable-built-in-auth.png)
47-
48-
To do so, navigate to **Manage** > **Admin** > **Authentication**. Then, toggle
49-
**Disable built-in authentication** to **On** and click **Save preferences**.
50-
51-
[Site managers](user-roles#site-manager-permissions) can still
52-
use built-in authentication. To view this option on the login page, add the
53-
following query parameter to the URL you use to access your Coder deployment:
54-
55-
```text
56-
/login?showAllAuthenticationTypes=1
57-
```
58-
59-
## Change the authentication method
60-
61-
You can change the authentication method by which a user logs into their Coder
62-
account.
63-
64-
To do so, go to **Manage** > **Users**. Find the user whose authentication type
65-
you want to change, and use the **Auth Type** to toggle between **Built-In** and
66-
**OpenID Connect**.
29+
- [User management in Coder](users/index.md)
30+
- [User password reset](users/password-reset.md)

‎admin/access-control/manage.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: Authentication management
3+
description: Learn how to manage Coder authentication.
4+
---
5+
6+
By default, Coder enables **built-in authentication**, though you can change
7+
this if desired.
8+
9+
To do so, go to **Manage** > **Users**. Find the user whose authentication type
10+
you want to change, and use the **Auth Type** to toggle between **Built-In** and
11+
**OpenID Connect**.
12+
13+
If you opt for **OpenID Connect**, you'll need to provide additional
14+
configuration steps, which are detailed in the subsequent sections of this
15+
article.
16+
17+
## Set up OIDC authentication
18+
19+
To set up OIDC authentication, you'll first need to register a Coder application
20+
with your OIDC provider. During this process, you'll be asked to provide a
21+
domain name for the OIDC token callback; use
22+
`https://coder.my-company.com/oidc/callback`.
23+
24+
Once you've registered a Coder application with your OIDC provider, you'll need
25+
to return to Coder and complete the setup process. Under **Admin** > **Manage** >
26+
**Authentication**, make sure that you've selected **OpenID Connect** as the
27+
authentication type. Then, provide the following parameters:
28+
29+
- **Client ID**: The client ID for the Coder application you registered with the
30+
OIDC provider
31+
- **Client Secret**: The secret assigned to the Coder application you registered
32+
with the OIDC provider
33+
- **Issuer** (e.g., `https://my-idp.com/realm/my-org`): The URL where Coder can
34+
find your OIDC provider's configuration document
35+
36+
> If you do not have values for any of these parameters, you can obtain them
37+
> from your OIDC provider.
38+
39+
There are several additional configuration parameters that may be of interest to
40+
you:
41+
42+
- **Enable Access Tokens:** Toggle **On** if you'd like to allow users to fetch
43+
tokens from `https://<yourDomain>/api/v0/users/me/oidc-access-token`
44+
- **Additional Scopes:** Specify any scopes (beyond the default) that you would
45+
like Coder to request during the login process
46+
- **Disable built-in authentication:** Choose whether Coder removes the ability
47+
to log in with an email/password option when you've enabled OIDC
48+
authentication
49+
50+
### Disable built-in authentication
51+
52+
You can disable built-in authentication as an option for accessing Coder if you
53+
have OIDC configured.
54+
55+
![Login page with built-in authentication
56+
disabled](../../assets/admin/disable-built-in-auth.png)
57+
58+
[Site managers](users/user-roles#site-manager-permissions) can still use
59+
built-in authentication. To view this option on the login page, add the
60+
following query parameter to the URL you use to access your Coder deployment:
61+
62+
```text
63+
/login?showAllAuthenticationTypes=1
64+
```

‎admin/access-control/organizations.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,8 @@ title: Organization roles
33
description: Learn how to manage organization roles.
44
---
55

6-
Like [User roles](user-roles.md), members of an
7-
[organization](../organizations.md) can be assigned different roles. There are
8-
two roles available:
6+
You can assign members of an [organization](../organizations.md) roles, which
7+
function like [user roles](users/user-roles.md). There are two roles available:
98

109
<table>
1110
<thead>

‎admin/access-control/user-management.md renamed to ‎admin/access-control/users/index.md

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,8 @@ title: "User management"
33
description: Learn how to add, delete and manage Coder users.
44
---
55

6-
[Site managers](/access-control/user-roles#site-manager-permissions) can create
7-
and manage users from the **Users** page, which is accessible at **Manage** >
8-
**Users**.
6+
[Site managers](user-roles#site-manager-permissions) can create and manage users
7+
from the **Users** page, which is accessible at **Manage** > **Users**.
98

109
## Creating a new user
1110

@@ -26,6 +25,18 @@ which they can use with their email to access their new account. For increased
2625
security, Coder prompts the new user to change their password immediately after
2726
they log in.
2827

28+
## Changing a user's role
29+
30+
Coder comes with built-in [user roles](user-roles.md) that define what actions a
31+
user can take in the deployment.
32+
33+
By default, all new users are assigned the **Member** role. These users can be
34+
upgraded to **Auditor** or **Site Manager** by another user with administrative
35+
privileges.
36+
37+
To change a user's role, go to **Manage** > **Users**. Find the user and use the
38+
**Site Role** drop-down to change the assigned role.
39+
2940
## Deleting a user
3041

3142
To delete a user:

‎admin/access-control/password-reset.md renamed to ‎admin/access-control/users/password-reset.md

Lines changed: 20 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,33 +3,41 @@ title: Password reset
33
description: Learn how to reset Coder user passwords.
44
---
55

6-
To reset a user's password:
6+
This article walks you through resetting a user password, as well as resetting a
7+
site admin's password.
78

8-
1. Go to **Manage** > **Users**.
9+
## Resetting a user password
10+
11+
To reset a non-site admin's password:
12+
13+
1. Log into Coder as a site manager, and go to **Manage** > **Users**.
914
1. Find the user whose password you want to reset and click the vertical
1015
ellipsis to the right.
1116
1. Click **Reset password**. Coder will display a temporary password that you
1217
can provide to the user. Click **Reset Password** to proceed with the reset.
1318

14-
![Confirm password reset](../../assets/admin/reset-password.png)
19+
![Confirm password reset](../../../assets/admin/reset-password.png)
1520

1621
When the user logs in using the temporary password, Coder will prompt them to
1722
change it.
1823

19-
> You can only reset passwords for users using **built-in authentication**.
24+
> You can only reset passwords for users using **built-in authentication** using
25+
> the Coder UI.
2026
2127
## Resetting the site admin password
2228

23-
If you need to reset the password for a site admin, you can do so using coderd's
24-
**reset-admin-password** command.
29+
If you need to reset the password for a site admin, you can do so using
30+
`coderd`'s **reset-admin-password** command.
2531

26-
> You should have the
27-
> [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) dependency
28-
> installed from when you first set up Coder; if not, please sure to install it
29-
> before proceeding. If you are using Docker, follow
30-
> [these instructions](../../setup/docker#admin-password) instead.
32+
> This process requires the
33+
> [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) dependency,
34+
> which should have been installed when you first set up Coder; if not, please
35+
> sure to install it before proceeding.
36+
>
37+
> If you are using Docker, follow
38+
> [these instructions](../../../setup/docker#admin-password) instead.
3139
32-
To reset the password, run the following in the terminal:
40+
To reset the site admin password, run the following in the terminal:
3341

3442
```console
3543
# point to the coder namespace

‎admin/access-control/user-roles.md renamed to ‎admin/access-control/users/user-roles.md

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -572,12 +572,3 @@ roles, but a summary of the roles are:
572572
</tr>
573573
</tbody>
574574
</table>
575-
576-
## Changing a user's role
577-
578-
By default, all new users are assigned the **Member** role. These users can be
579-
upgraded to **Auditor** or **Site Manager** by another user with administrative
580-
privileges.
581-
582-
To change a user's role, go to **Manage** > **Users**. Find the user and use the
583-
**Site Role** drop-down to change the assigned role.

‎assets/admin/reset-password.png

63.1 KB
Loading

‎guides/troubleshooting/admin-pwd.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Learn how to resolve issues with resetting your admin password.
44
---
55

66
When
7-
[resetting your Coder admin password](../../admin/access-control/password-reset.md#resetting-the-site-admin-password)
7+
[resetting your Coder admin password](../../admin/access-control/users/password-reset.md#resetting-the-site-admin-password)
88
in the terminal, you may encounter the following error:
99

1010
```console

‎manifest.json

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -202,16 +202,21 @@
202202
"path": "./admin/access-control/index.md",
203203
"children": [
204204
{
205-
"path": "./admin/access-control/user-roles.md"
205+
"path": "./admin/access-control/manage.md"
206206
},
207207
{
208208
"path": "./admin/access-control/organizations.md"
209209
},
210210
{
211-
"path": "./admin/access-control/password-reset.md"
212-
},
213-
{
214-
"path": "./admin/access-control/user-management.md"
211+
"path": "./admin/access-control/users/index.md",
212+
"children": [
213+
{
214+
"path": "./admin/access-control/users/user-roles.md"
215+
},
216+
{
217+
"path": "./admin/access-control/users/password-reset.md"
218+
}
219+
]
215220
}
216221
]
217222
},

‎setup/installation.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ kubectl config set-context --current --namespace=coder
148148
These are the credentials you need to continue setup using Coder's web UI.
149149

150150
> If you lose your admin credentials, you can use the
151-
> [admin password reset](../admin/access-control/password-reset.md#resetting-the-site-admin-password)
151+
> [admin password reset](../admin/access-control/users/password-reset.md#resetting-the-site-admin-password)
152152
> process to regain access.
153153

154154
## Logging

0 commit comments

Comments
 (0)