Merge pull request #5037 from yuvipanda/dummy-path

Add SharedPasswordAuthenticator

docs/source/reference/api/auth.md

@@ -1,33 +1,42 @@
 # Authenticators
 
-## Module: {mod}`jupyterhub.auth`
-
 ```{eval-rst}
-.. automodule:: jupyterhub.auth
+.. module:: jupyterhub.auth
 ```
 
-### {class}`Authenticator`
+## {class}`Authenticator`
 
 ```{eval-rst}
 .. autoconfigurable:: Authenticator
    :members:
 ```
 
-### {class}`LocalAuthenticator`
+## {class}`LocalAuthenticator`
 
 ```{eval-rst}
 .. autoconfigurable:: LocalAuthenticator
    :members:
 ```
 
-### {class}`PAMAuthenticator`
+## {class}`PAMAuthenticator`
 
 ```{eval-rst}
 .. autoconfigurable:: PAMAuthenticator
 ```
 
-### {class}`DummyAuthenticator`
+## {class}`DummyAuthenticator`
 
 ```{eval-rst}
 .. autoconfigurable:: DummyAuthenticator
 ```
+
+```{eval-rst}
+.. module:: jupyterhub.authenticators.shared
+```
+
+## {class}`SharedPasswordAuthenticator`
+
+```{eval-rst}
+.. autoconfigurable:: SharedPasswordAuthenticator
+   :no-inherited-members:
+```

docs/source/reference/authenticators.md

@@ -36,10 +36,15 @@ A [generic implementation](https://github.com/jupyterhub/oauthenticator/blob/mas
 
 ## The Dummy Authenticator
 
-When testing, it may be helpful to use the
-{class}`~.jupyterhub.auth.DummyAuthenticator`. This allows for any username and
-password unless a global password has been set. Once set, any username will
-still be accepted but the correct password will need to be provided.
+When testing, it may be helpful to use the {class}`~.jupyterhub.auth.DummyAuthenticator`:
+
+```python
+c.JupyterHub.authenticator_class = "dummy"
+# always a good idea to limit to localhost when testing with an insecure config
+c.JupyterHub.ip = "127.0.0.1"
+```
+
+This allows for any username and password to login, and is _wildly_ insecure.
 
 To use, specify
 
@@ -52,6 +57,35 @@ The DummyAuthenticator's default `allow_all` is True,
 unlike most other Authenticators.
 :::
 
+:::{deprecated} 5.3
+Setting a password on DummyAuthenticator is deprecated.
+Use the new {class}`~.jupyterhub.authenticators.shared.SharedPasswordAuthenticator`
+if you want to set a shared password for users.
+:::
+
+## Shared Password Authenticator
+
+:::{versionadded} 5.3
+{class}`~.jupyterhub.authenticators.shared.SharedPasswordAuthenticator` is added and [DummyAuthenticator.password](#DummyAuthenticator.password) is deprecated.
+:::
+
+For short-term deployments like workshops where there is no real user data to protect and you trust users to not abuse the system or each other,
+{class}`~.jupyterhub.authenticators.shared.SharedPasswordAuthenticator` can be used.
+
+Set a [user password](#SharedPasswordAuthenticator.user_password) for users to login:
+
+```python
+c.JupyterHub.authenticator_class = "shared-password"
+c.SharedPasswordAuthenticator.user_password = "my-workshop-2042"
+```
+
+You can also grant admin users access by adding them to `admin_users` and setting a separate [admin password](#SharedPasswordAuthenticator.admin_password):
+
+```python
+c.Authenticator.admin_users = {"danger", "eggs"}
+c.SharedPasswordAuthenticator.admin_password = "extra-super-secret-secure-password"
+```
+
 ## Additional Authenticators
 
 Additional authenticators can be found on GitHub