# Wolf RBAC

The `wolf-rbac` plugin integrates APISIX and API7 Gateway with [Wolf](https://github.com/iGeeky/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[​](#examples "Direct link to Examples")

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

### Authorize Requests with Wolf RBAC[​](#authorize-requests-with-wolf-rbac "Direct link to Authorize Requests with Wolf RBAC")

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

#### Set Up Wolf[​](#set-up-wolf "Direct link to 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](https://github.com/iGeeky/wolf/blob/0.8.0/quick-start-with-docker/README.md) 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](#connect-to-wolf-over-https).

#### Configure a Consumer and Routes[​](#configure-a-consumer-and-routes "Direct link to 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[​](#verify-access "Direct link to 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[​](#connect-to-wolf-over-https "Direct link to 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[​](#api-endpoints "Direct link to API Endpoints")

The plugin registers the following internal endpoints. Expose only the endpoints your clients need by creating routes with the [`public-api`](https://docs.api7.ai/hub/public-api.md) plugin.

| Method | Endpoint                              | Purpose                                               |
| ------ | ------------------------------------- | ----------------------------------------------------- |
| `POST` | `/apisix/plugin/wolf-rbac/login`      | Authenticate a Wolf user and return an `rbac_token`.  |
| `PUT`  | `/apisix/plugin/wolf-rbac/change_pwd` | Change the authenticated Wolf user's password.        |
| `GET`  | `/apisix/plugin/wolf-rbac/user_info`  | Return 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](https://docs.api7.ai/hub/wolf-rbac/configuration.md) for consumer fields and defaults.

## Upgrade[​](#upgrade "Direct link to 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`](https://docs.api7.ai/hub/multi-auth.md), 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.
