From 992b69d863a2ba5fb18e323acb5e0711396450cf Mon Sep 17 00:00:00 2001 From: jhermann Date: Mon, 17 Sep 2018 18:06:56 +0200 Subject: [PATCH] docs: Securing your JupyterHub web service with an SSL off-loader --- README.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/README.md b/README.md index 2047a6b..b675fcf 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ and on *Debian Stretch* in a Docker container * ['pkg-resources not found' or similar during virtualenv creation](#pkg-resources-not-found-or-similar-during-virtualenv-creation) * ['no such option: --no-binary' during package builds](#no-such-option---no-binary-during-package-builds) * [How to set up a simple service instance](#how-to-set-up-a-simple-service-instance) + * [Securing your JupyterHub web service with an SSL off-loader](#securing-your-jupyterhub-web-service-with-an-ssl-off-loader) * [Changing the Service Unit Configuration](#changing-the-service-unit-configuration) * [Configuration Files](#configuration-files) * [Data Directories](#data-directories) @@ -198,6 +199,31 @@ After an upgrade, the service restarts automatically by default – you can change that using the ``JUPYTERHUB_AUTO_RESTART`` variable in ``/etc/default/jupyterhub``. +## Securing your JupyterHub web service with an SSL off-loader + +Note that JupyterHub can directly offer an SSL endpoint, +but there are a few reasons to do that via a local proxy: + + * JupyterHub needs no special configuration to open a low port (remember, we do not run it as ``root``). + * Often there are already configuration management systems in place that, + for commodity web servers and proxies, seamlessly handle certificate management and other complexities. + * You can protect sensitive endpoints (e.g. metrics) against unauthorized access using + the built-in mechanisms of the chosen SSL off-loader. + +To hide the HTTP endpoint from the outside world, +change the bind URL in ``/etc/default/jupyterhub`` as follows: + + JUPYTERHUB_BIND_URL="http://127.0.0.1:8000" + +Restart the service and check that port 8000 is bound to localhost only: + + netstat -tulpn | grep :8000 + +Then install your chosen webserver / proxy for SSL off-loading, +listening on port 443 and forwarding to port 8000. +Typical candidates are NginX, Apache httpd, or Envoy. + + ## Changing the Service Unit Configuration The best way to change or augment the configuration of a *systemd* service