spiffe-envoy-agent

IMPORTANT NOTE: If you are using SPIRE to issue SPIFFE identities, the SPIRE Agent supports the Envoy SDS API natively, and this component is not necessary. Read more about how this works.

spiffe-envoy-agent

This component allows a user to integrate Envoy proxy with the SPIFFE identity framework.

How does this integration work?

This agent implements two services:

• Secret discovery service (SDS): Used to provide Envoy with x509-SVIDs fetched from SPIFFE Workload API.

• External authorization filter: Used for JWT-SVIDs injection and validation in HTTP requests.

Communication between components

When spiffe-envoy-agent starts, it registers with the SPIFFE Workload API and starts listening for requests from Envoy. Communication with the SPIFFE Workload API is done using gRPC over a unix domain socket (or UDS). Envoy uses the xDS API over UDS to talk to the spiffe-envoy-agent.

Transport layer: X509-SVID

For x509-SVID management, the spiffe-envoy-agent exposes a secret discovery service, or SDS. A stream is created between the spiffe-envoy-agent and the SPIFFE Workload API. The SPIFFE Workload API updates the stream with new SVIDs according to the configured settings.

At the same time, Envoy initiates the SDS communication with a discovery request message. The spiffe-envoy-agent establishes a stream and sends Envoy the latest certificate and key in a discovery response message. Certificate updates are then communicated in successive responses every time the SPIFFE Workload API rotates the SVID. Once Envoy applies the configurations received, it is ready to handle TLS connections.

Application layer: JWT-SVID

On top of mTLS, HTTP requests can be done carrying a JWT-SVID for authentication. In this case, the spiffe-envoy-agent works as an external authorization filter. There are two different cases to handle here.

Forward spiffe-envoy-agent (Injection)

Every HTTP request sent to the Envoy forward proxy is handled by the Envoy External Authorization module. This module forwards the request header to the configured spiffe-envoy-agent, which obtains a JWT-SVID for that request from the SPIFFE Workload API. The JWT is then injected as a new header and sent back to Envoy.

Reverse spiffe-envoy-agent (Validation)

When the HTTP request arrives at the reverse proxy, it is processed by the Envoy External Authorization module and sent to the spiffe-envoy-agent for validation/authorization. This time, spiffe-envoy-agent verifies the JWT-SVID included in the HTTP header. To do so, it utilizes a validation endpoint exposed over the SPIFFE Workload API. Once validated, spiffe-envoy-agent verifies that the SPIFFE ID in the subject claim matches one of the configured SPIFFE IDs, at which point the request is authorized and sent back to Envoy. If validation fails, or the SPIFFE ID does not match, then the request will be denied. Finally, Envoy forwards the validated and authorized request to the backend service.

Building spiffe-envoy-agent

Prerequisites

• Go 1.11

Clone this repository

git clone https://github.com/spiffe/spiffe-envoy-agent.git

Build from source

Set Go Modules on and build from the root repository folder:

cd spiffe-envoy-agent
GO111MODULE=on go build

If you are on darwin, remember to set the target operating system to linux:

GO111MODULE=on GOOS=linux go build

Running spiffe-envoy-agent

Sample configuration files are provided for spiffe-envoy-agent and for forward/reverse Envoy proxies. There is also a full demo scenario available here.