Add Basic Auth support to the REST API, given by Jimmy Bergman, with style

corrections by Barry.

1 files changed, 25 insertions, 3 deletions

diff --git a/src/mailman/rest/docs/basic.txt b/src/mailman/rest/docs/basic.txt
index e5dab9ea8..177082c4a 100644
--- a/src/mailman/rest/docs/basic.txt
+++ b/src/mailman/rest/docs/basic.txt
@@ -2,12 +2,20 @@
 REST server
 ===========
 
-Mailman exposes a REST_ HTTP server for administrative control.
+Mailman exposes a REST HTTP server for administrative control.
 
 The server listens for connections on a configurable host name and port.
+
+It is always protected by HTTP basic authentication using a single global
+username and password. The credentials are set in the webservice section
+of the config using the admin_user and admin_pass properties.
+
 Because the REST server has full administrative access, it should always be
-run only on localhost, unless you really know what you're doing.  The Mailman
-major and minor version numbers are in the URL.
+run only on localhost, unless you really know what you're doing.  In addition
+you should set the username and password to secure values and distribute them
+to any REST clients with reasonable precautions.
+
+The Mailman major and minor version numbers are in the URL.
 
 System information can be retrieved from the server.  By default JSON is
 returned.
@@ -31,4 +39,18 @@ When you try to access a link that doesn't exist, you get the appropriate HTTP
     HTTPError: HTTP Error 404: 404 Not Found
 
 
+Invalid credentials
+===================
+
+When you try to access the REST server using invalid credentials you will get
+an appropriate HTTP 401 Unauthorized error.
+
+    >>> dump_json('http://localhost:8001/3.0/system',
+    ...           username='baduser', password='badpass')
+    Traceback (most recent call last):
+    ...
+    HTTPError: HTTP Error 401: 401 Unauthorized
+    ...
+
+
 .. _REST: http://en.wikipedia.org/wiki/REST