From 91f209712599a00979cb3aacff1f30f538972c38 Mon Sep 17 00:00:00 2001
From: termie <github@anarkystic.com>
Date: Thu, 17 Nov 2011 12:13:09 -0800
Subject: [PATCH] add an example for capability rbac

---
 README.rst | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/README.rst b/README.rst
index a746089cd3..2d70832902 100644
--- a/README.rst
+++ b/README.rst
@@ -146,6 +146,30 @@ contain the matches. For example::
                      credentials)
 
 
+Credentials are generally built from the user metadata in the 'extras' part
+of the Identity API. So, adding a 'role' to the user just means adding the role
+to the user metadata.
+
+
+Capability RBAC
+---------------
+
+(Not yet implemented.)
+
+Another approach to authorization can be action-based, with a mapping of roles
+to which capabilities are allowed for that role. For example::
+
+  credentials = {'user_id': 'foo', 'is_admin': 1, 'roles': ['nova:netadmin']}
+
+  # add a policy
+  policy_api.add_policy('action:nova:add_network', ('roles:nova:netadmin',))
+
+  policy_api.can_haz(('action:nova:add_network',), credentials)
+
+
+In the backend this would look up the policy for 'action:nova:add_network' and
+then do what is effectively a 'Simple Match' style match against the creds.
+
 
 -----------
 Still To Do