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

Edit content for clarity

Browse Source
This commit is contained in:
Carol Willing
2017-07-20 18:09:17 -07:00
parent c89711d0d5
commit 6ee88a5424
2 changed files with 27 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/source/security-basics.rst
View File

@@ -1,18 +1,19 @@
Security Security basics
======== ===============
.. important:: .. important::
You should not run JupyterHub without SSL encryption on a public network You should not run JupyterHub without SSL encryption on a public network.
Security is the most important aspect of configuring Jupyter. There are four Security is the most important aspect of configuring Jupyter. Three
main aspects of the security configuration: configuration settings and one best practice are the main aspects of security
configuration:
1. `SSL encryption <ssl-encryption>`_ (to enable HTTPS) 1. :ref:`SSL encryption <ssl-encryption>` (to enable HTTPS)
2. `Cookie secret <cookie-secret>`_ (a key for encrypting browser cookies) 2. :ref:`Cookie secret <cookie-secret>` (a key for encrypting browser cookies)
3. Proxy `authentication token <authentication-token>`_ (used for the Hub and 3. Proxy :ref:`authentication token <authentication-token>` (used for the Hub and
other services to authenticate to the Proxy) other services to authenticate to the Proxy)
4. Periodic `security audits <security-audits>`_ 4. Periodic :ref:`security audits <security-audits>`
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 no database. A loss of control over read-access to the database should have no
@@ -100,11 +101,10 @@ An example would be to generate this file with:
openssl rand -hex 32 > /srv/jupyterhub/cookie_secret openssl rand -hex 32 > /srv/jupyterhub/cookie_secret
In most deployments of JupyterHub, you should point this to a secure location on In most deployments of JupyterHub, you should point this to a secure location on
the file system, such as ``/srv/jupyterhub/cookie_secret``. If the cookie secret the file system, such as ``/srv/jupyterhub/cookie_secret``. If the cookie secret
file doesn't exist when the Hub starts, a new cookie secret is generated and 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 stored in the file. The file must not be readable by ``group`` or ``other`` or the
server won't start. The recommended permissions for the cookie secret file are server won't start. The recommended permissions for the cookie secret file are
``600`` (owner-only rw). ``600`` (owner-only rw).
@@ -123,7 +123,7 @@ Hub. If you set it dynamically as above, all users will be logged out each time
the Hub starts. the Hub starts.
You can also set the cookie secret in the configuration file You can also set the cookie secret in the configuration file
itself,``jupyterhub_config.py``, as a binary string: itself, ``jupyterhub_config.py``, as a binary string:
.. code-block:: python .. code-block:: python
@@ -173,4 +173,4 @@ good practice to keep JupyterHub, configurable-http-proxy, and nodejs
versions up to date. versions up to date.
A handy website for testing your deployment is A handy website for testing your deployment is
[Qualsys' SSL analyzer tool](https://www.ssllabs.com/ssltest/analyze.html). `Qualsys' SSL analyzer tool <https://www.ssllabs.com/ssltest/analyze.html>`_.

20
docs/source/websecurity.md
View File

@@ -1,6 +1,11 @@
# Web Security and JupyterHub's design # Security Overview
## JupyterHub's design approach The **Security Overview** section helps you learn about the design of JupyterHub
with respect to web security, the semi-trusted user, and the available
mitigations to protect untrusted users from each other. It also helps you
obtain a deeper understanding of how JupyterHub works.
## Semi-trusted and untrusted users
JupyterHub is designed to be a *simple multi-user server for modestly sized JupyterHub is designed to be a *simple multi-user server for modestly sized
groups* of **semi-trusted** users. While the design reflects serving semi-trusted groups* of **semi-trusted** users. While the design reflects serving semi-trusted
@@ -18,7 +23,7 @@ single-user servers and the Hub, or between single-user servers and each
other, since browsers see the whole thing (proxy, Hub, and single user other, since browsers see the whole thing (proxy, Hub, and single user
servers) as a single website (i.e. single domain). servers) as a single website (i.e. single domain).
## How to protect users from each other ## Protect users from each other
To protect users from each other, a user must **never** be able to write arbitrary To protect users from each other, a user must **never** be able to write arbitrary
HTML and serve it to another user on the Hub's domain. JupyterHub's HTML and serve it to another user on the Hub's domain. JupyterHub's
@@ -46,10 +51,10 @@ If any additional services are run on the same domain as the Hub, the services
**must never** display user-authored HTML that is neither *sanitized* nor *sandboxed* **must never** display user-authored HTML that is neither *sanitized* nor *sandboxed*
(e.g. IFramed) to any user that lacks authentication as the author of a file. (e.g. IFramed) to any user that lacks authentication as the author of a file.
## Mitigate security issues through configuration options ## Mitigate security issues
There are two main approaches to mitigating these issues with configuration There are two main approaches to mitigating these issues with configuration
options provided by JupyterHub: options provided by JupyterHub.
### Enable subdomains ### Enable subdomains
@@ -64,7 +69,10 @@ institutional domains, wildcard DNS and SSL are not available. **If you do plan
to serve untrusted users, enabling subdomains is highly encouraged**, as it to serve untrusted users, enabling subdomains is highly encouraged**, as it
resolves the cross-site issues. resolves the cross-site issues.
### Steps to take when subdomains can not be used ### Unavailable subdomains
When subdomains are not available or not desirable, three steps can be taken
to secure JupyterHub from untrusted users.
#### Disable user config #### Disable user config