This component allows a user to integrate SPIFFE identity framework to Envoy proxy.
This agent implements two services:
-
Secret discovery service (SDS): Used to provide Envoy with x509-SVIDs fetched from SPIRE.
-
External authorization filter: Used for JWT-SVIDs injection and validation in HTTP requests.
When spiffe-envoy-agent starts, it registers with both components: SPIRE agent and Envoy proxy. Agent communication is done using a Workload API client through UDS. On the other hand, Envoy communication is ruled by Envoy xDS protocol which also uses UDS.
For x509-SVID management, the spiffe-envoy-agent will work as a secret discovery service. A stream is created between it and SPIRE agent. SPIRE will update the stream with new SVIDs according to the configured settings.
At the same time, Envoy initiates the communication with a discovery request message. The spiffe-envoy-agent establishes a stream and sends back the previously fetched certificate and key in a discovery response message. After that, certificates will be updated in successive responses every time SPIRE rotates a new SVID. Once Envoy applies the configurations received, it is ready to handle TLS connections.
On top of mTLS, HTTP requests can be done carrying a JWT-SVID for authentication. In this case, the spiffe-envoy-agent will work as an external authorization filter. There are two different cases to handle here.
Given an initial HTTP request sent to Envoy forward proxy, it will be handled by the Envoy External Authorization module. The module will forward the request header to spiffe-envoy-agent. It will query SPIRE agent to get a JWT-SVID for that request. When it gets the response, spiffe-envoy-agent will inject the JWT as a new header and will send it back to Envoy.
When the HTTP request arrives at the backward proxy, it is processed by the Envoy External Authorization module and sent to the spiffe-envoy-agent for authorization. This time, it will verify the JWT-SVID. To do so, spiffe-envoy-agent will do an RPC to SPIRE agent to validate the token. If the JWT-SVID is valid and the subject claim is one of the configured to be accepted, then the request will be authorized and sent back to Envoy. Otherwise, it will be denied. Finally, Envoy will forward the validated and authorized request to the backend service.
git clone https://github.com/spiffe/spiffe-envoy-agent.git
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
Sample configuration files are provided for spiffe-envoy-agent and for forward/backward Envoy proxies. There is also a full demo scenario available here.