From f5e2aae79512538d23a20e8a50133fb971f81f67 Mon Sep 17 00:00:00 2001 From: traky Date: Wed, 25 Dec 2024 15:10:55 +0800 Subject: [PATCH 1/2] update docs --- docs/en/latest/plugins/key-auth.md | 524 +++++++++++++++++++++++++---- docs/zh/latest/plugins/key-auth.md | 520 ++++++++++++++++++++++++---- 2 files changed, 914 insertions(+), 130 deletions(-) diff --git a/docs/en/latest/plugins/key-auth.md b/docs/en/latest/plugins/key-auth.md index 985036640cb0..93dfd09a8b48 100644 --- a/docs/en/latest/plugins/key-auth.md +++ b/docs/en/latest/plugins/key-auth.md @@ -6,7 +6,7 @@ keywords: - Plugin - Key Auth - key-auth -description: This document contains information about the Apache APISIX key-auth Plugin. +description: The key-auth plugin supports the use of an authentication key as a mechanism for clients to authenticate themselves before accessing Upstream resources. --- + + + + ## Description -The `key-auth` Plugin is used to add an authentication key (API key) to a Route or a Service. +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. -This works well with a [Consumer](../terminology/consumer.md). Consumers of the API can then add their key to the query string or the header to authenticate their requests. +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. ## Attributes -For Consumer: +For Consumer/Credential: | Name | Type | Requirement | Description | |------|--------|-------------|----------------------------| @@ -46,19 +52,19 @@ NOTE: `encrypt_fields = {"key"}` is also defined in the schema, which means that For Route: -| Name | Type | Requirement | Default | Valid | Description | +| Name | Type | Required | Default | Valid | Description | |--------|--------|-------------|---------|-------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| header | string | optional | apikey | | The header to get the key from. | -| query | string | optional | apikey | | The query string to get the key from. Lower priority than header. | -| hide_credentials | bool | optional | false | | Apache APISIX will pass the request header or query string that contains the authentication information to the Upstream if `hide_credentials` is `false`. Otherwise the authentication information will be removed before proxying.| - -## Enable Plugin +| 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. | -To enable the Plugin, you have to create a Consumer object with an authentication key and configure your Route to authenticate requests. +## Examples -First you can create a Consumer object through the [Admin API](../admin-api.md) with a unique key: +The examples below demonstrate how you can work with the `key-auth` plugin for different scenarios. :::note + You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command: ```bash @@ -67,107 +73,499 @@ 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. + +Create a Consumer `jack`: + ```shell -curl http://127.0.0.1:9180/apisix/admin/consumers -H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "username": "jack", +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "jack" + }' +``` + +Create `key-auth` credential for the consumer: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "cred-jack-key-auth", "plugins": { - "key-auth": { - "key": "auth-one" - } + "key-auth": { + "key": "jack-key" + } } -}' + }' +``` + +Create a Route with `key-auth`: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "key-auth-route", + "uri": "/anything", + "plugins": { + "key-auth": {} + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' ``` -You can also use the [APISIX Dashboard](/docs/dashboard/USER_GUIDE) to complete the operation through a web UI. +#### Verify with a Valid Key -First, create a Consumer object: +Send a request to with the valid key: -![create a consumer](https://raw.githubusercontent.com/apache/apisix/master/docs/assets/images/plugin/key-auth-1.png) +```shell +curl -i "http://127.0.0.1:9080/anything" -H 'apikey: jack-key' +``` -You can then add the `key-auth` Plugin: +You should receive an `HTTP/1.1 200 OK` response. -![enable key-auth plugin](https://raw.githubusercontent.com/apache/apisix/master/docs/assets/images/plugin/key-auth-2.png) +#### Verify with an Invalid Key -Once you have created a Consumer object, you can then configure a Route or a Service to authenticate requests: +Send a request with an invalid key: ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "methods": ["GET"], - "uri": "/index.html", - "id": 1, +curl -i "http://127.0.0.1:9080/anything" -H 'apikey: wrong-key' +``` + +You should see an `HTTP/1.1 401 Unauthorized` response with the following: + +```text +{"message":"Invalid API key in request"} +``` + +#### Verify without a Key + +Send a request to without a key: + +```shell +curl -i "http://127.0.0.1:9080/anything" +``` + +You should see an `HTTP/1.1 401 Unauthorized` response with the following: + +```text +{"message":"Missing API key found in request"} +``` + +### 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. + +Create a Consumer `jack`: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "jack" + }' +``` + +Create `key-auth` credential for the consumer: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "cred-jack-key-auth", "plugins": { - "key-auth": {} - }, - "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } + "key-auth": { + "key": "jack-key" + } } + }' +``` + +#### Without Hiding Credentials + +Create a Route with `key-auth` and configure `hide_credentials` to `false`, which is the default configuration: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ +-H "X-API-KEY: ${admin_key}" \ +-d '{ + "id": "key-auth-route", + "uri": "/anything", + "plugins": { + "key-auth": { + "hide_credentials": false + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } }' ``` -To fetch the key from a different header than `apikey`, change the `header` in the configuration: +Send a request with the valid key: + +```shell +curl -i "http://127.0.0.1:9080/anything?apikey=jack-key" +``` + +You should see an `HTTP/1.1 200 OK` response with the following: ```json { + "args": { + "auth": "jack-key" + }, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/8.2.1", + "X-Consumer-Username": "jack", + "X-Credential-Identifier": "cred-jack-key-auth", + "X-Amzn-Trace-Id": "Root=1-6502d8a5-2194962a67aa21dd33f94bb2", + "X-Forwarded-Host": "127.0.0.1" + }, + "json": null, + "method": "GET", + "origin": "127.0.0.1, 103.248.35.179", + "url": "http://127.0.0.1/anything?apikey=jack-key" +} +``` + +Note that the credential `jack-key` is visible to the Upstream service. + +#### Hide Credentials + +Update the plugin's `hide_credentials` to `true`: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes/key-auth-route" -X PATCH \ +-H "X-API-KEY: ${admin_key}" \ +-d '{ + "plugins": { "key-auth": { - "header": "Authorization" + "hide_credentials": true } + } +}' +``` + +Send a request with the valid key: + +```shell +curl -i "http://127.0.0.1:9080/anything?apikey=jack-key" +``` + +You should see an `HTTP/1.1 200 OK` response with the following: + +```json +{ + "args": {}, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/8.2.1", + "X-Consumer-Username": "jack", + "X-Credential-Identifier": "cred-jack-key-auth", + "X-Amzn-Trace-Id": "Root=1-6502d85c-16f34dbb5629a5960183e803", + "X-Forwarded-Host": "127.0.0.1" + }, + "json": null, + "method": "GET", + "origin": "127.0.0.1, 103.248.35.179", + "url": "http://127.0.0.1/anything" } ``` -## Example usage +Note that the credential `jack-key` is no longer visible to the Upstream service. + +### Demonstrate Priority of Keys in Header and Query -After you have configured the Plugin as mentioned above, you can make a request as shown: +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. + +Create a Consumer `jack`: ```shell -curl http://127.0.0.2:9080/index.html -H 'apikey: auth-one' -i +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "jack" + }' ``` +Create `key-auth` credential for the consumer: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "cred-jack-key-auth", + "plugins": { + "key-auth": { + "key": "jack-key" + } + } + }' ``` -HTTP/1.1 200 OK -... + +Create a Route with `key-auth`: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ +-H "X-API-KEY: ${admin_key}" \ +-d '{ + "id": "key-auth-route", + "uri": "/anything", + "plugins": { + "key-auth": { + "query": "auth" + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } +}' ``` -And if the request has a missing key or a wrong key: +#### Verify with a Valid Key + +Send a request to with the valid key: ```shell -curl http://127.0.0.2:9080/index.html -i +curl -i "http://127.0.0.1:9080/anything?auth=jack-key" ``` +You should receive an `HTTP/1.1 200 OK` response. + +#### Verify with an Invalid Key + +Send a request with an invalid key: + +```shell +curl -i "http://127.0.0.1:9080/anything?auth=wrong-key" ``` -HTTP/1.1 401 Unauthorized -... -{"message":"Missing API key in request"} + +You should see an `HTTP/1.1 401 Unauthorized` response with the following: + +```text +{"message":"Invalid API key in request"} ``` +#### Verify with a Valid Key in Query String + +However, if you include the valid key in header with the invalid key still in the URL query string: + ```shell -curl http://127.0.0.2:9080/index.html -H 'apikey: abcabcabc' -i +curl -i "http://127.0.0.1:9080/anything?auth=wrong-key" -H 'apikey: jack-key' ``` +You should see an `HTTP/1.1 200 OK` response. This shows that the key included in the header always has a higher priority. + +### 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. + +Create a Consumer `jack` with a custom ID label: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "jack", + "labels": { + "custom_id": "495aec6a" + } + }' ``` -HTTP/1.1 401 Unauthorized -... -{"message":"Invalid API key in request"} + +Create `key-auth` credential for the consumer: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "cred-jack-key-auth", + "plugins": { + "key-auth": { + "key": "jack-key" + } + } + }' ``` -## Delete Plugin +Create a Route with `key-auth`: -To remove the `key-auth` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "key-auth-route", + "uri": "/anything", + "plugins": { + "key-auth": {} + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` + +To verify, send a request to the Route with the valid key: ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' +curl -i "http://127.0.0.1:9080/anything?auth=jack-key" +``` + +You should see an `HTTP/1.1 200 OK` response similar to the following: + +```json { - "uri": "/index.html", - "plugins": {}, + "args": { + "auth": "jack-key" + }, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/8.6.0", + "X-Amzn-Trace-Id": "Root=1-66ea8d64-33df89052ae198a706e18c2a", + "X-Consumer-Username": "jack", + "X-Credential-Identifier": "cred-jack-key-auth", + "X-Consumer-Custom-Id": "495aec6a", + "X-Forwarded-Host": "127.0.0.1" + }, + "json": null, + "method": "GET", + "origin": "192.168.65.1, 205.198.122.37", + "url": "http://127.0.0.1/anything?apikey=jack-key" +} +``` + +### 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. + +Create a regular Consumer `jack` and configure the `limit-count` plugin to allow for a quota of 3 within a 30-second window: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "jack", + "plugins": { + "limit-count": { + "count": 3, + "time_window": 30, + "rejected_code": 429 + } + } + }' +``` + +Create the `key-auth` credential for the Consumer `jack`: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "cred-jack-key-auth", + "plugins": { + "key-auth": { + "key": "jack-key" + } + } + }' +``` + +Create an anonymous user `anonymous` and configure the `limit-count` plugin to allow for a quota of 1 within a 30-second window: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "anonymous", + "plugins": { + "limit-count": { + "count": 1, + "time_window": 30, + "rejected_code": 429 + } + } + }' +``` + +Create a Route and configure the `key-auth` plugin to accept anonymous Consumer `anonymous` from bypassing the authentication: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "key-auth-route", + "uri": "/anything", + "plugins": { + "key-auth": { + "anonymous_consumer": "anonymous" + } + }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -}' + }' +``` + +To verify, send five consecutive requests with `jack`'s key: + +```shell +resp=$(seq 5 | xargs -I{} curl "http://127.0.0.1:9080/anything" -H 'apikey: jack-key' -o /dev/null -s -w "%{http_code}\n") && \ + count_200=$(echo "$resp" | grep "200" | wc -l) && \ + count_429=$(echo "$resp" | grep "429" | wc -l) && \ + echo "200": $count_200, "429": $count_429 +``` + +You should see the following response, showing that out of the 5 requests, 3 requests were successful (status code 200) while the others were rejected (status code 429). + +```text +200: 3, 429: 2 +``` + +Send five anonymous requests: + +```shell +resp=$(seq 5 | xargs -I{} curl "http://127.0.0.1:9080/anything" -o /dev/null -s -w "%{http_code}\n") && \ + count_200=$(echo "$resp" | grep "200" | wc -l) && \ + count_429=$(echo "$resp" | grep "429" | wc -l) && \ + echo "200": $count_200, "429": $count_429 +``` + +You should see the following response, showing that only one request was successful: + +```text +200: 1, 429: 4 ``` diff --git a/docs/zh/latest/plugins/key-auth.md b/docs/zh/latest/plugins/key-auth.md index 13a08e7d94ee..fa6f469fbd7e 100644 --- a/docs/zh/latest/plugins/key-auth.md +++ b/docs/zh/latest/plugins/key-auth.md @@ -6,7 +6,7 @@ keywords: - Plugin - Key Auth - key-auth -description: 本文介绍了关于 Apache APISIX `key-auth` 插件的基本信息及使用方法。 +description: key-auth 插件支持使用身份验证密钥作为客户端在访问上游资源之前进行身份验证的机制。 --- + + + + ## 描述 -`key-auth` 插件用于向 Route 或 Service 添加身份验证密钥（API key）。 +`key-auth` 插件支持使用身份验证密钥作为客户端在访问上游资源之前进行身份验证的机制。 + +要使用该插件，您需要在 [Consumers](../terminology/consumer.md) 上配置身份验证密钥，并在路由或服务上启用该插件。密钥可以包含在请求 URL 查询字符串或请求标头中。然后，APISIX 将验证密钥以确定是否应允许或拒绝请求访问上游资源。 -它需要与 [Consumer](../terminology/consumer.md) 一起配合才能工作，通过 Consumer 将其密钥添加到查询字符串参数或标头中以验证其请求。 +当消费者成功通过身份验证后，APISIX 会在将请求代理到上游服务之前向请求添加其他标头，例如 `X-Consumer-Username`、`X-Credential-Indentifier` 和其他消费者自定义标头（如果已配置）。上游服务将能够区分消费者并根据需要实现其他逻辑。如果这些值中的任何一个不可用，则不会添加相应的标头。 ## 属性 -Consumer 端： +Consumer/Credential 端： | 名称 | 类型 | 必选项 | 描述 | | ---- | ------ | ------ | ------------------------------------------------------------------------------------------------------------- | @@ -44,19 +50,17 @@ Consumer 端： 注意：schema 中还定义了 `encrypt_fields = {"key"}`，这意味着该字段将会被加密存储在 etcd 中。具体参考 [加密存储字段](../plugin-develop.md#加密存储字段)。 -Router 端： +Route 端： | 名称 | 类型 | 必选项 | 默认值 | 描述 | | ----------------- | ------ | ----- | ------ |----------------------------------------------------------------------------------------------------------------------------------------------------------| | header | string | 否 | apikey | 设置我们从哪个 header 获取 key。 | | query | string | 否 | apikey | 设置我们从哪个 query string 获取 key，优先级低于 `header`。 | -| hide_credentials | bool | 否 | false | 当设置为 `false` 时将含有认证信息的 header 或 query string 传递给 Upstream。如果为 `true` 时将删除对应的 header 或 query string，具体删除哪一个取决于是从 header 获取 key 还是从 query string 获取 key。 | - -## 启用插件 +| hide_credentials | boolean | 否 | false | 如果为 `true`，则不要将含有认证信息的 header 或 query string 传递给 Upstream。 | -如果你要启用插件，就必须使用身份验证密钥创建一个 Consumer 对象，并且需要配置 Route 才可以对请求进行身份验证。 +## 示例 -首先，你可以通过 Admin API 创建一个具有唯一 key 的 Consumer： +以下示例演示了如何在不同场景中使用 `key-auth` 插件。 :::note @@ -68,117 +72,499 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### 在路由上实现密钥认证 + +以下示例演示如何在路由上实现密钥认证并将密钥包含在请求标头中。 + +创建一个消费者 `jack`： + ```shell -curl http://127.0.0.1:9180/apisix/admin/consumers \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "username": "jack", +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "jack" + }' +``` + +为消费者创建 `key-auth` 凭证： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "cred-jack-key-auth", "plugins": { - "key-auth": { - "key": "auth-one" - } + "key-auth": { + "key": "jack-key" + } } -}' + }' ``` -你还可以通过 [APISIX Dashboard](https://github.com/apache/apisix-dashboard) 的 Web 界面完成上述操作。 +使用 `key-auth` 创建路由： - +使用无效密钥发送请求： + +```shell +curl -i "http://127.0.0.1:9080/anything" -H 'apikey: wrong-key' +``` + +您应该看到以下 `HTTP/1.1 401 Unauthorized` 响应： + +```text +{"message":"Invalid API key in request"} +``` + +#### 无需密钥即可验证 -创建 Consumer 对象后，你可以创建 Route 进行验证： +无需密钥即可发送请求： ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "methods": ["GET"], - "uri": "/index.html", - "id": 1, +curl -i "http://127.0.0.1:9080/anything" +``` + +您应该看到以下 `HTTP/1.1 401 Unauthorized` 响应： + +```text +{"message":"Missing API key found in request"} +``` + +### 隐藏上游的身份验证信息 + +以下示例演示如何通过配置 `hide_credentials` 来防止密钥被发送到上游服务。默认情况下，身份验证密钥被转发到上游服务，这在某些情况下可能会导致安全风险。 + +创建一个消费者 `jack`： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "jack" + }' +``` + +为消费者创建 `key-auth` 凭证： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "cred-jack-key-auth", "plugins": { - "key-auth": {} - }, - "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } + "key-auth": { + "key": "jack-key" + } } + }' +``` + +#### 不隐藏凭据 + +使用 `key-auth` 创建路由，并将 `hide_credentials` 配置为 `false` (默认配置)： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ +-H "X-API-KEY: ${admin_key}" \ +-d '{ + "id": "key-auth-route", + "uri": "/anything", + "plugins": { + "key-auth": { + "hide_credentials": false + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } }' ``` -如果你不想从默认的 `apikey` header 获取 key，可以自定义 header，如下所示： +发送带有有效密钥的请求： + +```shell +curl -i "http://127.0.0.1:9080/anything?apikey=jack-key" +``` + +您应该看到以下 `HTTP/1.1 200 OK` 响应： ```json { + "args": { + "auth": "jack-key" + }, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/8.2.1", + "X-Consumer-Username": "jack", + "X-Credential-Identifier": "cred-jack-key-auth", + "X-Amzn-Trace-Id": "Root=1-6502d8a5-2194962a67aa21dd33f94bb2", + "X-Forwarded-Host": "127.0.0.1" + }, + "json": null, + "method": "GET", + "origin": "127.0.0.1, 103.248.35.179", + "url": "http://127.0.0.1/anything?apikey=jack-key" +} +``` + +注意凭证 `jack-key` 对于上游服务是可见的。 + +#### 隐藏凭据 + +将插件的 `hide_credentials` 更新为 `true`： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes/key-auth-route" -X PATCH \ +-H "X-API-KEY: ${admin_key}" \ +-d '{ + "plugins": { "key-auth": { - "header": "Authorization" + "hide_credentials": true } + } +}' +``` + +发送带有有效密钥的请求： + +```shell +curl -i "http://127.0.0.1:9080/anything?apikey=jack-key" +``` + +您应该看到以下 `HTTP/1.1 200 OK` 响应： + +```json +{ + "args": {}, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/8.2.1", + "X-Consumer-Username": "jack", + "X-Credential-Identifier": "cred-jack-key-auth", + "X-Amzn-Trace-Id": "Root=1-6502d85c-16f34dbb5629a5960183e803", + "X-Forwarded-Host": "127.0.0.1" + }, + "json": null, + "method": "GET", + "origin": "127.0.0.1, 103.248.35.179", + "url": "http://127.0.0.1/anything" } ``` -## 测试插件 +注意凭证 `jack-key` 对上游服务不再可见。 + +### 演示标头和查询中的密钥优先级 -通过上述方法配置插件后，可以通过以下命令测试插件： +以下示例演示了如何在路由上实现消费者的密钥身份验证，并自定义应包含密钥的 URL 参数。该示例还显示，当在标头和查询字符串中都配置了 API 密钥时，请求标头具有更高的优先级。 + +创建消费者 `jack`： ```shell -curl http://127.0.0.2:9080/index.html -H 'apikey: auth-one' -i +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "jack" + }' ``` +为消费者创建 `key-auth` 凭证： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "cred-jack-key-auth", + "plugins": { + "key-auth": { + "key": "jack-key" + } + } + }' ``` -HTTP/1.1 200 OK -... + +使用 `key-auth` 创建路由： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ +-H "X-API-KEY: ${admin_key}" \ +-d '{ + "id": "key-auth-route", + "uri": "/anything", + "plugins": { + "key-auth": { + "query": "auth" + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } +}' ``` -如果当前请求没有正确配置 `apikey`，将得到一个 `401` 的应答： +#### 使用有效密钥进行验证 + +使用有效密钥发送请求至： ```shell -curl http://127.0.0.2:9080/index.html -i +curl -i "http://127.0.0.1:9080/anything?auth=jack-key" ``` +您应该会收到 `HTTP/1.1 200 OK` 响应。 + +#### 使用无效密钥进行验证 + +使用无效密钥发送请求： + ```shell -HTTP/1.1 401 Unauthorized -... -{"message":"Missing API key in request"} +curl -i "http://127.0.0.1:9080/anything?auth=wrong-key" ``` +您应该看到以下 `HTTP/1.1 401 Unauthorized` 响应： + +```text +{"message":"Invalid API key in request"} +``` + +#### 使用查询字符串中的有效密钥进行验证 + +但是，如果您在标头中包含有效密钥，而 URL 查询字符串中仍包含无效密钥： + ```shell -curl http://127.0.0.2:9080/index.html -H 'apikey: abcabcabc' -i +curl -i "http://127.0.0.1:9080/anything?auth=wrong-key" -H 'apikey: jack-key' ``` +您应该会看到 `HTTP/1.1 200 OK` 响应。这表明标头中包含的密钥始终具有更高的优先级。 + +### 将消费者自定义 ID 添加到标头 + +以下示例演示了如何在 `Consumer-Custom-Id` 标头中将消费者自定义 ID 附加到经过身份验证的请求，该 ID 可用于根据需要实现其他逻辑。 + +创建一个带有自定义 ID 标签的消费者 `jack`： + ```shell -HTTP/1.1 401 Unauthorized -... -{"message":"Invalid API key in request"} +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "jack", + "labels": { + "custom_id": "495aec6a" + } + }' +``` + +Create `key-auth` credential for the consumer: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "cred-jack-key-auth", + "plugins": { + "key-auth": { + "key": "jack-key" + } + } + }' ``` -## 删除插件 +Create a Route with `key-auth`: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "key-auth-route", + "uri": "/anything", + "plugins": { + "key-auth": {} + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } + } + }' +``` -当你需要禁用 `key-auth` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务： +To verify, send a request to the Route with the valid key: ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' +curl -i "http://127.0.0.1:9080/anything?auth=jack-key" +``` + +You should see an `HTTP/1.1 200 OK` response similar to the following: + +```json { - "methods": ["GET"], - "uri": "/index.html", - "id": 1, + "args": { + "auth": "jack-key" + }, + "data": "", + "files": {}, + "form": {}, + "headers": { + "Accept": "*/*", + "Host": "127.0.0.1", + "User-Agent": "curl/8.6.0", + "X-Amzn-Trace-Id": "Root=1-66ea8d64-33df89052ae198a706e18c2a", + "X-Consumer-Username": "jack", + "X-Credential-Identifier": "cred-jack-key-auth", + "X-Consumer-Custom-Id": "495aec6a", + "X-Forwarded-Host": "127.0.0.1" + }, + "json": null, + "method": "GET", + "origin": "192.168.65.1, 205.198.122.37", + "url": "http://127.0.0.1/anything?apikey=jack-key" +} +``` + +### 匿名消费者的速率限制 + +以下示例演示了如何为常规消费者和匿名消费者配置不同的速率限制策略，其中匿名消费者不需要进行身份验证，并且配额较少。 + +创建常规消费者 `jack` 并配置 `limit-count` 插件以允许 30 秒内的配额为 3： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "jack", "plugins": { + "limit-count": { + "count": 3, + "time_window": 30, + "rejected_code": 429 + } + } + }' +``` + +为消费者 `jack` 创建 `key-auth` 凭证： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "cred-jack-key-auth", + "plugins": { + "key-auth": { + "key": "jack-key" + } + } + }' +``` + +创建匿名用户 `anonymous`，并配置 `limit-count`插件，以允许 30 秒内配额为 1： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "username": "anonymous", + "plugins": { + "limit-count": { + "count": 1, + "time_window": 30, + "rejected_code": 429 + } + } + }' +``` + +创建路由并配置 `key-auth` 插件以接受匿名消费者 `anonymous` 绕过身份验证： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "key-auth-route", + "uri": "/anything", + "plugins": { + "key-auth": { + "anonymous_consumer": "anonymous" + } }, "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } + "type": "roundrobin", + "nodes": { + "httpbin.org:80": 1 + } } -}' + }' +``` + +为了验证，请使用 `jack` 的密钥发送五个连续的请求： + +```shell +resp=$(seq 5 | xargs -I{} curl "http://127.0.0.1:9080/anything" -H 'apikey: jack-key' -o /dev/null -s -w "%{http_code}\n") && \ + count_200=$(echo "$resp" | grep "200" | wc -l) && \ + count_429=$(echo "$resp" | grep "429" | wc -l) && \ + echo "200": $count_200, "429": $count_429 +``` + +您应该看到以下响应，显示在 5 个请求中，3 个请求成功（状态代码 200），而其他请求被拒绝（状态代码 429）。 + +```text +200: 3, 429: 2 +``` + +发送五个匿名请求： + +```shell +resp=$(seq 5 | xargs -I{} curl "http://127.0.0.1:9080/anything" -o /dev/null -s -w "%{http_code}\n") && \ + count_200=$(echo "$resp" | grep "200" | wc -l) && \ + count_429=$(echo "$resp" | grep "429" | wc -l) && \ + echo "200": $count_200, "429": $count_429 +``` + +您应该看到以下响应，表明只有一个请求成功： + +```text +200: 1, 429: 4 ``` From 0305547d24bcf5b0325d0ab03bdfd6925e732601 Mon Sep 17 00:00:00 2001 From: Traky Deng Date: Wed, 25 Dec 2024 21:39:34 +0800 Subject: [PATCH 2/2] capitalize credential --- docs/en/latest/plugins/key-auth.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/en/latest/plugins/key-auth.md b/docs/en/latest/plugins/key-auth.md index 93dfd09a8b48..4523dc459cc1 100644 --- a/docs/en/latest/plugins/key-auth.md +++ b/docs/en/latest/plugins/key-auth.md @@ -87,7 +87,7 @@ curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ }' ``` -Create `key-auth` credential for the consumer: +Create `key-auth` Credential for the consumer: ```shell curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \ @@ -174,7 +174,7 @@ curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ }' ``` -Create `key-auth` credential for the consumer: +Create `key-auth` Credential for the consumer: ```shell curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \ @@ -245,7 +245,7 @@ You should see an `HTTP/1.1 200 OK` response with the following: } ``` -Note that the credential `jack-key` is visible to the Upstream service. +Note that the Credential `jack-key` is visible to the Upstream service. #### Hide Credentials @@ -293,7 +293,7 @@ You should see an `HTTP/1.1 200 OK` response with the following: } ``` -Note that the credential `jack-key` is no longer visible to the Upstream service. +Note that the Credential `jack-key` is no longer visible to the Upstream service. ### Demonstrate Priority of Keys in Header and Query @@ -309,7 +309,7 @@ curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ }' ``` -Create `key-auth` credential for the consumer: +Create `key-auth` Credential for the consumer: ```shell curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \ @@ -397,7 +397,7 @@ curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ }' ``` -Create `key-auth` credential for the consumer: +Create `key-auth` Credential for the consumer: ```shell curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \ @@ -486,7 +486,7 @@ curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \ }' ``` -Create the `key-auth` credential for the Consumer `jack`: +Create the `key-auth` Credential for the Consumer `jack`: ```shell curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \