add some notes on authz

1 files changed, 191 insertions, 0 deletions

diff --git a/learn/authz/README.md b/learn/authz/README.md
new file mode 100644
index 0000000..7e6d8e5
--- /dev/null
+++ b/learn/authz/README.md
@@ -0,0 +1,191 @@
+# Authorization via OIDC and OAuth 2.0
+
+[OAuth 2.0][3] is a framework for Authz and can be extended [OpenID Connect][4]
+for Authn.
+
+```plaintext
+OAuth 2.0 Protocol Flow
+
+    +--------+                               +---------------+
+    |        |--(A)- Authorization Request ->|   Resource    |
+    |        |                               |     Owner     |
+    |        |<-(B)-- Authorization Grant ---|               |
+    |        |                               +---------------+
+    |        |
+    |        |                               +---------------+
+    |        |--(C)-- Authorization Grant -->| Authorization |
+    | Client |                               |     Server    |
+    |        |<-(D)----- Access Token -------|               |
+    |        |                               +---------------+
+    |        |
+    |        |                               +---------------+
+    |        |--(E)----- Access Token ------>|    Resource   |
+    |        |                               |     Server    |
+    |        |<-(F)--- Protected Resource ---|               |
+    +--------+                               +---------------+
+```
+
+```plaintext
+OIDC Protocol Flow
+
++--------+                                   +--------+
+|        |                                   |        |
+|        |---------(1) AuthN Request-------->|        |
+|        |                                   |        |
+|        |  +--------+                       |        |
+|        |  |        |                       |        |
+|        |  |  End-  |<--(2) AuthN & AuthZ-->|        |
+|        |  |  User  |                       |        |
+|   RP   |  |        |                       |   OP   |
+|        |  +--------+                       |        |
+|        |                                   |        |
+|        |<--------(3) AuthN Response--------|        |
+|        |                                   |        |
+|        |---------(4) UserInfo Request----->|        |
+|        |                                   |        |
+|        |<--------(5) UserInfo Response-----|        |
+|        |                                   |        |
++--------+                                   +--------+
+```
+
+The IDToken is a [JWT][5] with the standard claims.
+The `scope` claim includes a space delimited list of
+permissions that the current subject is entitled to.
+
+For example:
+
+```json
+{
+  "sub": "<uuid-of-principal>",
+  "aud": "https://api.cmdzero.io",
+  "iss": "https://auth0.com",
+  "exp": "unix-timestamp-expires-at",
+  "iat": "unix-timestamp-issued-at"
+  "scope": "write:groups read:incident",
+}
+```
+
+If an `IDToken` is provided as part of an OpenID Connect transaction then this
+token can be used to fetch any profile information update from the OpenID user
+profile endpoint to stay in sync with any profile changes that occur.
+
+All Authz permissions (claims) for a given Principal (Resource Owner) can be
+included in a stateless Access Token that can be used to access a REST
+API (Resource Server). The API can check the validity of a token and its
+permissions by checking the disposition of the provided token against the
+[token introspection endpoint][1] and/or it can verify the signature of the
+token if the Access Token is a [JWT][5]
+
+Request:
+
+```plaintext
+POST /introspect HTTP/1.1
+Host: auth0.com
+Accept: application/json
+Content-Type: application/json
+
+{
+  "token": "mF_9.B5f-4.1JqM",
+  "token_type_hint": "access_token"
+}
+```
+
+Response:
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "active": true,
+  "sub": "<uuid-of-principal>",
+  "aud": "https://api.cmdzero.io",
+  "iss": "https://auth0.com",
+  "exp": "unix-timestamp-expires-at",
+  "iat": "unix-timestamp-issued-at"
+  "scope": "write:groups",
+}
+```
+
+Example Flow:
+
+```plaintext
+                ||-------------------------------------------------------------
+                ||
+                || VPC
+                ||
+--------------- || ---------------------  -------  ---------  --------- ------
+| Client (RP) | || | API Gateway (PEP) |  | PDP |  | API A |  | API B | | OP |
+--------------- || ---------------------  -------  ---------  --------- ------
+       |        ||             |             |         |          |       |
+       | GET /login            |             |         |          |       |
+       |----------------------------------------------------------------->|
+       |        ||             |             |         |          |       |
+       |        ...                                                       |
+       |        ...                                                       |
+       |<-----------------------------------------------------------------|
+       |        ||      return access_token: "x.y.z"   |          |       |
+       |        ||             |             |         |          |       |
+       | GET /my/organizations |             |         |          |       |
+       | Authorization: "x.y.z"|             |         |          |       |
+       |---------------------->|             |         |          |       |
+       |        ||             |             |         |          |       |
+       |        ||             |------------>|         |          |       |
+       |        ||             |             |         |          |       |
+       |        ||             |<------------|         |          |       |
+       |        ||             | Allow       |         |          |       |
+       |        ||             |             |         |          |       |
+       |        ||             |---------------------->|          |       |
+       |        ||             |             |         |          |       |
+       |        ||             |<----------------------|          |       |
+       |        ||             |             |         |          |       |
+       |<----------------------|             |         |          |       |
+       |        ||             |             |         |          |       |
+       |        ||             |             |         |          |       |
+       | GET /my/notifications |             |         |          |       |
+       | Authorization: "x.y.z"|             |         |          |       |
+       |---------------------->|             |         |          |       |
+       |        ||             |             |         |          |       |
+       |        ||             |------------>|         |          |       |
+       |        ||             |             |         |          |       |
+       |        ||             |<------------|         |          |       |
+       |        ||             | Allow       |         |          |       |
+       |        ||             |             |         |          |       |
+       |        ||             |--------------------------------->|       |
+       |        ||             |             |         |          |       |
+       |        ||             |<---------------------------------|       |
+       |        ||             |             |         |          |       |
+       |<----------------------|             |         |          |       |
+       |        ||             |             |         |          |       |
+       | DELETE /admin/users   |             |         |          |       |
+       | Authorization: "x.y.z"|             |         |          |       |
+       |---------------------->|             |         |          |       |
+       |        ||             |             |         |          |       |
+       |        ||             |------------>|         |          |       |
+       |        ||             |             |         |          |       |
+       |        ||             |<------------|         |          |       |
+       |        ||             | Deny        |         |          |       |
+       |<----------------------|             |         |          |       |
+       |        ||             |             |         |          |       |
+                ||
+                ||-------------------------------------------------------------
+```
+
+[Auth0][2] can be used as the OP in the diagram above.
+
+## Glossary
+
+* PEP: Policy Enforcement Point is a gateway that protects all requests routed
+  to this point to make a decision. It takes the incoming HTTP request and
+  creates an authz specific request. Usually this is the API Gateway.
+* PDP: Policy Decision Point consumes an authz request send from the PEP to make
+  a decision on whether to allow or deny the request.
+* RP: Relying Party is the OAuth 2.0 Client application.
+* OP: OpenID Provider is the OAuth 2.0 Authorization Server that is capable of
+  Authn and providing claims to a RP about the authn event and User.
+
+[1]: https://datatracker.ietf.org/doc/html/rfc7662#section-2
+[2]: https://auth0.com/docs/authenticate/login/oidc-conformant-authentication/oidc-adoption-access-tokens
+[3]: https://datatracker.ietf.org/doc/html/rfc6749
+[4]: https://openid.net/specs/openid-connect-core-1_0.html#Overview
+[5]: https://datatracker.ietf.org/doc/html/rfc7519