adopt myst

run rst2myst, with minimal manual formatting fixes

docs/howto/auth/firstuse.md

@@ -0,0 +1,79 @@
+(howto-auth-firstuse)=
+
+# Let users choose a password when they first log in
+
+The **First Use Authenticator** lets users choose their own password.
+Upon their first log-in attempt, whatever password they use will be stored
+as their password for subsequent log in attempts. This is
+the default authenticator that ships with TLJH.
+
+## Enabling the authenticator
+
+:::{note}
+the FirstUseAuthenticator is enabled by default in TLJH.
+:::
+
+1. Enable the authenticator and reload config to apply the configuration:
+
+```bash
+sudo tljh-config set auth.type firstuseauthenticator.FirstUseAuthenticator
+sudo tljh-config reload
+```
+
+Users who are currently logged in will continue to be logged in. When they
+log out and try to log back in, they will be asked to provide a username and
+password.
+
+## Users changing their own password
+
+Users can change their password by first logging into their account and then visiting
+the url `<your_server_ip>/hub/auth/change-password`.
+
+## Allowing anyone to log in to your JupyterHub
+
+By default, you need to manually create user accounts before they will be able
+to log in to your JupyterHub. If you wish to allow **any** user to access
+the JupyterHub, run the following command.
+
+```bash
+tljh-config set auth.FirstUseAuthenticator.create_users true
+tljh-config reload
+```
+
+## Resetting user password
+
+The admin can reset user passwords by _deleting_ the user from the JupyterHub admin
+page. This logs the user out, but does **not** remove any of their data or
+home directories. The user can then set a new password by logging in again with
+their new password.
+
+1. As an admin user, open the **Control Panel** by clicking the control panel
+   button on the top right of your JupyterHub.
+
+   ```{image} ../../images/control-panel-button.png
+   :alt: Control panel button in notebook, top right
+   ```
+
+2. In the control panel, open the **Admin** link in the top left.
+
+   ```{image} ../../images/admin/admin-access-button.png
+   :alt: Admin button in control panel, top left
+   ```
+
+   This opens up the JupyterHub admin page, where you can add / delete users,
+   start / stop peoples' servers and see who is online.
+
+3. **Delete** the user whose password needs resetting. Remember this **does not**
+   delete their data or home directory.
+
+   ```{image} ../../images/auth/firstuse/delete-user.png
+   :alt: Delete user button for each user
+   ```
+
+   If there is a confirmation dialog, confirm the deletion. This will also log the
+   user out if they were currently running.
+
+4. Re-create the user whose password needs resetting within that same dialog.
+
+5. Ask the user to log in again with their new password as usual. This will be their
+   new password going forward.