Configure Keycloak

Introduction to Keycloak

Keycloak is the open-source identity and access management tool that comes standard with Nebari. It is used as a centralized location to add new users, create user groups and update roles and permissions. Keycloak can be configured to work with your existing identity provider services such as GitHub, Auth0 and many others.

ℹ️note

Although Nebari allows you to connect with GitHub and Auth0 from the nebari-config.yaml, any identity provider that Keycloak can connect to will work. See these Keycloak docs for more information.

In Keycloak, as with many admin tools, you start with an initial login user (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 log in and manage the Keycloak identity management section of Nebari.

🔥warning

Trying to log in to JupyterHub using this root user will fail. Currently, this is the only user with access to the Keycloak administration console, therefore anyone wanting to add users, new groups, etc., will need to use this user and login here: https://{your-nebari-domain}/auth/admin/.

Change Keycloak root password

🔥warning

Once you change the root password you will not be able to add users from the command line

root's password is generated by the nebari init command. If you ran this command while following the steps under Installing Nebari, you should have seen something like the following in your terminal output:

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

The init command also saves the root user password to your nebari-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 possible.

1. To change the root user password, go to your Nebari instance's admin dashboard - e.g., something like https://{your-nebari-domain}/auth/admin/ and log in with the root password provided.

   

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

   

3. Under Account Security click Signing In.

   

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.

   

🔥warning

The security.keycloak.initial_root_password field in nebari-config.yaml has no effect after changing the root password. If you redeploy Nebari 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 to prevent later confusion.

Adding a Nebari user

No Nebari user is created for you during deployment, you will need to add a Nebari user manually in order to log in to JupyterHub and access the other Nebari services.

If you have chosen to use GitHub, Auth0 or any other single-sign-on, you must ensure the value you enter in Keycloak under Username exactly matches the username from GitHub or Auth0, respectively.

Add user using Keycloak admin console

To add a Nebari user from the Keycloak admin console, visit https://{your-nebari-domain}/auth/admin/ and login using the username root, as shown above.

Keycloak uses realms to separate their permission scopes under the Keycloak admin console. The realm for Nebari is nebari and all Nebari users will be part of the nebari realm, on the other hand, the realm for the Keycloak admin console is master.

ℹ️note

The root user alone is a member of the master realm. For security best practices, we recommend that you minimize the number of users in the master realm. See the Master realm Keycloak documentation for more information.

The nebari 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:

   

3. Fill out the three fields outlined above. These are Username, Email, and Groups. (See explanation below). Then click save.

   • 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

   • Once the Username field is updated, add a valid email address in the Email field.

ℹ️note

Although not required, users may not be able to log in to Grafana if this field isn't properly set.

• Associate the user with one or more of the Groups. Out of the box, Nebari is deployed with the following groups: admin, developer and analyst (see the Roles x Groups section below for more details).

4. Click Save.

If you are using the password authentication provider, you will also need to define a password for the user. 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.

ℹ️note

If using Auth0, GitHub or any other identity provider, the password field is not required.

Add user from the command line

🔥warning

If you changed the initial root password for Keycloak this method will not work.

To make adding users easier for new Nebari deployments, we've created a CLI command to help you.

nebari keycloak -c nebari-config.yaml adduser <username> <password>

This will create a new user <username> under the analyst group, with the initial password provided. Omit the password completely if you are using GitHub or Auth0. It will also add a placeholder email (i.e. username@your-domain) to the Email field.

Login to Nebari

Your new user can now log in to Nebari, visit your provided Nebari domain URI which will take you to the login form page and follow the How-to login in to Nebari and start a server.

In-depth look at Roles and Groups

Groups represent a collection of users that perform similar actions and therefore require similar permissions. By default, Nebari is deployed with the following groups: admin, developer, and analyst (in roughly descending order of permissions and scope).

❗️info

Users in a particular group will also get access to that groups shared folder. So if user A belongs to the developer, they will also have access to the ~/shared/developer folder. This also applies to new groups that you create.

Roles on the other hand represent the type or category of user. This includes access and permissions that this category of user will need to perform their regular job duties. The differences between groups and roles are subtle. Particular roles (one or many), like conda_store_admin, are associated with a particular group, such as admin and any user in this group will then assume the role of conda_store_admin.

❗️info

These roles can be stacked. This means that if a user is in one group with role conda_store_admin and another group with role conda_store_viewer, this user ultimately has the role conda_store_admin.

Group	Access to Nebari Resources	Roles	Permissions Description
analyst	Conda-Store Jupyterhub Argo Workflows Grafana	conda_store_developer jupyterhub_developer argo_viewer grafana_viewer	Default user permissions Access to start a server instance and generate JupyterHub access token. Read/write access to shared analyst folder group mount Read access to analyst and write access to personal conda-store namespace Read access to Argo-Workflows and Jupyter-Scheduler Inherent Grafana permissions from Grafana viewer scopes
developer	Conda-Store Dask Jupyterhub Argo Workflows Grafana Developer	conda_store_developer dask_developer jupyterhub_developer argo_developer grafana_developer	All of the above access, plus... Read access developer conda-store namespace Access to create Dask clusters. Read/write access to shared developer folder group mount Read/create access to Argo-Workflows and Jupyter-Scheduler Inherent Grafana permissions from Grafana editor scopes
admin	Conda-Store Dask Jupyterhub Argo Workflows Grafana	conda_store_admin dask_admin jupyterhub_admin argo_admin grafana_admin	All of the above access, plus... Read/write access to all conda-store available namespaces/environments. Access to Jupyterhub Admin page and can access JupyterLab users spaces Access to Keycloak and can add remove users and groups Inherent Grafana permissions from Grafana administrator scopes
superadmin	Conda-Store Dask Jupyterhub Argo Workflows Grafana	conda_store_superadmin dask_admin jupyterhub_admin argo_admin realm_admin (Keycloak) grafana_admin	All of the above access, plus... Delete (build and environment) access on conda-store Full access to Keycloak (realm) (same as root)

❗️info

Check Conda-store authorization model for more details on conda-store authorization.

⚠️caution

The role jupyterhub_admin gives users elevated permissions to JupyterHub and should be applied judiciously. As mentioned in the table above, a JupyterHub admin is able to impersonate other users and view the contents of their home folder. For more details, read through the JupyterHub documentation.

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. This group will have administrator access to the [Conda-Store service].

1. Click New in the upper-right hand corner under Groups.

• Then, give the new group an appropriate name.

2. Under Role Mapping, add the appropriate 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, conda_store_admin; however, it's possible to attach multiple Client Roles to a single group.

Once complete, return to the Users section in the dashboard and add the relevant users to this newly created group.