The JupyterHub API

Services Authentication

expand icon

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)

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

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

user_for_token(token, use_cache=True)

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

Parameters:
  • token (str) – the token
  • 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)

HubOAuth

class 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

cookie_name

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)

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

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:
  • (RequestHandler) (handler) –
  • (str) (next_url) –
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.

token_for_code(code)

Get token for OAuth temporary code

This is the last step of OAuth login. Should be called in OAuth Callback handler.

Parameters:code (str) – oauth code for finishing OAuth login
Returns:JupyterHub API Token
Return type:token (str)

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

hub_auth_class

alias of HubAuth

HubOAuthenticated

class jupyterhub.services.auth.HubOAuthenticated

Simple subclass of HubAuthenticated using OAuth instead of old shared cookies

HubOAuthCallbackHandler

class 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