Add DummyAuthenticator documentation

docs/source/api/auth.rst

@@ -26,3 +26,8 @@ Module: :mod:`jupyterhub.auth`
 
 .. autoconfigurable:: PAMAuthenticator
 
+:class:`DummyAuthenticator`
+---------------------------
+
+.. autoconfigurable:: DummyAuthenticator
+

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>`_ 
+:class:`~jupyterhub.auth.DummyAuthenticator` instead of the default JupyterHub
-instead of the default JupyterHub authenticator and
+authenticator and `SimpleSpawner <https://github.com/jupyterhub/simplespawner>`_ 
-`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

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

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,
+JupyterHub ships with the default [PAM][]-based Authenticator, for
-for logging in with local user accounts via a username and password.
+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

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']

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: