mirror of
https://github.com/alibaba/higress.git
synced 2026-05-30 15:47:28 +08:00
update plugins doc (#1305)
This commit is contained in:
澄潭
GitHub
@@ -1,31 +1,108 @@
|
||||
# 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 |
|
||||
| ----------- | --------------- | -------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------- |
|
||||
| `global_auth` | bool | Optional | - | If configured to true, the authentication mechanism will take effect globally; if configured to false, the authentication mechanism will only take effect for the configured domain names and routes; if not configured, the authentication mechanism will only take effect globally when no domain names and routes are configured (compatibility mechanism) |
|
||||
| `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. |
|
||||
## 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.
|
||||
|
||||
The configuration fields of each item in `consumers` are described as follows:
|
||||
### 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. |
|
||||
|
||||
| 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. |
|
||||
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. |
|
||||
|
||||
**Warning：**
|
||||
- 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.
|
||||
### 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. |
|
||||
|
||||
# Example configuration
|
||||
## 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.
|
||||
|
||||
## Enabled for specific routes or domains
|
||||
At the instance level, do the following plugin configuration:
|
||||
```yaml
|
||||
global_auth: false
|
||||
consumers:
|
||||
- credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5
|
||||
name: consumer1
|
||||
- credential: c8c8e9ca-558e-4a2d-bb62-e700dcc40e35
|
||||
name: consumer2
|
||||
keys:
|
||||
- apikey
|
||||
- x-api-key
|
||||
```
|
||||
|
||||
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.
|
||||
For routes route-a and route-b, do the following configuration:
|
||||
```yaml
|
||||
allow:
|
||||
- consumer1
|
||||
```
|
||||
|
||||
For the hostnames *.example.com and test.com, do the following configuration:
|
||||
```yaml
|
||||
allow:
|
||||
- consumer2
|
||||
```
|
||||
|
||||
**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.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
**Setting API Key in HTTP Request Headers**
|
||||
```bash
|
||||
curl http://xxx.hello.com/test -H 'x-api-key: 2bda943c-ba2b-11ec-ba07-00163e1250b5'
|
||||
```
|
||||
|
||||
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 be denied access:
|
||||
**Request without an API Key returns 401**
|
||||
```bash
|
||||
curl http://xxx.hello.com/test
|
||||
```
|
||||
|
||||
**Request with an invalid API Key returns 401**
|
||||
```bash
|
||||
curl http://xxx.hello.com/test?apikey=926d90ac-ba2e-11ec-ab68-00163e1250b5
|
||||
```
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
### 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
|
||||
@@ -37,73 +114,12 @@ consumers:
|
||||
keys:
|
||||
- apikey
|
||||
- x-api-key
|
||||
in_query: true
|
||||
```
|
||||
|
||||
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;
|
||||
|
||||
`*.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.
|
||||
|
||||
### Depending on this configuration, the following requests would allow access：
|
||||
|
||||
Assume that the following request will match the route-a route:
|
||||
|
||||
**Set the API Key in the url parameter**
|
||||
```bash
|
||||
curl http://xxx.hello.com/test?apikey=2bda943c-ba2b-11ec-ba07-00163e1250b5
|
||||
```
|
||||
**Set the API Key in the http request header**
|
||||
```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.
|
||||
|
||||
### The following requests will deny access：
|
||||
|
||||
**The request does not provide an API Key, return 401**
|
||||
```bash
|
||||
curl http://xxx.hello.com/test
|
||||
```
|
||||
**The API Key provided by the request is not authorized to access, return 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**
|
||||
```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 `matchRules` field, so Key Auth authentication will be enabled at the gateway instance level.
|
||||
|
||||
```yaml
|
||||
consumers:
|
||||
- credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5
|
||||
name: consumer1
|
||||
- credential: c8c8e9ca-558e-4a2d-bb62-e700dcc40e35
|
||||
name: consumer2
|
||||
keys:
|
||||
- apikey
|
||||
in_query: true
|
||||
```
|
||||
|
||||
configuration specify the `matchRules` field, like：
|
||||
```yaml
|
||||
matchRules:
|
||||
- config:
|
||||
allow:
|
||||
- consumer1
|
||||
```
|
||||
|
||||
# Error code
|
||||
|
||||
| HTTP status code | Error information | Reason |
|
||||
| ---------------- | --------------------------------------------------------- | -------------------------------------------- |
|
||||
| 401 | Muti API key found in request. | Muti API provided by request Key. |
|
||||
| 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 Key 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. |
|
||||
|
||||
Reference in New Issue
Block a user