Configuring JupyterHub authenticators

Any JupyterHub authenticator can be used with TLJH. A number of them ship by default with TLJH:

  1. OAuthenticator - Google, GitHub, CILogon, GitLab, Globus, Mediawiki, auth0, generic OpenID connect (for KeyCloak, etc) and other OAuth based authentication methods.
  2. LDAPAuthenticator - LDAP & Active Directory.
  3. DummyAuthenticator - Any username, one shared password. A how-to guide on using DummyAuthenticator is also available.
  4. FirstUseAuthenticator - Users set their password when they log in for the first time. Default authenticator used in TLJH.

We try to have specific how-to guides & tutorials for common authenticators. Since we can not cover everything, this guide shows you how to use any authenticator you want with JupyterHub by following the authenticator’s documentation.

Setting authenticator properties

JupyterHub authenticators are customized by setting traitlet properties. In the authenticator’s documentation, you will find these are usually represented as:

c.<AuthenticatorName>.<property-name> = <some-value>

You can set these with tljh-config with:

sudo tljh-config set auth.<AuthenticatorName>.<property-name> <some-value>

Example

LDAPAuthenticator’s documentation lists the various configuration options you can set for LDAPAuthenticator. When the documentation asks you to set LDAPAuthenticator.server_address to some value, you can do that with the following command:

sudo tljh-config set auth.LDAPAuthenticator.server_address = 'my-ldap-server'

Most authenticators require you set multiple configuration options before you can enable them. Read the authenticator’s documentation carefully for more information.

Enabling the authenticator

Once you have configured the authenticator as you want, you should then enable it. Usually, the documentation for the authenticator would ask you to add something like the following to your jupyterhub_config.py to enable it:

c.JupyterHub.authenticator_class = 'fully-qualified-authenticator-name'

You can accomplish the same with tljh-config:

sudo tljh-config set auth.type <fully-qualified-authenticator-name>

Once enabled, you need to reload JupyterHub for the config to take effect.

sudo tljh-config reload

Try logging in a separate incognito window to check if your configuration works. This lets you preserve your terminal in case there were errors. If there are errors, Looking at Logs should help you debug them.

Example

From the documentation for LDAPAuthenticator, we see that the fully qualified name is ldapauthenticator.LDAPAuthenticator. Assuming you have already configured it, the following commands enable LDAPAuthenticator.

sudo tljh-config set auth.type ldapauthenticator.LDAPAuthenticator
sudo tljh-config reload