coder · khorne3 · Feb 8, 2022 · Feb 2, 2022 · Feb 2, 2022 · Feb 2, 2022
diff --git a/admin/access-control/index.md b/admin/access-control/index.md
@@ -7,60 +7,24 @@ The **Authentication** tab allows you to choose how your users log in and gain
 access to Coder. Currently, you can choose between **Built-In Authentication**
 and **OpenID Connect**.
 
-## Built-In Authentication
+## Built-In authentication
 
-Built-in authentication allows you (or any admin) to manually create users who
-log in with their email address and temporary password. Coder will ask them to
-change their password after they log in the first time.
+Built-in authentication, which is the default method, allows you (or any admin)
+to manually create users who log in with their email address and temporary
+password. Coder will ask them to change their password after they log in the
+first time.
 
-## OpenID Connect
+## OIDC authentication
 
-The OpenID Connect (OIDC) option allows you to defer identity management to the
-OIDC provider of your choice.
+The OpenID Connect (OIDC) authentication option allows you to defer identity
+management to the OIDC provider of your choice (e.g., Google).
 
-### Set up authentication via OIDC
+## Managing authentication to Coder
 
-Before proceeding, you'll need to register a Coder application with your OIDC
-Provider. You'll need to provide a domain name for the OIDC token callback; use
-`https://coder.my-company.com/oidc/callback`.
+To manage the ways that users can login to Coder, see
+[Managing authentication](manage.md)
 
-Once you've done this, you'll need to complete the setup process in Coder. On
-the Authentication tab, provide the following parameters:
+## See also
 
-- **Client ID**: The client ID for the Coder application you registered with the
-  OIDC provider
-- **Client Secret**: The secret assigned to the Coder application you registered
-  with the OIDC provider
-- **Issuer** (e.g., `https://my-idp.com/realm/my-org`): The URL where Coder can
-  find your OIDC provider's configuration document
-
-If you do not have values for any of these parameters, you can obtain them from
-your OIDC provider.
-
-## Disable built-in authentication
-
-You can disable built-in authentication as an option for accessing Coder if you
-have OIDC configured.
-
-![Login page with built-in authentication
-disabled](../../assets/admin/disable-built-in-auth.png)
-
-To do so, navigate to **Manage** > **Admin** > **Authentication**. Then, toggle
-**Disable built-in authentication** to **On** and click **Save preferences**.
-
-[Site managers](user-roles#site-manager-permissions) can still
-use built-in authentication. To view this option on the login page, add the
-following query parameter to the URL you use to access your Coder deployment:
-
-```text
-/login?showAllAuthenticationTypes=1
-```
-
-## Change the authentication method
-
-You can change the authentication method by which a user logs into their Coder
-account.
-
-To do so, go to **Manage** > **Users**. Find the user whose authentication type
-you want to change, and use the **Auth Type** to toggle between **Built-In** and
-**OpenID Connect**.
+- [User management in Coder](users/index.md)
+- [User password reset](users/password-reset.md)
diff --git a/admin/access-control/manage.md b/admin/access-control/manage.md
@@ -0,0 +1,64 @@
+---
+title: Authentication management
+description: Learn how to manage Coder authentication.
+---
+
+By default, Coder enables **built-in authentication**, though you can change
+this if desired.
+
+To do so, go to **Manage** > **Users**. Find the user whose authentication type
+you want to change, and use the **Auth Type** to toggle between **Built-In** and
+**OpenID Connect**.
+
+If you opt for **OpenID Connect**, you'll need to provide additional
+configuration steps, which are detailed in the subsequent sections of this
+article.
+
+## Set up OIDC authentication
+
+To set up OIDC authentication, you'll first need to register a Coder application
+with your OIDC provider. During this process, you'll be asked to provide a
+domain name for the OIDC token callback; use
+`https://coder.my-company.com/oidc/callback`.
+
+Once you've registered a Coder application with your OIDC provider, you'll need
+to return to Coder and complete the setup process. Under **Admin** > **Manage** >
+**Authentication**, make sure that you've selected **OpenID Connect** as the
+authentication type. Then, provide the following parameters:
+
+- **Client ID**: The client ID for the Coder application you registered with the
+  OIDC provider
+- **Client Secret**: The secret assigned to the Coder application you registered
+  with the OIDC provider
+- **Issuer** (e.g., `https://my-idp.com/realm/my-org`): The URL where Coder can
+  find your OIDC provider's configuration document
+
+> If you do not have values for any of these parameters, you can obtain them
+> from your OIDC provider.
+
+There are several additional configuration parameters that may be of interest to
+you:
+
+- **Enable Access Tokens:** Toggle **On** if you'd like to allow users to fetch
+  tokens from `https://<yourDomain>/api/v0/users/me/oidc-access-token`
+- **Additional Scopes:** Specify any scopes (beyond the default) that you would
+  like Coder to request during the login process
+- **Disable built-in authentication:** Choose whether Coder removes the ability
+  to log in with an email/password option when you've enabled OIDC
+  authentication
+
+### Disable built-in authentication
+
+You can disable built-in authentication as an option for accessing Coder if you
+have OIDC configured.
+
+![Login page with built-in authentication
+disabled](../../assets/admin/disable-built-in-auth.png)
+
+[Site managers](users/user-roles#site-manager-permissions) can still use
+built-in authentication. To view this option on the login page, add the
+following query parameter to the URL you use to access your Coder deployment:
+
+```text
+/login?showAllAuthenticationTypes=1
+```
diff --git a/admin/access-control/organizations.md b/admin/access-control/organizations.md
@@ -3,9 +3,8 @@ title: Organization roles
 description: Learn how to manage organization roles.
 ---
 
-Like [User roles](user-roles.md), members of an
-[organization](../organizations.md) can be assigned different roles. There are
-two roles available:
+You can assign members of an [organization](../organizations.md) roles, which
+function like [user roles](users/user-roles.md). There are two roles available:
 
 <table>
     <thead>

diff --git a/admin/access-control/user-management.md → admin/access-control/users/index.md b/admin/access-control/user-management.md → admin/access-control/users/index.md
@@ -3,9 +3,8 @@ title: "User management"
 description: Learn how to add, delete and manage Coder users.
 ---
 
-[Site managers](/access-control/user-roles#site-manager-permissions) can create
-and manage users from the **Users** page, which is accessible at **Manage** >
-**Users**.
+[Site managers](user-roles#site-manager-permissions) can create and manage users
+from the **Users** page, which is accessible at **Manage** > **Users**.
 
 ## Creating a new user
 
@@ -26,6 +25,18 @@ which they can use with their email to access their new account. For increased
 security, Coder prompts the new user to change their password immediately after
 they log in.
 
+## Changing a user's role
+
+Coder comes with built-in [user roles](user-roles.md) that define what actions a
+user can take in the deployment.
+
+By default, all new users are assigned the **Member** role. These users can be
+upgraded to **Auditor** or **Site Manager** by another user with administrative
+privileges.
+
+To change a user's role, go to **Manage** > **Users**. Find the user and use the
+**Site Role** drop-down to change the assigned role.
+
 ## Deleting a user
 
 To delete a user:

diff --git a/admin/access-control/password-reset.md → admin/access-control/users/password-reset.md b/admin/access-control/password-reset.md → admin/access-control/users/password-reset.md
@@ -3,33 +3,41 @@ title: Password reset
 description: Learn how to reset Coder user passwords.
 ---
 
-To reset a user's password:
+This article walks you through resetting a user password, as well as resetting a
+site admin's password.
 
-1. Go to **Manage** > **Users**.
+## Resetting a user password
+
+To reset a non-site admin's password:
+
+1. Log into Coder as a site manager, and go to **Manage** > **Users**.
 1. Find the user whose password you want to reset and click the vertical
    ellipsis to the right.
 1. Click **Reset password**. Coder will display a temporary password that you
    can provide to the user. Click **Reset Password** to proceed with the reset.
 
-![Confirm password reset](../../assets/admin/reset-password.png)
+![Confirm password reset](../../../assets/admin/reset-password.png)
 
 When the user logs in using the temporary password, Coder will prompt them to
 change it.
 
-> You can only reset passwords for users using **built-in authentication**.
+> You can only reset passwords for users using **built-in authentication** using
+> the Coder UI.
 
 ## Resetting the site admin password
 
-If you need to reset the password for a site admin, you can do so using coderd's
-**reset-admin-password** command.
+If you need to reset the password for a site admin, you can do so using
+`coderd`'s **reset-admin-password** command.
 
-> You should have the
-> [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) dependency
-> installed from when you first set up Coder; if not, please sure to install it
-> before proceeding. If you are using Docker, follow
-> [these instructions](../../setup/docker#admin-password) instead.
+> This process requires the
+> [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) dependency,
+> which should have been installed when you first set up Coder; if not, please
+> sure to install it before proceeding.
+>
+> If you are using Docker, follow
+> [these instructions](../../../setup/docker#admin-password) instead.
 
-To reset the password, run the following in the terminal:
+To reset the site admin password, run the following in the terminal:
 
 ```console
 # point to the coder namespace

diff --git a/admin/access-control/user-roles.md → admin/access-control/users/user-roles.md b/admin/access-control/user-roles.md → admin/access-control/users/user-roles.md
@@ -572,12 +572,3 @@ roles, but a summary of the roles are:
         </tr>
     </tbody>
 </table>
-
-## Changing a user's role
-
-By default, all new users are assigned the **Member** role. These users can be
-upgraded to **Auditor** or **Site Manager** by another user with administrative
-privileges.
-
-To change a user's role, go to **Manage** > **Users**. Find the user and use the
-**Site Role** drop-down to change the assigned role.
diff --git a/assets/admin/reset-password.png b/assets/admin/reset-password.png
diff --git a/guides/troubleshooting/admin-pwd.md b/guides/troubleshooting/admin-pwd.md
@@ -4,7 +4,7 @@ description: Learn how to resolve issues with resetting your admin password.
 ---
 
 When
-[resetting your Coder admin password](../../admin/access-control/password-reset.md#resetting-the-site-admin-password)
+[resetting your Coder admin password](../../admin/access-control/users/password-reset.md#resetting-the-site-admin-password)
 in the terminal, you may encounter the following error:
 
 ```console

diff --git a/manifest.json b/manifest.json
@@ -202,16 +202,21 @@
           "path": "./admin/access-control/index.md",
           "children": [
             {
-              "path": "./admin/access-control/user-roles.md"
+              "path": "./admin/access-control/manage.md"
             },
             {
               "path": "./admin/access-control/organizations.md"
             },
             {
-              "path": "./admin/access-control/password-reset.md"
-            },
-            {
-              "path": "./admin/access-control/user-management.md"
+              "path": "./admin/access-control/users/index.md",
+              "children": [
+                {
+                  "path": "./admin/access-control/users/user-roles.md"
+                },
+                {
+                  "path": "./admin/access-control/users/password-reset.md"
+                }
+              ]
             }
           ]
         },

diff --git a/setup/installation.md b/setup/installation.md
@@ -148,7 +148,7 @@ kubectl config set-context --current --namespace=coder
    These are the credentials you need to continue setup using Coder's web UI.
 
 > If you lose your admin credentials, you can use the
-> [admin password reset](../admin/access-control/password-reset.md#resetting-the-site-admin-password)
+> [admin password reset](../admin/access-control/users/password-reset.md#resetting-the-site-admin-password)
 > process to regain access.
 
 ## Logging