This is an automated email from the ASF dual-hosted git repository.
Baoyuantop pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 46773fec2 docs(key-auth): re-port with Admin API, ADC, and Ingress
Controller tabs (#13241)
46773fec2 is described below
commit 46773fec2fd62ea0b3195615a4e663ba3e357b23
Author: Yilia Lin <[email protected]>
AuthorDate: Thu Apr 23 15:24:04 2026 +0800
docs(key-auth): re-port with Admin API, ADC, and Ingress Controller tabs
(#13241)
---
docs/en/latest/plugins/key-auth.md | 999 +++++++++++++++++++++++++++++++++++--
docs/zh/latest/plugins/jwt-auth.md | 2 +-
docs/zh/latest/plugins/key-auth.md | 998 ++++++++++++++++++++++++++++++++++--
3 files changed, 1941 insertions(+), 58 deletions(-)
diff --git a/docs/en/latest/plugins/key-auth.md
b/docs/en/latest/plugins/key-auth.md
index 8a7d7aa1a..5d7df8cae 100644
--- a/docs/en/latest/plugins/key-auth.md
+++ b/docs/en/latest/plugins/key-auth.md
@@ -32,33 +32,34 @@ description: The key-auth Plugin supports the use of an
authentication key as a
<link rel="canonical" href="https://docs.api7.ai/hub/key-auth"; />
</head>
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## Description
The `key-auth` Plugin supports the use of an authentication key as a mechanism
for clients to authenticate themselves before accessing Upstream resources.
-To use the plugin, you would configure authentication keys on
[Consumers](../terminology/consumer.md) and enable the Plugin on routes or
services. The key can be included in the request URL query string or request
header. APISIX will then verify the key to determine if a request should be
allowed or denied to access Upstream resources.
+To use the Plugin, you would configure authentication keys on
[Consumers](../terminology/consumer.md) and enable the Plugin on Routes or
Services. The key can be included in the request URL query string or request
header. APISIX will then verify the key to determine if a request should be
allowed or denied to access Upstream resources.
-When a Consumer is successfully authenticated, APISIX adds additional headers,
such as `X-Consumer-Username`, `X-Credential-Indentifier`, and other Consumer
custom headers if configured, to the request, before proxying it to the
Upstream service. The Upstream service will be able to differentiate between
consumers and implement additional logics as needed. If any of these values is
not available, the corresponding header will not be added.
+When a Consumer is successfully authenticated, APISIX adds additional headers,
such as `X-Consumer-Username`, `X-Credential-Identifier`, and other Consumer
custom headers if configured, to the request, before proxying it to the
Upstream service. The Upstream service will be able to differentiate between
consumers and implement additional logic as needed. If any of these values is
not available, the corresponding header will not be added.
## Attributes
For Consumer/Credential:
-| Name | Type | Required | Description |
-|------|--------|-------------|----------------------------|
-| key | string | True | Unique key for a Consumer. This field supports
saving the value in Secret Manager using the [APISIX
Secret](../terminology/secret.md) resource. |
-
-NOTE: `encrypt_fields = {"key"}` is also defined in the schema, which means
that the field will be stored encrypted in etcd. See [encrypted storage
fields](../plugin-develop.md#encrypted-storage-fields).
+| Name | Type | Required | Default | Valid values | Description |
+|------|------|----------|---------|--------------|-------------|
+| key | string | True | | | A unique key that identifies the Credential for a
Consumer. When `apisix.data_encryption.enable_encrypt_fields` is enabled and
the configuration is stored in etcd, the key is encrypted with AES before
storage. You can also store it in an environment variable and reference it
using the `$env://` prefix, or in a secret manager such as HashiCorp Vault's KV
secrets engine, and reference it using the `$secret://` prefix. |
For Route:
-| Name | Type | Required | Default | Description
|
-|--------|--------|-------------|-------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| header | string | False | apikey | The header to get the key from.
|
-| query | string | False | apikey | The query string to get the key from.
Lower priority than header.
|
-| hide_credentials | boolean | False | false | If true, do not pass the
header or query string with key to Upstream services. |
-| anonymous_consumer | string | False | false | Anonymous Consumer name.
If configured, allow anonymous users to bypass the authentication. |
-| realm | string | False | key | The realm to include in
the `WWW-Authenticate` header when authentication fails. |
+| Name | Type | Required | Default | Valid values | Description |
+|------|------|----------|---------|--------------|-------------|
+| header | string | False | apikey | | The header to get the key from. |
+| query | string | False | apikey | | The query string to get the key from.
Lower priority than `header`. |
+| hide_credentials | boolean | False | false | | If true, do not pass the
header or query string with key to Upstream services. |
+| anonymous_consumer | string | False | | | Anonymous Consumer name. If
configured, allow anonymous users to bypass the authentication. |
+| realm | string | False | key | | Realm in the
[`WWW-Authenticate`](https://datatracker.ietf.org/doc/html/rfc7235#section-4.1)
response header returned with a `401 Unauthorized` response due to
authentication failure. Available in Apache APISIX version 3.15.0 and later. |
## Examples
@@ -66,8 +67,6 @@ The examples below demonstrate how you can work with the
`key-auth` Plugin for d
:::note
-You can fetch the `admin_key` from `config.yaml` and save to an environment
variable with the following command:
-
```bash
admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed
's/"//g')
```
@@ -76,7 +75,18 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
### Implement Key Authentication on Route
-The following example demonstrates how to implement key authentications on a
Route and include the key in the request header.
+The following example demonstrates how to implement key authentication on a
Route and include the key in the request header.
+
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
Create a Consumer `jack`:
@@ -123,9 +133,188 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+Create a Consumer with `key-auth` Credential and a Route with `key-auth`
Plugin configured:
+
+```yaml title="adc.yaml"
+consumers:
+ - username: jack
+ credentials:
+ - name: key-auth
+ type: key-auth
+ config:
+ key: jack-key
+services:
+ - name: key-auth-service
+ routes:
+ - name: key-auth-route
+ uris:
+ - /anything
+ plugins:
+ key-auth: {}
+ upstream:
+ type: roundrobin
+ nodes:
+ - host: httpbin.org
+ port: 80
+ weight: 1
+```
+
+Synchronize the configuration to the gateway:
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+Create a Consumer with `key-auth` Credential and a Route with `key-auth`
Plugin configured:
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX Ingress Controller', value: 'apisix-ingress-controller'}
+]}>
+
+<TabItem value="gateway-api">
+
+```yaml title="key-auth-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: Consumer
+metadata:
+ namespace: aic
+ name: jack
+spec:
+ gatewayRef:
+ name: apisix
+ credentials:
+ - type: key-auth
+ name: primary-cred
+ config:
+ key: jack-key
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: key-auth-plugin-config
+spec:
+ plugins:
+ - name: key-auth
+ config:
+ _meta:
+ disable: false
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: key-auth-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /anything
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: key-auth-plugin-config
+ backendRefs:
+ - name: httpbin-external-domain
+ port: 80
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-ingress-controller">
+
+```yaml title="key-auth-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixConsumer
+metadata:
+ namespace: aic
+ name: jack
+spec:
+ ingressClassName: apisix
+ authParameter:
+ keyAuth:
+ value:
+ key: jack-key
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: key-auth-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: key-auth-route
+ match:
+ paths:
+ - /anything
+ upstreams:
+ - name: httpbin-external-domain
+ plugins:
+ - name: key-auth
+ enable: true
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
#### Verify with a Valid Key
-Send a request to with the valid key:
+Send a request to the Route with the valid key:
```shell
curl -i "http://127.0.0.1:9080/anything"; -H 'apikey: jack-key'
@@ -149,7 +338,7 @@ You should see an `HTTP/1.1 401 Unauthorized` response with
the following:
#### Verify without a Key
-Send a request to without a key:
+Send a request to the Route without a key:
```shell
curl -i "http://127.0.0.1:9080/anything";
@@ -163,7 +352,18 @@ You should see an `HTTP/1.1 401 Unauthorized` response
with the following:
### Hide Authentication Information From Upstream
-The following example demonstrates how to prevent the key from being sent to
the Upstream services by configuring `hide_credentials`. By default, the
authentication key is forwarded to the Upstream services, which might lead to
security risks in some circumstances.
+The following example first demonstrates the default behavior, where the
authentication key is forwarded to the Upstream services, and then shows how to
prevent the key from being sent by configuring `hide_credentials`. Forwarding
the authentication key to Upstream services might lead to security risks in
some circumstances.
+
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
Create a Consumer `jack`:
@@ -214,6 +414,189 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+Create a Consumer with `key-auth` Credential and a Route with `key-auth`
Plugin configured:
+
+```yaml title="adc.yaml"
+consumers:
+ - username: jack
+ credentials:
+ - name: key-auth
+ type: key-auth
+ config:
+ key: jack-key
+services:
+ - name: key-auth-service
+ routes:
+ - name: key-auth-route
+ uris:
+ - /anything
+ plugins:
+ key-auth:
+ hide_credentials: false
+ upstream:
+ type: roundrobin
+ nodes:
+ - host: httpbin.org
+ port: 80
+ weight: 1
+```
+
+Synchronize the configuration to the gateway:
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+Create a Consumer with `key-auth` Credential and a Route with `key-auth`
Plugin configured:
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX Ingress Controller', value: 'apisix-ingress-controller'}
+]}>
+
+<TabItem value="gateway-api">
+
+```yaml title="key-auth-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: Consumer
+metadata:
+ namespace: aic
+ name: jack
+spec:
+ gatewayRef:
+ name: apisix
+ credentials:
+ - type: key-auth
+ name: primary-cred
+ config:
+ key: jack-key
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: key-auth-plugin-config
+spec:
+ plugins:
+ - name: key-auth
+ config:
+ _meta:
+ disable: false
+ hide_credentials: false
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: key-auth-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /anything
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: key-auth-plugin-config
+ backendRefs:
+ - name: httpbin-external-domain
+ port: 80
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-ingress-controller">
+
+```yaml title="key-auth-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixConsumer
+metadata:
+ namespace: aic
+ name: jack
+spec:
+ ingressClassName: apisix
+ authParameter:
+ keyAuth:
+ value:
+ key: jack-key
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: key-auth-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: key-auth-route
+ match:
+ paths:
+ - /anything
+ upstreams:
+ - name: httpbin-external-domain
+ plugins:
+ - name: key-auth
+ enable: true
+ config:
+ hide_credentials: false
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
Send a request with the valid key:
```shell
@@ -225,7 +608,7 @@ You should see an `HTTP/1.1 200 OK` response with the
following:
```json
{
"args": {
- "auth": "jack-key"
+ "apikey": "jack-key"
},
"data": "",
"files": {},
@@ -250,7 +633,18 @@ Note that the Credential `jack-key` is visible to the
Upstream service.
#### Hide Credentials
-Update the plugin's `hide_credentials` to `true`:
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
+Update the Plugin's `hide_credentials` to `true`:
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes/key-auth-route"; -X PATCH \
@@ -264,6 +658,119 @@ curl
"http://127.0.0.1:9180/apisix/admin/routes/key-auth-route"; -X PATCH \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+Update the Route configuration:
+
+```yaml title="adc.yaml"
+services:
+ - name: key-auth-service
+ routes:
+ - name: key-auth-route
+ uris:
+ - /anything
+ plugins:
+ key-auth:
+ hide_credentials: true
+ upstream:
+ type: roundrobin
+ nodes:
+ - host: httpbin.org
+ port: 80
+ weight: 1
+```
+
+Synchronize the configuration to the gateway:
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX Ingress Controller', value: 'apisix-ingress-controller'}
+]}>
+
+<TabItem value="gateway-api">
+
+Update the PluginConfig to set `hide_credentials` to `true`:
+
+```yaml title="key-auth-ic.yaml"
+# other configs
+# ---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: key-auth-plugin-config
+spec:
+ plugins:
+ - name: key-auth
+ config:
+ _meta:
+ disable: false
+ hide_credentials: true
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-ingress-controller">
+
+Update the ApisixRoute to set `hide_credentials` to `true`:
+
+```yaml title="key-auth-ic.yaml"
+# other configs
+# ---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: key-auth-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: key-auth-route
+ match:
+ paths:
+ - /anything
+ upstreams:
+ - name: httpbin-external-domain
+ plugins:
+ - name: key-auth
+ enable: true
+ config:
+ hide_credentials: true
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
Send a request with the valid key:
```shell
@@ -300,6 +807,17 @@ Note that the Credential `jack-key` is no longer visible
to the Upstream service
The following example demonstrates how to implement key authentication by
consumers on a Route and customize the URL parameter that should include the
key. The example also shows that when the API key is configured in both the
header and the query string, the request header has a higher priority.
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
Create a Consumer `jack`:
```shell
@@ -347,9 +865,192 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+Create a Consumer with `key-auth` Credential and a Route with `key-auth`
Plugin configured:
+
+```yaml title="adc.yaml"
+consumers:
+ - username: jack
+ credentials:
+ - name: key-auth
+ type: key-auth
+ config:
+ key: jack-key
+services:
+ - name: key-auth-service
+ routes:
+ - name: key-auth-route
+ uris:
+ - /anything
+ plugins:
+ key-auth:
+ query: auth
+ upstream:
+ type: roundrobin
+ nodes:
+ - host: httpbin.org
+ port: 80
+ weight: 1
+```
+
+Synchronize the configuration to the gateway:
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+Create a Consumer with `key-auth` Credential and a Route with `key-auth`
Plugin configured:
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX Ingress Controller', value: 'apisix-ingress-controller'}
+]}>
+
+<TabItem value="gateway-api">
+
+```yaml title="key-auth-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: Consumer
+metadata:
+ namespace: aic
+ name: jack
+spec:
+ gatewayRef:
+ name: apisix
+ credentials:
+ - type: key-auth
+ name: primary-cred
+ config:
+ key: jack-key
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: key-auth-plugin-config
+spec:
+ plugins:
+ - name: key-auth
+ config:
+ _meta:
+ disable: false
+ query: auth
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: key-auth-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /anything
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: key-auth-plugin-config
+ backendRefs:
+ - name: httpbin-external-domain
+ port: 80
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-ingress-controller">
+
+```yaml title="key-auth-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixConsumer
+metadata:
+ namespace: aic
+ name: jack
+spec:
+ ingressClassName: apisix
+ authParameter:
+ keyAuth:
+ value:
+ key: jack-key
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: key-auth-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: key-auth-route
+ match:
+ paths:
+ - /anything
+ upstreams:
+ - name: httpbin-external-domain
+ plugins:
+ - name: key-auth
+ enable: true
+ config:
+ query: auth
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
#### Verify with a Valid Key
-Send a request to with the valid key:
+Send a request to the Route with the valid key:
```shell
curl -i "http://127.0.0.1:9080/anything?auth=jack-key";
@@ -383,7 +1084,18 @@ You should see an `HTTP/1.1 200 OK` response. This shows
that the key included i
### Add Consumer Custom ID to Header
-The following example demonstrates how you can attach a Consumer custom ID to
authenticated request in the `Consumer-Custom-Id` header, which can be used to
implement additional logics as needed.
+The following example demonstrates how you can attach a Consumer custom ID to
authenticated request in the `X-Consumer-Custom-Id` header, which can be used
to implement additional logic as needed.
+
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
Create a Consumer `jack` with a custom ID label:
@@ -433,10 +1145,58 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+Create a Consumer with `key-auth` Credential and a Route with `key-auth`
Plugin enabled:
+
+```yaml title="adc.yaml"
+consumers:
+ - username: jack
+ labels:
+ custom_id: "495aec6a"
+ credentials:
+ - name: key-auth
+ type: key-auth
+ config:
+ key: jack-key
+services:
+ - name: key-auth-service
+ routes:
+ - name: key-auth-route
+ uris:
+ - /anything
+ plugins:
+ key-auth: {}
+ upstream:
+ type: roundrobin
+ nodes:
+ - host: httpbin.org
+ port: 80
+ weight: 1
+```
+
+Synchronize the configuration to the gateway:
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+Consumer custom labels are currently not supported when configuring resources
through the Ingress Controller, and the `X-Consumer-Custom-Id` header is not
included in requests. At the moment, this example cannot be completed with the
Ingress Controller.
+
+</TabItem>
+
+</Tabs>
+
To verify, send a request to the Route with the valid key:
```shell
-curl -i "http://127.0.0.1:9080/anything?auth=jack-key";
+curl -i "http://127.0.0.1:9080/anything?apikey=jack-key";
```
You should see an `HTTP/1.1 200 OK` response similar to the following:
@@ -444,7 +1204,7 @@ You should see an `HTTP/1.1 200 OK` response similar to
the following:
```json
{
"args": {
- "auth": "jack-key"
+ "apikey": "jack-key"
},
"data": "",
"files": {},
@@ -468,7 +1228,18 @@ You should see an `HTTP/1.1 200 OK` response similar to
the following:
### Rate Limit with Anonymous Consumer
-The following example demonstrates how you can configure different rate
limiting policies by regular and anonymous consumers, where the anonymous
Consumer does not need to authenticate and has less quotas.
+The following example demonstrates how you can configure different rate
limiting policies by regular and anonymous consumers, where the anonymous
Consumer does not need to authenticate and has less quota.
+
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
Create a regular Consumer `jack` and configure the `limit-count` Plugin to
allow for a quota of 3 within a 30-second window:
@@ -481,7 +1252,8 @@ curl "http://127.0.0.1:9180/apisix/admin/consumers"; -X PUT
\
"limit-count": {
"count": 3,
"time_window": 30,
- "rejected_code": 429
+ "rejected_code": 429,
+ "policy": "local"
}
}
}'
@@ -513,7 +1285,8 @@ curl "http://127.0.0.1:9180/apisix/admin/consumers"; -X PUT
\
"limit-count": {
"count": 1,
"time_window": 30,
- "rejected_code": 429
+ "rejected_code": 429,
+ "policy": "local"
}
}
}'
@@ -541,6 +1314,174 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+Configure Consumers with different rate limits and a Route that accepts
anonymous users:
+
+```yaml title="adc.yaml"
+consumers:
+ - username: jack
+ plugins:
+ limit-count:
+ count: 3
+ time_window: 30
+ rejected_code: 429
+ policy: local
+ credentials:
+ - name: key-auth
+ type: key-auth
+ config:
+ key: jack-key
+ - username: anonymous
+ plugins:
+ limit-count:
+ count: 1
+ time_window: 30
+ rejected_code: 429
+ policy: local
+services:
+ - name: anonymous-rate-limit-service
+ routes:
+ - name: key-auth-route
+ uris:
+ - /anything
+ plugins:
+ key-auth:
+ anonymous_consumer: anonymous
+ upstream:
+ type: roundrobin
+ nodes:
+ - host: httpbin.org
+ port: 80
+ weight: 1
+```
+
+Synchronize the configuration to the gateway:
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX Ingress Controller', value: 'apisix-ingress-controller'}
+]}>
+
+<TabItem value="gateway-api">
+
+Configure Consumers with different rate limits and a Route that accepts
anonymous users:
+
+```yaml title="key-auth-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: Consumer
+metadata:
+ namespace: aic
+ name: jack
+spec:
+ gatewayRef:
+ name: apisix
+ credentials:
+ - type: key-auth
+ name: primary-key
+ config:
+ key: jack-key
+ plugins:
+ - name: limit-count
+ config:
+ count: 3
+ time_window: 30
+ rejected_code: 429
+ policy: local
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: Consumer
+metadata:
+ namespace: aic
+ name: anonymous
+spec:
+ gatewayRef:
+ name: apisix
+ plugins:
+ - name: limit-count
+ config:
+ count: 1
+ time_window: 30
+ rejected_code: 429
+ policy: local
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: key-auth-plugin-config
+spec:
+ plugins:
+ - name: key-auth
+ config:
+ anonymous_consumer: aic_anonymous # namespace_consumername
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: key-auth-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /anything
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: key-auth-plugin-config
+ backendRefs:
+ - name: httpbin-external-domain
+ port: 80
+```
+
+Apply the configuration to your cluster:
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-ingress-controller">
+
+The ApisixConsumer CRD currently does not support configuring plugins on
consumers, except for the authentication plugins allowed in `authParameter`.
This example cannot be completed with APISIX CRDs.
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
To verify, send five consecutive requests with `jack`'s key:
```shell
diff --git a/docs/zh/latest/plugins/jwt-auth.md
b/docs/zh/latest/plugins/jwt-auth.md
index fb7bbe35c..498cec4df 100644
--- a/docs/zh/latest/plugins/jwt-auth.md
+++ b/docs/zh/latest/plugins/jwt-auth.md
@@ -1225,7 +1225,7 @@ values={[
{label: 'Ingress Controller', value: 'ingress'}
]}>
-<TabItem value="dashboard">
+以下示例演示了如何在 `X-Consumer-Custom-Id` 标头中将消费者自定义 ID 附加到已验证的请求，该 ID 可用于根据需要实现其他逻辑。
创建带有自定义 ID 标签的消费者 `jack`：
diff --git a/docs/zh/latest/plugins/key-auth.md
b/docs/zh/latest/plugins/key-auth.md
index c693e750f..7944cf412 100644
--- a/docs/zh/latest/plugins/key-auth.md
+++ b/docs/zh/latest/plugins/key-auth.md
@@ -32,32 +32,34 @@ description: key-auth 插件支持使用身份验证密钥作为客户端在访
<link rel="canonical" href="https://docs.api7.ai/hub/key-auth"; />
</head>
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## 描述
`key-auth` 插件支持使用身份验证密钥作为客户端在访问上游资源之前进行身份验证的机制。
-要使用该插件，你需要在 [Consumers](../terminology/consumer.md)
上配置身份验证密钥，并在路由或服务上启用该插件。密钥可以包含在请求 URL 查询字符串或请求标头中。然后，APISIX
将验证密钥以确定是否应允许或拒绝请求访问上游资源。
+要使用该插件，你需要在[消费者](../terminology/consumer.md)上配置身份验证密钥，并在路由或服务上启用该插件。密钥可以包含在请求
URL 查询字符串或请求标头中。APISIX 将验证密钥以确定是否应允许或拒绝请求访问上游资源。
-当消费者成功通过身份验证后，APISIX 会在将请求代理到上游服务之前向请求添加其他标头，例如
`X-Consumer-Username`、`X-Credential-Indentifier`
和其他消费者自定义标头（如果已配置）。上游服务将能够区分消费者并根据需要实现其他逻辑。如果这些值中的任何一个不可用，则不会添加相应的标头。
+当消费者成功通过身份验证后，APISIX 会在将请求代理到上游服务之前向请求添加其他标头，例如
`X-Consumer-Username`、`X-Credential-Identifier`
和其他消费者自定义标头（如果已配置）。上游服务将能够区分消费者并根据需要实现其他逻辑。如果这些值中的任何一个不可用，则不会添加相应的标头。
## 属性
消费者/凭证端：
-| 名称 | 类型 | 必选项 | 描述
|
-| ---- | ------ | ------ |
-------------------------------------------------------------------------------------------------------------
|
-| key | string | 是 | 不同的消费者应有不同的 `key`，它应当是唯一的。如果多个消费者使用了相同的
`key`，将会出现请求匹配异常。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源，将值保存在
Secret Manager 中。 |
-
-注意：schema 中还定义了 `encrypt_fields = {"key"}`，这意味着该字段将会被加密存储在 etcd 中。具体参考
[加密存储字段](../plugin-develop.md#加密存储字段)。
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------|------|--------|--------|--------|------|
+| key | string | 是 | | | 标识消费者凭证的唯一密钥。使用 etcd 作为配置中心且开启
`apisix.data_encryption.enable_encrypt_fields` 时，密钥在存储到 etcd 之前会使用 AES
加密。你也可以将其存储在环境变量中并使用 `$env://` 前缀引用，或存储在 HashiCorp Vault 等密钥管理器中并使用
`$secret://` 前缀引用。 |
路由端：
-| 名称 | 类型 | 必选项 | 默认值 | 描述
|
-| ----------------- | ------ | ----- | ------
|----------------------------------------------------------------------------------------------------------------------------------------------------------|
-| header | string | 否 | apikey | 设置我们从哪个 header 获取 key。
|
-| query | string | 否 | apikey | 设置我们从哪个 query string 获取
key，优先级低于 `header`。
|
-| hide_credentials | boolean | 否 | false | 如果为 `true`，则不要将含有认证信息的 header
或 query string 传递给上游。 |
-| realm | string | 否 | key |在身份验证失败时，应包含在 `WWW-Authenticate` 标头中的域。|
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------|------|--------|--------|--------|------|
+| header | string | 否 | apikey | | 获取密钥的请求标头名称。 |
+| query | string | 否 | apikey | | 获取密钥的查询字符串参数名称，优先级低于 `header`。 |
+| hide_credentials | boolean | 否 | false | | 若为
`true`，则不将含有认证信息的标头或查询字符串传递给上游服务。 |
+| anonymous_consumer | string | 否 | | | 匿名消费者名称。如果已配置，则允许匿名用户绕过身份验证。 |
+| realm | string | 否 | key | | 在身份验证失败时，`401 Unauthorized` 响应中
[`WWW-Authenticate`](https://datatracker.ietf.org/doc/html/rfc7235#section-4.1)
标头的域值。该参数在 Apache APISIX 3.15.0 及以上版本中可用。 |
## 示例
@@ -65,8 +67,6 @@ description: key-auth 插件支持使用身份验证密钥作为客户端在访
:::note
-你可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
-
```bash
admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed
's/"//g')
```
@@ -77,6 +77,17 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
以下示例演示如何在路由上实现密钥认证并将密钥包含在请求标头中。
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
创建一个消费者 `jack`：
```shell
@@ -122,9 +133,188 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+创建带有 `key-auth` 凭证的消费者以及配置了 `key-auth` 插件的路由：
+
+```yaml title="adc.yaml"
+consumers:
+ - username: jack
+ credentials:
+ - name: key-auth
+ type: key-auth
+ config:
+ key: jack-key
+services:
+ - name: key-auth-service
+ routes:
+ - name: key-auth-route
+ uris:
+ - /anything
+ plugins:
+ key-auth: {}
+ upstream:
+ type: roundrobin
+ nodes:
+ - host: httpbin.org
+ port: 80
+ weight: 1
+```
+
+将配置同步到网关：
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+创建带有 `key-auth` 凭证的消费者以及配置了 `key-auth` 插件的路由：
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX Ingress Controller', value: 'apisix-ingress-controller'}
+]}>
+
+<TabItem value="gateway-api">
+
+```yaml title="key-auth-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: Consumer
+metadata:
+ namespace: aic
+ name: jack
+spec:
+ gatewayRef:
+ name: apisix
+ credentials:
+ - type: key-auth
+ name: primary-cred
+ config:
+ key: jack-key
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: key-auth-plugin-config
+spec:
+ plugins:
+ - name: key-auth
+ config:
+ _meta:
+ disable: false
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: key-auth-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /anything
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: key-auth-plugin-config
+ backendRefs:
+ - name: httpbin-external-domain
+ port: 80
+```
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-ingress-controller">
+
+```yaml title="key-auth-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixConsumer
+metadata:
+ namespace: aic
+ name: jack
+spec:
+ ingressClassName: apisix
+ authParameter:
+ keyAuth:
+ value:
+ key: jack-key
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: key-auth-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: key-auth-route
+ match:
+ paths:
+ - /anything
+ upstreams:
+ - name: httpbin-external-domain
+ plugins:
+ - name: key-auth
+ enable: true
+```
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
#### 使用有效密钥进行验证
-使用有效密钥发送请求至：
+使用有效密钥发送请求：
```shell
curl -i "http://127.0.0.1:9080/anything"; -H 'apikey: jack-key'
@@ -162,7 +352,18 @@ curl -i "http://127.0.0.1:9080/anything";
### 隐藏上游的身份验证信息
-以下示例演示如何通过配置 `hide_credentials`
来防止密钥被发送到上游服务。默认情况下，身份验证密钥被转发到上游服务，这在某些情况下可能会导致安全风险。
+以下示例首先演示默认行为（身份验证密钥被转发到上游服务），然后展示如何通过配置 `hide_credentials`
来防止密钥被发送。将身份验证密钥转发到上游服务在某些情况下可能会导致安全风险。
+
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
创建一个消费者 `jack`：
@@ -191,7 +392,7 @@ curl
"http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
#### 不隐藏凭据
-使用 `key-auth` 创建路由，并将 `hide_credentials` 配置为 `false` (默认配置)：
+使用 `key-auth` 创建路由，并将 `hide_credentials` 配置为 `false`（默认配置）：
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
@@ -213,6 +414,189 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+创建带有 `key-auth` 凭证的消费者以及配置了 `key-auth` 插件的路由：
+
+```yaml title="adc.yaml"
+consumers:
+ - username: jack
+ credentials:
+ - name: key-auth
+ type: key-auth
+ config:
+ key: jack-key
+services:
+ - name: key-auth-service
+ routes:
+ - name: key-auth-route
+ uris:
+ - /anything
+ plugins:
+ key-auth:
+ hide_credentials: false
+ upstream:
+ type: roundrobin
+ nodes:
+ - host: httpbin.org
+ port: 80
+ weight: 1
+```
+
+将配置同步到网关：
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+创建带有 `key-auth` 凭证的消费者以及配置了 `key-auth` 插件的路由：
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX Ingress Controller', value: 'apisix-ingress-controller'}
+]}>
+
+<TabItem value="gateway-api">
+
+```yaml title="key-auth-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: Consumer
+metadata:
+ namespace: aic
+ name: jack
+spec:
+ gatewayRef:
+ name: apisix
+ credentials:
+ - type: key-auth
+ name: primary-cred
+ config:
+ key: jack-key
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: key-auth-plugin-config
+spec:
+ plugins:
+ - name: key-auth
+ config:
+ _meta:
+ disable: false
+ hide_credentials: false
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: key-auth-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /anything
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: key-auth-plugin-config
+ backendRefs:
+ - name: httpbin-external-domain
+ port: 80
+```
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-ingress-controller">
+
+```yaml title="key-auth-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixConsumer
+metadata:
+ namespace: aic
+ name: jack
+spec:
+ ingressClassName: apisix
+ authParameter:
+ keyAuth:
+ value:
+ key: jack-key
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: key-auth-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: key-auth-route
+ match:
+ paths:
+ - /anything
+ upstreams:
+ - name: httpbin-external-domain
+ plugins:
+ - name: key-auth
+ enable: true
+ config:
+ hide_credentials: false
+```
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
发送带有有效密钥的请求：
```shell
@@ -224,7 +608,7 @@ curl -i "http://127.0.0.1:9080/anything?apikey=jack-key";
```json
{
"args": {
- "auth": "jack-key"
+ "apikey": "jack-key"
},
"data": "",
"files": {},
@@ -249,6 +633,17 @@ curl -i "http://127.0.0.1:9080/anything?apikey=jack-key";
#### 隐藏凭据
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
将插件的 `hide_credentials` 更新为 `true`：
```shell
@@ -263,6 +658,119 @@ curl
"http://127.0.0.1:9180/apisix/admin/routes/key-auth-route"; -X PATCH \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+更新路由配置：
+
+```yaml title="adc.yaml"
+services:
+ - name: key-auth-service
+ routes:
+ - name: key-auth-route
+ uris:
+ - /anything
+ plugins:
+ key-auth:
+ hide_credentials: true
+ upstream:
+ type: roundrobin
+ nodes:
+ - host: httpbin.org
+ port: 80
+ weight: 1
+```
+
+将配置同步到网关：
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX Ingress Controller', value: 'apisix-ingress-controller'}
+]}>
+
+<TabItem value="gateway-api">
+
+更新 PluginConfig，将 `hide_credentials` 设置为 `true`：
+
+```yaml title="key-auth-ic.yaml"
+# 其他配置
+# ---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: key-auth-plugin-config
+spec:
+ plugins:
+ - name: key-auth
+ config:
+ _meta:
+ disable: false
+ hide_credentials: true
+```
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-ingress-controller">
+
+更新 ApisixRoute，将 `hide_credentials` 设置为 `true`：
+
+```yaml title="key-auth-ic.yaml"
+# 其他配置
+# ---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: key-auth-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: key-auth-route
+ match:
+ paths:
+ - /anything
+ upstreams:
+ - name: httpbin-external-domain
+ plugins:
+ - name: key-auth
+ enable: true
+ config:
+ hide_credentials: true
+```
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
发送带有有效密钥的请求：
```shell
@@ -299,6 +807,17 @@ curl -i "http://127.0.0.1:9080/anything?apikey=jack-key";
以下示例演示了如何在路由上实现消费者的密钥身份验证，并自定义应包含密钥的 URL 参数。该示例还显示，当在标头和查询字符串中都配置了 API
密钥时，请求标头具有更高的优先级。
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
创建消费者 `jack`：
```shell
@@ -346,9 +865,192 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+创建带有 `key-auth` 凭证的消费者以及配置了 `key-auth` 插件的路由：
+
+```yaml title="adc.yaml"
+consumers:
+ - username: jack
+ credentials:
+ - name: key-auth
+ type: key-auth
+ config:
+ key: jack-key
+services:
+ - name: key-auth-service
+ routes:
+ - name: key-auth-route
+ uris:
+ - /anything
+ plugins:
+ key-auth:
+ query: auth
+ upstream:
+ type: roundrobin
+ nodes:
+ - host: httpbin.org
+ port: 80
+ weight: 1
+```
+
+将配置同步到网关：
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+创建带有 `key-auth` 凭证的消费者以及配置了 `key-auth` 插件的路由：
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX Ingress Controller', value: 'apisix-ingress-controller'}
+]}>
+
+<TabItem value="gateway-api">
+
+```yaml title="key-auth-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: Consumer
+metadata:
+ namespace: aic
+ name: jack
+spec:
+ gatewayRef:
+ name: apisix
+ credentials:
+ - type: key-auth
+ name: primary-cred
+ config:
+ key: jack-key
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: key-auth-plugin-config
+spec:
+ plugins:
+ - name: key-auth
+ config:
+ _meta:
+ disable: false
+ query: auth
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: key-auth-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /anything
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: key-auth-plugin-config
+ backendRefs:
+ - name: httpbin-external-domain
+ port: 80
+```
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-ingress-controller">
+
+```yaml title="key-auth-ic.yaml"
+apiVersion: apisix.apache.org/v2
+kind: ApisixConsumer
+metadata:
+ namespace: aic
+ name: jack
+spec:
+ ingressClassName: apisix
+ authParameter:
+ keyAuth:
+ value:
+ key: jack-key
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ ingressClassName: apisix
+ externalNodes:
+ - type: Domain
+ name: httpbin.org
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: key-auth-route
+spec:
+ ingressClassName: apisix
+ http:
+ - name: key-auth-route
+ match:
+ paths:
+ - /anything
+ upstreams:
+ - name: httpbin-external-domain
+ plugins:
+ - name: key-auth
+ enable: true
+ config:
+ query: auth
+```
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
#### 使用有效密钥进行验证
-使用有效密钥发送请求至：
+使用有效密钥发送请求：
```shell
curl -i "http://127.0.0.1:9080/anything?auth=jack-key";
@@ -382,7 +1084,18 @@ curl -i "http://127.0.0.1:9080/anything?auth=wrong-key";
-H 'apikey: jack-key'
### 将消费者自定义 ID 添加到标头
-以下示例演示了如何在 `Consumer-Custom-Id` 标头中将消费者自定义 ID 附加到经过身份验证的请求，该 ID 可用于根据需要实现其他逻辑。
+以下示例演示了如何在 `X-Consumer-Custom-Id` 标头中将消费者自定义 ID 附加到经过身份验证的请求，该 ID
可用于根据需要实现其他逻辑。
+
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
创建一个带有自定义 ID 标签的消费者 `jack`：
@@ -432,18 +1145,66 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
-使用有效密钥发送请求至：
+</TabItem>
+
+<TabItem value="adc">
+
+创建带有 `key-auth` 凭证的消费者以及启用 `key-auth` 插件的路由：
+
+```yaml title="adc.yaml"
+consumers:
+ - username: jack
+ labels:
+ custom_id: "495aec6a"
+ credentials:
+ - name: key-auth
+ type: key-auth
+ config:
+ key: jack-key
+services:
+ - name: key-auth-service
+ routes:
+ - name: key-auth-route
+ uris:
+ - /anything
+ plugins:
+ key-auth: {}
+ upstream:
+ type: roundrobin
+ nodes:
+ - host: httpbin.org
+ port: 80
+ weight: 1
+```
+
+将配置同步到网关：
```shell
-curl -i "http://127.0.0.1:9080/anything?auth=jack-key";
+adc sync -f adc.yaml
```
-你应该会收到 `HTTP/1.1 200 OK` 响应。
+</TabItem>
+
+<TabItem value="aic">
+
+通过 Ingress Controller 配置资源时，目前不支持消费者自定义标签，请求中不会包含 `X-Consumer-Custom-Id`
标头。暂时无法通过 Ingress Controller 完成此示例。
+
+</TabItem>
+
+</Tabs>
+
+为了验证，请使用有效密钥向路由发送请求：
+
+```shell
+curl -i "http://127.0.0.1:9080/anything?apikey=jack-key";
+```
+
+你应该看到一个带有 `X-Consumer-Custom-Id` 的 `HTTP/1.1 200 OK` 响应，类似于以下内容：
```json
{
"args": {
- "auth": "jack-key"
+ "apikey": "jack-key"
},
"data": "",
"files": {},
@@ -469,6 +1230,17 @@ curl -i "http://127.0.0.1:9080/anything?auth=jack-key";
以下示例演示了如何为常规消费者和匿名消费者配置不同的速率限制策略，其中匿名消费者不需要进行身份验证，并且配额较少。
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
创建常规消费者 `jack` 并配置 `limit-count` 插件以允许 30 秒内的配额为 3：
```shell
@@ -480,7 +1252,8 @@ curl "http://127.0.0.1:9180/apisix/admin/consumers"; -X PUT
\
"limit-count": {
"count": 3,
"time_window": 30,
- "rejected_code": 429
+ "rejected_code": 429,
+ "policy": "local"
}
}
}'
@@ -501,7 +1274,7 @@ curl
"http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
}'
```
-创建匿名用户 `anonymous`，并配置 `limit-count`插件，以允许 30 秒内配额为 1：
+创建匿名用户 `anonymous`，并配置 `limit-count` 插件，以允许 30 秒内配额为 1：
```shell
curl "http://127.0.0.1:9180/apisix/admin/consumers"; -X PUT \
@@ -512,7 +1285,8 @@ curl "http://127.0.0.1:9180/apisix/admin/consumers"; -X PUT
\
"limit-count": {
"count": 1,
"time_window": 30,
- "rejected_code": 429
+ "rejected_code": 429,
+ "policy": "local"
}
}
}'
@@ -540,6 +1314,174 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
+</TabItem>
+
+<TabItem value="adc">
+
+配置具有不同速率限制的消费者以及接受匿名用户的路由：
+
+```yaml title="adc.yaml"
+consumers:
+ - username: jack
+ plugins:
+ limit-count:
+ count: 3
+ time_window: 30
+ rejected_code: 429
+ policy: local
+ credentials:
+ - name: key-auth
+ type: key-auth
+ config:
+ key: jack-key
+ - username: anonymous
+ plugins:
+ limit-count:
+ count: 1
+ time_window: 30
+ rejected_code: 429
+ policy: local
+services:
+ - name: anonymous-rate-limit-service
+ routes:
+ - name: key-auth-route
+ uris:
+ - /anything
+ plugins:
+ key-auth:
+ anonymous_consumer: anonymous
+ upstream:
+ type: roundrobin
+ nodes:
+ - host: httpbin.org
+ port: 80
+ weight: 1
+```
+
+将配置同步到网关：
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX Ingress Controller', value: 'apisix-ingress-controller'}
+]}>
+
+<TabItem value="gateway-api">
+
+配置具有不同速率限制的消费者以及接受匿名用户的路由：
+
+```yaml title="key-auth-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: Consumer
+metadata:
+ namespace: aic
+ name: jack
+spec:
+ gatewayRef:
+ name: apisix
+ credentials:
+ - type: key-auth
+ name: primary-key
+ config:
+ key: jack-key
+ plugins:
+ - name: limit-count
+ config:
+ count: 3
+ time_window: 30
+ rejected_code: 429
+ policy: local
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: Consumer
+metadata:
+ namespace: aic
+ name: anonymous
+spec:
+ gatewayRef:
+ name: apisix
+ plugins:
+ - name: limit-count
+ config:
+ count: 1
+ time_window: 30
+ rejected_code: 429
+ policy: local
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: key-auth-plugin-config
+spec:
+ plugins:
+ - name: key-auth
+ config:
+ anonymous_consumer: aic_anonymous # namespace_consumername
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: key-auth-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /anything
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: key-auth-plugin-config
+ backendRefs:
+ - name: httpbin-external-domain
+ port: 80
+```
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f key-auth-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-ingress-controller">
+
+ApisixConsumer CRD 目前不支持在消费者上配置插件（`authParameter` 中允许的身份验证插件除外）。此示例无法通过 APISIX
CRD 完成。
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
为了验证，请使用 `jack` 的密钥发送五个连续的请求：
```shell
