Authenticating Services¶

Module: `jupyterhub.services.auth`¶

Authenticating services with JupyterHub

Cookies are sent to the Hub for verification, replying 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.

class 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:

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

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)

user_for_cookie(encrypted_cookie, use_cache=True)¶

Ask the Hub to identify the user for a given cookie.

Parameters:

encrypted_cookie (str) – the cookie value (not decrypted, the Hub will do that)
use_cache (bool) – Specify use_cache=False to skip cached cookie values (default: True)

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)

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

check_hub_user(user_model)¶

Check whether Hub-authenticated user 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:	user_model (dict) – the user 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)

Authenticating Services¶

Module: jupyterhub.services.auth¶

Module: `jupyterhub.services.auth`¶