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

The basic-auth plug-in is used for authentication based on the HTTP basic authentication specification. This topic describes how to configure the basic-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.
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 authentication and route-level authorization

This section provides an example on how to enable basic authentication and authorization for specific routes or domains of a gateway.

Note

The username and password in the credential information are separated by a colon (:).
The credential configuration item must be unique.

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

global_auth: false
consumers:
- credential: 'admin:123456'
  name: consumer1
- credential: 'guest:abc'
  name: consumer2

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

allow:
- consumer1

Apply the following plug-in configurations 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.

The username and password are specified in the request.

# In this example, route-a in the request is matched.
# Use the -u parameter in the curl command to specify the username and password.
curl -u admin:123456  http://xxx.hello.com/test
# You can also directly specify the Authorization request header in which the username and password are base64-encoded.
curl -H 'Authorization: Basic YWRtaW46MTIzNDU2'  http://xxx.hello.com/test

After the authentication is 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 preceding configurations deny access from the following requests.

The username and password are not specified in the request, and the HTTP status code 401 is returned.
```
curl  http://xxx.hello.com/test
```
The username or password is invalid in the request, and the HTTP status code 401 is returned.
```
curl -u admin:abc  http://xxx.hello.com/test
```
The caller who matches the username and password in the request has no access permission, and the HTTP status code 403 is returned.
```
# The consumer named consumer2 is not in the allow list of route-a.
curl -u guest:abc  http://xxx.hello.com/test
```

Enable authentication for gateways

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: 'admin:123456'
  name: consumer1
- credential: 'guest:abc'
  name: consumer2

HTTP status codes

HTTP status code	Error message	Reason
401	Request denied by Basic Auth check. No Basic Authentication information found.	The credential is not specified in the request.
401	Request denied by Basic Auth check. Invalid username and/or password.	The request credential is invalid.
403	Request denied by Basic Auth check. Unauthorized consumer.	The caller of the request does not have access permissions.