jiazhizhong/higress
1
0
Fork 0
mirror of https://github.com/alibaba/higress.git synced 2026-05-08 12:57:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

update plugins doc (#1305)

Browse Source
This commit is contained in:
澄潭
2024-09-12 21:48:40 +08:00
committed by GitHub
parent 0f9113ed82
commit c7c4ae1da2
80 changed files with 7373 additions and 2368 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
plugins/wasm-go/extensions/basic-auth/README.md
View File

@@ -14,12 +14,17 @@ description: Basic 认证插件配置参考
## 配置字段
### 全局配置
**注意：**
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
| ----------- | --------------- | -------- | ------ | ---------------------------------------------------- |
| `consumers` | array of object | 必填 | - | 配置服务的调用者，用于对请求进行认证 |
| `global_auth` | bool | 选填 | - | 若配置为true，则全局生效认证机制; 若配置为false，则只对做了配置的域名和路由生效认证机制; 若不配置则仅当没有域名和路由配置时全局生效（兼容机制） |
- 在一个规则里，鉴权配置和认证配置不可同时存在
- 对于通过认证鉴权的请求，请求的header会被添加一个`X-Mse-Consumer`字段，用以标识调用者的名称。
### 认证配置
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
| ----------- | --------------- | -------- | ------ | ---------------------------------------------------- |
| `global_auth` | bool | 选填（**仅实例级别配置**） | - | 只能在实例级别配置，若配置为true，则全局生效认证机制; 若配置为false，则只对做了配置的域名和路由生效认证机制，若不配置则仅当没有域名和路由配置时全局生效（兼容老用户使用习惯）。 |
| `consumers` | array of object | 必填 | - | 配置服务的调用者，用于对请求进行认证 |
`consumers`中每一项的配置字段说明如下：
@@ -28,22 +33,20 @@ description: Basic 认证插件配置参考
| `credential` | string | 必填 | - | 配置该consumer的访问凭证 |
| `name` | string | 必填 | - | 配置该consumer的名称 |
### 域名和路由级配置
### 鉴权配置（非必需）
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
| ---------------- | --------------- | ------------------------------------------------- | ------ | -------------------------------------------------- |
| `allow` | array of string | 必填 | - | 对于符合匹配条件的请求，配置允许访问的consumer名称 |
**注意：**
- 对于通过认证鉴权的请求，请求的header会被添加一个`X-Mse-Consumer`字段，用以标识调用者的名称。
## 配置示例
### 对特定路由或域名开启认证和鉴权
### 全局配置认证和路由粒度进行鉴权
以下配置将对网关特定路由或域名开启 Basic Auth 认证和鉴权，注意凭证信息中的用户名和密码之间使用":"分隔，`credential`字段不能重复
**全局配置**
在实例级别做如下插件配置：
```yaml
consumers:
@@ -54,9 +57,6 @@ consumers:
global_auth: false
```
**路由级配置**
对 route-a 和 route-b 这两个路由做如下配置：
```yaml
@@ -75,7 +75,7 @@ allow:
此例指定的 `*.example.com` 和 `test.com` 用于匹配请求的域名，当发现域名匹配时，将允许`name`为`consumer2`的调用者访问，其他调用者不允许访问。
#### 根据该配置，下列请求可以允许访问：
根据该配置，下列请求可以允许访问：
**请求指定用户名密码**
@@ -89,7 +89,7 @@ curl -H 'Authorization: Basic YWRtaW46MTIzNDU2' http://xxx.hello.com/test
认证鉴权通过后，请求的header中会被添加一个`X-Mse-Consumer`字段，在此例中其值为`consumer1`，用以标识调用方的名称
#### 下列请求将拒绝访问：
下列请求将拒绝访问：
**请求未提供用户名密码，返回401**
```bash
@@ -111,4 +111,4 @@ curl -u guest:abc http://xxx.hello.com/test
| ----------- |--------------------------------------------------------------------------------| ---------------------- |
| 401 | Request denied by Basic Auth check. No Basic Authentication information found. | 请求未提供凭证 |
| 401 | Request denied by Basic Auth check. Invalid username and/or password. | 请求凭证无效 |
| 403 | Request denied by Basic Auth check. Unauthorized consumer. | 请求的调用方无访问权限 |
| 403 | Request denied by Basic Auth check. Unauthorized consumer. | 请求的调用方无访问权限 |

140
plugins/wasm-go/extensions/basic-auth/README_EN.md
View File

@@ -1,119 +1,99 @@
---
title: Basic Auth
keywords: [higress, basic auth]
description: Basic authentication plug-in configuration reference
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.
## Description
`basic-auth` plugin implements the function of authentication based on the HTTP Basic Auth standard.
## Operation Attributes
Plugin execution stage: `Authentication Phase`
Plugin execution priority: `320`
## 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 |
**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.
- 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.
### 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. |
## 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.
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. |