跳到主要内容

basic-auth

basic-auth 插件为 消费者 (Consumers) 添加 基本访问认证 (Basic Access Authentication)，以便他们在访问上游资源之前进行身份验证。

当消费者成功通过认证后，APISIX 会在将请求代理到上游服务之前，向请求中添加额外的 Header，例如 X-Consumer-Username、X-Credential-Identifier，如果配置了消费者自定义 Header，也会一并添加。上游服务可以据此区分消费者并执行额外的逻辑。如果这些值不可用，则不会添加相应的 Header。

示例​

以下示例展示了如何在不同场景下使用 basic-auth 插件。

在路由上实现基本认证​

以下示例展示了如何在路由上实现基本认证。

创建一个消费者 johndoe：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "johndoe"
  }'

为该消费者创建 basic-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/johndoe/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-john-basic-auth",
    "plugins": {
      "basic-auth": {
        "username": "johndoe",
        "password": "john-key"
      }
    }
  }'

创建一个启用 basic-auth 的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "basic-auth-route",
    "uri": "/anything",
    "plugins": {
      "basic-auth": {}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

使用有效密钥进行验证​

使用有效密钥发送请求：

curl -i "http://127.0.0.1:9080/anything" -u johndoe:john-key

你应该会看到类似以下的 HTTP/1.1 200 OK 响应：

{
  "args": {}, 
  "headers": {
    "Accept": "*/*", 
    "Apikey": "john-key",
    "Authorization": "Basic am9obmRvZTpqb2huLWtleQ==",
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.6.0", 
    "X-Amzn-Trace-Id": "Root=1-66e5107c-5bb3e24f2de5baf733aec1cc",
    "X-Consumer-Username": "johndoe",
    "X-Credential-Identifier": "cred-john-basic-auth",
    "X-Forwarded-Host": "127.0.0.1"
  }, 
  "origin": "192.168.65.1, 205.198.122.37", 
  "url": "http://127.0.0.1/get"
}

使用无效密钥进行验证​

使用无效密钥发送请求：

curl -i "http://127.0.0.1:9080/anything" -u johndoe:invalid-key

你应该会看到包含以下内容的 HTTP/1.1 401 Unauthorized 响应：

{"message":"Invalid user authorization"}

未提供密钥进行验证​

未提供密钥发送请求：

curl -i "http://127.0.0.1:9080/anything"

你应该会看到包含以下内容的 HTTP/1.1 401 Unauthorized 响应：

{"message":"Missing authorization in request"}

向上游隐藏认证信息​

以下示例展示了如何通过配置 hide_credentials 来防止密钥被发送到上游服务。如果你正在使用 APISIX，默认情况下认证密钥会被转发到上游服务，这在某些情况下可能会导致安全风险，你应该考虑按照本例所示更新 hide_credentials。

创建一个消费者 johndoe：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "johndoe"
  }'

为该消费者创建 basic-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/johndoe/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-john-basic-auth",
    "plugins": {
      "basic-auth": {
        "username": "johndoe",
        "password": "john-key"
      }
    }
  }'

不隐藏凭证​

创建一个启用 basic-auth 的路由，并将 hide_credentials 配置为 false（这是默认配置）：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
  "id": "basic-auth-route",
  "uri": "/anything",
  "plugins": {
    "basic-auth": {
      "hide_credentials": false
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

使用有效密钥发送请求：

curl -i "http://127.0.0.1:9080/anything" -u johndoe:john-key

你应该会看到包含以下内容的 HTTP/1.1 200 OK 响应：

{
  "args": {}, 
  "data": "", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Authorization": "Basic am9obmRvZTpqb2huLWtleQ==",
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.6.0", 
    "X-Amzn-Trace-Id": "Root=1-66cc2195-22bd5f401b13480e63c498c6",
    "X-Consumer-Username": "johndoe",
    "X-Credential-Identifier": "cred-john-basic-auth",
    "X-Forwarded-Host": "127.0.0.1"
  }, 
  "json": null, 
  "method": "GET", 
  "origin": "192.168.65.1, 43.228.226.23", 
  "url": "http://127.0.0.1/anything"
}

注意，凭证以 base64 编码格式对上游服务可见。

提示

你也可以使用 Authorization Header 在请求中传递 base64 编码的凭证，如下所示：

curl -i "http://127.0.0.1:9080/anything" -H "Authorization: Basic am9obmRvZTpqb2huLWtleQ=="

隐藏凭证​

将插件的 hide_credentials 更新为 true：

curl "http://127.0.0.1:9180/apisix/admin/routes/basic-auth-route" -X PATCH \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
  "plugins": {
    "basic-auth": {
      "hide_credentials": true
    }
  }
}'

使用有效密钥发送请求：

curl -i "http://127.0.0.1:9080/anything" -u johndoe:john-key

你应该会看到包含以下内容的 HTTP/1.1 200 OK 响应：

{
  "args": {}, 
  "data": "", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*",
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.6.0",
    "X-Amzn-Trace-Id": "Root=1-66cc21a7-4f6ac87946e25f325167d53a",
    "X-Consumer-Username": "johndoe",
    "X-Credential-Identifier": "cred-john-basic-auth",
    "X-Forwarded-Host": "127.0.0.1"
  }, 
  "json": null,
  "method": "GET",
  "origin": "192.168.65.1, 43.228.226.23",
  "url": "http://127.0.0.1/anything"
}

注意，凭证不再对上游服务可见。

将消费者自定义 ID 添加到 Header​

以下示例展示了如何将消费者自定义 ID 附加到认证请求的 Consumer-Custom-Id Header 中，这可用于实现所需的额外逻辑。

创建一个带有自定义 ID 标签的消费者 johndoe：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "johndoe",
    "labels": {
      "custom_id": "495aec6a"
    }
  }'

为该消费者创建 basic-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/johndoe/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-john-basic-auth",
    "plugins": {
      "basic-auth": {
        "username": "johndoe",
        "password": "john-key"
      }
    }
  }'

创建一个启用 basic-auth 的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "basic-auth-route",
    "uri": "/anything",
    "plugins": {
      "basic-auth": {}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

要进行验证，请使用有效密钥向路由发送请求：

curl -i "http://127.0.0.1:9080/anything" -u johndoe:john-key

你应该会看到类似以下的 HTTP/1.1 200 OK 响应：

{
  "args": {},
  "data": "", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Authorization": "Basic am9obmRvZTpqb2huLWtleQ==", 
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.6.0",
    "X-Amzn-Trace-Id": "Root=1-66ea8d64-33df89052ae198a706e18c2a", 
    "X-Consumer-Username": "johndoe",
    "X-Credential-Identifier": "cred-john-basic-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"
}

如果你想将更多的消费者自定义 Header 附加到认证请求中，请参阅 attach-consumer-label 插件。

针对匿名消费者的速率限制​

以下示例展示了如何针对普通消费者和匿名消费者配置不同的速率限制策略，其中匿名消费者无需认证，但配额较少。

创建一个普通消费者 johndoe，并配置 limit-count 插件，允许在 30 秒窗口内有 3 次配额：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "johndoe",
    "plugins": {
      "limit-count": {
        "count": 3,
        "time_window": 30,
        "rejected_code": 429
      }
    }
  }'

为消费者 johndoe 创建 basic-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/johndoe/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-john-basic-auth",
    "plugins": {
      "basic-auth": {
        "username": "johndoe",
        "password": "john-key"
      }
    }
  }'

创建一个匿名用户 anonymous，并配置 limit-count 插件，允许在 30 秒窗口内有 1 次配额：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "anonymous",
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429
      }
    }
  }'

创建一个路由并配置 basic-auth 插件，允许匿名消费者 anonymous 绕过认证：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "basic-auth-route",
    "uri": "/anything",
    "plugins": {
      "basic-auth": {
        "anonymous_consumer": "anonymous"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

要进行验证，请使用 johndoe 的密钥连续发送 5 个请求：

resp=$(seq 5 | xargs -I{} curl "http://127.0.0.1:9080/anything" -u johndoe:john-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）。

200:    3, 429:    2

发送 5 个匿名请求：

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

你应该会看到以下响应，显示只有一个请求成功：

200:    1, 429:    4