Configure the key-auth plug-in - Microservices Engine - Alibaba Cloud Documentation Center

The key-auth plug-in is used for authentication based on API keys. You can use the key-auth plug-in to parse API keys from the URL parameters or request headers of HTTP requests and check whether the API keys are valid for access to services. This topic describes how to configure the key-auth plug-in.

Plug-in type

Authentication plug-in.

Fields

Authentication configuration

Name	Data type	Required	Default value	Description
consumers	array of object	Yes	-	The callers of the service. This field is used to authenticate requests.
keys	array of string	Yes	-	The source fields of the API keys. Source fields can be URL parameters or HTTP request headers.
in_query	bool	No (You must set at least one of `in_query` and `in_header` to true.)	true	If this field is set to `true`, the gateway attempts to parse API keys from URL parameters.
in_header	bool	No (You must set at least one of `in_query` and `in_header` to true.)	true	If this field is set to `true`, the gateway attempts to parse API keys from HTTP request headers.
global_auth	array of string	No (Required only for instance-level configurations.)	-	If global_auth is set to true, the authentication mechanism globally takes effect. If global_auth is set to false, the authentication mechanism takes effect only for the domain names and routes that you configure. If global_auth is not configured, the authentication mechanism globally takes effect only when no domain names and routes are configured.

The following table describes the configuration items in the consumers field.

Name	Data type	Required	Default value	Description
credential	string	Yes	-	The access credential of the consumer.
name	string	Yes	-	The name of the consumer.

Authorization configuration (optional)

Name	Data type	Required	Default value	Description
allow	array of string	No (Required for non-instance-level configurations)	-	You can only configure this field at a fine granularity such as route or domain name. For requests that meet the matching conditions, you can configure consumers that are allowed for access. This implements fine-grained permission control.

Important

The authorization configuration and authentication configuration cannot coexist in a rule.
For requests that are authenticated and authorized, the X-Mse-Consumer field is added to the request header to identify the names of the callers.

Configuration examples

Configure global authorization and route-level authentication

This section provides an example on how to enable authentication and authorization based on the key-auth plug-in for specific routes or domains of the gateway. The credential field must be unique.

Apply the following plug-in configurations at the instance level:

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

Apply the following plug-in configuration to the route-a and route-b routes:

allow:
- consumer1

Apply the following plug-in configuration to the *.example.com and test.com domain names:

allow:
- consumer2

Note

In this example, the route-a and route-b routes are those specified when the gateway routes are created. If a client request matches one of the routes, the caller whose name is consumer1 is allowed to access the gateway. Other callers are not allowed to access the gateway.
In this example, the *.example.com and test.com domain names are used to match domain names in requests. If a client request matches one of the domain names, the caller whose name is consumer2 is allowed to access the gateway. Other callers are not allowed to access the gateway.

The preceding configurations allow access from the following requests. In this example, route-a is matched.

Specify the API key in the URL parameter.

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

Specify the API key in the HTTP request header.

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

After the authentication and authorization are passed, the X-Mse-Consumer field is added to headers of requests to identify the caller. In this example, the value of this field is consumer1.

The following requests are denied:

No API key is specified in the request, and the HTTP status code 401 is returned.
```
curl  http://xxx.hello.com/test
```
The API key that is specified in the request is invalid, and the HTTP status code 401 is returned.
```
curl  http://xxx.hello.com/test?apikey=926d90ac-ba2e-11ec-ab68-00163e1250b5
```

The caller that is matched by using the API key has no access permission, and the HTTP status code 403 is returned.

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

Enable basic authentication for gateway instances

After you apply the following configurations to a gateway, basic authentication is enabled at the instance level and all requests must be authenticated to access the gateway.

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

HTTP status codes

HTTP status code	Error message	Reason
401	No API key found in request.	No API key is specified in the request.
401	Request denied by Key Auth check. Invalid API key.	The API key is invalid.
403	Request denied by Basic Auth check. Unauthorized consumer.	The caller of the request does not have access permissions.