{"id":24134,"library":"oauthenticator","title":"OAuthenticator","description":"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.","status":"active","version":"17.4.0","language":"python","source_language":"en","source_url":"https://github.com/jupyterhub/oauthenticator","tags":["jupyterhub","oauth","authentication","jupyter"],"install":[{"cmd":"pip install oauthenticator","lang":"bash","label":"Default install"},{"cmd":"pip install oauthenticator[github,google]","lang":"bash","label":"Install with extra provider dependencies"}],"dependencies":[{"reason":"OAuthenticator is a JupyterHub authenticator plugin; requires JupyterHub to function.","package":"jupyterhub","optional":false},{"reason":"Extra dependencies for GitHub OAuth provider.","package":"oauthenticator[github]","optional":true},{"reason":"Extra dependencies for Google OAuth provider.","package":"oauthenticator[google]","optional":true}],"imports":[{"note":"GitHubOAuthenticator is in the oauthenticator.github submodule, not the top-level package.","wrong":"from oauthenticator import GitHubOAuthenticator","symbol":"GitHubOAuthenticator","correct":"from oauthenticator.github import GitHubOAuthenticator"},{"note":"GoogleOAuthenticator is in the oauthenticator.google submodule.","wrong":"from oauthenticator import GoogleOAuthenticator","symbol":"GoogleOAuthenticator","correct":"from oauthenticator.google import GoogleOAuthenticator"},{"note":"GenericOAuthenticator is in the oauthenticator.generic submodule.","wrong":"from oauthenticator import GenericOAuthenticator","symbol":"GenericOAuthenticator","correct":"from oauthenticator.generic import GenericOAuthenticator"}],"quickstart":{"code":"import os\nfrom jupyterhub.spawner import LocalProcessSpawner\nfrom oauthenticator.github import GitHubOAuthenticator\n\nc.JupyterHub.authenticator_class = GitHubOAuthenticator\nc.GitHubOAuthenticator.oauth_callback_url = os.environ.get('OAUTH_CALLBACK_URL', 'http://localhost:8000/hub/oauth_callback')\nc.GitHubOAuthenticator.client_id = os.environ.get('GITHUB_CLIENT_ID', '')\nc.GitHubOAuthenticator.client_secret = os.environ.get('GITHUB_CLIENT_SECRET', '')","lang":"python","description":"Minimal JupyterHub config to enable GitHub OAuth authentication. Set environment variables GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET."},"warnings":[{"fix":"Use the correct new class names as shown in imports.","message":"In version 17.0, the class names changed from CamelCase to Provider+OAuthenticator. For example, GitHubOAuthenticator (was GitHubLoginHandler). Update your config.","severity":"breaking","affected_versions":"<17.0"},{"fix":"Use the correct import paths: from oauthenticator.github import GitHubOAuthenticator.","message":"The Authenticator classes are no longer importable from the top-level package. Always use submodules like oauthenticator.github.","severity":"gotcha","affected_versions":">=17.0"},{"fix":"Set c.GitHubOAuthenticator.oauth_callback_url = 'http://yourhost/hub/oauth_callback' (no trailing slash).","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use: from oauthenticator.github import GitHubOAuthenticator","cause":"Trying to import from top-level package instead of submodule.","error":"ImportError: cannot import name 'GitHubOAuthenticator' from 'oauthenticator'"},{"fix":"Set c.GitHubOAuthenticator.client_id = 'your-client-id' (or via environment variable).","cause":"The client_id configuration is not set or is empty.","error":"ValueError: Missing 'client_id' for OAuthenticator"},{"fix":"Ensure c.GitHubOAuthenticator.oauth_callback_url matches exactly the callback URL registered in the OAuth app (e.g., no trailing slash).","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.","error":"jupyterhub.errors.HTTPError: 403 : Forbidden"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}