The general steps to take when using
Register an OAuth2 application with the identity provider
Configure JupyterHub to use an authenticator class compatible with the identity provider
Configure the chosen authenticator class
Set chosen OAuthenticator#
The first step is to tell JupyterHub to use your chosen authenticator class.
Each authenticator is provided in a submodule of
each authenticator has a variant with
LocalGitHubOAuthenticator), which will map OAuth usernames
onto local system usernames.
from oauthenticator.github import GitHubOAuthenticator c.JupyterHub.authenticator_class = GitHubOAuthenticator
Set callback URL, client ID, and client secret#
OAuthenticators require setting a callback URL, client ID, and
client secret. You will generally get these when you register your OAuth
application with your OAuth provider. Provider-specific details are
available in sections below. When registering your oauth application
with your provider, you will probably need to specify a callback URL.
The callback URL should look like:
[your-host] is where your server will be running. Such as
You can also set these values in your configuration file,
# Replace MyOAuthenticator with your selected OAuthenticator class (e.g. c.GithubOAuthenticator). c.MyOAuthenticator.oauth_callback_url = 'http[s]://[your-host]/hub/oauth_callback' c.MyOAuthenticator.client_id = 'your-client-id' c.MyOAuthenticator.client_secret = 'your-client-secret'
When JupyterHub runs, these values can also be retrieved from the
But this approach is not recommended and might be deprecated in the future.
(Optional) Use a custom 403 error#
When a user successfully logins at an OAuth provider, but is forbidden access based on the config, e.g. the
allowed_userslist or the
blocked_userslist, the following message is shown by default:
Looks like you have not been added to the list of allowed users for this hub. Please contact the hub administrator.
But you can show a customized 403 error message instead, by changing the OAuthenticator config:
# Replace MyOAuthenticator with your selected OAuthenticator class (e.g. c.GithubOAuthenticator). c.MyOAuthenticator.custom_403_message = "Your message for the user"
Custom HTML page You can also show a customized 403 HTML page message by creating a custom HTML template, and point JupyterHub to it.
An example custom 403 html page can be found in the examples directory
# Replace MyOAuthenticator with your selected OAuthenticator class (e.g. c.GithubOAuthenticator). c.JupyterHub.template_paths = ["examples/templates"]