Function Description

The key-auth plugin implements authentication based on API Key, supporting the parsing of the API Key from HTTP request URL parameters or request headers, while also verifying whether the API Key has permission to access the resource.

Runtime Properties

Plugin Execution Phase: Authentication Phase Plugin Execution Priority: 310

Configuration Fields

Note:

  • Authentication and authorization configurations cannot coexist within a single rule.
  • For requests that are authenticated, a header field X-Mse-Consumer will be added to identify the caller’s name.

Authentication Configuration

NameData TypeRequirementsDefault ValueDescription
global_authboolOptional (Instance-Level Configuration Only)-Can only be configured at the instance level; if set to true, the authentication mechanism takes effect globally; if set to false, it only applies to the configured hostnames and routes. If not configured, it will only take effect globally when no hostname and route configurations are present (to maintain compatibility with older user habits).
consumersarray of objectRequired-Configures the service callers for request authentication.
keysarray of stringRequired-Source field names for the API Key, which can be URL parameters or HTTP request header names.
in_queryboolAt least one of in_query and in_header must be truetrueWhen configured as true, the gateway will attempt to parse the API Key from URL parameters.
in_headerboolAt least one of in_query and in_header must be truetrueWhen configured as true, the gateway will attempt to parse the API Key from HTTP request headers.

The configuration field descriptions for each item in consumers are as follows:

NameData TypeRequirementsDefault ValueDescription
credentialstringRequired-Configures the access credential for this consumer.
namestringRequired-Configures the name for this consumer.

Authorization Configuration (Optional)

NameData TypeRequirementsDefault ValueDescription
allowarray of stringOptional (Non-Instance Level Configuration)-Can only be configured on fine-grained rules such as routes or hostnames; specifies the allowed consumers for matching requests, allowing for fine-grained permission control.

Configuration Example

Global Configuration for Authentication and Granular Route Authorization

The following configuration will enable Key Auth authentication and authorization for specific routes or hostnames in the gateway. The credential field must not repeat.

At the instance level, do the following plugin configuration:

  1. global_auth: false
  2. consumers:
  3. - credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5
  4.   name: consumer1
  5. - credential: c8c8e9ca-558e-4a2d-bb62-e700dcc40e35
  6.   name: consumer2
  7. keys:
  8. - apikey
  9. - x-api-key

For routes route-a and route-b, do the following configuration:

  1. allow:
  2. - consumer1

For the hostnames *.example.com and test.com, do the following configuration:

  1. allow:
  2. - consumer2

Note: The routes route-a and route-b specified in this example refer to the route names filled in when creating the gateway routes. When matched with these two routes, requests from the caller named consumer1 will be allowed while others will be denied.

The specified hostnames *.example.com and test.com are used to match the request’s domain name. When a domain name is matched, callers named consumer2 will be allowed while others will be denied.

Based on this configuration, the following requests will be allowed:

Assuming the following request matches route-a: Setting API Key in URL Parameters

Setting API Key in HTTP Request Headers

  1. curl  http://xxx.hello.com/test -H ‘x-api-key: 2bda943c-ba2b-11ec-ba07-00163e1250b5’

After successful authentication and authorization, the request’s header will have an added X-Mse-Consumer field with the value consumer1, to identify the name of the caller.

The following requests will be denied access: Request without an API Key returns 401

Request with an invalid API Key returns 401

Caller matched with provided API Key has no access rights, returns 403

  1. # consumer2 is not in the allow list of route-a

Enabling at the Instance Level

The following configuration will enable Basic Auth authentication at the instance level for the gateway, requiring all requests to pass authentication before accessing.

  1. global_auth: true
  2. consumers:
  3. - credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5
  4.   name: consumer1
  5. - credential: c8c8e9ca-558e-4a2d-bb62-e700dcc40e35
  6.   name: consumer2
  7. keys:
  8. - apikey
  9. - x-api-key
HTTP Status CodeError MessageReason Explanation
401Request denied by Key Auth check. Multiple API keys found in requestMultiple API Keys provided in the request.
401Request denied by Key Auth check. No API key found in requestAPI Key not provided in the request.
401Request denied by Key Auth check. Invalid API keyThe current API Key is not authorized for access.
403Request denied by Key Auth check. Unauthorized consumerThe caller does not have access permissions.