forward-auth

描述

forward-auth 插件使用的是经典外部认证。当身份认证失败时,可以实现自定义错误或者重定向到认证页面的场景。

forward-auth 插件巧妙地将身份认证和授权逻辑移到了一个专门的外部服务中,APISIX 将用户的请求转发给认证服务并阻塞原始请求,然后在认证服务下以非 2xx 状态响应时进行结果替换。

属性

名称类型必选项默认值有效值描述
uristring设置 authorization 服务的地址 (例如:https://localhost:9188)。
ssl_verifybooleantrue[true, false]当设置为 true 时,验证 SSL 证书。
request_methodstringGET[“GET”,”POST”]客户端向 authorization 服务发送请求的方法。当设置为 POST 时,会将 request body 转发至 authorization 服务。
request_headersarray[string]设置需要由客户端转发到 authorization 服务的请求头。如果没有设置,则只发送 APISIX 提供的 headers (例如:X-Forwarded-XXX)。
upstream_headersarray[string]认证通过时,设置 authorization 服务转发至 upstream 的请求头。如果不设置则不转发任何请求头。
client_headersarray[string]认证失败时,由 authorization 服务向 client 发送的响应头。如果不设置则不转发任何响应头。
timeoutinteger3000ms[1, 60000]msauthorization 服务请求超时时间。
keepalivebooleantrue[true, false]HTTP 长连接。
keepalive_timeoutinteger60000ms[1000, …]ms长连接超时时间。
keepalive_poolinteger5[1, …]ms长连接池大小。
allow_degradationbooleanfalse当设置为 true 时,允许在身份验证服务器不可用时跳过身份验证。

数据定义

APISIX 将生成并发送如下所示的请求头到认证服务:

SchemeHTTP MethodHostURISource IP
X-Forwarded-ProtoX-Forwarded-MethodX-Forwarded-HostX-Forwarded-UriX-Forwarded-For

使用示例

首先,你需要设置一个外部认证服务。以下示例使用的是 Apache APISIX 无服务器插件模拟服务:

  1. curl -X PUT 'http://127.0.0.1:9180/apisix/admin/routes/auth' \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
  3. -H 'Content-Type: application/json' \
  4. -d '{
  5. "uri": "/auth",
  6. "plugins": {
  7. "serverless-pre-function": {
  8. "phase": "rewrite",
  9. "functions": [
  10. "return function (conf, ctx)
  11. local core = require(\"apisix.core\");
  12. local authorization = core.request.header(ctx, \"Authorization\");
  13. if authorization == \"123\" then
  14. core.response.exit(200);
  15. elseif authorization == \"321\" then
  16. core.response.set_header(\"X-User-ID\", \"i-am-user\");
  17. core.response.exit(200);
  18. else core.response.set_header(\"Location\", \"http://example.com/auth\");
  19. core.response.exit(403);
  20. end
  21. end"
  22. ]
  23. }
  24. }
  25. }'

现在你可以在指定 Route 上启用 forward-auth 插件:

  1. curl -X PUT 'http://127.0.0.1:9180/apisix/admin/routes/1' \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
  3. -d '{
  4. "uri": "/headers",
  5. "plugins": {
  6. "forward-auth": {
  7. "uri": "http://127.0.0.1:9080/auth",
  8. "request_headers": ["Authorization"],
  9. "upstream_headers": ["X-User-ID"],
  10. "client_headers": ["Location"]
  11. }
  12. },
  13. "upstream": {
  14. "nodes": {
  15. "httpbin.org:80": 1
  16. },
  17. "type": "roundrobin"
  18. }
  19. }'

完成上述配置后,可通过以下三种方式进行测试:

  • 在请求头中发送认证的详细信息:
  1. curl http://127.0.0.1:9080/headers -H 'Authorization: 123'
  1. {
  2. "headers": {
  3. "Authorization": "123",
  4. "Next": "More-headers"
  5. }
  6. }
  • 转发认证服务响应头到 Upstream。
  1. curl http://127.0.0.1:9080/headers -H 'Authorization: 321'
  1. {
  2. "headers": {
  3. "Authorization": "321",
  4. "X-User-ID": "i-am-user",
  5. "Next": "More-headers"
  6. }
  7. }
  • 当授权失败时,认证服务可以向用户发送自定义响应:
  1. curl -i http://127.0.0.1:9080/headers
  1. HTTP/1.1 403 Forbidden
  2. Location: http://example.com/auth

删除插件

当你需要禁用 forward-auth 插件时,可以通过以下命令删除相应的 JSON 配置,APISIX 将会自动重新加载相关配置,无需重启服务:

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4. "methods": ["GET"],
  5. "uri": "/hello",
  6. "plugins": {},
  7. "upstream": {
  8. "type": "roundrobin",
  9. "nodes": {
  10. "httpbin.org:80": 1
  11. }
  12. }
  13. }'