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 Python packages.
JupyterHub provides a base class, Authenticator, 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.
Authenticator
We configure JupyterHub to use our chosen authenticator class and the authenticator class itself through this Helm chart’s hub.config configuration.
hub.config
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 details.
Some authenticator classes may have dedicated logic in addition this this to authorize users.
hub: config: Authenticator: admin_users: - user1 - user2 allowed_users: - user3 - user4 # ... DummyAuthenticator: password: a-shared-secret-password JupyterHub: authenticator_class: dummy
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-4
a-shared-secret-password
user1 and user2 will have admin permissions, while user3 and user4 will be regular users.
user1
user2
user3
user4
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.
/hub/login
auto_login
true
hub: config: Authenticator: auto_login: 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 and decryption.
The recommended way of doing so for this Helm chart is to configure CryptKeeper with keys rather than setting an environment variable.
For more information, see JupyterHub’s own documentation about authentication state.
hub: config: Authenticator: enable_auth_state: true CryptKeeper: keys: - 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
Below we provide a few configuration examples of commonly used authentication classes. For more details about them, please see the authentication class’ own documentation.
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 oauthenticator’s documentation.
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 ID/Secret.
To enable GitHub authentication, your config.yaml should contain the following configuration:
config.yaml
hub: config: GitHubOAuthenticator: client_id: your-client-id client_secret: your-client-secret oauth_callback_url: https://your-jupyterhub-domain/hub/oauth_callback JupyterHub: authenticator_class: github
Make sure that the oauth_callback_url matches the one you set in GitHub.
oauth_callback_url
To restrict access to the members of one or more GitHub organizations, amend your previous configuration with these parts.
hub: config: GitHubOAuthenticator: allowed_organizations: - my-github-organization scope: - read:user
Alternative scopes
While you can set other scopes than read:user as described in GitHub OAuth scopes documentation, we recommend read:user.
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 Credentials API.
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 JavaScript origins” to be your hub’s URL.
Set “Authorized redirect URIs” to be your hub’s URL followed by /hub/oauth_callback. For example, https://your-jupyterhub-domain/hub/oauth_callback.
/hub/oauth_callback
https://your-jupyterhub-domain/hub/oauth_callback
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 are done.
Update your Helm chart’s configuration (config.yaml) to look like this.
hub: config: GoogleOAuthenticator: client_id: your-client-id.apps.googleusercontent.com client_secret: your-client-secret oauth_callback_url: https://your-jupyterhub-domain/hub/oauth_callback hosted_domain: - your-university.edu login_service: Your university JupyterHub: authenticator_class: google
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.
hosted_domain
login_service
Please see CyberInfrastructure Logon’s website for more information about what kind of identity is managed by CILogon.
hub: config: CILogonOAuthenticator: client_id: your-client-id client_secret: your-client-secret oauth_callback_url: https://your-jupyterhub-domain/hub/oauth_callback JupyterHub: authenticator_class: cilogon
Based on this caveat, you may need to also set the following.
hub: config: CILogonOAuthenticator: username_claim: email
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!
hub: config: GlobusOAuthenticator: client_id: your-client-id client_secret: your-client-secret oauth_callback_url: https://your-jupyterhub-domain/hub/oauth_callback identity_provider: your-university.edu JupyterHub: authenticator_class: globus
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.
hub: config: AzureAdOAuthenticator: client_id: your-client-id client_secret: your-client-secret oauth_callback_url: https://your-jupyterhub-domain/hub/oauth_callback tenant_id: your-tenant-id JupyterHub: authenticator_class: azuread
Auth0 is a commercial provider of identity management.
hub: config: Auth0OAuthenticator: client_id: client-id-from-auth0-here client_secret: client-secret-from-auth0-here oauth_callback_url: https://your-jupyterhub-domain/hub/oauth_callback scope: - openid - email auth0_subdomain: prod-8ua-1yy9 Authenticator: admin_users: - devops@example.com auto_login: true JupyterHub: authenticator_class: auth0
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.
hub: config: GenericOAuthenticator: client_id: your-client-id client_secret: your-client-secret oauth_callback_url: https://your-jupyterhub-domain/hub/oauth_callback authorize_url: https://your-domain.us.auth0.com/authorize token_url: https://your-domain.us.auth0.com/oauth/token userdata_url: https://your-domain.us.auth0.com/userinfo scope: - openid - name - profile - email username_key: name JupyterHub: authenticator_class: generic-oauth
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 server.
To configure an OpenID Connect client, see KeyCloak’s own documentation.
hub: config: GenericOAuthenticator: client_id: your-client-id client_secret: your-client-secret oauth_callback_url: https://your-jupyterhub-domain/hub/oauth_callback authorize_url: https://${host}/auth/realms/${realm}/protocol/openid-connect/auth token_url: https://${host}/auth/realms/${realm}/protocol/openid-connect/token userdata_url: https://${host}/auth/realms/${realm}/protocol/openid-connect/userinfo login_service: keycloak username_key: preferred_username userdata_params: state: state JupyterHub: authenticator_class: generic-oauth
JupyterHub supports LDAP and Active Directory authentication. Read the ldapauthenticator 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.
server_address
bind_dn_template
hub: config: JupyterHub: authenticator_class: ldapauthenticator.LDAPAuthenticator LDAPAuthenticator: bind_dn_template: - cn={username},ou=edir,ou=people,ou=EXAMPLE-UNIT,o=EXAMPLE server_address: ldap.EXAMPLE.org
Another example is provided below, equivalent to the example given in the ldapauthenticator README.
hub: config: JupyterHub: authenticator_class: ldapauthenticator.LDAPAuthenticator LDAPAuthenticator: allowed_groups: - cn=researcher,ou=groups,dc=wikimedia,dc=org - cn=operations,ou=groups,dc=wikimedia,dc=org bind_dn_template: - uid={username},ou=people,dc=wikimedia,dc=org - uid={username},ou=developers,dc=wikimedia,dc=org escape_userdn: false lookup_dn: true lookup_dn_search_filter: ({login_attr}={login}) lookup_dn_search_password: secret lookup_dn_search_user: ldap_search_user_technical_account lookup_dn_user_dn_attribute: cn server_address: ad.EXAMPLE.org user_attribute: sAMAccountName user_search_base: ou=people,dc=wikimedia,dc=org