API key auth

This HTTP filter can be used to authenticate users based on the unique API key. The filter will extract the API keys from either an HTTP header, a parameter query, or a cookie and verify them against the configured credential list.

If the API key is valid and the related client is allowed, the request will be allowed to continue. If the API key is invalid or not exists, the request will be denied with 401 status code. If the API key is valid but the related client is not allowed, the request will be denied with 403 status code.

Configuration

• This filter should be configured with the type URL type.googleapis.com/envoy.extensions.filters.http.api_key_auth.v3.ApiKeyAuth.

• v3 API reference

An example configuration of the filter may look like the following:

api-key-auth-filter.yaml

          - name: api_key_auth
            typed_config:
              "@type": type.googleapis.com/envoy.extensions.filters.http.api_key_auth.v3.ApiKeyAuth
              credentials:
              - key: one_key
                client: one_client
              - key: another_key
                client: another_client
              key_sources:
              - header: Authorization

Per-Route Configuration

It’s possible to override the filter’s configuration for a specific scope like a route or virtual host. And the overriding configuration could be partial to override only credential list or to override only the API key source.

And this filter also provides very limited authorization control. A simple allowed_clients could be configured for specific scope like a route or virtual host to allow or deny specific clients.

An example scope specific configuration of the filter may look like the following:

api-key-auth-filter.yaml

            name: local_route
            virtual_hosts:
            - name: local_service
              domains: ["*"]
              routes:
              - match:
                  path: "/admin"
                route:
                  cluster: upstream_com
                typed_per_filter_config:
                  api_key_auth:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.api_key_auth.v3.ApiKeyAuthPerRoute
                    key_sources:
                    - query: api_key
                    allowed_clients:
                    - another_client
              - match:
                  path: "/special"
                route:
                  cluster: upstream_com
                typed_per_filter_config:
                  api_key_auth:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.api_key_auth.v3.ApiKeyAuthPerRoute
                    credentials:
                    - key: special_key
                      client: special_client
                    key_sources:
                    - header: X-Special-Key
              - match:
                  prefix: "/static"
                route:
                  cluster: upstream_com
                typed_per_filter_config:
                  api_key_auth:
                    "@type": type.googleapis.com/envoy.config.route.v3.FilterConfig
                    disabled: true
              - match:
                  prefix: "/"
                route:
                  cluster: upstream_com

In this example we customize key source for /admin route and only allow limited clients to access this route. We also customize the credential list for /special route and disable the filter for /static route.

Combining the per-route configuration example and the filter configuration example, given the following requests, the filter will behave as follows:

# The request will be allowed because the API key is valid and the client is allowed.
GET /admin?api_key=another_key HTTP/1.1
host: example.com

# The request will be denied with 403 status code because the API key is valid but the client is
# not allowed.
GET /admin?api_key=one_key HTTP/1.1
host: example.com

# The request will be denied with 401 status code because the API key is invalid.
GET /admin?api_key=invalid_key HTTP/1.1
host: example.com

# The request will be allowed because the API key is valid and no client validation is configured.
GET /special HTTP/1.1
host: example.com
X-Special-Key: "special_key"

# The request will be allowed because the filter is disabled for specific route.
GET /static HTTP/1.1
host: example.com

# The request will be allowed because the API key is valid and no client validation is configured.
GET / HTTP/1.1
host: example.com
Authorization: "Bearer one_key"

Statistics

The HTTP API key auth filter outputs statistics in the http.<stat_prefix>.api_key_auth. namespace.

Name	Type	Description
allowed	Counter	Total number of allowed requests
unauthorized	Counter	Total number of requests that have invalid API key
forbidden	Counter	Total number of requests that have valid API key but not allowed