From a78655c5a71d85e836a3890365d8fb65d1965671 Mon Sep 17 00:00:00 2001
From: Kyla Harper <kyla.seraphine@gmail.com>
Date: Thu, 27 Sep 2018 11:42:06 -0500
Subject: [PATCH] Add DummyAuthenticator documentation

---
 docs/source/api/auth.rst                              |  5 +++++
 docs/source/contributing/setup.rst                    |  7 +++----
 .../getting-started/authenticators-users-basics.md    | 11 +++++++++++
 docs/source/reference/authenticators.md               | 11 +++++++++--
 jupyterhub/auth.py                                    |  2 ++
 testing/jupyterhub_config.py                          |  3 +++
 6 files changed, 33 insertions(+), 6 deletions(-)

diff --git a/docs/source/api/auth.rst b/docs/source/api/auth.rst
index 39d0e791..fa5e7cd2 100644
--- a/docs/source/api/auth.rst
+++ b/docs/source/api/auth.rst
@@ -26,3 +26,8 @@ Module: :mod:`jupyterhub.auth`
 
 .. autoconfigurable:: PAMAuthenticator
 
+:class:`DummyAuthenticator`
+---------------------------
+
+.. autoconfigurable:: DummyAuthenticator
+
diff --git a/docs/source/contributing/setup.rst b/docs/source/contributing/setup.rst
index 159441be..73ffada6 100644
--- a/docs/source/contributing/setup.rst
+++ b/docs/source/contributing/setup.rst
@@ -116,9 +116,8 @@ Using DummyAuthenticator & SimpleSpawner
 ========================================
 
 To simplify testing of JupyterHub, it’s helpful to use
-`DummyAuthenticator <https://github.com/jupyterhub/dummyauthenticator>`_ 
-instead of the default JupyterHub authenticator and
-`SimpleSpawner <https://github.com/jupyterhub/simplespawner>`_ 
+:class:`~jupyterhub.auth.DummyAuthenticator` instead of the default JupyterHub
+authenticator and `SimpleSpawner <https://github.com/jupyterhub/simplespawner>`_ 
 instead of the default spawner.
 
 There is a sample configuration file that does this in
@@ -127,7 +126,7 @@ configuration:
 
 .. code:: bash
 
-   pip install jupyterhub-simplespawner jupyterhub-dummyauthenticator
+   pip install jupyterhub-simplespawner
    jupyterhub -f testing/jupyterhub_config.py
 
 The default JupyterHub `authenticator
diff --git a/docs/source/getting-started/authenticators-users-basics.md b/docs/source/getting-started/authenticators-users-basics.md
index 83c40951..5064d769 100644
--- a/docs/source/getting-started/authenticators-users-basics.md
+++ b/docs/source/getting-started/authenticators-users-basics.md
@@ -95,5 +95,16 @@ popular services:
 A generic implementation, which you can use for OAuth authentication
 with any provider, is also available.
 
+## Use DummyAuthenticator for testing
+
+The :class:`~jupyterhub.auth.DummyAuthenticator` is a simple authenticator that
+allows for any username/password unless if a global password has been set. If
+set, it will allow for any username as long as the correct password is provided.
+To set a global password, add this to the config file:
+
+```python
+c.DummyAuthenticator.password = "some_password"
+```
+
 [PAM]: https://en.wikipedia.org/wiki/Pluggable_authentication_module
 [OAuthenticator]: https://github.com/jupyterhub/oauthenticator
diff --git a/docs/source/reference/authenticators.md b/docs/source/reference/authenticators.md
index 68aa23d6..34bafaaf 100644
--- a/docs/source/reference/authenticators.md
+++ b/docs/source/reference/authenticators.md
@@ -5,8 +5,8 @@ Hub and single user notebook servers.
 
 ## The default PAM Authenticator
 
-JupyterHub ships only with the default [PAM][]-based Authenticator,
-for logging in with local user accounts via a username and password.
+JupyterHub ships with the default [PAM][]-based Authenticator, for
+logging in with local user accounts via a username and password.
 
 ## The OAuthenticator
 
@@ -34,6 +34,13 @@ popular services:
 A generic implementation, which you can use for OAuth authentication
 with any provider, is also available.
 
+## The Dummy Authenticator
+
+When testing, it may be helpful to use the
+:class:`~jupyterhub.auth.DummyAuthenticator`. This allows for any username and
+password unless if a global password has been set. Once set, any username will
+still be accepted but the correct password will need to be provided.
+
 ## Additional Authenticators
 
 A partial list of other authenticators is available on the
diff --git a/jupyterhub/auth.py b/jupyterhub/auth.py
index aaefe483..93c25f94 100644
--- a/jupyterhub/auth.py
+++ b/jupyterhub/auth.py
@@ -688,6 +688,7 @@ class PAMAuthenticator(LocalAuthenticator):
             self.open_sessions = False
 
 class DummyAuthenticator(Authenticator):
+    """Simple authentication for testing use"""
     password = Unicode(
         None,
         allow_none=True,
@@ -701,6 +702,7 @@ class DummyAuthenticator(Authenticator):
 
     @gen.coroutine
     def authenticate(self, handler, data):
+        """Checks against a global password if it's been set. If not, allow any user/pass combo"""
         if self.password:
             if data['password'] == self.password:
                 return data['username']
diff --git a/testing/jupyterhub_config.py b/testing/jupyterhub_config.py
index 1fbbf66c..8cee48f9 100644
--- a/testing/jupyterhub_config.py
+++ b/testing/jupyterhub_config.py
@@ -9,6 +9,9 @@ to enable testing without administrative privileges.
 c = get_config() # noqa
 c.JupyterHub.authenticator_class = DummyAuthenticator
 
+# Optionally set a global password that all users must use
+# c.DummyAuthenticator.password = "your_password"
+
 try:
     from simplespawner import SimpleLocalProcessSpawner
 except ImportError: