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

docs/source/getting-started/security-basics.rst

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