APIKey Auth (proto)

This extension has the qualified name envoy.filters.http.api_key_auth

Note

This extension is functional but has not had substantial production burn time, use only with this caveat.

This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted.

Tip

This extension extends and can be used with the following extension category:

This extension must be configured with one of the following type URLs:

Warning

This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.

APIKey Auth configuration overview.

extensions.filters.http.api_key_auth.v3.ApiKeyAuth

[extensions.filters.http.api_key_auth.v3.ApiKeyAuth proto]

API Key HTTP authentication.

For example, the following configuration configures the filter to authenticate the clients using the API key from the header X-API-KEY. And only the clients with the key real-key are considered as authenticated.

credentials:
- key: real-key
  client: user
key_sources:
 - header: "X-API-KEY"

{
  "credentials": [],
  "key_sources": []
}
credentials

(repeated extensions.filters.http.api_key_auth.v3.Credential) The credentials that are used to authenticate the clients.

key_sources

(repeated extensions.filters.http.api_key_auth.v3.KeySource) The key sources to fetch the key from the coming request.

extensions.filters.http.api_key_auth.v3.ApiKeyAuthPerRoute

[extensions.filters.http.api_key_auth.v3.ApiKeyAuthPerRoute proto]

API key auth configuration of per route or per virtual host or per route configuration.

{
  "credentials": [],
  "key_sources": [],
  "allowed_clients": []
}
credentials

(repeated extensions.filters.http.api_key_auth.v3.Credential) The credentials that are used to authenticate the clients. If this field is non-empty, then the credentials in the filter level configuration will be ignored and the credentials in this configuration will be used.

key_sources

(repeated extensions.filters.http.api_key_auth.v3.KeySource) The key sources to fetch the key from the coming request. If this field is non-empty, then the key sources in the filter level configuration will be ignored and the key sources in this configuration will be used.

allowed_clients

(repeated string) A list of clients that are allowed to access the route or vhost. The clients listed here should be subset of the clients listed in the credentials to provide authorization control after the authentication is successful. If the list is empty, then all authenticated clients are allowed. This provides very limited but simple authorization. If more complex authorization is required, then use the HTTP RBAC filter instead.

Note

Setting this field and credentials at the same configuration entry is not an error but also makes no much sense because they provide similar functionality. Please only use one of them at same configuration entry except for the case that you want to share the same credentials list across multiple routes but still use different allowed clients for each route.

extensions.filters.http.api_key_auth.v3.Credential

[extensions.filters.http.api_key_auth.v3.Credential proto]

Single credential entry that contains the API key and the related client id.

{
  "key": ...,
  "client": ...
}
key

(string, REQUIRED) The value of the unique API key.

client

(string, REQUIRED) The unique id or identity that used to identify the client or consumer.

extensions.filters.http.api_key_auth.v3.KeySource

[extensions.filters.http.api_key_auth.v3.KeySource proto]

{
  "header": ...,
  "query": ...,
  "cookie": ...
}
header

(string) The header name to fetch the key. If multiple header values are present, the first one will be used. If the header value starts with ‘Bearer ‘, this prefix will be stripped to get the key value.

If set, takes precedence over query and cookie.

query

(string) The query parameter name to fetch the key. If multiple query values are present, the first one will be used.

The field will be used if header is not set. If set, takes precedence over cookie.