From b48b45f22fade3d1c610d3af5d1e471f7d744eef Mon Sep 17 00:00:00 2001
From: Jeff Knupp <jknupp@appnexus.com>
Date: Fri, 18 Apr 2014 07:58:42 -0400
Subject: [PATCH] update docs

---
 docs/authentication.rst | 61 +++++++++++++++++++++++++++++++++++++++++
 docs/index.rst          |  1 +
 2 files changed, 62 insertions(+)
 create mode 100644 docs/authentication.rst

diff --git a/docs/authentication.rst b/docs/authentication.rst
new file mode 100644
index 0000000..219f972
--- /dev/null
+++ b/docs/authentication.rst
@@ -0,0 +1,61 @@
+==============
+Authentication
+==============
+
+``sandman`` supports HTTP basic authentication, meaning a username and password
+must be passed on each request via the ``Authorization`` header. 
+
+Enabling Authentication
+-----------------------
+
+Enabling authentication in your ``sandman`` installation is a straight-forward task.
+You'll need to define two functions:
+
+* ``get_password()``
+* ``before_request()``
+
+The former is required by ``Flask-HTTPAuth``, which powers ``sandman's``
+authentication. The latter is used to ensure that _all_ requests are authorized.
+
+``get_password``
+~~~~~~~~~~~~~~~~
+
+The ``get_password`` function takes a ``username`` as an argument and should
+return the associated password for that user. To notify Flask-HTTPAuth that this
+is the function responsible for returning passwords, it must be wrapped with the 
+``@auth.get_password`` decorator (``auth`` is importable from ``sandman``, e.g.
+``from sandman import app, db, auth``). How you implement your user
+management system is up to you; you simply need to implement ``get_password`` in
+whatever way is most appropriate for your security setup.
+
+As a trivial example, here's an implementation of ``get_password`` that always
+returns ``secret``, meaning ``secret`` must be the password, regardless of
+the ``username``::
+
+    @auth.get_password
+    def get_password(username):
+        """Return the password for *username*."""
+        return 'secret'
+
+``before_request``
+~~~~~~~~~~~~~~~~~~
+
+Once you've hooked up your password function, it's time to tell Flask which
+requests should require authentication. Rather than picking and choosing on a
+request by request basis, we use the ``@app.before_request`` decorator included
+in Flask to make sure _all_ requests are authenticated. Here's a sample
+implementation::
+
+    @app.before_request
+    @auth.login_required
+    def before_request():
+        pass
+
+Notice the function just calls ``pass``; it needn't have any logic, since the
+logic is added by Flask-HTTPAuth's ``@auth.login_required`` decorator.
+
+Token-based Authentication
+--------------------------
+
+There are plans for ``sandman`` to support token-based authentication, but this
+currently isn't supported and no time frame for implementation has been set.
diff --git a/docs/index.rst b/docs/index.rst
index c58491f..44910d1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,6 +14,7 @@ Contents:
    installation
    using_sandman
    admin
+   authentication
    sandman