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

Plug-in type

Authentication and authorization.

Fields

Authentication configuration

Field	Data type	Required	Default value	Description
consumers	array of object	Yes	-	Service callers, used to authenticate requests.
global_auth	array of string	No (Required only for instance-level configurations)	-	Configurable only at the instance level. When set to true, authentication applies globally. When set to false, authentication applies only to configured domain names and routes. When not configured, authentication applies globally only if no domain names or routes are configured, for backward compatibility.

Fields in consumers:

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

(Optional) Authorization configuration

Field	Data type	Required	Default value	Description
allow	array of string	No (Required for non-instance-level configurations)	-	Configurable only at the route or domain name level. Specifies which consumers can access requests that match the configured conditions.

Important

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

Examples

Globally configure authentication and configure authorization for routes

This example enables basic authentication and authorization for specific routes or domains of a gateway.

Note

The username and password in the credential are separated by a colon (:).
The credential value 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 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.

These configurations allow 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 authentication succeeds, the X-Mse-Consumer field is added to request headers to identify the caller. In this example, the value is consumer1.

These configurations deny the following requests:

No credentials are provided in the request, and HTTP status code 401 is returned.
```
curl  http://xxx.hello.com/test
```
The username or password is invalid, and HTTP status code 401 is returned.
```
curl -u admin:abc  http://xxx.hello.com/test
```

The caller matched by the credentials does not have access permission, and 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

Apply the following configuration to enable instance-level basic authentication. All requests must then be authenticated.

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

Error codes

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