docs and an example

Author: leifj

example/plugins/microservices/attribute_authz.yaml.example

@@ -0,0 +1,21 @@
+module: satosa.micro_services.attribute_authorization.AttributeAuthorization
+name: AttributeAuthorization
+config:
+    attribute_allow:
+        target_provider1:
+            requester1:
+                attr1: 
+                   - "^foo:bar$"
+                   - "^kaka$"
+            default:
+                attr1:
+                   - "plupp@.+$"
+        "":
+            "":
+                attr2:
+                   - "^knytte:.*$"
+    attribute_deny:
+        default:
+            default:
+                eppn:
+                   - "^[^@]+$"

src/satosa/micro_services/attribute_authorization.py

@@ -10,6 +10,43 @@ def _filters(f, requester, provider):
 
 class AttributeAuthorization(ResponseMicroService):
 
+    """
+A microservice that performs simple regexp-based authorization based on response
+attributes. The configuration assumes a dict with two keys: attributes_allow
+and attributes_deny. An examples speaks volumes:
+
+```yaml
+config:
+    attribute_allow:
+        target_provider1:
+            requester1:
+                attr1:
+                   - "^foo:bar$"
+                   - "^kaka$"
+            default:
+                attr1:
+                   - "plupp@.+$"
+        "":
+            "":
+                attr2:
+                   - "^knytte:.*$"
+    attribute_deny:
+        default:
+            default:
+                eppn:
+                   - "^[^@]+$"
+
+```
+
+The use of "" and 'default' is synonymous. Attribute rules are not overloaded
+or inherited. For instance a response from "provider2" would only be allowed
+through if the eppn attribute had all values containing an '@' (something 
+perhaps best implemented via an allow rule in practice). Responses from
+target_provider1 bound for requester1 would be allowed through only if attr1
+contained foo:bar or kaka. Note that attribute filters (the leaves of the 
+structure above) are ORed together - i.e any attribute match is sufficient.
+    """
+
     def __init__(self, config, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.attribute_allow = config.get("attribute_allow", {})