Hub Authentication

This section documents the different options of configuring authentication for a hub and how to setup each one of them for your hub. Each hub can have a differently configured authentication mechanism

Available auth methods:

  • Google OAuth

  • GitHub OAuth

  • Hash authentication

Below we explain how to configure each option.

GitHub OAuth is good when you want to provide logins to people who have a GitHub account already.

Google OAuth is good for a hub that is used by UC Boulder students as they will not need to create a new account.

Hash authentication is good for workshops with participants who might not have a UC Boulder account. The Hash authenticator is not part of the default JupyterHub setup we use, so you will have to create a Self-made hub image.

User Whitelist and Admin Accounts

You can control what users can login by creating a whitelist of usernames. This is independent of which authenticator you use. All authenticators eventually assign a user a username. This is then checked against the whitelist. You can also create a list of admin users, these people get special privileges like being able to restart individual user’s servers.

To add the users swiss-roll and bbq-pizza to the whitelist use the following snippet in your hub’s values.yaml:

jupyterhub:
  auth:
    whitelist:
      users:
        - swiss-roll
        - bbq-pizza

With this setup no one except these two users will be able to login.

To make a user the above two users admins and let them access individual user’s servers use the following snippet:

jupyterhub:
  auth:
    admin:
      access: true
      users:
        - swiss-roll
        - bbq-pizza

GitHub OAuth

GitHub authentication is good if you want people who already have a GitHub account to login.

For a full description on using GitHub authentication with JupyterHub, check the GitHub Authentication section of the zero2jupyterhub guide.

Step 1: Create a OAuth Application

To begin setup of GitHub based logins on your JupyterHub, create a OAuth application on GitHub.com by going to Github developer settings,

In “OAuth apps” create a new app. You will have to provide a name and description. The most important field is “Authorization callback URL” which has to be set to https://hub.earthdatascience.org/<NAMEOFYOURHUB>/hub/oauth_callback. Once you create the app you will be provided with a Client ID and a Client secret. You will need to add both in secrets/<NAMEOFYOURHUB>.yaml.

Note

Note that to modify the secrets files you need to first unlock those files using git-crypt. Once the files are unlocked, you can edit them locally and then push them to GitHub. Git-crypt will manage re-encrypting the files prior to committing & pushing.

An example of what to add to your secrets file:

jupyterhub:
  auth:
    type: github
    github:
      clientId: "5636ad98ccccbbbbaaaa"
      clientSecret: "3683566baaaabbbbccccxxxxff1ba7198a3022be"

The public part of the configuration has to be done in hub-charts/<NAMEOFYOURHUB>/values.yaml:

jupyterhub:
  auth:
    type: github
    github:
      callbackUrl: "https://hub.earthdatascience.org/<NAMEOFYOURHUB>/hub/oauth_callback"
      org_whitelist:
        - "earthlab"
    scopes:
      - "read:user"

In this example configuration only users who are members of the earthlab organization on GitHub will be allowed to login. To allow anyone to login remove that part of the configuration.

Google OAuth

The Google OAuth setup is good if you want students from UC Boulder to be able to login without needing an additional account.

For full details check the Google Authentication section of the zero2jupyterhub guide.

Create a OAuth application in the Google Developer console by going to https://console.developers.google.com/apis/credentials?project=ea-jupyter. Make sure you are in the “credentials” section of “API&Services”.

Click “Create credentials” and select “OAuth client ID” from the dropdown. Select “Web application” in the next menu. Fill out the form. The most important field is “Authorized redirect URIs”. Set this to https://hub.earthdatascience.org/<NAMEOFYOURHUB>/hub/oauth_callback.

Once you create the app you will be provided with a Client ID and a Client secret. You need to add both in secrets/<NAMEOFYOURHUB>.yaml.

An example of what to add to your secrets file:

jupyterhub:
  auth:
    google:
      clientId: "12345678988-abcdabcdat331tvltueu44elt98rb54f.apps.googleusercontent.com"
      clientSecret: "abcabcabcababcabcabc-abc"

The public part of the configuration has to be done in hub-charts/<NAMEOFYOURHUB>/values.yaml:

jupyterhub:
  auth:
    type: google
    google:
      callbackUrl: "https://hub.earthdatascience.org/<NAMEOFYOURHUB>/hub/oauth_callback"
      hostedDomain: "colorado.edu"
      loginService: "Colorado University"

In this configuration only users with a Google account that ends in colorado.edu will be able to login.

Hash authenticator

The Hash authenticator setup is good for hubs that are used during a workshop with participants who do not have a UC Boulder account.

To be able to use the hash authenticator you will need to have a custom image for your hub as the Hash authenticator package is not installed by default. You will have to create a Self-made hub image.

The public part of the configuration has to be done in hub-charts/<NAMEOFYOURHUB>/values.yaml:

jupyterhub:
  hub:
    extraConfig:
      auth: |
        c.JupyterHub.authenticator_class = 'hashauthenticator.HashAuthenticator'
      admin: |
        c.Authenticator.admin_users = {'leah-admin', 'tim-admin'}
        c.JupyterHub.admin_access = True

An example of what to add to your secrets/<NAMEOFYOURHUB>.yaml:

jupyterhub:
  hub:
    extraConfig:
      auth: |
        c.HashAuthenticator.secret_key = 'not-secret-at-all-replace-me!'
Troubleshooting Hub Deployments Get Started: Setup