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

Name	Data type	Required	Default value	Description
consumers	array of object	Yes	-	The callers of the service. This field is used to authenticate requests.
_rules_	array of object	No	-	The access permission list for specific routes or domains. This field is used to authenticate requests.

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.

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

Name	Data type	Required	Default value	Description
_match_route_	array of string	No (You must configure `_match_route_` or `_match_domain_`.)	-	The names of the routes to match for request authentication.
_match_domain_	array of string	No (You must configure `_match_route_` or `_match_domain_`.)	-	The names of the domains to match for request authentication.
allow	array of string	Yes	-	The names of the authorized consumers if requests meet the matching conditions.

Note

If you do not configure the _rules_ field, authentication is enabled for all routes of the current gateway.
For authenticated requests, the X-Mse-Consumer field is added to the request headers to identify the name of the caller.

Configuration examples

Enable authentication for specific routes or domains

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

Note

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

# Use the _rules_ field to configure fine-grained rules.
consumers:
- credential: 'admin:123456'
  name: consumer1
- credential: 'guest:abc'
  name: consumer2
_rules_:
# Rule 1: match by route name
  - _match_route_:
    - route-a
    - route-b
    allow:
    - consumer1
# Rule 2: match by domain name
  - _match_domain_:
    - "*.example.com"
    - test.com
    allow:
    - consumer2

Note

route-a and route-b specified in _match_route_ are the names of the routes that you specify when you create gateway routes. If the two routes are matched, the caller whose name is consumer1 is allowed to access the gateway routes. Other callers are not allowed to access the gateway routes.
The *.example.com and test.com domain names specified in _match_domain_ are used to match the domain names in requests. If a domain name match is found, the caller whose name is consumer2 is allowed to access the matched domain name. Other callers are not allowed to access the matched domain name.

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

In this example, the _rules_ field is not specified, and basic authentication is enabled for gateways.

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.