Configure the key-auth plug-in - API Gateway - Alibaba Cloud Documentation Center

Obtain an API key (credential)

Each caller authenticates with a credential value in the plug-in configuration — a string key you define. No console application is required.

When defining a credential, follow these guidelines:

Use a random string of 32+ characters, for example in UUID format: 2bda943c-ba2b-11ec-ba07-00163e125d8f
Keep it secure. Do not expose it in client-side code or public documentation.
To assign different permissions to multiple callers, define a unique credential for each and configure them in the consumers field.

Plug-in type

Authentication and authorization.

Fields

Authentication configuration

Configuration item	Data type	Required	Default value	Description
consumers	array of object	Yes	-	Service callers for request authentication.
keys	array of string	Yes	-	Names of URL parameters or HTTP headers from which to extract API keys.
in_query	bool	At least one of `in_query` and `in_header` must be set to true.	true	When set to `true`, the gateway parses API keys from URL parameters.
in_header	bool	At least one of `in_query` and `in_header` must be set to true.	true	When set to `true`, the gateway parses API keys from HTTP headers.
global_auth	array of string	No (Required only for instance-level configurations)	-	Instance-level only. If true, authentication applies globally. If false, authentication applies only to configured domains and routes. If unset, global authentication is enabled only when no domains or routes are configured.

Fields in the consumers object:

Configuration item	Data type	Required	Default value	Description
credential	string	Yes	-	Access credential for the consumer.
name	string	Yes	-	Consumer name.

Authorization configuration (optional)

Configuration item	Data type	Required	Default value	Description
allow	array of string	No (Required for non-instance-level configurations)	-	Route or domain-level only. Lists the consumers allowed to access matched requests.

Important

Authorization and authentication configurations cannot coexist in a single rule.
For authenticated requests, an X-Mse-Consumer header is added to identify the caller.

Example

Global authentication with route-level authorization

This example configures authentication at the instance level and authorization at the route and domain level. Each credential value must be unique.

Instance-level plug-in configuration:

global_auth: false
consumers:
- credential: 2bda943c-ba2b-11ec-ba07-00163e125***
  name: consumer1
- credential: c8c8e9ca-558e-4a2d-bb62-e700dcc40***
  name: consumer2
keys:
- apikey
- x-api-key

Plug-in configuration for the route-a and route-b routes:

allow:
- consumer1

Plug-in configuration for the *.example.com and test.com domains:

allow:
- consumer2

Note

When a request matches route-a or route-b, only the caller with name set to consumer1 is allowed access.
When a request matches *.example.com or test.com, only the caller with name set to consumer2 is allowed access.

Allowed requests (matching the route-a route):

API key in a URL parameter:

curl  http://xxx.hello.com/test?apikey=2bda943c-ba2b-11ec-ba07-00163e1***

API key in an HTTP header:

curl  http://xxx.hello.com/test -H 'x-api-key: 2bda943c-ba2b-11ec-ba07-00163e1***'

After authentication succeeds, the X-Mse-Consumer header identifies the caller. In this example, the value is consumer1.

Denied requests:

No API key provided. Returns HTTP 401.
```
curl  http://xxx.hello.com/test
```

Invalid API key. Returns HTTP 401.

curl  http://xxx.hello.com/test?apikey=926d90ac-ba2e-11ec-ab68-00163e1***

The matched caller lacks access permission. Returns HTTP 403.

# The caller consumer2 is not in the whitelist of route-a.
curl  http://xxx.hello.com/test?apikey=c8c8e9ca-558e-4a2d-bb62-e700dcc***

Enable gateway-wide authentication

With the following instance-level configuration, all requests require key-auth authentication.

global_auth: true
consumers:
- credential: 2bda943c-ba2b-11ec-ba07-00163e1***
  name: consumer1
- credential: c8c8e9ca-558e-4a2d-bb62-e700dcc***
  name: consumer2
keys:
- apikey
- x-api-key

Error codes

HTTP status code	Error message	Reason
401	No API key found in request.	The request contains no API key.
401	Request denied by Key Auth check. Invalid API key.	The API key is not valid.
403	Request denied by Key Auth check. Unauthorized consumer.	The caller lacks access permission.