hazza/jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/jupyterhub.git synced 2025-10-17 06:52:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into copyediting

Browse Source
This commit is contained in:
Min RK
2022-11-24 09:40:21 +01:00
committed by GitHub
parent e243812745 1cf13bea66
commit de5fb1e7ce
328 changed files with 35662 additions and 7475 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -5,17 +5,17 @@ Security settings
You should not run JupyterHub without SSL encryption on a public network.
Security is the most important aspect of configuring Jupyter. Three
configuration settings are the main aspects of security configuration:
Security is the most important aspect of configuring Jupyter.
Three (3) configuration settings are the main aspects of security configuration:
1. :ref:`SSL encryption <ssl-encryption>` (to enable HTTPS)
2. :ref:`Cookie secret <cookie-secret>` (a key for encrypting browser cookies)
3. Proxy :ref:`authentication token <authentication-token>` (used for the Hub and
other services to authenticate to the Proxy)
The Hub hashes all secrets (e.g., auth tokens) before storing them in its
The Hub hashes all secrets (e.g. auth tokens) before storing them in its
database. A loss of control over read-access to the database should have
minimal impact on your deployment; if your database has been compromised, it
minimal impact on your deployment. If your database has been compromised, it
is still a good idea to revoke existing tokens.
.. _ssl-encryption:
@@ -31,7 +31,7 @@ Using an SSL certificate
This will require you to obtain an official, trusted SSL certificate or create a
self-signed certificate. Once you have obtained and installed a key and
certificate you need to specify their locations in the ``jupyterhub_config.py``
certificate, you need to specify their locations in the ``jupyterhub_config.py``
configuration file as follows:
.. code-block:: python
@@ -72,7 +72,7 @@ would be the needed configuration:
If SSL termination happens outside of the Hub
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In certain cases, for example if the hub is running behind a reverse proxy, and
In certain cases, for example, if the hub is running behind a reverse proxy, and
`SSL termination is being provided by NGINX <https://www.nginx.com/resources/admin-guide/nginx-ssl-termination/>`_,
it is reasonable to run the hub without SSL.
@@ -80,12 +80,55 @@ To achieve this, remove ``c.JupyterHub.ssl_key`` and ``c.JupyterHub.ssl_cert``
from your configuration (setting them to ``None`` or an empty string does not
have the same effect, and will result in an error).
.. _authentication-token:
Proxy authentication token
--------------------------
The Hub authenticates its requests to the Proxy using a secret token that
the Hub and Proxy agree upon. Note that this applies to the default
``ConfigurableHTTPProxy`` implementation. Not all proxy implementations
use an auth token.
The value of this token should be a random string (for example, generated by
``openssl rand -hex 32``). You can store it in the configuration file or an
environment variable.
Generating and storing token in the configuration file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can set the value in the configuration file, ``jupyterhub_config.py``:
.. code-block:: python
c.ConfigurableHTTPProxy.api_token = 'abc123...' # any random string
Generating and storing as an environment variable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can pass this value of the proxy authentication token to the Hub and Proxy
using the ``CONFIGPROXY_AUTH_TOKEN`` environment variable:
.. code-block:: bash
export CONFIGPROXY_AUTH_TOKEN=$(openssl rand -hex 32)
This environment variable needs to be visible to the Hub and Proxy.
Default if token is not set
~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you do not set the Proxy authentication token, the Hub will generate a random
key itself. This means that any time you restart the Hub, you **must also
restart the Proxy**. If the proxy is a subprocess of the Hub, this should happen
automatically (this is the default configuration).
.. _cookie-secret:
Cookie secret
-------------
The cookie secret is an encryption key, used to encrypt the browser cookies
The cookie secret is an encryption key, used to encrypt the browser cookies,
which are used for authentication. Three common methods are described for
generating and configuring the cookie secret.
@@ -93,8 +136,8 @@ Generating and storing as a cookie secret file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The cookie secret should be 32 random bytes, encoded as hex, and is typically
stored in a ``jupyterhub_cookie_secret`` file. An example command to generate the
``jupyterhub_cookie_secret`` file is:
stored in a ``jupyterhub_cookie_secret`` file. Below, is an example command to generate the
``jupyterhub_cookie_secret`` file:
.. code-block:: bash
@@ -112,7 +155,7 @@ The location of the ``jupyterhub_cookie_secret`` file can be specified in the
If the cookie secret file doesn't exist when the Hub starts, a new cookie
secret is generated and stored in the file. The file must not be readable by
``group`` or ``other`` or the server won't start. The recommended permissions
``group`` or ``other``, otherwise the server won't start. The recommended permissions
for the cookie secret file are ``600`` (owner-only rw).
Generating and storing as an environment variable
@@ -133,54 +176,79 @@ the Hub starts.
Generating and storing as a binary string
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can also set the cookie secret in the configuration file
itself, ``jupyterhub_config.py``, as a binary string:
You can also set the cookie secret, as a binary string,
in the configuration file (``jupyterhub_config.py``) itself:
.. code-block:: python
c.JupyterHub.cookie_secret = bytes.fromhex('64 CHAR HEX STRING')
.. _cookies:
.. important::
Cookies used by JupyterHub authentication
-----------------------------------------
If the cookie secret value changes for the Hub, all single-user notebook
servers must also be restarted.
The following cookies are used by the Hub for handling user authentication.
This section was created based on this post_ from Discourse.
.. _authentication-token:
.. _post: https://discourse.jupyter.org/t/how-to-force-re-login-for-users/1998/6
Proxy authentication token
--------------------------
jupyterhub-hub-login
~~~~~~~~~~~~~~~~~~~~
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
string (for example, generated by ``openssl rand -hex 32``).
This is the login token used when visiting Hub-served pages that are
protected by authentication, such as the main home, the spawn form, etc.
If this cookie is set, then the user is logged in.
Generating and storing token in the configuration file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Resetting the Hub cookie secret effectively revokes this cookie.
Or you can set the value in the configuration file, ``jupyterhub_config.py``:
This cookie is restricted to the path ``/hub/``.
.. code-block:: python
jupyterhub-user-<username>
~~~~~~~~~~~~~~~~~~~~~~~~~~
c.JupyterHub.proxy_auth_token = '0bc02bede919e99a26de1e2a7a5aadfaf6228de836ec39a05a6c6942831d8fe5'
This is the cookie used for authenticating with a single-user server.
It is set by the single-user server, after OAuth with the Hub.
Generating and storing as an environment variable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
You can pass this value of the proxy authentication token to the Hub and Proxy
using the ``CONFIGPROXY_AUTH_TOKEN`` environment variable:
Each OAuth access token is associated with a session id (see ``jupyterhub-session-id`` section
below).
.. code-block:: bash
To avoid hitting the Hub on every request, the authentication response is cached.
The cache key is comprised of both the token and session id, to avoid a stale cache.
export CONFIGPROXY_AUTH_TOKEN=$(openssl rand -hex 32)
Resetting the Hub cookie secret effectively revokes this cookie.
This environment variable needs to be visible to the Hub and Proxy.
This cookie is restricted to the path ``/user/<username>``,
to ensure that only the user’s server receives it.
Default if token is not set
~~~~~~~~~~~~~~~~~~~~~~~~~~~
jupyterhub-session-id
~~~~~~~~~~~~~~~~~~~~~
If you don't set the Proxy authentication token, the Hub will generate a random
key itself, which means that any time you restart the Hub you **must also
restart the Proxy**. If the proxy is a subprocess of the Hub, this should happen
automatically (this is the default configuration).
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 coordinate logout of the multiple OAuth cookies.
This cookie is set to ``/`` so all endpoints can receive it, 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 you 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.