jiazhizhong/higress
1
0
Fork 0
mirror of https://github.com/alibaba/higress.git synced 2026-02-21 22:40:59 +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

106
plugins/wasm-cpp/extensions/basic_auth/README.md
View File

@@ -1,16 +1,30 @@
<p>
<a href="README_EN.md">English</a> | 中文
</p>
---
title: Basic 认证
keywords: [higress,basic auth]
description: Basic 认证插件配置参考
---
# 功能说明
## 功能说明
`basic-auth`插件实现了基于 HTTP Basic Auth 标准进行认证鉴权的功能
# 配置字段
## 运行属性
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
| ----------- | --------------- | -------- | ------ | ---------------------------------------------------- |
| `consumers` | array of object | 必填 | - | 配置服务的调用者，用于对请求进行认证 |
| `_rules_` | array of object | 选填 | - | 配置特定路由或域名的访问权限列表，用于对请求进行鉴权 |
插件执行阶段：`认证阶段`
插件执行优先级：`320`
## 配置字段
**注意：**
- 在一个规则里，鉴权配置和认证配置不可同时存在
- 对于通过认证鉴权的请求，请求的header会被添加一个`X-Mse-Consumer`字段，用以标识调用者的名称。
### 认证配置
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
| ----------- | --------------- | -------- | ------ | ---------------------------------------------------- |
| `global_auth` | bool | 选填（**仅实例级别配置**） | - | 只能在实例级别配置，若配置为true，则全局生效认证机制; 若配置为false，则只对做了配置的域名和路由生效认证机制，若不配置则仅当没有域名和路由配置时全局生效（兼容老用户使用习惯）。 |
| `consumers` | array of object | 必填 | - | 配置服务的调用者，用于对请求进行认证 |
`consumers`中每一项的配置字段说明如下：
@@ -19,51 +33,49 @@
| `credential` | string | 必填 | - | 配置该consumer的访问凭证 |
| `name` | string | 必填 | - | 配置该consumer的名称 |
`_rules_` 中每一项的配置字段说明如下：
### 鉴权配置（非必需）
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
| ---------------- | --------------- | ------------------------------------------------- | ------ | -------------------------------------------------- |
| `_match_route_` | array of string | 选填，`_match_route_`，`_match_domain_`中选填一项 | - | 配置要匹配的路由名称 |
| `_match_domain_` | array of string | 选填，`_match_route_`，`_match_domain_`中选填一项 | - | 配置要匹配的域名 |
| `allow` | array of string | 必填 | - | 对于符合匹配条件的请求，配置允许访问的consumer名称 |
**注意：**
- 若不配置`_rules_`字段，则默认对当前网关实例的所有路由开启认证；
- 对于通过认证鉴权的请求，请求的header会被添加一个`X-Mse-Consumer`字段，用以标识调用者的名称。
## 配置示例
# 配置示例
## 对特定路由或域名开启认证和鉴权
### 全局配置认证和路由粒度进行鉴权
以下配置将对网关特定路由或域名开启 Basic Auth 认证和鉴权，注意凭证信息中的用户名和密码之间使用":"分隔，`credential`字段不能重复
在实例级别做如下插件配置：
```yaml
# 使用 _rules_ 字段进行细粒度规则配置
consumers:
- credential: 'admin:123456'
name: consumer1
- credential: 'guest:abc'
name: consumer2
_rules_:
# 规则一：按路由名称匹配生效
- _match_route_:
- route-a
- route-b
allow:
- consumer1
# 规则二：按域名匹配生效
- _match_domain_:
- "*.example.com"
- test.com
allow:
- consumer2
global_auth: false
```
此例 `_match_route_` 中指定的 `route-a` 和 `route-b` 即在创建网关路由时填写的路由名称，当匹配到这两个路由时，将允许`name`为`consumer1`的调用者访问，其他调用者不允许访问；
对 route-a 和 route-b 这两个路由做如下配置：
此例 `_match_domain_` 中指定的 `*.example.com` 和 `test.com` 用于匹配请求的域名，当发现域名匹配时，将允许`name`为`consumer2`的调用者访问，其他调用者不允许访问。
```yaml
allow:
- consumer1
```
### 根据该配置，下列请求可以允许访问：
对 *.example.com 和 test.com 在这两个域名做如下配置:
```yaml
allow:
- consumer2
```
若是在控制台进行配置，此例指定的 `route-a` 和 `route-b` 即在控制台创建路由时填写的路由名称，当匹配到这两个路由时，将允许`name`为`consumer1`的调用者访问，其他调用者不允许访问；
此例指定的 `*.example.com` 和 `test.com` 用于匹配请求的域名，当发现域名匹配时，将允许`name`为`consumer2`的调用者访问，其他调用者不允许访问。
根据该配置，下列请求可以允许访问：
**请求指定用户名密码**
@@ -77,7 +89,7 @@ curl -H 'Authorization: Basic YWRtaW46MTIzNDU2' http://xxx.hello.com/test
认证鉴权通过后，请求的header中会被添加一个`X-Mse-Consumer`字段，在此例中其值为`consumer1`，用以标识调用方的名称
### 下列请求将拒绝访问：
下列请求将拒绝访问：
**请求未提供用户名密码，返回401**
```bash
@@ -93,22 +105,10 @@ curl -u admin:abc http://xxx.hello.com/test
curl -u guest:abc http://xxx.hello.com/test
```
## 网关实例级别开启
## 相关错误码
以下配置未指定`_rules_`字段，因此将对网关实例级别开启 Basic Auth 认证
```yaml
consumers:
- credential: 'admin:123456'
name: consumer1
- credential: 'guest:abc'
name: consumer2
```
# 相关错误码
| HTTP 状态码 | 出错信息 | 原因说明 |
| ----------- | ------------------------------------------------------------------------------ | ---------------------- |
| HTTP 状态码 | 出错信息 | 原因说明 |
| ----------- |--------------------------------------------------------------------------------| ---------------------- |
| 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 | 请求的调用方无访问权限 |
| 401 | Request denied by Basic Auth check. Invalid username and/or password. | 请求凭证无效 |
| 403 | Request denied by Basic Auth check. Unauthorized consumer. | 请求的调用方无访问权限 |

144
plugins/wasm-cpp/extensions/basic_auth/README_EN.md
View File

@@ -1,117 +1,99 @@
<p>
English | <a href="README.md">中文</a>
</p>
---
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.
# 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 |
## 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.
- 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. |