better docs for token auth

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 <https://github.com/jupyterlab/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

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

notebook/notebookapp.py

@@ -576,11 +576,12 @@ def _write_cookie_secret_file(self, secret):
                 self.cookie_secret_file
             )
 
-    token = Unicode(
+    token = Unicode('<generated>',
         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)

notebook/templates/login.html

@@ -20,7 +20,7 @@
       <div class="navbar-inner">
         <div class="container">
           <div class="center-nav">
-            <p class="navbar-text nav">Password:</p>
+            <p class="navbar-text nav">Password or token:</p>
             <form action="{{base_url}}login?next={{next}}" method="post" class="navbar-form pull-left">
               <input type="password" name="password" id="password_input" class="form-control">
               <button type="submit" id="login_submit">Log in</button>
@@ -30,22 +30,6 @@
       </div>
     </div>
     </div>
-    {% elif login_token_available %}
-      <div class="col-sm-6 col-sm-offset-3 text-left">
-      <p class="warning">
-        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:
-      </p>
-      <pre>jupyter notebook list</pre>
-      <p>
-        will show you the URLs of running servers with their tokens,
-        which you can copy and paste into your browser.
-      </p>
-    </div>
     {% else %}
     <p>No login available, you shouldn't be seeing this page.</p>
     {% endif %}
@@ -58,6 +42,28 @@
       {% endfor %}
       </div>
     {% endif %}
+    {% block token_message %}
+    <div class="col-sm-6 col-sm-offset-3 text-left">
+      <p class="warning">
+        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:
+      </p>
+      <pre>jupyter notebook list</pre>
+      <p>
+        will show you the URLs of running servers with their tokens,
+        which you can copy and paste into your browser. For example:
+      </p>
+      <pre>Currently running servers:
+http://localhost:8888/?token=c8de56fa... :: /Users/you/notebooks
+</pre>
+      <p>
+        Or you can paste just the token value into the password field on this page.
+      </p>
+    </div>
+    {% endblock token_message %}
 </div>
 
 {% endblock %}