hazza/jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/jupyterhub.git synced 2025-10-10 03:23:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add more docs about authentication and cookies, using text posted by MinRK on Discourse

Browse Source
This commit is contained in:
Bruno P. Kinoshita
2020-02-19 13:46:45 +13:00
parent 31c0788bd9
commit 287b0302d9
1 changed files with 69 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
docs/source/getting-started/security-basics.rst
View File

@@ -86,7 +86,7 @@ Proxy authentication token
--------------------------
The Hub authenticates its requests to the Proxy using a secret token that
the Hub and Proxy agree upon. The value of this string should be a random
the Hub and Proxy agree upon. The value of this token should be a random
string (for example, generated by ``openssl rand -hex 32``).
Generating and storing token in the configuration file
@@ -96,7 +96,7 @@ Or you can set the value in the configuration file, ``jupyterhub_config.py``:
.. code-block:: python
c.JupyterHub.proxy_auth_token = '0bc02bede919e99a26de1e2a7a5aadfaf6228de836ec39a05a6c6942831d8fe5'
c.ConfigurableHTTPProxy.api_token = 'abc123...' # any random string
Generating and storing as an environment variable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -183,3 +183,70 @@ itself, ``jupyterhub_config.py``, as a binary string:
If the cookie secret value changes for the Hub, all single-user notebook
servers must also be restarted.
.. _cookies:
Cookies used by JupyterHub authentication
-----------------------------------------
The following cookies are used by the Hub for handling user authentication.
jupyterhub-hub-login
~~~~~~~~~~~~~~~~~~~~
This is the login token used when visiting Hub-served pages encrypted such
as the main home, the spawn form, etc. If this cookie is set, then the
user is logged in.
Resetting the Hub cookie secret effectively revokes this cookie.
This cookie is restricted to the path ``/hub/``.
jupyterhub-user-<username>
~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the cookie used for authenticating with a single-user server
encrypted. It is set by the single-user server after OAuth with the Hub.
Effectively the same as ``jupyterhub-hub-login``, but for the
single-user server instead of the Hub. It contains an OAuth access token,
which is checked with the Hub to authenticate the browser.
Each OAuth access token is associated with a session id (see ``jupyterhub-session-id`` section
below).
To avoid hitting the Hub on every request, the authentication response
is cached. And to avoid a stale cache the cache key is comprised of both
the token and session id.
Resetting the Hub cookie secret effectively revokes this cookie.
This cookie is restricted to the path ``/user/<username>``, so that
only the user’s server receives it.
jupyterhub-session-id
~~~~~~~~~~~~~~~~~~~~~
This is a random string, meaningless in itself, and the only cookie
shared by the Hub and single-user servers.
Its sole purpose is to to coordinate logout of the multiple OAuth cookies.
This cookie is set to ``/`` so all endpoints can receive it, or clear it, etc.
jupyterhub-user-<username>-oauth-state
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A short-lived cookie, used solely to store and validate OAuth state.
It is only set while OAuth between the single-user server and the Hub
is processing.
If you use your browser development tools, you should see this cookie
for a very brief moment before your are logged in,
with an expiration date shorter than ``jupyterhub-hub-login`` or
``jupyterhub-user-<username>``.
This cookie should not exist after you have successfully logged in.
This cookie is restricted to the path ``/user/<username>``, so that only
the user’s server receives it.