Registry / auth-security / oauthenticator

oauthenticator

library17.4.0pypypi✓ verified 83d ago

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.

auth-security web-framework

pip install oauthenticator

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OAUTHENTICATOR

oauthenticator

auth-securitypythonv17.4.0

Install

12.0s avg

Import

8348ms

Disk

103MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v17.4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 8.672s · 101.6MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 12.0s · import 8.023s · 99MB

103MB installed

● package 103MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GitHubOAuthenticator

✓ from oauthenticator.github import GitHubOAuthenticator

✗ from oauthenticator import GitHubOAuthenticator

GitHubOAuthenticator is in the oauthenticator.github submodule, not the top-level package.

GoogleOAuthenticator

✓ from oauthenticator.google import GoogleOAuthenticator

✗ from oauthenticator import GoogleOAuthenticator

GoogleOAuthenticator is in the oauthenticator.google submodule.

GenericOAuthenticator

✓ from oauthenticator.generic import GenericOAuthenticator

✗ from oauthenticator import GenericOAuthenticator

GenericOAuthenticator is in the oauthenticator.generic submodule.

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', '')

Debug

Known issues

breakingIn 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.

affects: <17.0

gotchaThe 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.

affects: >=17.0

gotchaThe 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).

affects: all

Errors

Common errors & fixes

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

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

fix

Use: from oauthenticator.github import GitHubOAuthenticator

ValueError: Missing 'client_id' for OAuthenticator

The client_id configuration is not set or is empty.

fix

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

jupyterhub.errors.HTTPError: 403 : Forbidden

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).

Upgrade

Version history

17.4.0latest on PyPI · released Mar 26, 2026

Audit

Dependencies

jupyterhubrequiredOAuthenticator is a JupyterHub authenticator plugin; requires JupyterHub to function.

oauthenticator[github]optionalExtra dependencies for GitHub OAuth provider.

oauthenticator[google]optionalExtra dependencies for Google OAuth provider.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jupyterhub/oauthenticator ↗

packagehttps://pypi.org/project/oauthenticator/ ↗

homepagehttps://jupyter.org ↗