Skip to main content

Casbin Authorization

The authz-casbin plugin authorizes requests with Casbin models and policies before they reach an upstream. It can apply a policy to one route or reuse a shared policy across routes, supporting role-based and other Casbin access-control models.

Authorization Behavior​

The plugin evaluates three request values against the configured policy:

Casbin valueRequest value
SubjectValue of the configured request header, or anonymous when the header is absent.
ObjectNormalized request path.
ActionHTTP request method.

An allowed request continues to the upstream. A denied request returns 403 Forbidden with an Access Denied message.

The plugin uses the configured header value as the subject without authenticating it. In production, ensure that a trusted component establishes the value and that clients cannot override it.

Examples​

The examples first configure a role-based policy on one route. The second example moves the policy to plugin metadata so that it can be reused and updated independently of the route.

Create and enter a working directory for the example:

mkdir authz-casbin-example
cd authz-casbin-example

If Admin API authentication is enabled, export an admin-role key as ADMIN_API_KEY before using the Admin API tab.

Authorize a Role on One Route​

The example policy gives the reader role permission to send GET requests to paths under /anything/ and assigns that role to Alice.

Create the Casbin model:

model.conf
[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, p.sub) && keyMatch(r.obj, p.obj) && keyMatch(r.act, p.act)

Create the policy:

policy.csv
p, reader, /anything/*, GET
g, alice, reader

Create the route with the model and policy embedded as text:

jq -n \
--rawfile model model.conf \
--rawfile policy policy.csv \
'{
uri: "/anything/*",
plugins: {
"authz-casbin": {
model: $model,
policy: $policy,
username: "x-user"
}
},
upstream: {
type: "roundrobin",
nodes: {
"httpbin.org:80": 1
}
}
}' | \
curl "http://127.0.0.1:9180/apisix/admin/routes/authz-casbin-route" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-H "Content-Type: application/json" \
--data-binary @-

Send a request as Alice:

curl "http://127.0.0.1:9080/anything/article" \
-H "X-User: alice" \
--silent \
--output /dev/null \
--write-out "Allowed response: %{http_code}\n"

The assigned role allows the request to reach the upstream:

Allowed response: 200

Send the same request as Bob:

curl --include "http://127.0.0.1:9080/anything/article" \
-H "X-User: bob"

The policy denies the request:

HTTP/1.1 403 Forbidden
...
{"message":"Access Denied"}

Share a Policy with Plugin Metadata​

Plugin metadata lets routes reuse one model and policy. Update the policy from the first example to assign the reader role to Bob, then configure the route to read the shared policy.

A route configured with only the subject header depends on complete model and policy metadata. If that metadata is missing, the gateway returns 503 Service Unavailable without contacting the upstream.

Update policy.csv:

policy.csv
p, reader, /anything/*, GET
g, bob, reader

Store the model and updated policy in plugin metadata:

jq -n \
--rawfile model model.conf \
--rawfile policy policy.csv \
'{model: $model, policy: $policy}' | \
curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/authz-casbin" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-H "Content-Type: application/json" \
--data-binary @-

Replace the route-level model and policy with the header selection:

curl "http://127.0.0.1:9180/apisix/admin/routes/authz-casbin-route/plugins/authz-casbin" -X PATCH \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"username": "x-user"
}'

Send the request as Bob again:

curl "http://127.0.0.1:9080/anything/article" \
-H "X-User: bob" \
--silent \
--output /dev/null \
--write-out "Allowed response: %{http_code}\n"

The shared policy now allows Bob to reach the upstream:

Allowed response: 200

Send a request without the configured identity header:

curl --include "http://127.0.0.1:9080/anything/article"

The plugin evaluates the request as the anonymous subject and denies it:

HTTP/1.1 403 Forbidden
...
{"message":"Access Denied"}