add policies and examples

1 files changed, 124 insertions, 15 deletions

diff --git a/README.md b/README.md
index 4c00719..d5e5e59 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,24 @@
-# Example
+# API Authn/Authz
 
-This example is broken down into 3 services:
+* Authn: Prove who you say you are (e.g. passport)
+* Authz: Prove that you're allowed to do what you're trying to do. (e.g. plane ticket)
 
-* api:
-  * provides a simple rest API
-  * port: 4000
-* ui:
-  * provides just enough HTML to login and click buttons to demonstrate authz.
-  * port: 3000
+## Example
 
+* Auth0
+  * provides OpenID Connect.
+  * returns an access token.
+* UI (:3000)
+  * initiates a login/logout with Auth0.
+  * retrieves data from the api using the access token.
+* API (:4000)
+  * authorizes requests using the access token from the request.
+  * returns data via a REST API.
 
 ```
                           ||========================||
   ----------    --------- || --------------- ------ ||
-  | Browser |   | Auth0 | || | API ||| PDP | | DB | ||
+  |   UI   |    | Auth0 | || | API ||| PDP | | DB | ||
   ----------    --------- || --------------- ------ ||
        |            |     ||    |       |       |   ||
        | GET /login |     ||    |       |       |   ||
@@ -43,12 +48,7 @@ This example is broken down into 3 services:
        |            |     ||========================||
 ```
 
-The PDP enforces policy by checking:
-
-* casbin policies to match the `sub`, request url path, and request method.
-* permissions defined in token.
-
-See below for an example:
+## Access Token
 
 ```json
 {
@@ -67,3 +67,112 @@ See below for an example:
   ]
 }
 ```
+
+## Policy
+
+The PDP enforces policy by checking:
+
+* casbin policies to match the subject, request path, and request method.
+* subject is defined in the access token.
+* permissions are defined in the access token.
+
+## Example
+
+Rule
+
+  ```conf
+  [request_definition]
+  r = subject, resource, action
+
+  [policy_definition]
+  p = subject, resource, action
+
+  [policy_effect]
+  e = some(where (p.eft == allow))
+
+  [matchers]
+  m = (p.subject == "*" || r.subject == p.subject) && r.resource == p.resource && r.action == p.action
+  ```
+
+| policy | subject                  | resource                        | method |
+| ------ | ------------------------ | ------------------------------- | ------ |
+| p      | *                        | /api/atlas                      | GET    |
+| p      | *                        | /api/notifications/global       | GET    |
+| p      | *                        | /api/public                     | GET    |
+| p      | 627b10e1019dd10068e03db4 | /api/notifications/QwfsJDutXwPD | GET    |
+
+
+Example 1:
+
+  ```http
+  GET /api/public
+
+  200 OK
+  ```
+
+Example 2:
+
+  ```http
+  GET /api/public
+  Authorization: Bearer access_token("627b10e1019dd10068e03db4")
+
+  200 OK
+  ```
+
+Example 3:
+
+  ```http
+  GET /api/notifications/QwfsJDutXwPD
+  Authorization: Bearer access_token("627b10e1019dd10068e03db4")
+
+  200 OK
+  ```
+
+Example 4:
+
+  ```http
+  GET /api/notifications/QwfsJDutXwPD
+  Authorization: Bearer access_token("f00d1e")
+
+  401 Unauthorized
+  ```
+
+## Roles
+
+What about Roles?
+
+Rule
+
+  ```
+  [request_definition]
+  r = subject, resource, action
+
+  [role_definition]
+  g = subject, role, domain
+
+  [policy_definition]
+  p = role, domain, resource, action
+
+  [policy_effect]
+  e = some(where (p.eft == allow))
+
+  [matchers]
+  m = g(r.subject, p.role, r.domain) && r.resource == p.resource && r.action == p.action
+  ```
+
+Policies
+
+| policy | role  | domain  | resource | action |
+| ------ | ----- | ------- | -------- | ------ |
+| p      | admin | domain1 | data1    | read   |
+| p      | admin | domain1 | data1    | write  |
+| p      | admin | domain2 | data2    | read   |
+| p      | admin | domain2 | data2    | write  |
+
+
+Groups
+
+| group | subject | role  | domain  |
+| ----- | ------- | ----  | ------  |
+| g     | alice   | admin | *       |
+| g     | bob     | admin | domain2 |