Authentication is about identity, while authorization is about permissions. In
this section you will learn how to configure both. As an example, you can
configure authentication using GitHub accounts and restrict what users are
authorized based on membership of a GitHub organization.
Before configuring this, you should have setup HTTPS.
JupyterHub by default ships with only one source of authentication:
PAM, the underlying unix authentication of the host system.
To use other sources of authentication, choose one authenticator
class to use.
Several such classes are already available in the hub image through installed
JupyterHub provides a base class,
that all other authenticator classes are supposed to derive from. By configuring
this base class, we influence the behavior of the derived class as well.
We configure JupyterHub to use our chosen authenticator class and the
authenticator class itself through this Helm chart’s
As all authenticator classes derive from the Authenticator base class, they
share some configuration options. Below are some common configuration options,
but please refer to the official configuration
reference for more
Some authenticator classes may have dedicated logic in addition this this to
In the above configuration, we have configured three things:
JupyterHub is instructed to use the dummy authenticator to login (only appropriate for testing purposes),
anyone will be able to login with username user1-4 and the password a-shared-secret-password
user1 and user2 will have admin permissions, while user3 and user4 will be regular users.
If you have configured authentication with GitHub for example, the page
/hub/login will feature a single orange button that users are to press to
login. If you want to bypass this screen and send users directly to GitHub login, you can
set auto_login to true.
If you want JupyterHub to persist often sensitive information received as part
of logging in, you need to enable it and provide one or more keys for encryption
The recommended way of doing so for this Helm chart is to configure
with keys rather than setting an environment variable.
For more information, see JupyterHub’s own
about authentication state.
Below we provide a few configuration examples of commonly used authentication
classes. For more details about them, please see the authentication class’ own
JupyterHub’s oauthenticator has
support for enabling your users to authenticate via a third-party OAuth2
identity provider such as GitHub, Google, and CILogon. All of these will
require an OAuth2 client id and client secret.
For details on how to acquire a client id and client secret, please refer to
GitHub is the largest hosting service for git repositories. It is free to create
an account at GitHub, and relatively straightforward to set up OAuth credentials
so that users can authenticate with their GitHub username/password.
To create OAuth credentials on GitHub, follow these steps:
Click your profile picture -> settings -> developer settings
Make sure you’re on the “OAuth Apps” tab, then click “New OAuth App”
Fill out the forms (you’ll need your hub address) and generate your
To enable GitHub authentication, your config.yaml should contain the following
Make sure that the oauth_callback_url matches the one you set in GitHub.
To restrict access to the members of one or more GitHub organizations, amend
your previous configuration with these parts.
While you can set other scopes than read:user as described in GitHub OAuth scopes documentation, we recommend read:user.
With read:user, the user will be requested to permit JupyterHub to read their profile data. The benefit of this choice is that it won’t require configuration by the GitHub organizations’ admins by by its members.
Google authentication is used by many universities (it is part of “G Suite”).
If your institution is a G Suite customer that
integrates with Google services such as Gmail, Calendar, and Drive, you can
authenticate users to your JupyterHub using Google for authentication.
Log in to the Google API Console.
Select a project > Create a project… and set ‘Project name’. This is a
short term that is only displayed in the console. If you have already
created a project you may skip this step.
Type “Credentials” in the search field at the top and click to access the
Click “Create credentials”, then “OAuth client ID”. Choose “Application
type” > “Web application”.
Enter a name for your JupyterHub instance. You can give it a descriptive
name or set it to be the hub’s hostname.
Set “Authorized redirect URIs” to be your hub’s URL followed by
/hub/oauth_callback. For example,
When you click “Create”, the console will generate and display a Client ID
and Client Secret. Save these values.
Type “consent screen” in the search field at the top and click to access the
OAuth consent screen. Here you will customize what your users see when they
login to your JupyterHub instance for the first time. Click Save when you
Update your Helm chart’s configuration (config.yaml) to look like this.
login_service: Your university
The oauth_callback_url key is set to the authorized redirect URI you specified
earlier. Set hosted_domain to your institution’s domain name. The value of
login_service is a descriptive term for your institution that reminds your
users which account they are using to login.
Please see CyberInfrastructure Logon’s website for
more information about what kind of identity is managed by CILogon.
Based on this
you may need to also set the following.
Globus Auth is a foundational identity and access management platform
service designed to address unique needs of the science and engineering
community. Globus provides cloud-based services for reliably moving,
sharing, publishing and discovering data, whether your files live on a
supercomputer, lab cluster, tape archive, public cloud, or your own
laptop. Start a Globus app here!
Azure Active Directory
is an identity provider from Microsoft Azure. Apart from needing a OAuth2
client id and client secret, you will also need a tenant id.
Auth0 is a commercial provider of identity management.
OpenID Connect is an identity layer on top of the
OAuth 2.0 protocol, implemented by various servers and
services. While OpenID
Connect endpoint discovery is not supported by oauthentiator, you can still
configure JupyterHub to authenticate with OpenID Connect providers by specifying
all endpoints in the GenericOAuthenticator class.
Below is an example on how you can configure the GenericOAuthenticator to
authenticate against Auth0.
KeyCloak is an open source based provider of
identity management that you can host yourself. Below is an example on how you
can configure the GenericOAuthenticator class to authenticate against a KeyCloak
To configure an OpenID Connect client, see KeyCloak’s own
JupyterHub supports LDAP and Active Directory authentication. Read the
documentation for a full explanation of the available parameters.
Only server_address and bind_dn_template are required, so a minimal
configuration would look like this.
Another example is provided below, equivalent to the example given in the