Running a notebook server with SSL

Sep 1, 2017. | By: Alex Staravoitau

In order to use Jupyter Notebook over HTTPS on your iPad or iPhone in both Juno and Safari, one needs to correctly configure SSL certificates. Since issuing a proper certificate from a trusted authority could be challenging in some cases, a self-signed certificate should suffice, provided it was signed by a CA that is trusted by your iOS device.

Do I need this?

Please, mind that you only need SSL certificate if you plan to connect to your server over HTTPS; you don’t need SSL certificates for plain HTTP connections. Whether you should use HTTPS or plain HTTP depends on how you connect to your Jupyter Notebook server.

Typically, you should use HTTPS:

Usually, you can use plain HTTP:

For HTTPS, please follow the steps below to prepare a self-signed SSL certificate, which will be trusted by your iOS device.


The openssl library is required to generate your own certificate. Run the following command in your local environment to see if you already have openssl installed.

which openssl
# You should get something like /usr/bin/openssl if it's installed

If which command does not return a path then you will need to install openssl yourself.

If you have… Install with…
macOS Homebrew: brew install openssl
Windows Windows complete package .exe installer
Ubuntu apt-get install openssl

Prepare configuration file

Download configuration file and put it in the folder, where you are going to store your SSH keys and certificates.

Open configuration file in a text editor of your choice and put domain names and/or IP addresses of your servers at the bottom, in the [ alt_names ] section. If you connect to your server using its IP address (which happens to be, your configuration file should end with:


[ alt_names ]
IP.1 	=

Generate CA certificate

Open terminal and go to the directory with your configuration file, which will also be the root directory of where all your keys and certificates will be stored.

Create the directory structure for CA keys and certificates. The index.txt and serial files act as a flat file database to keep track of signed certificates.

mkdir ca ca/certs ca/crl ca/newcerts ca/private
chmod 700 ca/private
touch ca/index.txt
echo 1000 > ca/serial

Generate the CA root key, you will be asked to come up with a password to protect this key with.

openssl genrsa -aes256 -out ca/private/ca.key.pem 4096
chmod 400 ca/private/ca.key.pem

Use the root key (ca.key.pem) to create a root certificate (ca.cert.pem). Enter your private key pass phrase from the previous step and provide information that will be incorporated into your CA certificate (or hit Enter to use default value in square brackets).

openssl req -config openssl.cnf \
    -key ca/private/ca.key.pem \
    -new -x509 -days 7300 -sha256 -extensions v3_ca \
    -out ca/certs/ca.cert.pem
chmod 444 ca/certs/ca.cert.pem

Generate SSL certificate

Assuming you are still in the directory where your configuration file is, create the directory structure and generate a new server key.

mkdir jupyter jupyter/csr jupyter/certs jupyter/private
chmod 700 jupyter/private
openssl genrsa -out jupyter/private/ssl.key.pem 2048
chmod 400 jupyter/private/ssl.key.pem

Request certificate for your server. Provide information that will be incorporated into your SSL certificate (or simply hit Enter to use defaults).

openssl req -config openssl.cnf \
    -key jupyter/private/ssl.key.pem \
    -new -sha256 -out jupyter/csr/ssl.csr.pem

Finally, issue your server SSL certificate. You will be asked to provide your CA private key pass phrase that you used earlier, and confirm your intention to sign SSL certificate.

openssl ca -config openssl.cnf \
    -extensions server_cert -days 1024 -notext -md sha256 \
    -in jupyter/csr/ssl.csr.pem \
    -out jupyter/certs/ssl.cert.pem
chmod 444 jupyter/certs/ssl.cert.pem

Install CA certificate on your iOS device

Install the CA certificate on your device (the one located at ca/certs/ca.cert.pem). You can e-mail it to yourself, share it via AirDrop or Dropbox — as soon as you open it on your iOS device you will see installation popup.

iOS certificate installation

Enable full trust for installed certificate

As of iOS 10.3 you must manually turn on trust for SSL when you install a certificate. In order to turn on SSL trust for CA certificate, go to Settings > General > About > Certificate Trust Settings. Under “Enable full trust for root certificates”, turn on trust for the certificate.

iOS certificate installation

Run Jupyter Notebook

Once CA certificate is trusted on the device, all certificates signed with it will be trusted too, including the one we generated for SSL, located at jupyter/certs/ssl.cert.pem. You can now use it when launching Jupyter Notebook by providing absolute paths to both key and certificate. If you generate all your certificate and keys in ~/.ssh/ folder, your paths will be:

jupyter notebook --certfile ~/.ssh/jupyter/certs/ssl.cert.pem --keyfile ~/.ssh/jupyter/private/ssl.key.pem

Alternatively, you can specify paths to key and certificate in Jupyter configuration file.

This material was based on OpenSSL Certificate Authority and Creating a Self-Signed SSL Certificate articles.