To integrate heimdall with Envoy globally, you need to configure two things:
a cluster
entry referencing the actual heimdall address, and
the aforesaid filter in the http filter chain
The following snippet provides an example on how to create a cluster
instance referencing heimdall. It assumes, you have just one heimdall instance deployed, which is also available via heimdall
DNS name.
clusters:
# other cluster entries
- name: ext-authz (1)
type: strict_dns
typed_extension_protocol_options: (2)
envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
"@type": "type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions"
explicit_http_config:
http2_protocol_options: {}
load_assignment: (3)
cluster_name: ext-authz
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: heimdall
port_value: 4456
# other cluster entries
1 | The name of our cluster |
2 | Here, we configure envoy to communicate with heimdall by making use of HTTP 2. This configuration is only required if you want to integrate heimdall via Envoy’s grpc_service (see below), as otherwise envoy will use HTTP 1 for GRPC communication, which is actually not allowed by GRPC (only HTTP 2 is supported). |
3 | The endpoints in the cluster. In this example, only one endpoint is configured. |
You can now include an External Authorization HTTP filter in the definition of the HTTP connection manager and depending on the used configuration, either configure the http_service
and let it contain the required header name(s), heimdall sets in the HTTP responses (depends on your Contextualizers and Finalizers configuration), or configure the grpc_service
.
Using HTTP protocol
The following snipped shows, how an External Authorization can be defined using http_service
to let Envoy communicating with heimdall by making use of the previously defined cluster
(see snippet from above) as well as forwarding all request headers to heimdall and to let it forward headers, set by heimdall in its responses (here the Authorization
header) to the upstream services.
http_filters:
# other http filter
- name: envoy.filters.http.ext_authz
typed_config:
"@type": "type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz" (1)
transport_api_version: V3 (2)
http_service:
server_uri: (3)
uri: heimdall:4456
cluster: ext-authz
timeout: 0.25s
authorization_request:
allowed_headers: (4)
patterns:
- safe_regex:
google_re2: {}
regex: ".*"
authorization_response: (5)
allowed_upstream_headers:
patterns:
- exact: authorization
# other http filter
1 | The type of the filter, we’re going to configure |
2 | Heimdall supports only the version 3 of the GRPC protocol defined by Envoy for that filter. So we set the required version here. |
3 | The reference to our previously configured cluster |
4 | Here, we say envoy to forward all headers from the received request to heimdall |
5 | And here, we instruct envoy to forward the Authorization header set bei heimdall in its response to envoy to the upstream service |
| Envoy does not set X-Forwarded-* headers, as long as the envoy.filters.http.dynamic_forward_proxy is not configured. In such cases matching of URLs happens based on those URLs, used by Envoy while communicating with heimdall. That means your rules should ignore the scheme and host parts, respectively use the values specific for heimdall and not of the domain. Please follow Security Considerations if your rules rely on any of the X-Forwarded-* headers, and you integrate heimdall with envoy using http_service . If you integrate heimdall with envoy via grpc_service (see below), spoofing of the aforesaid headers is not possible. |
Using GRPC protocol
The following snipped shows, how an External Authorization can be defined using grpc_service
to let Envoy communicating with heimdall by making use of the previously defined cluster
(see snippet from above). In that configuration envoy by default forwards all request header to heimdall and also forwards headers, set by heimdall in its responses to the upstream services.
http_filters:
# other http filter
- name: envoy.filters.http.ext_authz
typed_config:
"@type": "type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthz" (1)
transport_api_version: V3 (2)
grpc_service: (3)
envoy_grpc:
cluster_name: ext-authz
# other http filter
1 | The type of the filter, we’re going to configure. Same filter is used for both approaches, communication via HTTP and GRPC |
2 | Heimdall supports only the version 3 of the GRPC protocol defined by Envoy for that filter. So we set the required version here |
3 | The reference to our previously configured cluster |