Skip to main content

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 RBAC token and selects the matching gateway consumer. It then asks Wolf whether that user can perform the request method on the requested URI.

Before it checks the RBAC token, the plugin removes client-supplied values for the identity headers. When Wolf permits the request and returns user information, the gateway adds the verified user's ID, username, and nickname to the upstream request and the client response. The header_prefix configured on the route or service sets the header names. With the default 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 and check out version 0.8.0:

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

Create docker-compose.docs.yaml to build the Wolf server locally from the checked-out 0.8.0 source:

docker-compose.docs.yaml
services:
server:
image: wolf-server-docs:0.8.0
build:
context: ../server

Start the Wolf database, cache, and source-built server:

docker compose \
-f docker-compose.yaml \
-f docker-compose.docs.yaml \
up -d --build 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}"
}
}
}
EOF

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

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

Create a protected route that accepts GET and POST requests. Enable wolf-rbac with a custom identity header prefix, and remove the RBAC 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": {
"header_prefix": "X-Wolf-"
},
"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 RBAC token.

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

❸ 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 an RBAC 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 an RBAC 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 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 RBAC 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 RBAC 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 an RBAC 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",
"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.

MethodEndpointPurpose
POST/apisix/plugin/wolf-rbac/loginAuthenticate a Wolf user and return an rbac_token.
PUT/apisix/plugin/wolf-rbac/change_pwdChange the authenticated Wolf user's password.
GET/apisix/plugin/wolf-rbac/user_infoReturn information about the authenticated Wolf user.

The password-change and user-information endpoints require a valid RBAC token. These endpoints use the server and ssl_verify of the consumer whose appid matches the request. See the wolf-rbac configuration reference for consumer fields and defaults.

Upgrade​

In APISIX 3.20.0 and API7 Enterprise 3.10.10, header_prefix is configured on routes and services instead of consumers. appid, server, and ssl_verify stay on the consumer, and appid is required.

After the upgrade, the gateway does not load a consumer whose wolf-rbac configuration sets no appid or sets header_prefix to a value other than X-. Requests to routes protected by wolf-rbac with RBAC tokens for such a consumer fail with HTTP 401. A consumer that sets header_prefix to X- is accepted, and the value is ignored.

Before you upgrade:

  • Set appid on every consumer that has none. A consumer without appid previously matched tokens for the application ID unset, so set appid to unset to keep accepting the same tokens.
  • Move each custom header_prefix from the consumer to every route or service that uses wolf-rbac, including wolf-rbac configured inside multi-auth, and then remove it from the consumer.
  • If consumers with different custom prefixes share a route or service, choose one prefix for that route or service and update its upstream to expect it, or move the traffic to separate routes or services with their own prefixes.

Gateway instances that are not yet upgraded take header_prefix only from the consumer and ignore it on routes and services. From the moment you remove a custom header_prefix from a consumer until every gateway instance in the gateway group is upgraded, those instances send the identity headers with the default X- prefix. Upstreams that depend on the custom prefix must also accept the X- headers during the rollout.