docs: add notes on authorization

1 files changed, 44 insertions, 0 deletions

diff --git a/share/man/ENVOY.md b/share/man/ENVOY.md
index 3635b52..cbbf8ff 100644
--- a/share/man/ENVOY.md
+++ b/share/man/ENVOY.md
@@ -224,3 +224,47 @@ IdP, OIDC Provider) the transaction between the service (i.e. SAML Service
 Provider, OIDC Relaying Party) depends on an exchange of public key information
 ahead of time (AoT). Without this pre-prequisite, none of the downstream
 assumptions about user authentication is valid.
+
+The `id_token` in the OpenID Connect (OIDC) workflow represents the authentication context.
+This _DOES NOT_ represent an authorization context.
+
+### Authorization
+
+Authorization is the act of verifying that a party is allowed to perform a
+specific action against a resource. This is separate from Authentication because
+in many cases the Resource Server providing access to the Resource does not need
+to know who the party is. This creates a decoupling that allows an API to
+determine just how much information it actually needs to know about the party
+making the request. See the Bus vis Airplane example above for an explanation.
+
+OAuth was designed as a protocol for delegating authorization to an intermediate
+entity so that this entity could access resources on behalf of a user without
+needing full access to everything that the user has access too. By adhering to
+the OAuth2 protocol flow we can ensure that requests made on behalf of end users
+do not operate at the highest level of privilege available to them. We can
+ensure that requests that are made on behalf of end users use the lowest level
+of privilege necessary for the service (OAuth client) to perform their desired
+function.
+
+The OAuth2 `access_token` represents the authorization context and this is
+distinct from the `id_token` which represents the authentication context. The
+`id_token` tells us who the currently logged in user is but it _should not_ be
+used to make authorization decisions. Authorization decisions should be made
+using the `access_token` because this represents the delegated authorization
+access granted to the service that the token was minted for. In general, most
+API's that receive a request should make authorization decisions based on the
+privileges granted to the `access_token`.
+
+The authorization server that generates the `access_token` should only grant
+just enough privileges to this token that is required by the service (OAuth
+client) that this token is intended for.
+
+The separation of the authentication context from the authorization context is
+incredibly important. This ensures that services cannot access resources based
+on the full scope of access that a user has but rather the delegated authorized
+access that is granted to an access token. The access token represents the
+low-privilege session for a specific service. A single `id_token` can be used
+across services to allow the service to know who is logged in but each service
+should have its own access token for each user based on the permissions that the
+service declares that it needs and the permissions that the user agrees to give
+it. I need to say this again because understanding this is crucial!