Jupyter Notebook — adding certificates for security & ease of use.

This howto covers adding ssh certs to the jupyter notebook.

We will be editing the jupyter config file using vim. Vim isn’t scary and pretty much an essential tool to learn, or at least become comfortable with. Gui interfaces are nice, vim will be accessible on pretty much every *nix based server.

1. ssh to your server.

ssh -i /path/to/your/security-keys.pem ec2-user@ec2-???-???-???-???.us-west-2.compute.amazonaws.com

2. generate the ssl certificate and key

cd ~
mkdir ssl
cd ssl
sudo openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout "cert.key" -out "cert.pem" -batch
#now show the files generated
ls
pwd

This will generate two files “cert.key” & “cert.pem”. We will be editing the jupyter config file to tell jupyter where to find these files. Jupyter will then have https working.

No we have to generate a password for jupyter, this will be added to the jupyter config file later.

ipython

This will open an ipython session, bash prompt will be replaced by ipython prompt.

from IPython.lib import passwd 
passwd()

This will prompt you for a password and generate a sha hash of your password entered. Copy paste both to a secure place. exit ipython back to bash shell.

exit()

3. edit the jupyter config file.

test if your config file exists.

ls ~/.jupyter/jupyter_notebook_config.py

If the config file does not exist, generate it with this.

jupyter notebook --generate-config

open the config file in vi.

vi ~/.jupyter/jupyter_notebook_config.py

It will look like this.

We will be inserting these lines into the file.
Lazy version = insert at end of the config file.

‘better’ method = find the existing values in the config file and edit.

I like to copy paste the existing line and edit so I can see what I’ve changed.

It’s not a bad idea to copy this config file into your own records to keep track of how your server was configured. Given the ease of terminating instances and recreating them, scripting this entire process is something to be considered in future.

NB: we need to use full pathname to .pem and .key files.

NBB: check your path. ec2-user is default username for AWS AMI, other AMI’s and different users will have different default home. check.

c.NotebookApp.certfile = '/home/ec2-user/ssl/cert.pem' 
# path to the certificate we  generated
c.NotebookApp.keyfile = '/home/ec2-user/ssl/cert.key' 
# path to the certificate key  we generated
c.NotebookApp.password = 'sha1:<copy key generated in step above>'

While we are editing the jupyter notebook, these config lines below are worth adding/editing as will make life easier later on.

c.IPKernelApp.pylab = 'inline' 
#auto enables Matplotlib in-line figures 
c.NotebookApp.ip = '*' 
#allows connection to jupyter server from other than localhost.
#nbb: if using ssh tunnelling don't need this.
#nbb: refer my medium blog on this.
c.NotebookApp.open_browser = False
#eliminates an error message during notebook startup

When done making the above changes save and exit vim.

We can also test if file .jupyter/jupyter_notebook_config.json exists.

if yes, we can delete this file as the value entered for c.NotebookApp.password makes jupyter_notebook_config.json redundant. Leaving both will result in an error during jupyter notebook startup.

less .jupyter/jupyter_notebook_config.json
rm .jupyter/jupyter_notebook_config.json

There are many vim cheat sheets covering commonly used key sequences. Commands below should be adequate for most common edits.

search = [Esc]/<search-text>

copy line = [Esc]yy

paste = [Esc]p

Edit mode = [Esc]i

exit edit mode = [Esc]

write file = [Esc]:w

write file and exit vim = [Esc]:wq

exit vim without writing file = [Esc]q!

jump to end of file = [Esc]G

jump to start of file = [Esc]gg

There are _many_ configuration options for vim, this example of linting providing color coding to show a typo is default on many *nix installs. YMMV.

Now we need to start jupyter notebook and test our config file produces the desired results.

NB: when starting jupyter, be in the directory you want to save/access files in by default.

cd ~
source activate python3
jupyter notebook

Now when we start jupyter, we do not see a token in the url. Nice.

jupyter now serves on https not http, point your browser to the https version.

ie: if using the ssh tunnelling previously shown here.

https://localhost:9999

Because our certificate was not produced by a trusted certificate provider known to our browser, will see a message like this.

Advanced > add exception. (will need to do this only once)

Obviously best practice is to create the ssl certificate using a trusted certificate provider.

[firefox example below.]

We are asked for a password to login. This is the password used to generate the sha key above.

After login will see the list of files + directories accessible by jupyter notebook. NB: your browser will store the password for future use.

if we attempt to load with http instead of https

http://localhost:9999/

Will see this result in browser.

The yellow error logs below will appear in the console running jupyter when http:// requests are made to jupyter instead of https://

Green log files are for successful https:// requests.