update readme

README.md

@@ -1,5 +1,5 @@
-Swift3
+SwiftPolicy Middleware.
-------
+-----------------------
 
 SwiftPolicy Middleware for OpenStack Swift, allows to use json policy file 
 format to handle swift authorizations.
@@ -15,18 +15,18 @@ Install
 -------
 
 1) Install SwiftPolicy  with ``sudo python setup.py install`` or ``sudo python
-   setup.py develop`` or via whatever packaging system you may be using.
+   setup.py develop``.
 
 2) Alter your proxy-server.conf pipeline to have SwiftPolicy:
 
-You can use SwiftPolicy in place of keystoneauth middleware:
+For example, you can use SwiftPolicy in place of keystoneauth middleware:
 
-    Was::
+    Change::
 
         [pipeline:main]
         pipeline = catch_errors cache tempauth proxy-server
 
-    Change To::
+    To::
 
         [pipeline:main]
         pipeline = catch_errors cache swiftpolicy tempauth proxy-server
@@ -37,4 +37,54 @@ Policy file is given using ``policy`` option
 
     [filter:swift3]
     use = egg:swiftpolicy#swiftpolicy
-    policy = {HERE}/default.json
+    policy = %(here)s/default.json
+
+We install along with this middleare a default policy file in /etc/swift/default.json, which make our middleware behaves
+the same way as keystoneauth (for compatibility reasons).
+
+
+Policy file
+-----------
+
+The policy file will list all possible actions on swift proxy.
+Action's format is: "<http verbe>_<swift entity>" (example: "get_container", "put_object", etc).
+
+    ...
+    "get_container": "rule:allowed_for_user",
+    "put_container": "rule:allowed_for_user",
+    "delete_container": "rule:allowed_for_user",
+    ...
+
+Policy file contains also two specific rules: "swift_owner" "reseller_request", they define
+when swift_owner and reseller_request headers are set to true, as those two value are part
+of the contract between the auth system and swift.
+
+    ...
+    "swift_owner": "rule:swift_reseller or rule:swift_operator",
+    "reseller_request": "rule:swift_reseller",
+    ...
+ 
+
+Example
+-------
+
+* To deny creation of new containers: set put_container to '!':
+
+        ...
+        "get_container": "rule:allowed_for_user",
+        "put_container": "!",
+        ...
+
+* To restrict creation of new container to users with role "admin":
+
+        ...
+        "get_container": "rule:allowed_for_user",
+        "put_container": "role:admin",
+        ...
+
+Limitations
+-----------
+
+* swiftpolicy does not support dynamic laoding of the policy file, and thus, swift proxy have
+to be restarted when policy file is updated.
+

policies/default.json

@@ -1,18 +1,17 @@
 {
     "is_anonymous": "identity:None",
     "is_authenticated": "not rule:is_anonymous",
+
     "swift_reseller": "role:reseller",
-    "swift_operator": "role:admin or role:swiftoperator",
+    "swift_operator": "role:admin or role:Member",
 
     "swift_owner": "rule:swift_reseller or rule:swift_operator",
-
     "reseller_request": "rule:swift_reseller",
+
     "same_tenant": "account:%(account)s",
     "tenant_mismatch": "not rule:same_tenant",
-
     "allowed_for_authenticated": "rule:swift_reseller or acl:check_cross_tenant or acl:check_is_public or (rule:same_tenant and rule:swift_operator) or (rule:same_tenant and acl:check_roles)",
     "allowed_for_anonymous": "is_authoritative:True and acl:check_is_public",
-
     "allowed_for_user": "(rule:is_authenticated and rule:allowed_for_authenticated) or rule:allowed_for_anonymous",
 
     "get_account": "rule:allowed_for_user",
@@ -20,12 +19,14 @@
     "head_account": "rule:allowed_for_user",
     "delete_account": "rule:swift_reseller",
     "options_account": "",
+
     "get_container": "rule:allowed_for_user",
     "put_container": "rule:allowed_for_user",
     "delete_container": "rule:allowed_for_user",
     "post_container": "rule:allowed_for_user",
     "head_container": "rule:allowed_for_user",
     "options_container": "",
+
     "get_object": "rule:allowed_for_user",
     "put_object": "rule:allowed_for_user",
     "copy_object": "rule:allowed_for_user",