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
¶jupyterhub.services.auth.
HubAuth
(**kwargs)¶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:
The following config MAY be set:
/hub/login
URL of the Hub).config c.HubAuth.api_token = Unicode('')
API key for accessing Hub API.
Generate with jupyterhub token [username]
or add to JupyterHub.services config.
config 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
config 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
config 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)
config c.HubAuth.cookie_name = Unicode('jupyterhub-services')
The name of the cookie I should be looking for
config c.HubAuth.hub_host = Unicode('')
The public host of JupyterHub
Only used if JupyterHub is spreading servers across subdomains.
config c.HubAuth.hub_prefix = Unicode('/hub/')
The URL prefix for the Hub itself.
Typically /hub/
config c.HubAuth.login_url = Unicode('/hub/login')
The login URL to use
Typically /hub/login
config c.HubAuth.api_token = Unicode('')
API key for accessing Hub API.
Generate with jupyterhub token [username]
or add to JupyterHub.services config.
config 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
config 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
config 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)
config c.HubAuth.cookie_name = Unicode('jupyterhub-services')
The name of the cookie I should be looking for
get_token
(handler)¶Get the user token from a request
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) |
config c.HubAuth.hub_host = Unicode('')
The public host of JupyterHub
Only used if JupyterHub is spreading servers across subdomains.
config c.HubAuth.hub_prefix = Unicode('/hub/')
The URL prefix for the Hub itself.
Typically /hub/
config c.HubAuth.login_url = Unicode('/hub/login')
The login URL to use
Typically /hub/login
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) |
HubOAuth
¶jupyterhub.services.auth.
HubOAuth
(**kwargs)¶HubAuth using OAuth for login instead of cookies set by the Hub.
config c.HubOAuth.api_token = Unicode('')
API key for accessing Hub API.
Generate with jupyterhub token [username]
or add to JupyterHub.services config.
config 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
config 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
config 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)
config c.HubOAuth.hub_host = Unicode('')
The public host of JupyterHub
Only used if JupyterHub is spreading servers across subdomains.
config c.HubOAuth.hub_prefix = Unicode('/hub/')
The URL prefix for the Hub itself.
Typically /hub/
config c.HubOAuth.login_url = Unicode('/hub/login')
The login URL to use
Typically /hub/login
config c.HubOAuth.oauth_authorization_url = Unicode('/hub/api/oauth2/authorize')
The URL to redirect to when starting the OAuth process
config c.HubOAuth.oauth_client_id = Unicode('')
The OAuth client ID for this application.
Use JUPYTERHUB_CLIENT_ID by default.
config c.HubOAuth.oauth_redirect_uri = Unicode('')
OAuth redirect URI
Should generally be /base_url/oauth_callback
config c.HubOAuth.oauth_token_url = Unicode('')
The URL for requesting an OAuth token from JupyterHub
Clear the OAuth cookie
Use OAuth client_id for cookie name
because we don’t want to use the same cookie name across OAuth clients.
generate_state
(next_url=None, **extra_state)¶Generate a state string, given a next_url redirect target
Parameters: | (str) (next_url) – |
---|---|
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 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.
config c.HubOAuth.oauth_authorization_url = Unicode('/hub/api/oauth2/authorize')
The URL to redirect to when starting the OAuth process
config c.HubOAuth.oauth_client_id = Unicode('')
The OAuth client ID for this application.
Use JUPYTERHUB_CLIENT_ID by default.
config c.HubOAuth.oauth_redirect_uri = Unicode('')
OAuth redirect URI
Should generally be /base_url/oauth_callback
config c.HubOAuth.oauth_token_url = Unicode('')
The URL for requesting an OAuth token from JupyterHub
Set a cookie recording OAuth result
Generate an OAuth state and store it in a cookie
Parameters: |
|
---|---|
Returns: | state (str) |
Return type: | The OAuth state that has been stored in the cookie (url safe, base64-encoded) |
The cookie name for storing OAuth state
This cookie is only live for the duration of the OAuth handshake.
HubAuthenticated
¶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:
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):
...
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.
Parameters: | model (dict) – the user or service model returned from HubAuth |
---|---|
Returns: | The user model if the user should be allowed, None otherwise. |
Return type: | user_model (dict) |
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
¶jupyterhub.services.auth.
HubOAuthenticated
¶Simple subclass of HubAuthenticated using OAuth instead of old shared cookies
HubOAuthCallbackHandler
¶jupyterhub.services.auth.
HubOAuthCallbackHandler
(application, request, **kwargs)¶OAuth Callback handler
Finishes the OAuth flow, setting a cookie to record the user’s info.
Should be registered at SERVICE_PREFIX/oauth_callback