-
Notifications
You must be signed in to change notification settings - Fork 471
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
80 changed files
with
7,379 additions
and
2,374 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,117 +1,99 @@ | ||
| <p> | ||
| English | <a href="README.md">中文</a> | ||
| </p> | ||
|
|
||
| # Description | ||
| `basic-auth` plugin implements the function of authentication based on the HTTP Basic Auth standard. | ||
|
|
||
| # Configuration Fields | ||
|
|
||
| | Name | Type | Requirement | Default Value | Description | | ||
| | ----------- | --------------- | -------- | ------ | ---------------------------------------------------- | | ||
| | `consumers` | array of object | Required | - | Caller of the service for authentication of requests | | ||
| | `_rules_` | array of object | Optional | - | Configure access permission list for specific routes or domains to authenticate requests | | ||
|
|
||
| Filed descriptions of `consumers` items: | ||
|
|
||
| | Name | Type | Requirement | Default Value | Description | | ||
| | ------------ | ------ | ----------- | ------------- | ------------------------------------- | | ||
| | `credential` | string | Required | - | Credential for this consumer's access | | ||
| | `name` | string | Required | - | Name of this consumer | | ||
|
|
||
| Configuration field descriptions for each item in `_rules_` are as follows: | ||
|
|
||
| | Field Name | Data Type | Requirement | Default | Description | | ||
| | ---------------- | --------------- | ------------------------------------------------- | ------ | -------------------------------------------------- | | ||
| | `_match_route_` | array of string | One of `_match_route_` or `_match_domain_` | - | Configure the routes to match for request authorization | | ||
| | `_match_domain_` | array of string | One of `_match_route_` , `_match_domain_` | - | Configure the domains to match for request authorization | | ||
| | `allow` | array of string | Required | - | Configure the consumer names allowed to access requests that match the match condition | | ||
|
|
||
| --- | ||
| title: Basic Authentication | ||
| keywords: [higress,basic auth] | ||
| description: Basic authentication plugin configuration reference | ||
| --- | ||
| ## 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:** | ||
|
|
||
| - If the `_rules_` field is not configured, authentication is enabled for all routes of the current gateway instance by default; | ||
| - For authenticated requests, `X-Mse-Consumer` field will be added to the request header to identify the name of the caller. | ||
|
|
||
| # Configuration Samples | ||
|
|
||
| ## Enable Authentication and Authorization for specific routes or domains | ||
|
|
||
| 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 a ":", and the `credential` field cannot be repeated. | ||
|
|
||
|
|
||
|
|
||
| - 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 | ||
| | Name | Data Type | Requirements | Default Value | Description | | ||
| | ------------- | ---------------- | ------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `global_auth` | bool | Optional (**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). | | ||
| | `consumers` | array of object | Required | - | Configures the service callers for request authentication. | | ||
|
|
||
| Each configuration field in `consumers` is described as follows: | ||
| | Name | Data Type | Requirements | Default Value | Description | | ||
| | ------------ | --------- | ------------ | ------------- | ------------------------------- | | ||
| | `credential` | string | Required | - | Configures the access credentials for this consumer. | | ||
| | `name` | string | Required | - | Configures the name of this consumer. | | ||
|
|
||
| ### Authorization Configuration (Optional) | ||
| | Name | Data Type | Requirements | Default Value | Description | | ||
| | ---------------- | ---------------- | ---------------------------------------------------- | -------------- | -------------------------------------------------------- | | ||
| | `allow` | array of string | Required | - | 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: | ||
| ```yaml | ||
| # use the _rules_ field for fine-grained rule configuration. | ||
| consumers: | ||
| - credential: 'admin:123456' | ||
| name: consumer1 | ||
| - credential: 'guest:abc' | ||
| name: consumer2 | ||
| _rules_: | ||
| # rule 1: match by the route name. | ||
| - _match_route_: | ||
| - route-a | ||
| - route-b | ||
| allow: | ||
| - consumer1 | ||
| # rule 2: match by the domain. | ||
| - _match_domain_: | ||
| - "*.example.com" | ||
| - test.com | ||
| allow: | ||
| - consumer2 | ||
| global_auth: false | ||
| ``` | ||
| In this sample, `route-a` and `route-b` specified in `_match_route_` are the route names filled in when creating gateway routes. When these two routes are matched, the caller with `name` as `consumer1` is allowed to access, and other callers are not allowed to access. | ||
| The `*.example.com` and `test.com` specified in `_match_domain_` are used to match the domain name of the request. When the domain name is matched, the caller with `name` as `consumer2` is allowed to access, and other callers are not allowed to access. | ||
| For routes `route-a` and `route-b`, configure as follows: | ||
| ```yaml | ||
| allow: | ||
| - consumer1 | ||
| ``` | ||
|
|
||
| For the domains `*.example.com` and `test.com`, configure as follows: | ||
| ```yaml | ||
| allow: | ||
| - consumer2 | ||
| ``` | ||
|
|
||
| ### According to this configuration, the following requests are allowed: | ||
| 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. | ||
|
|
||
| **Requests with specified username and password** | ||
| 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** | ||
| ```bash | ||
| # Assuming the following request will match with route-a | ||
| # Use -u option of curl to specify the credentials | ||
| # Assuming the following request matches the route-a route | ||
| # Using curl's -u parameter to specify | ||
| curl -u admin:123456 http://xxx.hello.com/test | ||
| # Or specify the Authorization request header directly with the credentials in base64 encoding | ||
| # Or directly specify the Authorization request header with the username and password encoded in base64 | ||
| curl -H 'Authorization: Basic YWRtaW46MTIzNDU2' http://xxx.hello.com/test | ||
| ``` | ||
|
|
||
| A `X-Mse-Consumer` field will be added to the headers of the request, and its value in this example is `consumer1`, used to identify the name of the caller when passed authentication and authorization. | ||
| 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: | ||
|
|
||
| **Requests without providing username and password, returning 401** | ||
| The following requests will be denied access: | ||
| **Request without username and password, returns 401** | ||
| ```bash | ||
| curl http://xxx.hello.com/test | ||
| ``` | ||
| **Requests with incorrect username or password, returning 401** | ||
|
|
||
| **Request with incorrect username and password, returns 401** | ||
| ```bash | ||
| curl -u admin:abc http://xxx.hello.com/test | ||
| ``` | ||
| **Requests matched with a caller who has no access permission, returning 403** | ||
|
|
||
| **Caller matched by username and password has no access, returns 403** | ||
| ```bash | ||
| # consumer2 is not in the allow list of route-a | ||
| # consumer2 is not in the allow list for route-a | ||
| curl -u guest:abc http://xxx.hello.com/test | ||
| ``` | ||
|
|
||
| ## Enable basic auth for gateway instance | ||
|
|
||
| The following configuration does not specify the `_rules_` field, so Basic Auth authentication will be effective for the whole gateway instance. | ||
|
|
||
| ```yaml | ||
| consumers: | ||
| - credential: 'admin:123456' | ||
| name: consumer1 | ||
| - credential: 'guest:abc' | ||
| name: consumer2 | ||
| ``` | ||
|
|
||
| # Error Codes | ||
|
|
||
| | HTTP Status Code | Error Info | Reason | | ||
| | ----------- | ------------------------------------------------------------------------------ | ---------------------- | | ||
| | 401 | Request denied by Basic Auth check. No Basic Authentication information found. | Credentials not provided in the request | | ||
| | 401 | Request denied by Basic Auth check. Invalid username and/or password | Invalid username and/or password | | ||
| | 403 | Request denied by Basic Auth check. Unauthorized consumer | Unauthorized consumer | | ||
| ## Related Error Codes | ||
| | HTTP Status Code | Error Message | Reason Description | | ||
| | ---------------- | ------------------------------------------------------------------------------------- | -------------------------------- | | ||
| | 401 | Request denied by Basic Auth check. No Basic Authentication information found. | Request did not provide credentials. | | ||
| | 401 | Request denied by Basic Auth check. Invalid username and/or password. | Request credentials are invalid. | | ||
| | 403 | Request denied by Basic Auth check. Unauthorized consumer. | The caller making the request does not have access. | |
Oops, something went wrong.