wolf-rbac

The wolf-rbac plugin integrates APISIX and API7 Gateway with Wolf role-based access control. It reads the Wolf application ID from the caller's token and selects the matching gateway consumer. It then asks Wolf whether that user can perform the request method on the requested URI.

After a token selects a valid consumer, the plugin removes client-supplied values for the identity headers. When Wolf returns user information, the gateway adds the verified user's ID, username, and nickname to the client response. Permitted requests also forward these values upstream. With the default header prefix, the headers are X-UserId, X-Username, and X-Nickname.

Examples​

A single protected HTTPBin route demonstrates how the gateway handles unauthenticated, denied, and permitted requests.

Authorize Requests with Wolf RBAC​

The gateway must be running and able to reach the Wolf server.

Set Up Wolf​

Use an existing Wolf deployment with an application and user whose policy permits GET / and denies POST /. If you need a local fixture, install Docker and Git, then clone the Wolf repository at the revision used by this example:

git clone https://github.com/iGeeky/wolf.git
cd wolf
git checkout --detach 0.8.0
cd quick-start-with-docker

Start the Wolf database, cache, and server:

docker compose up -d database cache server

Wait until the Wolf server accepts requests:

until curl --max-time 2 -fsS "http://127.0.0.1:12180/wolf/ping" > /dev/null; do
  sleep 1
done

Initialize Wolf's demo applications and assign the same local test password to their users:

sh wolf-demo-init.sh wolf-test-password

The initialization creates the restful-demo application and grants its app-man user permission to send GET requests to /. See the Wolf 0.8.0 Docker quickstart for more information about the demo stack.

The quickstart credentials and secrets are intended only for local testing. Generate unique secrets and follow the Wolf project's deployment guidance for any non-test environment.

Export the application ID and user credentials. These values match the local fixture; replace them for an existing deployment:

export WOLF_APP_ID="restful-demo"
export WOLF_USERNAME="app-man"
export WOLF_PASSWORD="wolf-test-password"

Set WOLF_SERVER to the Wolf origin as reached from the gateway. Include the http:// or https:// scheme and do not include a trailing slash:

export WOLF_SERVER="YOUR_GATEWAY_REACHABLE_WOLF_URL"

Use HTTP only on a trusted test network. In production, use HTTPS and enable certificate verification as described in Connect to Wolf over HTTPS.

Configure a Consumer and Routes​

Set ADMIN_API_KEY to the gateway Admin API key. The commands use the default local Admin API and proxy addresses; replace them with the addresses for your deployment.

Create a consumer for the Wolf application:

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d @- <<EOF
{
  "username": "wolf-consumer",
  "plugins": {
    "wolf-rbac": {
      "appid": "${WOLF_APP_ID}",
      "server": "${WOLF_SERVER}",
      "header_prefix": "X-Wolf-"
    }
  }
}
EOF

❶ appid: selects this consumer when it matches the application ID embedded in the Wolf token.

❷ server: sets the Wolf origin for the gateway's requests to Wolf.

❸ header_prefix: changes the verified identity headers to X-Wolf-UserId, X-Wolf-Username, and X-Wolf-Nickname.

Create a protected route that accepts GET and POST requests. Enable wolf-rbac with an empty plugin configuration, and remove the token from the request before it is forwarded to HTTPBin:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "wolf-rbac-route",
    "uri": "/",
    "methods": ["GET", "POST"],
    "plugins": {
      "wolf-rbac": {},
      "proxy-rewrite": {
        "headers": {
          "remove": ["Authorization"]
        }
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

❶ wolf-rbac: checks the request method and URI against the permissions assigned to the user in Wolf. The connection settings come from the consumer selected by the token.

❷ proxy-rewrite: runs after authorization and removes the Authorization header used by this example before the request is sent upstream.

Create a separate route that exposes the plugin's login endpoint. Configure only public-api on this route so that callers can log in without already having a Wolf token:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "wolf-rbac-login",
    "uri": "/apisix/plugin/wolf-rbac/login",
    "plugins": {
      "public-api": {}
    }
  }'

Verify Access​

Send a request without a Wolf token:

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

The gateway rejects the request with HTTP/1.1 401 Unauthorized:

{"message":"Missing rbac token in request"}

Use jq to log in through the exposed Wolf endpoint and save the returned Wolf RBAC token. The token is exported only if the response contains a non-empty string:

RBAC_TOKEN="$(
  jq -n \
    --arg appid "${WOLF_APP_ID}" \
    --arg username "${WOLF_USERNAME}" \
    --arg password "${WOLF_PASSWORD}" \
    '{appid: $appid, username: $username, password: $password}' | \
  curl -sS "http://127.0.0.1:9080/apisix/plugin/wolf-rbac/login" \
    -H 'Content-Type: application/json' \
    -d @- | \
  jq -er '.rbac_token | select(type == "string" and length > 0)'
)" &&
  export RBAC_TOKEN

Send a POST request with the token unchanged in the Authorization header. Do not add a Bearer prefix:

curl -i "http://127.0.0.1:9080/" -X POST \
  -H "Authorization: ${RBAC_TOKEN}"

The local fixture grants app-man permission to send GET requests to /, but not POST requests. Wolf therefore rejects the request with HTTP/1.1 403 Forbidden.

Send an authorized GET request:

curl -i "http://127.0.0.1:9080/" \
  -H "Authorization: ${RBAC_TOKEN}"

You should receive an HTTP/1.1 200 OK response with X-Wolf-UserId, X-Wolf-Username, and X-Wolf-Nickname headers.

The plugin also accepts the token in the x-rbac-token header, the rbac_token query parameter, or the x-rbac-token cookie.

By itself, wolf-rbac does not remove a token from its request source. The route above removes the Authorization header with proxy-rewrite. If clients use another source, prevent the upstream from receiving the corresponding header, query parameter, or cookie.

Connect to Wolf over HTTPS​

In production, configure an HTTPS Wolf address and set ssl_verify to true on the consumer. The gateway then verifies the Wolf server certificate when it logs in users and checks permissions:

{
  "wolf-rbac": {
    "appid": "restful-demo",
    "server": "https://wolf.internal.example",
    "header_prefix": "X-Wolf-",
    "ssl_verify": true
  }
}

When ssl_verify is omitted or set to false, the gateway does not verify the Wolf server certificate.

API Endpoints​

The plugin registers the following internal endpoints. Expose only the endpoints your clients need by creating routes with the public-api plugin.

The password-change and user-information endpoints require a valid Wolf token. See the wolf-rbac configuration reference for consumer fields and defaults.