3 files changed, 33 insertions, 8 deletions

diff --git a/src/mailman/rest/docs/basic.txt b/src/mailman/rest/docs/basic.txt
index e5dab9ea8..179185a95 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.
@@ -30,5 +38,16 @@ 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', None, None, 'baduser', 'badpass')
+    Traceback (most recent call last):
+    ...
+    HTTPError: HTTP Error 401: 401 Unauthorized
+    ...
 
 .. _REST: http://en.wikipedia.org/wiki/REST
diff --git a/src/mailman/testing/layers.py b/src/mailman/testing/layers.py
index 8f16d5940..ed0755819 100644
--- a/src/mailman/testing/layers.py
+++ b/src/mailman/testing/layers.py
@@ -37,7 +37,8 @@ import tempfile
 
 from pkg_resources import resource_string
 from textwrap import dedent
-from urllib2 import urlopen, URLError
+from urllib2 import urlopen, URLError, Request
+from base64 import encodestring
 from zope.component import getUtility
 
 from mailman.config import config
@@ -273,7 +274,10 @@ class RESTLayer(SMTPLayer):
         until = datetime.datetime.now() + TEST_TIMEOUT
         while datetime.datetime.now() < until:
             try:
-                fp = urlopen('http://localhost:8001/3.0/system')
+                request = Request('http://localhost:8001/3.0/system')
+                base64string = encodestring('%s:%s' % ("restadmin", "restpass")).replace('\n', '')
+                request.add_header("Authorization", "Basic %s" % base64string)   
+                fp = urlopen(request)
             except URLError:
                 pass
             else:
diff --git a/src/mailman/tests/test_documentation.py b/src/mailman/tests/test_documentation.py
index c0f8dca20..2b3e417f3 100644
--- a/src/mailman/tests/test_documentation.py
+++ b/src/mailman/tests/test_documentation.py
@@ -39,6 +39,7 @@ from email import message_from_string
 from httplib2 import Http
 from urllib import urlencode
 from urllib2 import HTTPError
+from base64 import encodestring
 
 import mailman
 
@@ -109,7 +110,7 @@ def dump_msgdata(msgdata, *additional_skips):
         print '{0:{2}}: {1}'.format(key, msgdata[key], longest)
 
 
-def call_http(url, data=None, method=None):
+def call_http(url, data=None, method=None, username="restadmin", password="restpass"):
     """'Call' a URL with a given HTTP method and return the resulting object.
 
     The object will have been JSON decoded.
@@ -131,6 +132,7 @@ def call_http(url, data=None, method=None):
         else:
             method = 'POST'
     method = method.upper()
+    headers['Authorization'] = 'Basic %s' % encodestring('%s:%s' % (username, password)).replace('\n', '')
     response, content = Http().request(url, method, data, headers)
     # If we did not get a 2xx status code, make this look like a urllib2
     # exception, for backward compatibility with existing doctests.
@@ -143,7 +145,7 @@ def call_http(url, data=None, method=None):
     return json.loads(content)
 
 
-def dump_json(url, data=None, method=None):
+def dump_json(url, data=None, method=None, username="restadmin", password="restpass"):
     """Print the JSON dictionary read from a URL.
 
     :param url: The url to open, read, and print.
@@ -153,7 +155,7 @@ def dump_json(url, data=None, method=None):
     :param method: Alternative HTTP method to use.
     :type method: str
     """
-    data = call_http(url, data, method)
+    data = call_http(url, data, method, username, password)
     if data is None:
         return
     for key in sorted(data):