Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update the login/Keycloak docs page #1289

Merged
merged 2 commits into from
May 24, 2022
+62 −45
Merged

Update the login/Keycloak docs page #1289

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
72caf2e
Update the login/Keycloak docs page
gabalafou May 16, 2022
221eaf2
Apply suggestions from code review
gabalafou May 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# QHub docs

We use `nox` to build the to docs.
We use `nox` to build the docs.

```
pip install nox
Expand Down
89 changes: 50 additions & 39 deletions docs/source/installation/login.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,48 @@
# Login

[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.
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 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 `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.
As with many user admin tools, in Keycloak you start with an initial login (`root`) that has the ability to administer and create new users. The `root` user is a Keycloak-specific user. It can only be used to login and manage the Keycloak identity management section of QHub. It's not a user of the wider QHub data science platform.

## Change Keycloak root password

`root`'s password is generated by the `qhub init` command. If you ran this command while following the steps under [Usage](usage.md), you should have seen something like the following in the output:
gabalafou marked this conversation as resolved.
Show resolved Hide resolved

```
Securely generated default random password=<alphanumeric-string> for Keycloak root user
```

The init command also saves the root user password to your `qhub-config.yaml` configuration file under the following path:

`security.keycloak.initial_root_password`

After the initial deployment, it is **highly** recommended that you change the Keycloak `root` user password as soon as you can.

> NOTE: Once you change the root password you will not be able to [add users from the command line](login.md#add-user-from-the-command-line)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why change the root password? Is it because the yaml config file gets checked in to version control?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not needed but is advised, I agree that this text does not reflect this idea correctly. Another thing that can be done is changing the Keycloak password to use qhub secrets (though I haven't tested it yet in this case).


> 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.
> old one (or anything else that might be in the field in your YAML file). We strongly recommend you delete this field to prevent later confusion.

1. To change the `root` user password, your QHub's instance admin dashboard i.e <https://myqhubsite.com/auth/admin/>, and log in with the password provided.
1. To change the `root` user password, go to your QHub instance's admin dashboard—e.g., something like <https://myqhubsite.com/auth/admin/>—and log in with the password provided.

![QhHub admin view - Root Login to Keycloak form](../images/keycloak_master_login.png)
![QHub admin view - Root Login to Keycloak form](../images/keycloak_master_login.png)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we don't indent here, then Sphinx will not continue the list numbering—it will render the "2." below as "1."


2. From there, click on the 'Root' dropdown in the top right of the screen, and select 'Manage account'.

![Keycloak root user page - manage account tab selected](../images/keycloak_root_user_manage_account.png)
![Keycloak root user page - manage account tab selected](../images/keycloak_root_user_manage_account.png)

3. Under 'Account Security' click 'Signing In'.

![Keycloak root user page - account security](../images/keycloak_root_user_account_security.png)
![Keycloak root user page - account security](../images/keycloak_root_user_account_security.png)
gabalafou marked this conversation as resolved.
Show resolved Hide resolved

4. In the Password section, click the 'Update' button. This will guide you through entering your existing root password, and then creating a new password.

![Keycloak root user page - account security, update password](../images/keycloak_root_user_update_password.png)
![Keycloak root user page - account security, update password](../images/keycloak_root_user_update_password.png)
gabalafou marked this conversation as resolved.
Show resolved Hide resolved

## Adding a QHub user

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.
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 value you enter in Keycloak under 'Username' exactly matches the usernames from GitHub or Auth0, respectively.

### Add user using Keycloak console

Expand All @@ -46,43 +54,45 @@ All QHub users will be part of the `qhub` realm (a realm is a distinct identity

The `qhub` realm is selected by default, we strongly recommend leaving it as is.

Steps to create a new user:

1. Click 'Users' along the left-hand side of the page.

2. Click the 'Add user' button and you will see the new user form:

![Keycloak add user tab screenshot - new user form ](../images/keycloak_add_users.png)
![Keycloak add user tab screenshot - new user form](../images/keycloak_add_users.png)

3. Fill out the three fields, outlined above. These are 'Username', 'Email', and 'Groups'.
3. Fill out the three fields outlined above. These are 'Username', 'Email', and 'Groups'. (We explain these fields below.) 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
4. Username. 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:

| | Password | GitHub | Auth0 |
| -------- | ----------------- | ----------------- | --------------------- |
| Username | *unique username* | *GitHub username* | *Email to login with* |
| | Password | GitHub | Auth0 |
| -------- | ----------------- | ----------------- | --------------------- |
| Username | *unique username* | *GitHub username* | *Email to login with* |

Once the 'Username' field is updated, please add a valid email address in the 'Email' field.
5. Once the 'Username' field is updated, please add a valid email address in the 'Email' field.

> NOTE: Although not required, users may not be able to log into Grafana if this field isn't properly set.
> NOTE: Although not required, users may not be able to log in to Grafana if this field isn't 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 the
6. 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 the
[Groups](./login.md#groups) section below for more details).

Enter the name you would like for the user then click 'Save'.
7. Click save.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be honest, I don't love the indentation that these markdown lists create. I wonder if it would be better to reformat as:

Step 1. Blah blah blah

![some screenshot](url-to-screenshot.jpeg)

Step 2.

in order to avoid the indentation.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

feel free to adopt it, we can always switch back if needed 🙂


Once the user is 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.
It's best to put the 'Temporary' toggle in the 'OFF' position. Otherwise the user will be forced to change the password on first login.

### Add user from the command line

To make adding users easier for new QHub deployments, there is a QHub command that can help.

> NOTE: If you changed the initial_root_password for Keycloak this method will not work.
> NOTE: If you [changed the initial_root_password for Keycloak](login.md#change-keycloak-root-password) this method will not work.

> NOTE: This method is primarily used by developers as a quick workaround.

Expand All @@ -94,46 +104,47 @@ 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.
> NOTE: This will also add the user to the 'analyst' group.

## Login to QHub

Your new user can now log into the main QHub dashboard (not Keycloak's admin console).
Your new user can now log in to the main QHub dashboard (not Keycloak's admin console).

Visit <https://myqhubsite.com/> (or whatever domain you have chosen for your QHub).

Click 'Sign in with Keycloak'.
Click 'Sign in with Keycloak'. This will take you to the login form:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't love the two-step login, even if it's used at places as preeminent as Gmail. I wonder if the button should say "Sign in with Keycloak" or just "Sign In".

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

well, that's customizable, but I don't see a good enough reason for the change. But is open for discussion 🙂


![QHub - Log in to Keycloak page](../images/keycloak_qhub_login.png)

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.
chose 'Password' based authentication, enter the username and password you chose when you added a user to QHub above.

## Groups

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'.
Groups represent a collection of users that perform similar actions and therefore require similar permissions. By default, QHub is deployed with the following groups: 'admin',
'developer', 'analyst' and 'viewer' (in roughly descending order of power).
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why isn't 'viewer' in the table below?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we don't even have the viewer anymore, but I would need to do a fresh deploy to be sure.


| 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 |
| 'admin' | Conda-Store Admin <br> Dask Admin <br> Jupyterhub Admin <br> Grafana Admin |
| 'developer' | Conda-Store Developer <br> Dask Developer <br> Jupyterhub Developer <br> Grafana Developer |
| 'analyst' | Conda-Store Developer <br> Jupyterhub Developer <br> Grafana Viewer |

To create new groups or modify (or delete) existing groups, log in as `root` and click 'Groups' on the left-hand side.

As an example, we create a new group named `conda-store-manager` and this group will have administrator access to the Conda-Store service.
As an example, we create a new group named `conda-store-manager`. This group will have administrator access to the Conda-Store service.

![Keycloak group tab screenshot - user goups view](../images/keycloak_groups.png)
![Keycloak groups tab screenshot - user groups view](../images/keycloak_groups.png)

To create a new group, click 'New' in the upper-right hand corner. First, give the new group an appropriate name.

![Keycloak add group form - name field set to conda-store-manager](../images/keycloak_new_group1.png)

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.
Then under 'Role Mapping', add the appriopriate 'Client Roles' as needed; there should be no need to update the 'Realm Roles'.

![Keycloak group conda-store-manager form - role mappings tab focused with expanded client roles dropdown](../images/keycloak_new_group2.png)

![Keycloak group conda-store-manager form - role mappings tab focused with expanded client roles dropdown](../images/keycloak_new_group2.png)
In this example, the new group only has one mapped role (`conda_store_admin`); however it's possible to attached multiple 'Client Roles' to a single group.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The relationship between groups and roles here is not at all intuitive if you don't have a background in user permission systems, I think.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree this is a tough topic as some of those groups as acting as a permission system and some as user "groups" only. c.c @costrouc here to better elucidate this if needed.


![Keycloak group conda-store-manager form - role mappings tab focused ](../images/keycloak_new_group3.png)

Expand Down
4 changes: 2 additions & 2 deletions docs/source/installation/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

## Cloud Deployment

Great, you've gone through the `qhub` [Installation](installation.md) and [Setup Initialization](setup.md) steps, and have ensured that all the necessary environment variables have
been properly set, it is time to deploy QHub from your terminal.
Great, you've gone through the [Installation](installation.md) and [Setup Initialization](setup.md) steps, and have ensured that all the necessary environment variables have
been properly set. Now it is time to deploy QHub from your terminal.

### Initialize configuration

Expand Down
12 changes: 9 additions & 3 deletions docs/source/introduction/qhub-101.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# QHub 101

QHub is an open source framework that allows data science team to initialize and maintain their data science stack on cloud. QHub makes use of Terraform to deploy JupyterHub,
QHub is an open source framework that allows data science teams to initialize and maintain their data science stack on the cloud. QHub makes use of Terraform to deploy JupyterHub,
JupyterLab, Dask, and Conda environments on Kubernetes clusters across all major cloud providers.

Through QHub, the deployment is managed using a single configuration file and is powered by GitHub Actions. This allows teams to build and maintain cost-effective and scalable
Expand Down Expand Up @@ -39,8 +39,14 @@ To learn more about the nitty gritty of QHub's internal architecture, refer to t

QHub can be easily installed using either `conda` or `pip`.

- `conda`: `conda install -c conda-forge qhub`
- `pip`: `pip install qhub`
- conda:
```sh
conda install -c conda-forge qhub
```
- pip:
```sh
pip install qhub
```

QHub CLI will be installed automatically as part of the install process. After installation, QHub CLI can be used to deploy and manage your environment on HPC, cloud, on-premises
or even locally. To install QHub locally, follow the [testing](../dev_guide/testing.md) section.
Expand Down