User authentication and access

Authentication vs. Authorization

• Authentication allows your users to prove who their are.

• Authorization gives users certain permissions depending on their identity (such as “access to your hub”, or “administrative privileges”).

Authentication

Users can prove who they are by logging in via an authentication provider. Currently, the following providers are supported:

CILogon

An extremely popular provider for various institutional logins, Google accounts (including @gmail.com accounts), Microsoft accounts, etc. This is our primary authentication provider. It can support allowing users from multiple institutions to login as well, which is very helpful. 2i2c can manage CILogon using the JupyterHub CILogonOAuthenticator.

Some key terms about CILogon authentication worth mentioning:

Identity Provider : The authentication service available through the CILogon connection.

When a user logs in via CILogon, they are first presented with a list of various institutions and organizations that they may choose from (Australia National University, UC Berkeley, etc.).

The available identity providers are members of InCommon, a federation of universities and other organizations that provide single sign-on access to various resources.

Note

Check if a community’s login provider is available on CILogon, by going to https://cilogon.org/idplist and filter after its name.

User account : Within an institution, each user is expected to have their own user account (e.g. myname@berkeley.edu). This is the account that is used to give somebody an ID on their JupyterHub. This is entered on an Identity Provider’s login screen.

GitHub

Extremely popular community of people creating, publishing and collaborating on code. Accounts are free, and many people already have them especially since the target community for most hubs are people who also write some kind of code. We can setup GitHub authentication so you can either manage a list of specific GitHub handles in the JupyterHub admin panel, or so that members of a specific GitHub organisation or team are automatically authorised to use the hub.

<a different provider>

We may be able to support other authentication providers, depending on your specific needs and the provider’s complexity. However, this should be used as a last resort and will come with an increase in management cost, to offset the extra engineering complexity. Please reach out to us if none of those above work for your use-case.

We will ask you what provider you want when we set up the hub. We can change the provider after the fact, but only if absolutely necessary.

Authorization

Not everyone who can authenticate is granted access to the hub - that would mean everyone with a @gmail.com account can log in if you use Google as your authentication provider! Instead, we support multiple ways for hub admins to specify which users are authorized to be on the hub.

Authorizing regular users : Currently, there are only three supported methods for authorizing regular users:

1. Manually add users via the admin panel in JupyterHub

2. (Google only) Allow all users who are logged in via a particular domain - so you can allow access to anyone who is part of your organization or educational institution.

3. (GitHub only) Allow all users who are members of a specific organisation or team. This approach gives you fine-grained control over who has access to the hub inline with your access policies on GitHub

Tip

If your hub has a range of different machine sizes or environments to choose from, we can also configure which users can see which options based on their GitHub team membership! For example, a team like @MyCoolOrg/all-users might be able to see Small and Medium sized machines, but the @MyCoolOrg/advanced-users team can additionally have access to the Large and GPU machines. You can manage these teams within GitHub.

Speak to a Hub Engineer about enabling this feature for your hub.

Authorizing admin users : Admin users are authorized in a hub’s YAML config, with support from 2i2c staff.

Manage users from the administrator panel

The Administrator Panel can be used to maintain the list of users who are authorized to use your hub. You can access this panel by clicking the ‘Admin’ button in the top bar in your hub control panel. Alternatively, you can go to this URL in your browser: https://<your-hub-url>/hub/admin

To add users

1. Click the Add Users button. The Add Users dialog box will pop up.

2. Add one or more users, and hit the Add Users button to authorize all the users you just added.

Fig. 5 The Add Users button in the Administrator Panel.

Fig. 6 Fill in usernames and optionally make them administrators. You can add multiple users at once by putting a username on each line.

Remove users from a hub

You can revoke a user’s access to the JupyterHub by removing them from the allowed users list, using the admin panel.

1. Find the name of the user in your admin panel. If they have a running server, click the Stop server button to stop their running server.

2. Click the Delete user button for this user. Confirm the deletion in the dialog box that pops up.

After this, the user would not be able to log in. However, their files will not be deleted - if you add them later, their files will still be present.

Finding usernames

Access is granted or revoked based on usernames, and these depend on the kind of authentication provider your hub is using. In general, it matches whatever the visible ‘username’ in your authentication provider is. The table below lists the available providers, and how to determine their username.

Provider	Username
Google	Email address
GitHub	GitHub user name

Debug user authentication issues

If users are running into strange errors when they log in (for example CILogon error pages that say “Looks like something went wrong!”), ask them to try these steps in debugging:

1. Try logging in with an incognito window. This will help determine if their issue is due to some cookie / cache that is stored on their machine.

2. Ask them to clear their cookies / cache for all CILogon websites. For example, here are the Google Chrome instructions to clear cookies.

3. If using CILogon, double-check that they’ve signed in with the correct account, and ask them to switch accounts if needed.