Services Authentication#
Module: jupyterhub.services.auth
#
Authenticating services with JupyterHub.
Cookies are sent to the Hub for verification. The Hub replies with a JSON model describing the authenticated user.
HubAuth
can be used in any application, even outside tornado.
HubAuthenticated
is a mixin class for tornado handlers that should
authenticate with the Hub.
HubAuth
#
- class jupyterhub.services.auth.HubAuth(**kwargs: Any)#
A class for authenticating with JupyterHub
This can be used by any application.
If using tornado, use via
HubAuthenticated
mixin. If using manually, use the.user_for_cookie(cookie_value)
method to identify the user corresponding to a given cookie value.The following config must be set:
api_token (token for authenticating with JupyterHub API), fetched from the JUPYTERHUB_API_TOKEN env by default.
The following config MAY be set:
api_url: the base URL of the Hub’s internal API, fetched from JUPYTERHUB_API_URL by default.
cookie_cache_max_age: the number of seconds responses from the Hub should be cached.
login_url (the public
/hub/login
URL of the Hub).cookie_name: the name of the cookie I should be using, if different from the default (unlikely).
- api_token c.HubAuth.api_token = Unicode('')#
API key for accessing Hub API.
Generate with
jupyterhub token [username]
or add to JupyterHub.services config.
- api_url c.HubAuth.api_url = Unicode('http://127.0.0.1:8081/hub/api')#
The base API URL of the Hub.
Typically
http://hub-ip:hub-port/hub/api
- base_url c.HubAuth.base_url = Unicode('/')#
The base URL prefix of this application
e.g. /services/service-name/ or /user/name/
Default: get from JUPYTERHUB_SERVICE_PREFIX
- cache_max_age c.HubAuth.cache_max_age = Int(300)#
The maximum time (in seconds) to cache the Hub’s responses for authentication.
A larger value reduces load on the Hub and occasional response lag. A smaller value reduces propagation time of changes on the Hub (rare).
Default: 300 (five minutes)
- certfile c.HubAuth.certfile = Unicode('')#
The ssl cert to use for requests
Use with keyfile
- client_ca c.HubAuth.client_ca = Unicode('')#
The ssl certificate authority to use to verify requests
Use with keyfile and certfile
- cookie_cache_max_age Int(0)#
DEPRECATED. Use cache_max_age
- cookie_name c.HubAuth.cookie_name = Unicode('jupyterhub-services')#
The name of the cookie I should be looking for
- cookie_options c.HubAuth.cookie_options = Dict()#
Additional options to pass when setting cookies.
Can include things like
expires_days=None
for session-expiry orsecure=True
if served on HTTPS and default HTTPS discovery fails (e.g. behind some proxies).
- get_session_id(handler)#
Get the jupyterhub session id
from the jupyterhub-session-id cookie.
- get_token(handler)#
Get the user token from a request
in URL parameters: ?token=<token>
in header: Authorization: token <token>
- get_user(handler)#
Get the Hub user for a given tornado handler.
Checks cookie with the Hub to identify the current user.
- Parameters
handler (tornado.web.RequestHandler) – the current request handler
- Returns
The user model, if a user is identified, None if authentication fails.
The ‘name’ field contains the user’s name.
- Return type
user_model (dict)
- hub_host c.HubAuth.hub_host = Unicode('')#
The public host of JupyterHub
Only used if JupyterHub is spreading servers across subdomains.
- hub_prefix c.HubAuth.hub_prefix = Unicode('/hub/')#
The URL prefix for the Hub itself.
Typically /hub/
- keyfile c.HubAuth.keyfile = Unicode('')#
The ssl key to use for requests
Use with certfile
- login_url c.HubAuth.login_url = Unicode('/hub/login')#
The login URL to use
Typically /hub/login
- user_for_cookie(encrypted_cookie, use_cache=True, session_id='')#
Ask the Hub to identify the user for a given cookie.
- Parameters
- Returns
The user model, if a user is identified, None if authentication fails.
The ‘name’ field contains the user’s name.
- Return type
user_model (dict)
- user_for_token(token, use_cache=True, session_id='')#
Ask the Hub to identify the user for a given token.
HubOAuth
#
- class jupyterhub.services.auth.HubOAuth(**kwargs: Any)#
HubAuth using OAuth for login instead of cookies set by the Hub.
- api_token c.HubOAuth.api_token = Unicode('')#
API key for accessing Hub API.
Generate with
jupyterhub token [username]
or add to JupyterHub.services config.
- api_url c.HubOAuth.api_url = Unicode('http://127.0.0.1:8081/hub/api')#
The base API URL of the Hub.
Typically
http://hub-ip:hub-port/hub/api
- base_url c.HubOAuth.base_url = Unicode('/')#
The base URL prefix of this application
e.g. /services/service-name/ or /user/name/
Default: get from JUPYTERHUB_SERVICE_PREFIX
- cache_max_age c.HubOAuth.cache_max_age = Int(300)#
The maximum time (in seconds) to cache the Hub’s responses for authentication.
A larger value reduces load on the Hub and occasional response lag. A smaller value reduces propagation time of changes on the Hub (rare).
Default: 300 (five minutes)
- certfile c.HubOAuth.certfile = Unicode('')#
The ssl cert to use for requests
Use with keyfile
- clear_cookie(handler)#
Clear the OAuth cookie
- client_ca c.HubOAuth.client_ca = Unicode('')#
The ssl certificate authority to use to verify requests
Use with keyfile and certfile
- property cookie_name#
Use OAuth client_id for cookie name
because we don’t want to use the same cookie name across OAuth clients.
- cookie_options c.HubOAuth.cookie_options = Dict()#
Additional options to pass when setting cookies.
Can include things like
expires_days=None
for session-expiry orsecure=True
if served on HTTPS and default HTTPS discovery fails (e.g. behind some proxies).
- generate_state(next_url=None, **extra_state)#
Generate a state string, given a next_url redirect target
- Parameters
next_url (str) – The URL of the page to redirect to on successful login.
- Returns
state (str)
- Return type
The base64-encoded state string.
- get_next_url(b64_state='')#
Get the next_url for redirection, given an encoded OAuth state
- get_state_cookie_name(b64_state='')#
Get the cookie name for oauth state, given an encoded OAuth state
Cookie name is stored in the state itself because the cookie name is randomized to deal with races between concurrent oauth sequences.
- hub_host c.HubOAuth.hub_host = Unicode('')#
The public host of JupyterHub
Only used if JupyterHub is spreading servers across subdomains.
- hub_prefix c.HubOAuth.hub_prefix = Unicode('/hub/')#
The URL prefix for the Hub itself.
Typically /hub/
- keyfile c.HubOAuth.keyfile = Unicode('')#
The ssl key to use for requests
Use with certfile
- login_url c.HubOAuth.login_url = Unicode('/hub/login')#
The login URL to use
Typically /hub/login
- oauth_authorization_url c.HubOAuth.oauth_authorization_url = Unicode('/hub/api/oauth2/authorize')#
The URL to redirect to when starting the OAuth process
- oauth_client_id c.HubOAuth.oauth_client_id = Unicode('')#
The OAuth client ID for this application.
Use JUPYTERHUB_CLIENT_ID by default.
- oauth_redirect_uri c.HubOAuth.oauth_redirect_uri = Unicode('')#
OAuth redirect URI
Should generally be /base_url/oauth_callback
- oauth_token_url c.HubOAuth.oauth_token_url = Unicode('')#
The URL for requesting an OAuth token from JupyterHub
- set_cookie(handler, access_token)#
Set a cookie recording OAuth result
- set_state_cookie(handler, next_url=None)#
Generate an OAuth state and store it in a cookie
- property state_cookie_name#
The cookie name for storing OAuth state
This cookie is only live for the duration of the OAuth handshake.
HubAuthenticated
#
- class jupyterhub.services.auth.HubAuthenticated#
Mixin for tornado handlers that are authenticated with JupyterHub
A handler that mixes this in must have the following attributes/properties:
.hub_auth: A HubAuth instance
.hub_users: A set of usernames to allow. If left unspecified or None, username will not be checked.
.hub_groups: A set of group names to allow. If left unspecified or None, groups will not be checked.
Examples:
class MyHandler(HubAuthenticated, web.RequestHandler): hub_users = {'inara', 'mal'} def initialize(self, hub_auth): self.hub_auth = hub_auth @web.authenticated def get(self): ...
- property allow_all#
Property indicating that all successfully identified user or service should be allowed.
- check_hub_user(model)#
Check whether Hub-authenticated user or service should be allowed.
Returns the input if the user should be allowed, None otherwise.
Override if you want to check anything other than the username’s presence in hub_users list.
- get_current_user()#
Tornado’s authentication method
- Returns
The user model, if a user is identified, None if authentication fails.
- Return type
user_model (dict)
- get_login_url()#
Return the Hub’s login URL
HubOAuthenticated
#
- class jupyterhub.services.auth.HubOAuthenticated#
Simple subclass of HubAuthenticated using OAuth instead of old shared cookies