Auth0 is a commercial authentication provider that some communities would like to use, for the various extra features it offers. Since it’s outside the primary two authentication mechanisms we offer, this costs extra - please confirm with partnerships team that the community is being billed for it.

Set up the hub with CILogon#

First, we set up the hub and use CILogon for authentication, so the community can get started and poke around. This decouples getting started from the auth0 process, to make everything smoother (for both 2i2c engineers and the community).

Requesting credentials from the community#

We have to ask the community to create and provision Auth0 credentials for us. They will need to create a Regular Auth0 Web App for each hub - so at the least, for the staging hub and the production hub.

Under Application URIs, they should use the following URL under “Allowed Callback URLs”:


Once created, they should collect the following information:

  1. client_secret and client_id for the created application.

  2. The “Auth0 domain” for the created application.

These are secure credentials, and must be sent to us using the encrypted support mechanism

They can configure this with whatever connections they prefer - 2i2c is not responsible for and hence can not really help with configuring this.


It may be advantageous to 2i2c engineers to have shared access to this auth0 web application, so we can debug issues that may arise. But we don’t want to create too much friction here, by having to manually create accounts for each 2i2c engineer for each auth0 application we administer. Solutions (potentially a shared account) are being explored.

Configuring the JupyterHub to use Auth0#

While there is an upstream Auth0OAuthenticator, it doesn’t have any specific features that aren’t in the upstream GenericOAuthenticator, and is missing some features that are present in the GenericOAuthenticator. Using the GenericOAuthenticator here also allows us to support other Generic OAuth providers in the future, and not tie ourselves down to Auth0.

In the common.yaml file for the cluster hosting the hubs, we set the authenticator to be generic.

        authenticator_class: generic

In the encrypted, per-hub config (of form enc-<hub-name>.secret.values.yaml), we specify the secret values we received from the community.

        client_id: <client-id>
        client_secret: <client-secret>
        logout_redirect_url: https://<auth0-domain>/v2/logout?client_id=<client-id>

And in the unencrypted, per-hub config (of form <hub-name>.values.yaml), we specify the non-secret config values.

        token_url: https://<auth0-domain>/oauth/token
        authorize_url: https://<auth0-domain>/authorize
        userdata_url: https://<auth0-domain>/userinfo
        scope: openid
        username_claim: sub

Auth0 has documentation for the userinfo, token and authorize endpoints.

Once deployed, this should allow users authorized by Auth0 to login to the hub! Their usernames will look like <auth-provider>:<id>, which looks a little strange but allows differentiation between people who use multiple accounts but the same email.