hazza/jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/jupyterhub.git synced 2025-10-18 15:33:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update security-basics.rst

Browse Source
This commit is contained in:
Deborah Udoh
2022-10-22 10:32:16 +01:00
committed by GitHub
parent b15d56432d
commit 29ba669c73
1 changed files with 16 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,4 +1,4 @@
Security Settings Security settings
================= =================
.. important:: .. important::
@@ -20,13 +20,13 @@ is still a good idea to revoke existing tokens.
.. _ssl-encryption: .. _ssl-encryption:
Enabling SSL Encryption Enabling SSL encryption
----------------------- -----------------------
Since JupyterHub includes authentication and allows arbitrary code execution, Since JupyterHub includes authentication and allows arbitrary code execution,
you should not run it without SSL (HTTPS). you should not run it without SSL (HTTPS).
Using an SSL Certificate Using an SSL certificate
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
This will require you to obtain an official, trusted SSL certificate or create a This will require you to obtain an official, trusted SSL certificate or create a
@@ -44,7 +44,7 @@ Some cert files also contain the key, in which case only the cert is needed. It
is important that these files be put in a secure location on your server, where is important that these files be put in a secure location on your server, where
they are not readable by regular users. they are not readable by regular users.
If you are using a **chain certificate**, see also, chained certificate for SSL If you are using a **chain certificate**, see also chained certificate for SSL
in the JupyterHub `Troubleshooting FAQ <../troubleshooting.html>`_. in the JupyterHub `Troubleshooting FAQ <../troubleshooting.html>`_.
Using letsencrypt Using letsencrypt
@@ -82,7 +82,7 @@ To achieve this, simply omit the configuration settings
.. _authentication-token: .. _authentication-token:
Proxy Authentication Token Proxy authentication token
-------------------------- --------------------------
The Hub authenticates its requests to the Proxy using a secret token that The Hub authenticates its requests to the Proxy using a secret token that
@@ -94,7 +94,7 @@ 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 ``openssl rand -hex 32``). You can store it in the configuration file or an
environment variable. environment variable.
Generating and Storing Token in the Configuration File Generating and storing token in the configuration file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can set the value in the configuration file, ``jupyterhub_config.py``: You can set the value in the configuration file, ``jupyterhub_config.py``:
@@ -103,7 +103,7 @@ You can set the value in the configuration file, ``jupyterhub_config.py``:
c.ConfigurableHTTPProxy.api_token = 'abc123...' # any random string c.ConfigurableHTTPProxy.api_token = 'abc123...' # any random string
Generating and Storing as an Environment Variable Generating and storing as an environment variable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can pass this value of the proxy authentication token to the Hub and Proxy You can pass this value of the proxy authentication token to the Hub and Proxy
@@ -115,7 +115,7 @@ using the ``CONFIGPROXY_AUTH_TOKEN`` environment variable:
This environment variable needs to be visible to the Hub and Proxy. This environment variable needs to be visible to the Hub and Proxy.
Default if Token is Not Set Default if token is not set
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you don't set the Proxy authentication token, the Hub will generate a random If you don't set the Proxy authentication token, the Hub will generate a random
@@ -125,18 +125,18 @@ automatically (this is the default configuration).
.. _cookie-secret: .. _cookie-secret:
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 which are used for authentication. Three common methods are described for
generating and configuring the cookie secret. generating and configuring the cookie secret.
Generating and Storing as a Cookie Secret File Generating and storing as a cookie secret file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The cookie secret should be 32 random bytes, encoded as hex, and is typically The cookie secret should be 32 random bytes, encoded as hex, and is typically
stored in a ``jupyterhub_cookie_secret`` file. Below, is an example of a command to generate the stored in a ``jupyterhub_cookie_secret`` file. Below, is an example command to generate the
``jupyterhub_cookie_secret`` file: ``jupyterhub_cookie_secret`` file:
.. code-block:: bash .. code-block:: bash
@@ -155,10 +155,10 @@ 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 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 secret is generated and stored in the file. The file must not be readable by
``group`` or ``other``, otherwise, 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). for the cookie secret file are ``600`` (owner-only rw).
Generating and Storing as an Environment Variable Generating and storing as an environment variable
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you would like to avoid the need for files, the value can be loaded in the If you would like to avoid the need for files, the value can be loaded in the
@@ -173,7 +173,7 @@ For security reasons, this environment variable should only be visible to the
Hub. If you set it dynamically as above, all users will be logged out each time Hub. If you set it dynamically as above, all users will be logged out each time
the Hub starts. the Hub starts.
Generating and Storing as a Binary String Generating and storing as a binary string
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can also set the cookie secret, as a binary string, You can also set the cookie secret, as a binary string,
@@ -185,7 +185,7 @@ in the configuration file (``jupyterhub_config.py``) itself:
.. _cookies: .. _cookies:
Cookies Used by JupyterHub Authentication Cookies used by JupyterHub authentication
----------------------------------------- -----------------------------------------
The following cookies are used by the Hub for handling user authentication. The following cookies are used by the Hub for handling user authentication.