docs: write notes on Envoy

1 files changed, 84 insertions, 0 deletions

diff --git a/share/man/ENVOY.md b/share/man/ENVOY.md
new file mode 100644
index 0000000..3f610df
--- /dev/null
+++ b/share/man/ENVOY.md
@@ -0,0 +1,84 @@
+# Envoy
+
+Envoy Proxy is described as an edge and service proxy. What this means is that
+Envoy can take care of managing inbound and outbound networks requests to and
+from your application. This allows your application to not to have to worry
+about managing key material like OAuth Client secrets, JSON Web Tokens (JWTs),
+and other sensitive information.
+
+Envoy provides a plugin system that allows application developers to use built
+in plugins to handle things like:
+
+* Redirecting to an Identity Provider
+* Doing an OAuth handshake with an OAuth Authorization Server
+  * Performing an Authorization Code Grant Exchange
+  * Exchanging a refresh token for a new access token
+* Validating incoming JSON Web Tokens
+* Connecting to a policy decision point to authorize request before forwarding
+  them to your application.
+
+Envoy can be run in multiple ways and seems to work best when working as a
+sidecar process to your application. The idea behind this is that you would
+expose envoy to the externally and use it to reverse proxy requests to your
+application that is only accessible via envoy. This is typically configured
+using a loopback address for tcp connections. Envoy can speak gRPC and HTTP
+quite fluently and the Envoy documentation is fairly extensive.
+
+You can configure Envoy to receive its configuration from a static YAML file or
+dynamically by giving it the location of a control plane for it to connect to
+and receive its configuration from. Envoy Gateway and Istio are popular control
+planes that allow you to manage a fleet of envoy proxies through a central
+management point.
+
+In this document I'm going to go over how to configure Envoy in a standalone
+mode using static configuration. This configuration is written in YAML and is
+provided to the Envoy program as a command line option during startup.
+
+In order to adequately understand what Envoy is providing I will start with
+going over the following primitives:
+
+1. Authentication
+  * Public Key Cryptography
+  * Public Key Infrastructure
+  * Digital Signing
+1. Authorization
+  * Access Control Models
+    * DAC
+    * RBAC
+    * ABAC
+
+After this brief overview I will dive into how to configure Envoy to provide
+the bare necessities for booting up a new service with authentication
+and authorization delegated to Envoy.
+
+1. Authentication
+  * OpenID Connect Provider using `envoy.filters.http.oauth2`
+  * JSON Web Token Validation using `envoy.filters.http.jwt_authn`
+1. Authorization
+  * External policy decision point (PDP) using `envoy.filters.http.ext_authz`
+
+## Pre-requisite Concepts
+
+Authentication is the act of prooving you are who you claim to be.
+Authorization is the act of prooving that you are allowed to do what
+you're trying to do. The distinction between the two is important because the
+context determines which elements are necessary.
+
+An example of this is the difference between commuting via municipal transit
+versus commuting via an airplane. The security context between the two modes of
+transportation are different therefore the level or rigor applied to
+authenticating versus authorizing access to the resource differ. To board a bus
+you must present a bus token/ticket to the bus driver before you are able to
+board the bus. The bus driver does not require you to verify who you are.
+Instead, they are only interested in verifying that you have a valid bus ticket
+that has not expired, is for the bus that they operate and is issued from a
+legitimate authority (the transit authority). TO ride an airplane you must
+provide both your passport and your boarding pass in order to board the plane.
+The passport is used to verify that you are who you say you are and the boarding
+pass is used to ensure that you have a valid seat on the plane. The passport is
+used to authenticate the passenger and the bus ticket/boarding pass is used to
+authorize the passenger. The bus and plane are protected resources like an API
+and the operator of the API understand the security context the best. They
+understand whether a rigorous authentication and authorization check is
+warranted or not. The passenger is responsible for obtaining a passport,
+boarding pass, bus ticket from trusted and reputable authorities.