Function Description

The basic-auth plugin implements authentication and authorization based on the HTTP Basic Auth standard.

Operation Attributes

Plugin execution stage: Authentication Phase
Plugin execution priority: 320

Configuration Fields

Note:

  • In one rule, authentication configurations and authorization configurations cannot coexist.
  • For requests that pass authentication, the request header will include an X-Mse-Consumer field to identify the caller’s name.

Authentication Configuration

NameData TypeRequirementsDefault ValueDescription
global_authboolOptional (instance-level only)-Can only be configured at the instance level. If set to true, the authentication mechanism will take effect globally; if set to false, it will only take effect for the configured domains and routes. If not configured, it will only take effect globally when there are no domain and route configurations (compatible with old user habits).
consumersarray of objectRequired-Configures the service callers for request authentication.

Each configuration field in consumers is described as follows:

NameData TypeRequirementsDefault ValueDescription
credentialstringRequired-Configures the access credentials for this consumer.
namestringRequired-Configures the name of this consumer.

Authorization Configuration (Optional)

NameData TypeRequirementsDefault ValueDescription
allowarray of stringRequired-Configures the consumer names allowed to access for matching requests.

Configuration Example

Global Authentication and Route Granularity Authorization

The following configuration will enable Basic Auth authentication and authorization for specific routes or domains of the gateway. Note that the username and password in the credential information are separated by ”:”, and the credential field cannot be duplicated.

Make the following plugin configuration at the instance level:

  1. consumers:
  2. - credential: ‘admin:123456’
  3.   name: consumer1
  4. - credential: ‘guest:abc’
  5.   name: consumer2
  6. global_auth: false

For routes route-a and route-b, configure as follows:

  1. allow:
  2. - consumer1

For the domains *.example.com and test.com, configure as follows:

  1. allow:
  2. - consumer2

If configured in the console, the specified route-a and route-b refer to the route names filled in when creating the routes in the console. When matching these two routes, callers with the name consumer1 will be allowed access, while other callers will not.

The specified *.example.com and test.com are used to match the request domain. When a match is found, callers with the name consumer2 will be allowed access, while other callers will not.

Based on this configuration, the following requests may be allowed access: Request with specified username and password

  1. # Assuming the following request matches the route-a route
  2. # Using curl’s -u parameter to specify
  3. curl -u admin:123456  http://xxx.hello.com/test
  4. # Or directly specify the Authorization request header with the username and password encoded in base64
  5. curl -H ‘Authorization: Basic YWRtaW46MTIzNDU2’  http://xxx.hello.com/test

After successful authentication, the request header will have an added X-Mse-Consumer field, which in this case is consumer1 to identify the caller’s name.

The following requests will be denied access: Request without username and password, returns 401

Request with incorrect username and password, returns 401

  1. curl -u admin:abc  http://xxx.hello.com/test

Caller matched by username and password has no access, returns 403

  1. # consumer2 is not in the allow list for route-a
  2. curl -u guest:abc  http://xxx.hello.com/test
HTTP Status CodeError MessageReason Description
401Request denied by Basic Auth check. No Basic Authentication information found.Request did not provide credentials.
401Request denied by Basic Auth check. Invalid username and/or password.Request credentials are invalid.
403Request denied by Basic Auth check. Unauthorized consumer.The caller making the request does not have access.