Building an authentication helper library for JupyterHub

Wed, 26 Aug 2026 00:00:00 +0000

2i2c have been working with the University of Toronto to add support for logging in to a JupyterHub using Canvas as an Identity Provider. JupyterHub implements support for authenticating users (figuring out who there are) and authorizing users (figuring out whether they are permitted to log into the hub) using an Authenicator interface. Via the oauthenticator package, JupyterHub has support for many kinds of OAuth2-based Identity Providers such as Google or GitHub, in addition to providing a generic authenticator GenericOAuthenticator that can be used with any OAuth2 implementation.

Diagram of an OAuth flow during the authentication process, taken from the oauthenticator documentation.

Our friends at UC Berkeley maintain the CanvasOAuthenticator project, an implementation of a Canvas OAuth2 authenticator for JupyterHub. This project has been in-use by UC Berkeley for over four years, authenticating thousands of students. In the time since CanvasOAuthenticator was first written (with involvement from 2i2c members), the GenericOAuthenticator has seen significant improvements, such that it is now possible to implement Canvas authentication without maintaining an entirely dedicated authenticator project.

After recognizing that it is much easier to maintain a small set of OAuth2 rules (adaptors) for each Identity Provider (like Canvas) rather than full-blown authenticators, 2i2c built jupyterhub_oauthenticator_authz_helpers. This library maintains an implementation of a subset of UC Berkeley’s CanvasOAuthenticator rules for mapping Canvas courses and groups onto JupyterHub groups. With this work, adding Canvas authentication requires only a few additional lines:

from jupyterhub_oauthenticator_authz_helpers.canvas build_auth_urls

cfg = c.GenericOAuthenticator

canvas_url = "<CANVAS-URL>"

# Configure auths
cfg.authorize_url, cfg.token_url, cfg.userdata_url = build_auth_urls(canvas_url)

# Scopes that this token will need
cfg.scope = [*build_auth_urls.scopes]

Adding support for group population (from Canvas groups and courses) requires a little bit more config:

from jupyterhub_oauthenticator_authz_helpers.canvas get_user_groups, get_course_groups, build_auth_urls

# ...

# Define a custom key for auth groups
cfg.auth_state_groups_key = "custom-groups"

# Define and inject auth state
async def auth_state_hook(authenticator, auth_state):
 if auth_state is None:
 return None

 access_token = auth_state["access_token"]
 auth_state[authenticator.auth_state_groups_key] = [
 # Populate groups from Canvas courses, using the scheme defined in get_course_groups
 *await get_course_groups(canvas_url, access_token, "course_code"),
 # Populate groups from Canvas groups, using the scheme defined in get_user_groups
 *await get_user_groups(canvas_url, access_token),
 ]
 return auth_state

cfg.modify_auth_state_hook = auth_state_hook

# Request additional scopes for the course / user group fetching
cfg.scope = [*build_auth_urls.scopes, *get_user_groups.scopes, *get_course_groups.scopes]

In addition to building out this library, 2i2c hopes to foster collaboration with other users and maintainers to continue to upstream additional OAuth2 adaptors. As part of the funded initiative, 2i2c will spend time conducting gonvernance and community work upstream to establish a jupyterhub-contrib organisation that provides stewardship and maintainance of this work, and future third-party projects.

Acknowledgements #

Thanks to the University of Toronto for collaborating with us, and funding this work.
Thanks to UC Berkeley for the prior work that inspired this project.

How regularly upgrading core infrastructure leads to upstream improvements and better infrastructure

Fri, 03 Apr 2026 00:00:00 +0000

Our collaborators at NASA VEDA recently asked us about the rationale behind policies for upgrading our infrastructure relatively quickly when new versions come out. Here’s the explanation that we shared with them, in case it’s useful for others as well.

In this case, the decision was whether to upgrade to Helm 4, and you can find our rationale in the /initiatives repository. Here’s a brief summary from Yuvi:

Fundamentally, it helps keep moving us and the ecosystem forward, and drive improvements upstream, in both JupyterHub and Helm.

It has driven these PRs in JupyterHub:

jupyterhub/action-k3s-helm#126 (merged)
jupyterhub/zero-to-jupyterhub-k8s#3797 (validated, but not merged yet)

It’s also driven improvements to helm itself - see this bug report that is being worked on:

helm/helm#31919

Upgrading helm versions can break things (and it has for some of our other communities in the past - see this example). So it’s important we do that on a reasonable timeframe and carefully, to avoid disruptions.

We’re also discovering for example that potentially the new nginx-ingress controller we had to move to has some issues working with older helm versions (ongoing WIP in 2i2c-org/infrastructure#7995). That feels much more tractable because we can now go ‘ok, let us just apply a quick fix now, and wait for the helm 4 rollout, and try again’ instead of being totally stuck.

This is similar to the other part of [/our VEDA objective] - rolling out new versions of jupyterhub. If we need to roll out security fixes, it’s much easier now because we already did the hard work of being up to date:

2i2c-org/infrastructure#7996

This isn’t the case quite yet for helm v3, as it’s still supported, but it’s much better to do this work earlier than wait.

If you encounter a bug in a popular open source software, often you can just ‘wait’ for it to be fixed. But this isn’t just about time - someone somewhere has to put in the effort of getting it fixed, filing helpful upstream bug reports, and testing to make sure it works. This is an example of 2i2c continuing to contribute this effort upstream wherever we can.

Acknowledgements #

Thanks to NASA VEDA for collaborating deeply with us on infrastructure questions like this.

Upstream | 2i2c

Building an authentication helper library for JupyterHub

Acknowledgements #

How regularly upgrading core infrastructure leads to upstream improvements and better infrastructure

Acknowledgements #