OAuthenticator

17.4.0 verified Fri May 01 auth: no python

OAuthenticator is an authenticator plugin for JupyterHub that enables authentication via common OAuth providers (e.g., GitHub, Google, Azure AD, GitLab, etc.). It provides both generic OAuth 2.0 support and provider-specific implementations. Version 17.4.0 requires Python >=3.10. The library follows JupyterHub's release cadence, with major releases roughly yearly.

pip install oauthenticator

Common errors

error ImportError: cannot import name 'GitHubOAuthenticator' from 'oauthenticator' ↓

cause Trying to import from top-level package instead of submodule.

fix

Use: from oauthenticator.github import GitHubOAuthenticator

error ValueError: Missing 'client_id' for OAuthenticator ↓

cause The client_id configuration is not set or is empty.

fix

Set c.GitHubOAuthenticator.client_id = 'your-client-id' (or via environment variable).

error jupyterhub.errors.HTTPError: 403 : Forbidden ↓

cause OAuth callback URL mismatch or token validation failure. Often due to missing trailing slash in callback URL or incorrect redirect URI in OAuth provider settings.

fix

Ensure c.GitHubOAuthenticator.oauth_callback_url matches exactly the callback URL registered in the OAuth app (e.g., no trailing slash).

Warnings

breaking In version 17.0, the class names changed from CamelCase to Provider+OAuthenticator. For example, GitHubOAuthenticator (was GitHubLoginHandler). Update your config. ↓

fix Use the correct new class names as shown in imports.

gotcha The Authenticator classes are no longer importable from the top-level package. Always use submodules like oauthenticator.github. ↓

fix Use the correct import paths: from oauthenticator.github import GitHubOAuthenticator.

gotcha The oauth_callback_url must be set exactly as expected by the OAuth provider, including trailing slash. JupyterHub's default callback URL is /hub/oauth_callback (no trailing slash). A mismatch causes redirect errors. ↓

fix Set c.GitHubOAuthenticator.oauth_callback_url = 'http://yourhost/hub/oauth_callback' (no trailing slash).

Install

pip install oauthenticator[github,google]

Imports

GitHubOAuthenticator
wrong
```
from oauthenticator import GitHubOAuthenticator
```
correct
```
from oauthenticator.github import GitHubOAuthenticator
```
GitHubOAuthenticator is in the oauthenticator.github submodule, not the top-level package.

GoogleOAuthenticator

wrong

from oauthenticator import GoogleOAuthenticator

correct

from oauthenticator.google import GoogleOAuthenticator

GoogleOAuthenticator is in the oauthenticator.google submodule.

GenericOAuthenticator

wrong

from oauthenticator import GenericOAuthenticator

correct

from oauthenticator.generic import GenericOAuthenticator

GenericOAuthenticator is in the oauthenticator.generic submodule.

Quickstart

Minimal JupyterHub config to enable GitHub OAuth authentication. Set environment variables GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET.

import os
from jupyterhub.spawner import LocalProcessSpawner
from oauthenticator.github import GitHubOAuthenticator

c.JupyterHub.authenticator_class = GitHubOAuthenticator
c.GitHubOAuthenticator.oauth_callback_url = os.environ.get('OAUTH_CALLBACK_URL', 'http://localhost:8000/hub/oauth_callback')
c.GitHubOAuthenticator.client_id = os.environ.get('GITHUB_CLIENT_ID', '')
c.GitHubOAuthenticator.client_secret = os.environ.get('GITHUB_CLIENT_SECRET', '')