- Add interface docs related to how to create authentication policies

  and authorization policies to the "Security" narrative chapter.

3 files changed, 68 insertions, 6 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index f5d9eca37..30e11ee96 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -172,6 +172,9 @@ Bug Fixes
 Documentation
 -------------
 
+- Add interface docs related to how to create authentication policies
+  and authorization policies to the "Security" narrative chapter.
+
 - Added a (fairly sad) "Combining Traversal and URL Dispatch" chapter
   to the narrative documentation.
 
diff --git a/TODO.txt b/TODO.txt
index 7fe2840f8..d785f7581 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -1,11 +1,5 @@
 - path module: use pkg_resources (if feasible, given ZCML)
 
-- audit use of "functools.wraps" (pickling no longer required)
-
-- Docs: add interface docs for IAuthenticationPolicy and
-  IAuthorizationPolicy, so people who care might be able to write
-  their own.
-
 - See if we can do something about always looking up ISettings when we
   want to see if auto template reload is on (queryUility is a bit
   expensive for this task).
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 52178fa26..0a97452ca 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -388,3 +388,68 @@ these objects will have a ``msg`` attribute, which is a string
 indicating why permission was denied or allowed.  Introspecting this
 information in the debugger or via print statements when a
 ``has_permission`` fails is often useful.
+
+Creating Your Own Authentication Policy
+---------------------------------------
+
+:mod:`repoze.bfg` ships with a number of useful out-of-the-box
+security policies (see :ref:`authentication_policies_api_section`).
+However, creating your own authentication policy is often necessary
+when you want to control the "horizontal and vertical" of how your
+users authenticate.  Doing so is matter of creating an instance of
+something that implements the following interface:
+
+.. code-block:: python
+
+   class AuthenticationPolicy(object):
+       """ An object representing a BFG authentication policy. """
+       def authenticated_userid(self, request):
+           """ Return the authenticated userid or ``None`` if no
+           authenticated userid can be found. """
+
+       def effective_principals(self, request):
+           """ Return a sequence representing the effective principals
+           including the userid and any groups belonged to by the current
+           user, including 'system' groups such as Everyone and
+           Authenticated. """
+
+       def remember(self, request, principal, **kw):
+           """ Return a set of headers suitable for 'remembering' the
+           principal named ``principal`` when set in a response.  An
+           individual authentication policy and its consumers can decide
+           on the composition and meaning of **kw. """
+       
+       def forget(self, request):
+           """ Return a set of headers suitable for 'forgetting' the
+           current user on subsequent requests. """
+
+Pass the object you create into the ``repoze.bfg.router.make_app``
+function as the ``authentication_policy`` argument at application
+startup time (usually within a ``run.py`` module).
+
+Creating Your Own Authorization Policy
+--------------------------------------
+
+An authentiction policy the policy that allows or denies access after
+a user is authenticated.  By default, :mod:`repoze.bfg` will use the
+``repoze.bfg.authorization.ACLAuthorizationPolicy`` if an
+authentication policy is activated.  Creating and using your own
+authorization policy is a matter of creating an instance of an object
+that implements the following interface:
+
+.. code-block:: python
+
+    class IAuthorizationPolicy(object):
+        """ A adapter on context """
+        def permits(self, context, principals, permission):
+            """ Return True if any of the principals is allowed the
+            permission in the current context, else return False """
+            
+        def principals_allowed_by_permission(self, context, permission):
+            """ Return a set of principal identifiers allowed by the 
+                permission """
+
+Pass the object you create into the ``repoze.bfg.router.make_app``
+function as the ``authorization_policy`` argument at application
+startup time (usually within a ``run.py`` module).  You must also pass
+an ``authentication_policy`` if you pass an ``authorization_policy``.