docs: describe the oauth2 filter in detail

1 files changed, 25 insertions, 0 deletions

diff --git a/share/man/ENVOY.md b/share/man/ENVOY.md
index 29fbe64..5391aa3 100644
--- a/share/man/ENVOY.md
+++ b/share/man/ENVOY.md
@@ -536,6 +536,26 @@ does not support the OIDC Discovery endpoint but an Envoy Gateway
 [plugin](https://gateway.envoyproxy.io/docs/tasks/security/oidc/) does.
 Envoy Gateway is a control plane that is outside the scope of this document.
 
+In the configuration below, the `envoy.filters.http.oauth2` HTTP filter is used
+to manage an OAuth handshake with an OAuth Authorization server. By adding the
+`openid` scope to the handshake we have implicitly upgraded the transaction from
+a generic OAuth2 handshake to an OpenID Connect transaction. This upgrade allows
+the OAuth handshake to receive an additional `id_token` from the Security Token
+Service (STS) described by the `token_endpoint` configuration.
+
+The `authorization_endpoint` is the location of the Identity Provider (OIDC
+Provider IdP) that this filter will redirect the user-agent to in order to begin a
+transaction. The `token_endpoint` is the location that the OAuth client will
+forward an OAuth Grant to in order to retrieve an `access_token`, `id_token`,
+and `refresh_token`. This HTTP filter takes care of generating a nonce to handle
+abusive clients that may wish to try to hit the callback endpoint. It also takes
+care of calling the `token_endpoint` with a Refresh Token Grant when it needs to
+generate a new `access_token`, `id_token`. This entire exchange is complex and
+error prone and by using this filter we reduce the amount of errors that can be
+introduced by incorrectly negotiating a new session with the IdP. This ensures
+that we use a standards based approach for interoperating with our IdP in the
+same manner as any external integration.
+
 ```yaml
                 # ...
                 http_filters:
@@ -566,6 +586,11 @@ Envoy Gateway is a control plane that is outside the scope of this document.
                   # ...
 ```
 
+The `signout_path` is a virtual path that is managed by Envoy to take care of
+clearing session cookies and terminating a session. The `token_endpoint`
+configuration will be something that we can utilize to extract the STS code from
+the `gitlab-org/gitlab` codebase into a separate isolated service.
+
 ### Authorization Flow
 
 TODO:: model these examples from https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/merge_requests/12#note_2516950269