jiazhizhong/higress
1
0
Fork 0
mirror of https://github.com/alibaba/higress.git synced 2026-03-01 23:20:52 +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

113
plugins/wasm-cpp/extensions/key_auth/README.md
View File

@@ -1,15 +1,32 @@
# 功能说明
---
title: Key 认证
keywords: [higress,key auth]
description: Key 认证插件配置参考
---
## 功能说明
`key-auth`插件实现了基于 API Key 进行认证鉴权的功能，支持从 HTTP 请求的 URL 参数或者请求头解析 API Key，同时验证该 API Key 是否有权限访问。
# 配置字段
## 运行属性
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
| ----------- | --------------- | ------------------------------------------- | ------ | ----------------------------------------------------------- |
| `consumers` | array of object | 必填 | - | 配置服务的调用者，用于对请求进行认证 |
| `keys` | array of string | 必填 | - | API Key 的来源字段名称，可以是 URL 参数或者 HTTP 请求头名称 |
| `in_query` | bool | `in_query` 和 `in_header` 至少有一个为 true | true | 配置 true 时，网关会尝试从 URL 参数中解析 API Key |
| `in_header` | bool | `in_query` 和 `in_header` 至少有一个为 true | true | 配置 true 时，网关会尝试从 HTTP 请求头中解析 API Key |
| `_rules_` | array of object | 选填 | - | 配置特定路由或域名的访问权限列表，用于对请求进行鉴权 |
插件执行阶段：`认证阶段`
插件执行优先级：`310`
## 配置字段
**注意：**
- 在一个规则里，鉴权配置和认证配置不可同时存在
- 对于通过认证鉴权的请求，请求的header会被添加一个`X-Mse-Consumer`字段，用以标识调用者的名称。
### 认证配置
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
| ----------- | --------------- | ------------------------------------------- | ------ | ----------------------------------------------------------- |
| `global_auth` | bool | 选填（**仅实例级别配置**） | - | 只能在实例级别配置，若配置为true，则全局生效认证机制; 若配置为false，则只对做了配置的域名和路由生效认证机制，若不配置则仅当没有域名和路由配置时全局生效（兼容老用户使用习惯）。 |
| `consumers` | array of object | 必填 | - | 配置服务的调用者，用于对请求进行认证 |
| `keys` | array of string | 必填 | - | API Key 的来源字段名称，可以是 URL 参数或者 HTTP 请求头名称 |
| `in_query` | bool | `in_query` 和 `in_header` 至少有一个为 true | true | 配置 true 时，网关会尝试从 URL 参数中解析 API Key |
| `in_header` | bool | `in_query` 和 `in_header` 至少有一个为 true | true | 配置 true 时，网关会尝试从 HTTP 请求头中解析 API Key |
`consumers`中每一项的配置字段说明如下：
@@ -18,25 +35,22 @@
| `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名称 |
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
| ----------- | --------------- | ------------------------------------------- | ------ | ----------------------------------------------------------- |
| `allow` | array of string | 选填(**非实例级别配置**) | - | 只能在路由或域名等细粒度规则上配置，对于符合匹配条件的请求，配置允许访问的 consumer，从而实现细粒度的权限控制 |
**注意：**
- 若不配置`_rules_`字段，则默认对当前网关实例的所有路由开启认证；
- 对于通过认证鉴权的请求，请求的header会被添加一个`X-Mse-Consumer`字段，用以标识调用者的名称。
## 配置示例
# 配置示例
### 全局配置认证和路由粒度进行鉴权
## 对特定路由或域名开启
以下配置将对网关特定路由或域名开启Key Auth认证和鉴权。credential字段不能重复。
以下配置将对网关特定路由或域名开启 Key Auth 认证和鉴权，注意`credential`字段不能重复
在实例级别做如下插件配置：
```yaml
global_auth: false
consumers:
- credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5
name: consumer1
@@ -44,31 +58,33 @@ consumers:
name: consumer2
keys:
- apikey
in_query: true
# 使用 _rules_ 字段进行细粒度规则配置
_rules_:
# 规则一：按路由名称匹配生效
- _match_route_:
- route-a
- route-b
allow:
- consumer1
# 规则二：按域名匹配生效
- _match_domain_:
- "*.example.com"
- test.com
allow:
- consumer2
- x-api-key
```
此例 `_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的调用者访问，其他调用者不被允许访问。
根据该配置，下列请求可以允许访问：
假设以下请求会匹配到route-a这条路由
n
**将 API Key 设置在 url 参数中**
```bash
curl http://xxx.hello.com/test?apikey=2bda943c-ba2b-11ec-ba07-00163e1250b5
@@ -80,7 +96,7 @@ curl http://xxx.hello.com/test -H 'x-api-key: 2bda943c-ba2b-11ec-ba07-00163e125
认证鉴权通过后，请求的header中会被添加一个`X-Mse-Consumer`字段，在此例中其值为`consumer1`，用以标识调用方的名称
### 下列请求将拒绝访问：
下列请求将拒绝访问：
**请求未提供 API Key，返回401**
```bash
@@ -97,11 +113,12 @@ curl http://xxx.hello.com/test?apikey=926d90ac-ba2e-11ec-ab68-00163e1250b5
curl http://xxx.hello.com/test?apikey=c8c8e9ca-558e-4a2d-bb62-e700dcc40e35
```
## 网关实例级别开启
### 网关实例级别开启
以下配置未指定`_rules_`字段，因此将对网关实例级别开启 Key Auth 认证
以下配置将对网关实例级别开启 Basic Auth 认证，所有请求均需要经过认证后才能访问。
```yaml
global_auth: true
consumers:
- credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5
name: consumer1
@@ -109,13 +126,15 @@ consumers:
name: consumer2
keys:
- apikey
in_query: true
- x-api-key
```
# 相关错误码
## 相关错误码
| HTTP 状态码 | 出错信息 | 原因说明 |
| ----------- | --------------------------------------------------------- | ----------------------- |
| 401 | No API key found in request | 请求未提供 API Key |
| 401 | Request denied by Key Auth check. Muti API key found in request | 请求提供多个 API Key |
| 401 | Request denied by Key Auth check. No API key found in request | 请求未提供 API Key |
| 401 | Request denied by Key Auth check. Invalid API key | 不允许当前 API Key 访问 |
| 403 | Request denied by Basic Auth check. Unauthorized consumer | 请求的调用方无访问权限 |
| 403 | Request denied by Key Auth check. Unauthorized consumer | 请求的调用方无访问权限 |

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

@@ -1,43 +1,47 @@
# Features
The `key-auth` plug-in implements the authentication function based on the API Key, supports parsing the API Key from the URL parameter or request header of the HTTP request, and verifies whether the API Key has permission to access.
---
title: Key Authentication
keywords: [higress,key auth]
description: Key Authentication Plugin Configuration Reference
---
## Function Description
The `key-auth` plugin implements authentication based on API Key, supporting the parsing of the API Key from HTTP request URL parameters or request headers, while also verifying whether the API Key has permission to access the resource.
# Configuration field
## Runtime Properties
Plugin Execution Phase: `Authentication Phase`
Plugin Execution Priority: `310`
| Name | Data Type | Parameter requirements | Default| Description |
| ----------- | --------------- | -------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------- |
| `consumers` | array of object | Required | - | Configure the caller of the service to authenticate the request. |
| `keys` | array of string | Required | - | The name of the source field of the API Key, which can be a URL parameter or an HTTP request header name. |
| `in_query` | bool | At least one of `in_query` and `in_header` must be true. | true | When configured true, the gateway will try to parse the API Key from the URL parameters. |
| `in_header` | bool | The same as above. | true | The same as above. |
| `_rules_` | array of object | Optional | - | Configure the access list of a specific route or domain name for authenticating requests. |
## Configuration Fields
**Note:**
- Authentication and authorization configurations cannot coexist within a single rule.
- For requests that are authenticated, a header field `X-Mse-Consumer` will be added to identify the caller's name.
### Authentication Configuration
| Name | Data Type | Requirements | Default Value | Description |
| ------------- | ---------------- | ----------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `global_auth` | bool | Optional (**Instance-Level Configuration Only**) | - | Can only be configured at the instance level; if set to true, the authentication mechanism takes effect globally; if set to false, it only applies to the configured hostnames and routes. If not configured, it will only take effect globally when no hostname and route configurations are present (to maintain compatibility with older user habits). |
| `consumers` | array of object | Required | - | Configures the service callers for request authentication. |
| `keys` | array of string | Required | - | Source field names for the API Key, which can be URL parameters or HTTP request header names. |
| `in_query` | bool | At least one of `in_query` and `in_header` must be true | true | When configured as true, the gateway will attempt to parse the API Key from URL parameters. |
| `in_header` | bool | At least one of `in_query` and `in_header` must be true | true | When configured as true, the gateway will attempt to parse the API Key from HTTP request headers. |
The configuration fields of each item in `consumers` are described as follows:
The configuration field descriptions for each item in `consumers` are as follows:
| Name | Data Type | Requirements | Default Value | Description |
| ------------ | --------- | ------------ | ------------- | ------------------------------ |
| `credential` | string | Required | - | Configures the access credential for this consumer. |
| `name` | string | Required | - | Configures the name for this consumer. |
| Name | Data Type | Parameter requirements | Default | Description |
| ------------ | --------- | -----------------------| ------ | ------------------------------------------- |
| `credential` | string | Required | - | Configure the consumer's access credentials. |
| `name` | string | Required | - | Configure the name of the consumer. |
### Authorization Configuration (Optional)
| Name | Data Type | Requirements | Default Value | Description |
| ----------- | ---------------- | ----------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allow` | array of string | Optional (**Non-Instance Level Configuration**) | - | Can only be configured on fine-grained rules such as routes or hostnames; specifies the allowed consumers for matching requests, allowing for fine-grained permission control. |
The configuration fields of each item in `_rules_` are described as follows:
| Name | Data Type | Parameter requirements | Default| Description |
| ---------------- | --------------- | --------------------------------------------------------------------- | ------ | -------------------------------------------------- |
| `_match_route_` | array of string | Optional，Optionally fill in one of `_match_route_`, `_match_domain_`. | - | Configure the route name to match. |
| `_match_domain_` | array of string | Optional，Optionally fill in one of `_match_route_`, `_match_domain_`. | - | Configure the domain name to match. |
| `allow` | array of string | Required | - | For requests that meet the matching conditions, configure the name of the consumer that is allowed to access. |
**Warning：**
- If the `_rules_` field is not configured, authentication will be enabled for all routes of the current gateway instance by default;
- For a request that passes authentication, an `X-Mse-Consumer` field will be added to the request header to identify the name of the caller.
# Example configuration
## Enabled for specific routes or domains
The following configuration will enable Key Auth authentication and authentication for gateway-specific routes or domain names. Note that the `credential` field can not be repeated.
## Configuration Example
### Global Configuration for Authentication and Granular Route Authorization
The following configuration will enable Key Auth authentication and authorization for specific routes or hostnames in the gateway. The `credential` field must not repeat.
At the instance level, do the following plugin configuration:
```yaml
global_auth: false
consumers:
- credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5
name: consumer1
@@ -45,64 +49,63 @@ consumers:
name: consumer2
keys:
- apikey
in_query: true
# Use the _rules_ field for fine-grained rule configuration
_rules_:
# Rule 1: Match by route name to take effect
- _match_route_:
- route-a
- route-b
allow:
- consumer1
# Rule 2: Take effect by domain name matching
- _match_domain_:
- "*.example.com"
- test.com
allow:
- consumer2
- x-api-key
```
The `route-a` and `route-b` specified in `_match_route_` in this example are the route names filled in when creating the gateway route. When these two routes are matched, calls whose `name` is `consumer1` will be allowed Access by callers, other callers are not allowed to access;
For routes route-a and route-b, do the following configuration:
```yaml
allow:
- consumer1
```
`*.example.com` and `test.com` specified in `_match_domain_` in this example are used to match the domain name of the request. When the domain name matches, the caller whose `name` is `consumer2` will be allowed to access, and other calls access is not allowed.
For the hostnames *.example.com and test.com, do the following configuration:
```yaml
allow:
- consumer2
```
### Depending on this configuration, the following requests would allow access：
**Note:**
The routes route-a and route-b specified in this example refer to the route names filled in when creating the gateway routes. When matched with these two routes, requests from the caller named consumer1 will be allowed while others will be denied.
Assume that the following request will match the route-a route:
The specified hostnames *.example.com and test.com are used to match the request's domain name. When a domain name is matched, callers named consumer2 will be allowed while others will be denied.
**Set the API Key in the url parameter**
Based on this configuration, the following requests will be allowed:
Assuming the following request matches route-a:
**Setting API Key in URL Parameters**
```bash
curl http://xxx.hello.com/test?apikey=2bda943c-ba2b-11ec-ba07-00163e1250b5
```
**Set the API Key in the http request header**
**Setting API Key in HTTP Request Headers**
```bash
curl http://xxx.hello.com/test -H 'x-api-key: 2bda943c-ba2b-11ec-ba07-00163e1250b5'
```
After the authentication is passed, an `X-Mse-Consumer` field will be added to the header of the request. In this example, its value is `consumer1`, which is used to identify the name of the caller.
After successful authentication and authorization, the request's header will have an added `X-Mse-Consumer` field with the value `consumer1`, to identify the name of the caller.
### The following requests will deny access：
**The request does not provide an API Key, return 401**
The following requests will be denied access:
**Request without an API Key returns 401**
```bash
curl http://xxx.hello.com/test
```
**The API Key provided by the request is not authorized to access, return 401**
**Request with an invalid API Key returns 401**
```bash
curl http://xxx.hello.com/test?apikey=926d90ac-ba2e-11ec-ab68-00163e1250b5
```
**The caller matched according to the API Key provided in the request has no access rights, return 403**
**Caller matched with provided API Key has no access rights, returns 403**
```bash
# consumer2 is not in the allow list of route-a
curl http://xxx.hello.com/test?apikey=c8c8e9ca-558e-4a2d-bb62-e700dcc40e35
```
## Gateway instance level enabled
The following configuration does not specify the `_rules_` field, so Key Auth authentication will be enabled at the gateway instance level.
### Enabling at the Instance Level
The following configuration will enable Basic Auth authentication at the instance level for the gateway, requiring all requests to pass authentication before accessing.
```yaml
global_auth: true
consumers:
- credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5
name: consumer1
@@ -110,14 +113,13 @@ consumers:
name: consumer2
keys:
- apikey
in_query: true
- x-api-key
```
# Error code
| HTTP status code | Error information | Reason |
| ---------------- | --------------------------------------------------------- | -------------------------------------------- |
| 401 | No API key found in request. | API not provided by request Key. |
| 401 | Request denied by Key Auth check. Invalid API key. | Current API Key access is not allowed. |
| 403 | Request denied by Basic Auth check. Unauthorized consumer. | The requested caller does not have access. |
## Related Error Codes
| HTTP Status Code | Error Message | Reason Explanation |
| ---------------- | ---------------------------------------------------------- | --------------------------------- |
| 401 | Request denied by Key Auth check. Multiple API keys found in request | Multiple API Keys provided in the request. |
| 401 | Request denied by Key Auth check. No API key found in request | API Key not provided in the request. |
| 401 | Request denied by Key Auth check. Invalid API key | The current API Key is not authorized for access. |
| 403 | Request denied by Key Auth check. Unauthorized consumer | The caller does not have access permissions. |