Package: jhproxy
jhproxyA port proxy for JupyterHub when using the DockerSpawner, optionally with
authentication.This code is hosted athttps://github.com/aiidalab/jhproxy.If you use JupyterHub, and some app inside the docker spawned by Jupyter
opens a port (e.g. it exposes a REST API), these are not accessible outside the
docker container, in general.A nice Jupyter server exension,nbserverproxy, exists to proxy a given port
through the notebook server.
This would work, but requires that anybody performing a request has access to
the JupyterHub token. This could be extracted from the browser and passed to an
external app that wants to use the API (command line, or throgh AJAX requests
from a different site), but:this is cumbersomeif someone gets the token, they get access to the whole docker container of the
userTo alleviate this, we wrotejhproxy.
This needs to be installed by the person maintaining the JupyterHub installation,
but allows to:decide which ports can be forwarded (more can be forwarded, but they need to
be specified, see documentation below)allow for (optional) authentication of the proxy requests (via aX-Proxy-Tokenthat should be passed in the HTTP Request Headers)Allow a logged-in JupyterHub user to enable, disable or regenerate a tokenAdd an API endpoint to obtain the current token for the currently logged-in
JupyterHub user (so this can be given to a client performing the API requests
via the proxy).Note that this proxy only works currently for a DockerSpawner (to use
token authentication you need to use the providedjhproxy.spawners.TokenizedDockerSpawner, that extends the image).DocumentationIn order to install and use this extension, you need to do the following on
the machine where JupyterHub is installed:installjhproxy:pip instal jhproxyconfigure properly yourjupyterhub_config.pyto decide which ports to
proxy, under which address, etc.
We provide a fully documented working example insideexamples/jupyterhub_config.py. Feel free to copy, reuse and edit to your needs.We provide below just a few additional notes on how to configure itAuthorization setupIf you don't need authorization, you can just use the standardDockerSpawnerspawner; ports will simply be proxied.If you instead want authorization, usejbproxy.spawners.TokenizedDockerSpawneras in the configuration example. As shown there, there are also a few options
to decide the default token to be generated the first time the spawner is
create (disabled, allow all, generate new random token).How to use itThe user (once logged in JupyterHub) can use theProxyTokenHandler(under the
urlhttp(s)://JUPYTERHUBHOST/hub/proxytoken/) to get the current token (via GET requests) or to ask to change it (via POST requests).
This endpoint requires to be authenticated.To see an example, load inside your jupyter the notebook provided underexamples/Proxy token manager.ipynb.
Run it and then press the buttons to get the current token, or change it (disabling all access, enabling it for everybody, or generating a new random token).NOTE: this needs to be done inside the jupyter provided by JupyterHub,
otherwise the JupyterHub authorization cookies will not be passed and you
will not be able to access these endpoints.To use it:Login in JupyterHub(Optional, if you did not choose the option in thejupyterhub_config.pyto generate a random token at startup) Upload theexamples/Proxy token manager.ipynb, run it and create a new tokenOpen a terminal and start a server serving on one of the ports you chose (e.g.:python -m SimpleHTTPServer 5000)Try to connect to it. If you set it without token check (allow all), you can
just go to the correct URL in your browser (e.g.http://localhost:8000/hub/proxy5000/YOURJUPYTERHUBUSERNAME). Otherwise, to check using a proxy
via a AJAX request (that checks that also the CORS headers are properly
set in the server), use the simple example underexamples/client_ajax_CORS_example.html: put the correct URL (change the stringUSERNAMEHERE, and possibly change the token, that you can get as
described above via the Jupyter notebook, or via the link provided in the
page, if you have already logged into JupyterHub in the same browser and you have not changed the URL of the/proxytoken/endpoint).NotesIf the Docker host is a Mac, you need to start the server to be proxied
inside docker on the 0.0.0.0 interface, otherwise Docker will not allow to
forward it due to the way networking is configured by default on Docker
on the Mac. Note that this is a Docker configuration and not a jhproxy issue.LicenseThis code is released under a MIT license.
We acknowledgenbserverproxyfrom
which we have taken free inspiration for the proxy part.