From eaf8d7ff8fecc8e0d5b9d7c549ff0c969e90f2cd Mon Sep 17 00:00:00 2001 From: mo khan Date: Mon, 26 May 2025 12:02:43 -0600 Subject: docs: write notes on Envoy --- share/man/ENVOY.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++ share/man/README.md | 4 +++ 2 files changed, 88 insertions(+) create mode 100644 share/man/ENVOY.md create mode 100644 share/man/README.md (limited to 'share/man') 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. diff --git a/share/man/README.md b/share/man/README.md new file mode 100644 index 0000000..e74a961 --- /dev/null +++ b/share/man/README.md @@ -0,0 +1,4 @@ +# Documentation + +* [Developer Docs](./DEVELOPMENT.md) + * [Envoy](./ENVOY.md) -- cgit v1.2.3