nebari-dev · iameskild · Feb 28, 2022 · Feb 22, 2022 · Feb 22, 2022 · Feb 25, 2022
diff --git a/docs/source/images/keycloak_add_users.png b/docs/source/images/keycloak_add_users.png
diff --git a/docs/source/images/keycloak_groups.png b/docs/source/images/keycloak_groups.png
diff --git a/docs/source/images/keycloak_master_login.png b/docs/source/images/keycloak_master_login.png
diff --git a/docs/source/images/keycloak_new_group1.png b/docs/source/images/keycloak_new_group1.png
diff --git a/docs/source/images/keycloak_new_group2.png b/docs/source/images/keycloak_new_group2.png
diff --git a/docs/source/images/keycloak_new_group3.png b/docs/source/images/keycloak_new_group3.png
diff --git a/docs/source/images/keycloak_root_user_account_security.png b/docs/source/images/keycloak_root_user_account_security.png
diff --git a/docs/source/images/keycloak_root_user_manage_account.png b/docs/source/images/keycloak_root_user_manage_account.png
diff --git a/docs/source/images/keycloak_root_user_update_password.png b/docs/source/images/keycloak_root_user_update_password.png
diff --git a/docs/source/installation/login.md b/docs/source/installation/login.md
@@ -1,58 +1,87 @@
 # Login
 
-Keycloak is the name of the open source user management software that's automatically deployed within QHub. It's used to store the database of all users in your QHub site, and can provide connectivity to other services such GitHub/Auth0 single-sign on.
+[Keycloak](https://www.keycloak.org/) is the name of the open-source user management software that's automatically deployed within QHub. It's used to store the database of all users in your QHub instance, and can provide connectivity to other services such as GitHub/Auth0 single-sign-on.
 
-If you ran `qhub init` to create your `qhub-config.yaml` configuration file in the [Usage](usage.md) step, you will have been provided with a `random password for Keycloak root user`.
+If you ran `qhub init` to create your `qhub-config.yaml` configuration file as detailed in the [Usage guide](usage.md), you will have been provided with a `random password for Keycloak root user`. **The password will also be visible in the `qhub-config.yaml` file under the `security.keycloak.initial_root_password` field**.
 
-The password will also be visible in the `qhub-config.yaml` file under the `security.keycloak.initial_root_password` field.
+The `root` Keycloak user is only able to login and manage the Keycloak identity management section of QHub. It's not a user of the wider QHub data science platform.
 
-Note that when your QHub is first deployed, the password given at that location will be set for the root Keycloak user. If added or changed for subsequent deployments, that password value will have no effect.
+## Change Keycloak root password
 
-Please note the root Keycloak user is only able to login and manage the Keycloak identity management section of QHub. It's not a user of the wider QHub data science platform.
+After the inital deployment, it is **highly** recommended that you change the Keycloak `root` user password as soon as you can.
+> NOTE: From this point on, the `security.keycloak.initial_root_password` field in `qhub-config.yaml` has no effect. If you redeploy QHub it will not reset the password back to the old one (or anything else that might be in the field in your YAML file). We strongly recommend you delete this field.
 
-## Adding a QHub user
+To change the `root` user password, navigate to `https://myqhubsite.com/auth/admin/`, and login with the pasword provided.
 
-You will need to add a QHub user in order to login to your QHub platform. If you have chosen to use GitHub or Auth0 single-sign on, you must ensure the usernames you provide for new users in Keycloak match the usernames from GitHub/Auth0.
+![Root Login to Keycloak](../images/keycloak_master_login.png)
 
-### Add user from command line
+From there, click on the 'Root' dropdown in the top right of the screen, and select 'Manage account'.
 
-To make adding users easier for new QHub deployments, there is a QHub command that can help. It will only work if the initial_root_password for Keycloak has not yet been changed, so the value available in `qhub-config.yaml` is still correct.
+![Keycloak root user, manage account](../images/keycloak_root_user_manage_account.png)
 
-Run:
-```
-qhub keycloak -c qhub-config.yaml adduser bob pa55w0rd
-```
+Under 'Account Security' click 'Signing In'.
 
-This will create a user called bob with the initial password provided. Omit the password completely if you are using GitHub or Auth0.
+![Keycloak root user, account security](../images/keycloak_root_user_account_security.png)
 
-### Add user using Keycloak console
+In the Password box, click the 'Update' button. This will guide you through entering your existing root password, and then creating a new password.
 
-To add a QHub user from the web console for Keycloak, visit `https://myqhubsite.com/auth/admin/`
+![Keycloak root user, update password](../images/keycloak_root_user_update_password.png)
 
-(Switch 'myqhubsite.com' for the domain you provided for your QHub deployment.)
 
-![Root Login to Keycloak](../images/keycloak_master_login.png)
+## Adding a QHub user
 
-Login using the username `root` and the password provided for the initial Keycloak root password.
+You will need to add a QHub user in order to log in to your QHub platform. If you have chosen to use GitHub or Auth0 single-sign-on, you must ensure the 'Username' you provide for new users in Keycloak matches the usernames from GitHub or Auth0 respectively.
 
-All QHub users will be part of the `qhub` realm (a realm is a distinct identity provider and set of users in Keycloak). Note that the root user alone is a member of the `master` realm.
+### Add user using Keycloak console
 
-The qhub realm should be selected by default.
+To add a QHub user from the web console for Keycloak, visit <https://myqhubsite.com/auth/admin/>. Log in using the username `root`, as shown above.
+
+All QHub users will be part of the `qhub` realm (a realm is a distinct identity provider and set of users in Keycloak).
+> NOTE: The root user alone is a member of the `master` realm.
+
+The `qhub` realm should be selected by default.
 
 Click 'Users' along the left-hand side of the page.
 
 Click the 'Add user' button and you will see the new user form:
 
-![Add User to Keycloak](../images/keycloak_adduser.png)
+![Keycloak add user tab screenshot - new user form ](../images/keycloak_add_users.png)
+
+There are three fields, outlined above, which should be filled out. These are 'Username', 'Email', and 'Groups'.
 
-Enter the name you would like for the user then click Save.
+Depending on the authentication provider selected ('password', 'GitHub' or 'Auth0'), the values entered into the 'Username' field will differ slightly. The following table outlines those differences:
 
-Once the user has been created, you can set a password (not needed for GitHub/Auth0 login):
+|   | Password  | GitHub  | Auth0   |
+|---|---|---|---|
+| Username | *unique username*  | *GitHub username* | *Email to login with* |
 
-![Set Password in Keycloak](../images/keycloak_user_password.png)
+Once the 'Username' field has been updated, please add a valid email address in the 'Email' field.
+> NOTE: Although not required, users may not be able to log into Graphana if this field is not properly set.
+
+Lastly, associate the user with one or more of the 'Groups'. Out of the box, QHub is deployed with the following groups: 'admin', 'analyst', and 'developer' (see below for more information about 'Groups').
+
+Enter the name you would like for the user then click 'Save'.
+
+Once the user has been created, you can set a password
+> NOTE: not needed for GitHub/Auth0 based authentication.
+
+![Keycloak add user > credentials tab screenshot - set password](../images/keycloak_user_password.png)
 
 It's best to unset the 'Temporary' on/off button so the user won't be forced to change the password on first login.
 
+### Add user from command line
+
+To make adding users easier for new QHub deployments, there is a QHub command that can help. It will only work if the initial_root_password for Keycloak has not yet been changed, so the value available in `qhub-config.yaml` is still correct.
+
+Run:
+
+```shell
+qhub keycloak -c qhub-config.yaml adduser <username> <password>
+```
+
+This will create a user  `<username>` with the initial password provided. Omit the password completely if you are using GitHub or Auth0.
+> NOTE: This will also add the user to 'analyst' group.
+
 ## Login to QHub
 
 Your new user can now log into QHub proper (not Keycloak's admin console).
@@ -61,30 +90,34 @@ Visit `https://myqhubsite.com/` (or whatever domain you have chosen for your QHu
 
 Click 'Sign in with Keycloak'.
 
-![Login to Keycloak](../images/keycloak_qhub_login.png)
+![QHub - Log in to Keycloak page](../images/keycloak_qhub_login.png)
 
-Enter the username and password you chose when you added a user to QHub above.
+If you chose GitHub or Auth0 login, click the 'GitHub' button to be taken to a GitHub login page and single-sign-on from there (as shown in the screenshot above). Otherwise, if you choose 'Password` based authentication, enter the username and password you chose when you added a user to QHub above.
 
-If you chose GitHub or Auth0 login, click the 'GitHub' button to be taken to a GitHub login page and single-sign on from there.
+## Groups
 
-# Change Keycloak root password
+Groups represent a collection of users that perform similar actions and therefore require the similar permissions. By default, QHub is deployed with the following groups: 'admin', 'developer', 'analyst' and 'viewer'.
 
-You should change your root password for Keycloak now that you've got things running.
+| Group | Access to QHub Resources |
+|---|---|
+| 'admin' | Conda-Store Admin <br> Dask Admin <br> Jupyterhub Admin <br> Graphana Admin |
+| 'analyst' | Conda-Store Developer <br> Jupyterhub Developer <br> Graphana Viewer |
+| 'developer' | Conda-Store Developer <br> Dask Developer <br> Jupyterhub Developer <br> Graphana Developer |
 
-Back in `https://myqhubsite.com/auth/admin/` you can click on the 'Root' dropdown in the top right of the screen, and select 'Manage account'.
+To create new groups or modify (or delete) existing groups, log in as `root` and click 'Groups' on the left-hand side.
 
-Under 'Account Security' click 'Signing In'.
+As an example, we create a new group named `conda-store-manager` and this group will have administrator access to the Conda-Store service.
 
-In the Password box, click the 'Update' button. This will guide you through entering your existing root password, and then entering a new password.
+![Keycloak group tab screenshot - user goups view](../images/keycloak_groups.png)
 
-From this point, the `security.keycloak.initial_root_password` field in `qhub-config.yaml` has no effect. If you redeploy QHub it will not reset the password back to the old one (or anything else that might be in the field in your YAML file). You can delete that line from your YAML file if you wish.
+To create a new group, click 'New' in the upper-right hand corner. First, give the new group an appropriate name.
 
-# Groups
+![Keycloak add group form - name field set to conda-store-manager](../images/keycloak_new_group1.png)
 
-Add Groups in the same Keycloak backend as you can add users - that's, login as `root` to `https://myqhubsite.com/auth/admin/`. Click Groups on the left-hand side.
+Then under 'Role Mapping', add the appriopriate 'Client Roles' as needed; there should be no need to update the 'Realm Roles'. In this example, the new group only has one mapped role however it's possible to attached multiple 'Client Roles' to a single group.
 
-Groups named `users` and `admin` will have been created automatically by QHub. All users will be added to the `users` group automatically when you create them. You should never remove them from the `users` group as that group must contain all users.
+![Keycloak group conda-store-manager form - role mappings tab focused with expanded client roles  dropdown](../images/keycloak_new_group2.png)
 
-Members of `admin` group will have access to admin features within QHub.
+![Keycloak group conda-store-manager form - role mappings tab focused ](../images/keycloak_new_group3.png)
 
-Neither `users` nor `admin` groups should ever be deleted.
+Once complete, return to the 'Users' section in the dashboard and add the relevant users to this newly created group.