diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst index 8b1bf61001..dcf51b132b 100644 --- a/docs/source/changelog.rst +++ b/docs/source/changelog.rst @@ -15,14 +15,14 @@ For more detailed information, see .. _release-4.3: 4.3 ------ +--- 4.3 is a minor release with many bug fixes and improvements. Highlights: - API for creating mime-type based renderer extensions using :code:`OutputArea.register_mime_type` and :code:`Notebook.render_cell_output` methods. See `mimerender-cookiecutter `__ for reference implementations and cookiecutter. -- Enable token authentication by default +- Enable token authentication by default. See :ref:`server_security` for more details. - Update security docs to reflect new signature system - Switched from term.js to xterm.js @@ -31,7 +31,7 @@ Bug fixes: - Ensure variable is set if exc_info is falsey - Catch and log handler exceptions in :code:`events.trigger` - Add debug log for static file paths -- Don't check origin on token-authenticated requests +- Don't check origin on token-authenticated requests - Remove leftover print statement - Fix highlighting of Python code blocks - :code:`json_errors` should be outermost decorator on API handlers diff --git a/docs/source/security.rst b/docs/source/security.rst index eb1e039e4a..4912707899 100644 --- a/docs/source/security.rst +++ b/docs/source/security.rst @@ -1,7 +1,77 @@ + +.. _server_security: + +Security in the Jupyter notebook server +======================================= + +Since access to the Jupyter notebook server means access to running arbitrary code, +it is important to restrict access to the notebook server. +For this reason, notebook 4.3 introduces token-based authentication that is **on by default**. + +.. note:: + + If you enable a password for your notebook server, + token authentication is not enabled by default, + and the behavior of the notebook server is unchanged from from versions earlier than 4.3. + +When token authentication is enabled, the notebook uses a token to authenticate requests. +This token can be provided to login to the notebook server in three ways: + +- in the ``Authorization`` header, e.g.:: + + Authorization: token abcdef... + +- In a URL parameter, e.g.:: + + https://my-notebook/tree/?token=abcdef... + +- In the password field of the login form that will be shown to you if you are not logged in. + +When you start a notebook server with token authentication enabled (default), +a token is generated to use for authentication. +This token is logged to the terminal, so that you can copy/paste the URL into your browser:: + + [I 11:59:16.597 NotebookApp] The Jupyter Notebook is running at: http://localhost:8888/?token=c8de56fa4deed24899803e93c227592aef6538f93025fe01 + + +If the notebook server is going to open your browser automatically +(the default, unless ``--no-browser`` has been passed), +an *additional* token is generated for launching the browser. +This additional token can be used only once, +and is used to set a cookie for your browser once it connects. +After your browser has made its first request with this one-time-token, +the token is discarded and a cookie is set in your browser. + +At any later time, you can see the tokens and URLs for all of your running servers with :command:`jupyter notebook list`:: + + $ jupyter notebook list + Currently running servers: + http://localhost:8888/?token=abc... :: /home/you/notebooks + https://0.0.0.0:9999/?token=123... :: /tmp/public + http://localhost:8889/ :: /tmp/has-password + +For servers with token-authentication enabled, the URL in the above listing will include the token, +so you can copy and paste that URL into your browser to login. +If a server has no token (e.g. it has a password or has authentication disabled), +the URL will not include the token argument. +Once you have visited this URL, +a cookie will be set in your browser and you won't need to use the token again, +unless you switch browsers, clear your cookies, or start a notebook server on a new port. + + +You can disable authentication altogether by setting the token and password to empty strings, +but this is **NOT RECOMMENDED**, unless authentication or access restrictions are handled at a different layer in your web application: + +.. sourcecode:: python + + c.NotebookApp.token = '' + c.NotebookApp.password = '' + + .. _notebook_security: -Security in Jupyter notebooks -============================= +Security in notebook documents +============================== As Jupyter notebooks become more popular for sharing and collaboration, the potential for malicious people to attempt to exploit the notebook diff --git a/notebook/notebookapp.py b/notebook/notebookapp.py index 88be0fba94..783737b5af 100755 --- a/notebook/notebookapp.py +++ b/notebook/notebookapp.py @@ -576,11 +576,12 @@ def _write_cookie_secret_file(self, secret): self.cookie_secret_file ) - token = Unicode( + token = Unicode('', help="""Token used for authenticating first-time connections to the server. - - Only used when no password is enabled. - + + When no password is enabled, + the default is to generate a new, random token. + Setting to an empty string disables authentication altogether, which is NOT RECOMMENDED. """ ).tag(config=True) diff --git a/notebook/templates/login.html b/notebook/templates/login.html index c3b2bef72a..1cf0a3fad1 100644 --- a/notebook/templates/login.html +++ b/notebook/templates/login.html @@ -20,7 +20,7 @@ - {% elif login_token_available %} -
-

- This notebook server has no password set, - but token-authentication is enabled. - - You need to open the notebook server with its first-time login token in the URL, - or enable a password in order to gain access. - The command: -

-
jupyter notebook list
-

- will show you the URLs of running servers with their tokens, - which you can copy and paste into your browser. -

-
{% else %}

No login available, you shouldn't be seeing this page.

{% endif %} @@ -58,6 +42,28 @@ {% endfor %} {% endif %} + {% block token_message %} +
+

+ If this notebook server has no password set, token authentication is enabled. + + You need to open the notebook server with its first-time login token in the URL, + or enable a password in order to gain access. + The command: +

+
jupyter notebook list
+

+ will show you the URLs of running servers with their tokens, + which you can copy and paste into your browser. For example: +

+
Currently running servers:
+http://localhost:8888/?token=c8de56fa... :: /Users/you/notebooks
+
+

+ Or you can paste just the token value into the password field on this page. +

+
+ {% endblock token_message %} {% endblock %}