跳到主要内容

basic-auth

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

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

关于 X-Consumer-Username

使用 Ingress Controller 配置消费者时，消费者名称会生成为 namespace_consumername 格式。因此，X-Consumer-Username 请求头也会采用此格式，而不只是 consumername。

示例​

以下示例展示了如何在不同场景下使用 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": "*/*", 
    "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/anything"
}

使用无效密钥进行验证​

使用无效密钥发送请求：

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

你应该会看到包含以下内容的 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，防止将客户端凭证（Authorization 请求头）发送到上游服务。使用 APISIX 时，包含客户端凭证的 Authorization 请求头默认会转发到上游服务，这在某些情况下可能带来安全风险，因此应考虑按本示例更新 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 请求头传递经过 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 添加到请求头​

以下示例展示了如何将消费者自定义 ID 添加到已认证请求的 Consumer-Custom-Id 请求头中，以便按需实现额外逻辑。

创建一个带有自定义 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": "aic_johndoe",
    "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"
}

如果你想将更多消费者自定义请求头添加到已认证请求中，请参阅 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,
        "policy": "local"
      }
    }
  }'

为消费者 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,
        "policy": "local"
      }
    }
  }'

创建一个路由并配置 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