forward-auth

The forward-auth plugin supports the integration with an external authorization service for authentication and authorization. If the authentication fails, a customizable error message will be returned to the client. If the authentication succeeds, the request will be forwarded to the upstream service along with the following request headers that APISIX added:

• X-Forwarded-Proto: scheme
• X-Forwarded-Method: HTTP method
• X-Forwarded-Host: host
• X-Forwarded-Uri: URI
• X-Forwarded-For: source IP

Examples​

The examples below demonstrate how you can use forward-auth for different scenarios.

To follow along the examples, please have your external authorization service set up, or create a mock auth service using the serverless function plugin as shown below:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "auth-mock",
    "uri": "/auth",
    "plugins": {
      "serverless-pre-function": {
        "phase": "rewrite",
        "functions": [
          "return function (conf, ctx)
            local core = require(\"apisix.core\");
            local authorization = core.request.header(ctx, \"Authorization\");
            if authorization == \"123\" then
              core.response.exit(200);
            elseif authorization == \"321\" then
              core.response.set_header(\"X-User-ID\", \"i-am-user\");
              core.response.exit(200);
            else core.response.set_header(\"X-Forward-Auth\", \"Fail\");
              core.response.exit(403);
            end
          end"
        ]
      }
    }
  }'

The function above implements the following logics:

❶ If the Authorization header has a value of 123, respond with 200 OK;

❷ If the Authorization header has a value of 321, set a header X-User-ID: i-am-user and respond with 200 OK;

❸ Otherwise, set a header X-Forward-Auth: Fail and respond with 403 Forbidden.

Forward Designated Headers to Upstream Resource​

The following example demonstrates how to set up forward-auth on a route to regulate client access to the resources upstream based on a value in the request header. It also allows passing a specific header from the authorization service to the upstream resource.

Create a route with the forward-auth plugin as such:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "forward-auth-route",
    "uri": "/headers",
    "plugins": {
      "forward-auth": {
        "uri": "http://127.0.0.1:9080/auth",
        "request_headers": ["Authorization"],
        "upstream_headers": ["X-User-ID"]
      }
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 1
      },
      "type": "roundrobin"
    }
  }'

❶ the URI of the authorization service

❷ the request header that should be forwarded to the authorization service

❸ the request header set by the authorization service that should be forwarded to the upstream resource when the authorization succeeds

Send a request to the route with authorization detail in the header:

curl "http://127.0.0.1:9080/headers" -H 'Authorization: 123'

You should see an HTTP/1.1 200 OK response of the following:

{
  "headers": {
    "Accept": "*/*", 
    "Authorization": "123", 
    ...
  }
}

To verify if the X-User-ID header set by the authorization service will be forwarded to the upstream service, send a request to the route with the corresponding authorization detail:

curl "http://127.0.0.1:9080/headers" -H 'Authorization: 321'

You should see an HTTP/1.1 200 OK response of the following, showing the header is forwarded to the upstream:

{
  "headers": {
    "Accept": "*/*", 
    "Authorization": "123",
    "X-User-ID": "i-am-user",
    ...
  }
}

Return Designated Headers to Clients on Authentication Failure​

The following example demonstrates how you can configure forward-auth on a route to regulate client access to the upstream resources. It also passes a specific header returned by the authorization service to the client when the authentication fails.

Create a route with the forward-auth plugin as such:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "forward-auth-route",
    "uri": "/headers",
    "plugins": {
      "forward-auth": {
        "uri": "http://127.0.0.1:9080/auth",
        "request_headers": ["Authorization"],
        "client_headers": ["X-Forward-Auth"]
      }
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 1
      },
      "type": "roundrobin"
    }
  }'

❶ pass the X-Forward-Auth header from the authorization service back to the client when authentication fails

Send a request without any authentication information:

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

You should receive an HTTP/1.1 403 Forbidden response:

...
X-Forward-Auth: Fail
Server: APISIX/3.x.x

<html>
<head><title>403 Forbidden</title></head>
<body>
<center><h1>403 Forbidden</h1></center>
<hr><center>openresty</center>
<p><em>Powered by <a href="https://apisix.apache.org/">APISIX</a>.</em></p></body>
</html>