diff options
| -rw-r--r-- | app/middleware/id_token.go | 2 | ||||
| -rwxr-xr-x | bin/entrypoint.sh | 8 | ||||
| -rw-r--r-- | share/man/ENVOY.md | 680 | ||||
| -rw-r--r-- | share/man/README.md | 4 |
4 files changed, 691 insertions, 3 deletions
diff --git a/app/middleware/id_token.go b/app/middleware/id_token.go index 8084af0..0c1503e 100644 --- a/app/middleware/id_token.go +++ b/app/middleware/id_token.go @@ -8,7 +8,6 @@ import ( "github.com/xlgmokha/x/pkg/x" xcfg "gitlab.com/gitlab-org/software-supply-chain-security/authorization/sparkled/app/cfg" "gitlab.com/gitlab-org/software-supply-chain-security/authorization/sparkled/pkg/pls" - "gitlab.com/gitlab-org/software-supply-chain-security/authorization/sparkled/pkg/web" ) func IDToken(provider *oidc.Provider, config *oidc.Config, parsers ...TokenParser) func(http.Handler) http.Handler { @@ -22,7 +21,6 @@ func IDToken(provider *oidc.Provider, config *oidc.Config, parsers ...TokenParse if err != nil { pls.LogError(r.Context(), err) - web.ExpireCookie(w, xcfg.IDTokenCookie) } else { log.WithFields(r.Context(), log.Fields{"id_token": idToken}) next.ServeHTTP( diff --git a/bin/entrypoint.sh b/bin/entrypoint.sh index a770286..ab38bfa 100755 --- a/bin/entrypoint.sh +++ b/bin/entrypoint.sh @@ -8,4 +8,10 @@ cd "$(dirname "$0")/.." ./bin/envoy.sh & # launch envoy in background ./bin/authzd & # launch authzd in background -./bin/sparkled # launch sparkled in foreground + +/usr/bin/env -i - \ + APP_ENV="$APP_ENV" \ + BIND_ADDR="$BIND_ADDR" \ + OAUTH_CLIENT_ID="$OAUTH_CLIENT_ID" \ + OIDC_ISSUER="$OIDC_ISSUER" \ + ./bin/sparkled # launch sparkled in foreground diff --git a/share/man/ENVOY.md b/share/man/ENVOY.md new file mode 100644 index 0000000..907d53e --- /dev/null +++ b/share/man/ENVOY.md @@ -0,0 +1,680 @@ +# Envoy Proxy + +## Overview + +Envoy Proxy is described as an edge and service proxy. This means 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 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. + +```mermaid +sequenceDiagram + participant P as Passenger + participant BD as Bus Driver + participant B as Bus + + P->>BD: request access + BD->>P: request ticket + P->>BD: present ticket + Note over BD: authorize (bus #, expiration, fake/legit?) + + alt Valid ticket + BD->>P: grant access + P->>B: board bus + else Invalid ticket + BD->>P: deny access + end +``` + +The Bus # indicates the canonical identifier for the resource and +this is similar to accessing a resource exposed via a REST/GraphQL +API. The expiration check ensures that the same token cannot be re-used +indefinitely and that the access granted by the ticket is limited in +scope to prevent abuse of the resource and this is similar to ensuring +that a JWT cannot be used indefinitely. The check to make sure that the +ticket is legitimate and issued from a trusted authority is similar to +a digital signature check. In this example, the bus driver does not need to +authenticate the passenger by verifying that they are who they say they are. The +bus driver does not care. The bus driver only cares about whether or not they +carry a token that awards them access to the resource. In this scenario the +passenger could give the token to someone else (for example a child) so that +they can access the resource. The security context of this resource does not +warrant the need for authentication and only requires authorization. + +```mermaid +sequenceDiagram + participant P as Passenger + participant SA as Security Agent + participant BA as Boarding Agent + participant Plane as Plane + + P->>SA: request access to gate + SA->>P: request boarding pass + P->>SA: present boarding pass + SA->>SA: validate boarding pass + SA->>P: allow access to gate + + P->>BA: request access to board plane + BA->>P: request passport + P->>BA: present passport + BA->>P: request boarding pass + P->>BA: present boarding pass + BA->>P: allow access to board plane + + P->>Plane: board plane +``` + +To board a plane you must pass through more security checks before you can +access the airplane. That is because flying in an airplane is a high security +context that requires additional checks to ensure the safety of everyone and the +risk of allowing access to a bad actor has more severe consequences. To board +the airplane you must pass through the security checkpoint by presenting a valid +boarding pass for a flight. This check ensures that we do not allow people into +the gate that do not have a valid pass. A valid pass is one that hasn't already +been used, is for a flight that is set to take off in the future and is for a +known and registered airline. Depending on whether the flight is a domestic or +international flight the gate may require other forms of proof of access. Once +the passenger has made it to the gate they are required to provide a passport +and boarding pass to an airline agent before they are allowed to board the +aircraft. This ensures that everyone who is aboard the airplane is known ahead +of time and that known bad actors are not allowed to board the aircraft. The +airline agent performs an authentication AND authorization check. The airplane +is a metaphor for a high security context that the operators of the airplane +understand. The credit card company and each intermediate authority that was +used to ensure entry do not determine the access controls for gaining entry into +the plane. + +### Authentication + +Authentication is the act of verifying that an entity is who they say they are. + +How do we do this on the internet? To accomplish this we depend on public key +cryptography which is a form of asymmetic crypto. In this style of crypto each +party has a public and private key. Entities distribute their public keys while +keeping their private keys private. The interesting property of the +public/private key relationship is that messages that are encrypted by either +the public or private key can only be decrypted by the other corresponding key. + +#### Confidentiality + +So if I give you my public key then you can encrypt a message with my public key +and send that message to me. Only I can decrypt that message using my private +key. This ensures confidentiality so that the ciphertext produced can be snooped +by anyone but only the recipient can convert the ciphertext back into plaintext. + +#### Authenticity + +To ensure that a message originated from the entity that claims to have sent the +message an additional signature can be appended to the message. The signature +can contain any arbitrary text but is usually a hash (e.g. SHA256) of the +original plaintext message and encrypted using the private key of the sender. +I'll explain below why a hash is used below. If the recipient has the public key of the sender +then they can decrypt the signature using the public key of the sender. If +signature can be decrypted without an error then we can trust that the message +did in fact originate from the sender. This authenticates the message. + +#### Integrity + +When a recipient receives a message from a sender the recipient also needs to +verify that the message wasn't altered. If the signature of the message includes +an encrypted hash then the recipient can compute a hash of the plaintext message +and compare it with the hash in the encrypted signature. This ensures that the +message hasn't been tampered with. + +In order for us to be able to trust JSON Web Tokens we need public/private key +pairs that we can use to validate the authenticity and integrity of the token. +It is also possible to encrypt the JWT body but this isn't necessary and this is +why storing sensitive information like personally identifiable information in a +JWT claim is not recommended. + +The problem of sharing and distributing public keys is solved using Public Key +Infrastructure (PKI). PKI provides a mechanism for distributing X.509 +certificates that include metadata and the public keys for different entities. +X.509 certificates can include a digital signature from other authorities +provides a chain of trust. Each X.509 certificate stores in the CA trust store +on your computer is a self signed certificate that is considered trusted. +Intermediate certificates can be traced back to a root certificate and provides +a web of trust. i.e. I trust this JWT because it was signed by a public key that +I found in this intermediate certificate that was signed by a public key found +in this root certificate that is in my operating systems root certificate +authority trust store. Typically, organizations will operate an internal +certificate authority that can sign intermediate certificates that can be +installed in the trust store for internal services. This makes it easier to +issue internal certificates without need direct access to private keys that can +be abused by bad actors. I apologize for the weak summary of this but a cursory +knowledge of how this works is important for understanding authentication. + +When a service federates user authentication to an Identity Provider (.e.g. SAML +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. + +TODO:: Describe the sections of a JWT and the schema of the `id_token`. + +### 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! + +## Envoy Architecture + +Given all the concerns listed above this is where Envoy shines. It can be used +to take care of Authentication via an OpenID Connect transaction by slightly +abusing the built-in `envoy.filters.http.oauth2` HTTP filter. It can also be +used to validate any incoming JWTs via the `envoy.filters.http.jwt_authn` HTTP +filter. Finally, we can use the `envoy.filters.http.ext_authz` HTTP filter to +delegate authorization decisions to an external policy decision point (PDP). + +I wrote Sparkle as a proof-of-concept to model these ideas using Envoy. Before +we dive into the configuration I want to quickly go over the high level +architecture of how these pieces work together. + +The proposed architecture ensures that authorization decisions are made consistently at the edge before requests reach the application. + +Envoy can be configured to host multiple listeners and each listener can be +configured to have its own pipeline of middleware to execute in the order that +the middleware is declared. Sparkle uses a single listener on all interfaces +listening for TCP traffic on port 10000 to accept all incoming HTTP traffic. +The last HTTP filter to execute is the `envoy.filter.http.router` filter that +will reverse proxy the incoming request to Sparkle. + +Below is a snippet of configuration required to setup the reverse proxy. + +```yaml +static_resources: + - name: listener_0 + address: + socket_address: + protocol: TCP + address: 0.0.0.0 + port_value: 10000 + filter_chains: + - filters: + - name: envoy.filters.network.http_connection_manager + typed_config: + "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager + http_filters: + - name: envoy.filters.http.router + typed_config: + "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router + route_config: + virtual_hosts: + - name: local + domains: ["*"] + routes: + - match: + prefix: "/" + route: + cluster: sparkle + clusters: + - name: sparkle + load_assignment: + cluster_name: sparkle + endpoints: + - lb_endpoints: + - endpoint: + address: + socket_address: + address: 127.0.0.1 + port_value: 8080 +``` + +### Authentication Flow + +```mermaid +sequenceDiagram + participant User + box grey Docker Image + participant Envoy + participant authzd + participant sparkled + end + participant OIDC Provider + + User->>Envoy: GET /dashboard (no auth) + Envoy->>Envoy: OAuth2 filter detects no auth + Envoy->>User: Redirect to OIDC Provider + User->>OIDC Provider: Login + OIDC Provider->>User: Redirect to /callback with code + User->>Envoy: GET /callback?code=... + Envoy->>OIDC Provider: Exchange code for tokens + OIDC Provider->>Envoy: Return tokens (ID, access, refresh) + Envoy->>User: Set cookies & redirect to /dashboard +``` + +The `envoy.filters.http.oauth2` HTTP filter can be configured to detect an +unauthenticated request and intercept all inbound requests by redirecting the +user-agent to the hard-coded OAuth Authorization Server endpoints. This filter +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. + +```yaml + # ... + http_filters: + - name: envoy.filters.http.oauth2 + typed_config: + "@type": type.googleapis.com/envoy.extensions.filters.http.oauth2.v3.OAuth2 + config: + auth_scopes: + - email + - openid + - profile + authorization_endpoint: "https://gitlab.com/oauth/authorize" + credentials: + client_id: "OAUTH_CLIENT_ID" + cookie_names: + id_token: id_token + redirect_path_matcher: + path: + exact: /callback + redirect_uri: "%REQ(x-forwarded-proto)%://%REQ(:authority)%/callback" + signout_path: + path: + exact: /signout + token_endpoint: + uri: "https://gitlab.com/oauth/token" + use_refresh_token: true + - name: envoy.filters.http.router + # ... +``` + +### Authorization Flow + +TODO:: model these examples from https://gitlab.com/gitlab-org/architecture/auth-architecture/design-doc/-/merge_requests/12#note_2516950269 + +Example 1: Session cookie + +1. Request with a Cookie arrives to Envoy. +1. Envoy sends the request context to a separate service. +1. Separate auth service responds with HTTP OK and a token from STS representing the authenticated principal. +1. Envoy forwards the request to GitLab with the identity token injected into a header. + +Example 2: Authorization header + +1. Request with an Authorization: Bearer token arrives to Envoy. +1. Envoy sends the token to a separate service. +1. Separate service responds with an identity token from STS. +1. Envoy forwards the request to Rails. + +Example 3: Unauthenticated + +1. Unauthenticated request arrives. +1. Envoy forwards the request to Rails without an identity token. + +Example 4: Workload Identity Federation + +1. OAuth authorization request arrives for 3rd-party integration. +1. Envoy forwards the request to the authorization server. + +Example 5: ? + +1. OAuth authorization request arrives for internal service integration. +1. Envoy forwards the request to the authorization service. +1. Envoy captures authorization grant and exchanges it for the token (current solution). + +```mermaid +sequenceDiagram + participant User + box grey Docker Image + participant Envoy + participant authzd + participant sparkled + end + participant OIDC Provider + + User->>Envoy: GET /dashboard (with cookies) + Envoy->>Envoy: Extract ID token from cookie + Envoy->>Envoy: JWT filter validates & extracts claims + Note right of Envoy: Sets headers:<br/>x-jwt-payload<br/>x-jwt-claim-sub + + Envoy->>authzd: Check authorization (gRPC) + Note right of authzd: Request includes:<br/>- Method & Path<br/>- Headers (inc. cookies)<br/>- JWT claims + authzd->>authzd: Evaluate authorization rules + authzd->>Envoy: Return OK/Denied decision + + alt Authorization OK + Envoy->>sparkled: Forward request with JWT headers + sparkled->>sparkled: Extract user from x-jwt-claim-sub + sparkled->>User: Return dashboard content + else Authorization Denied + Envoy->>User: Return 401 Unauthorized + end +``` + +The ID token can be validated using the `envoy.filters.http.jwt_authn` HTTP +filter. The following configuration will look for an `id_token` cookie and then +parse the value, validate it against the list of keys specified at the +`remote_jwks` uri and then it will inject a header called `x-jwt-payload` with +the valid JWT as well as the `x-jwt-claim-sub` with the body section of the JWT. +This filter ensures ensures the integrity and authenticity of the detected JWT +and will immediately reject tokens that are invalid. + +```yaml + # ... + - name: envoy.filters.http.oauth2 + # ... + - name: envoy.filters.http.jwt_authn + typed_config: + "@type": type.googleapis.com/envoy.extensions.filters.http.jwt_authn.v3.JwtAuthentication + providers: + gitlab_provider: + audiences: + - OAUTH_CLIENT_ID + claim_to_headers: + - header_name: x-jwt-claim-sub + claim_name: sub + forward: true + forward_payload_header: x-jwt-payload + from_cookies: + - id_token + issuer: https://gitlab.com + remote_jwks: + http_uri: + uri: https://gitlab.com/oauth/discovery/keys + rules: + - match: + path: / + requires: + provider_name: gitlab_provider + - name: envoy.filters.http.router + # ... +``` + +The `envoy.filters.http.ext_authz` filter can be used to forward the incoming HTTP request to an external +policy decision point that can be used to make the authorization decision. For +Sparkle the PDP is hosted as a sidecar process called `authzd` that makes the +authorization decision specifically on the contents of the HTTP request. + +```yaml + # ... + - name: envoy.filters.http.oauth2 + # ... + - name: envoy.filters.http.jwt_authn + # ... + - name: envoy.filters.http.ext_authz + typed_config: + "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz + grpc_service: + envoy_grpc: + cluster_name: authzd + failure_mode_allow: false + - name: envoy.filters.http.router + # ... +``` + +The external authorization service must implement the [`CheckRequest` protobuf](https://github.com/envoyproxy/envoy/blob/04378898516847d1107c5b15c22ac602ff06372c/api/envoy/service/auth/v3/external_auth.proto#L35) service definition. +An example of this can be found in the Sparkle repo. Below is an example +snippet: + +```golang +package authz + +import ( + "context" + + core "github.com/envoyproxy/go-control-plane/envoy/config/core/v3" + auth "github.com/envoyproxy/go-control-plane/envoy/service/auth/v3" + types "github.com/envoyproxy/go-control-plane/envoy/type/v3" + status "google.golang.org/genproto/googleapis/rpc/status" + "google.golang.org/grpc/codes" +) + +type CheckService struct { + auth.UnimplementedAuthorizationServer +} + +func (svc *CheckService) Check(ctx context.Context, request *auth.CheckRequest) (*auth.CheckResponse, error) { + if svc.isAllowed(ctx, request) { + return svc.OK(ctx), nil + } + return svc.Denied(ctx), nil +} + +func (svc *CheckService) OK(ctx context.Context) *auth.CheckResponse { + return &auth.CheckResponse{ + Status: &status.Status{ + Code: int32(codes.OK), + }, + HttpResponse: &auth.CheckResponse_OkResponse{ + OkResponse: &auth.OkHttpResponse{ + Headers: []*core.HeaderValueOption{}, + HeadersToRemove: []string{}, + ResponseHeadersToAdd: []*core.HeaderValueOption{}, + }, + }, + } +} + +func (svc *CheckService) Denied(ctx context.Context) *auth.CheckResponse { + return &auth.CheckResponse{ + Status: &status.Status{ + Code: int32(codes.PermissionDenied), + }, + HttpResponse: &auth.CheckResponse_DeniedResponse{ + DeniedResponse: &auth.DeniedHttpResponse{ + Status: &types.HttpStatus{ + Code: types.StatusCode_Unauthorized, + }, + Headers: []*core.HeaderValueOption{}, + }, + }, + } + + // ... +} +``` + +## Distribution + +To deploy Sparkle I used bundled envoy, sparkled and authzd inside a single +docker image. This docker image uses dumb-init to run these three services +simultaneously so that these three processes can coordinate with one another to +form a logical service. Sparkle is currently distributed via Runway and all +secrets and configuration management is handled through environment variables +that are exported into the docker container when it is booted up by Runway and +OpenBao. + +Below is the Dockerfile that is used to build and distribute the Sparkle docker +image. It uses a temporary stage to build the sparkle and authz services and +then copies the compiled artifacts into the envoy base image. The final image +bundles dumb-init, sparkled, authzd and envoy. + +```Dockerfile +# syntax=docker/dockerfile:1 +FROM golang:1.24.3 AS build +ENV CGO_ENABLED=0 +WORKDIR /app +COPY . ./ +RUN go build -o /bin/sparkled ./cmd/sparkled/main.go +RUN go build -o /bin/authzd ./cmd/authzd/main.go + +FROM envoyproxy/envoy:v1.34-latest +EXPOSE 8080 9901 10000 10003 +RUN apt-get update && apt-get install -y dumb-init && rm -rf /var/lib/apt/lists/* +WORKDIR /opt/sparkle/ +RUN mkdir -p bin etc public +COPY --from=build /bin/authzd bin/authzd +COPY --from=build /bin/sparkled bin/sparkled +COPY --from=build /app/public public +COPY etc/ etc +COPY bin/*.sh bin/ +RUN chmod +x bin/*.sh +ENTRYPOINT ["/usr/bin/dumb-init", "--"] +CMD ["/opt/sparkle/bin/entrypoint.sh"] +``` + +The entrypoint script uses dumb-init as PID 1 to forward signals to child +processes. Sparkle is started up with on a limited set of environment variables. +Environment variables such as `HMAC_SECRET` and `OAUTH_CLIENT_SECRET` are not +available to sparkle. + +```sh +#!/usr/bin/dumb-init /bin/sh +# shellcheck shell=sh +set -e + +[ -n "$DEBUG" ] && set -x + +cd "$(dirname "$0")/.." + +./bin/envoy.sh & # launch envoy in background +./bin/authzd & # launch authzd in background + +/usr/bin/env -i - \ + APP_ENV="$APP_ENV" \ + BIND_ADDR="$BIND_ADDR" \ + OAUTH_CLIENT_ID="$OAUTH_CLIENT_ID" \ + OIDC_ISSUER="$OIDC_ISSUER" \ + ./bin/sparkled # launch sparkled in foreground +``` + +## Summary + +Envoy provides a lot of features out of the box making it possible for +application developers to focus on their core domain. This makes it easier to +offload complex and error prone duties such as interacting with an OIDC Provider +and managing key material like an OAuth Client Secret a non-event. By moving +these responsibilities into Envoy we reduce the opportunity for tokens to get +leaked and we ensure that we adhere to open standards while also creating safe +extension points for extending authorization decisions. Envoy's ability to +modify incoming and outgoing requests before delivery makes it possible to +remove sensitive headers and/or convert them to a canonical representation in a +single consistent way. Envoy can handle mapping Authorization headers, session +cookies, query string parameters into a single consistent interface making it +possible to reduce the need for each application to handle each +authentication/authorization strategy that GitLab as a whole supports. + +## References + +* [Envoy Proxy](https://www.envoyproxy.io/) +* [`envoy.filters.http.oauth2`](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/oauth2_filter.html) +* [`envoy.filters.http.jwt_authn`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/jwt_authn/v3/config.proto) +* [`envoy.filters.http.ext_authz`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto) +* [`envoy.filters.http.router`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/router/v3/router.proto) +* [Sparkle](https://gitlab.com/gitlab-org/software-supply-chain-security/authorization/sparkled) + * https://gitlab.com/gitlab-org/software-supply-chain-security/authorization/sparkled/-/merge_requests/3 + * https://gitlab.com/gitlab-org/software-supply-chain-security/authorization/sparkled/-/merge_requests/4 + * https://gitlab.com/gitlab-org/software-supply-chain-security/authorization/sparkled/-/merge_requests/6 + * https://gitlab.com/gitlab-org/software-supply-chain-security/authorization/sparkled/-/merge_requests/7 + * https://gitlab.com/gitlab-org/software-supply-chain-security/authorization/sparkled/-/merge_requests/8 + * https://gitlab.com/gitlab-org/software-supply-chain-security/authorization/sparkled/-/merge_requests/9 + 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) |