authz-casbin

Authorizes requests with a Casbin model and policy.

Category AuthenticationAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin authz-casbinPriority 2560

What it does

authz-casbin decides by a Casbin model and policy whether a caller may send a request's method to its path. It reads the caller's name from the request header named under Username, and each line of the Policy allows one user one path and one method. The model and the policy are written under Written here, read from files on the gateway host under Read from files, or kept once for the environment in the plugin metadata.

The plugin does not check who the caller is; it trusts the header. Add key-auth to the same route with a higher Priority, 2600 in the examples, and name X-Consumer-Username. The header then carries the consumer's username, whatever the client sent. A request the policy does not allow is answered 403 with Access Denied, and one without a key 401 by key-auth.

When to use it

• Who may change orders and who may only read them is kept as a list of rules: one client may read and create orders, a partner may only read them.
• Several routes, /orders and /invoices for example, share one policy kept once in the plugin metadata, and each route names only the header.
• The operations team deploys the model and the policy as files to every gateway host, and the routes read them from there.
• Every client already holds a key, and the rules of what each one may call depend on the path and the method, not on the route alone.

Not for letting whole consumers onto a route or keeping them off it — see consumer-restriction (Allows or denies requests by consumer, group, route or service), permissions kept in Keycloak's authorization services — see authz-keycloak (Authorizes requests with Keycloak's authorization services) or a decision an authorization service of your own makes — see forward-auth (Delegates authentication to an external service).

Set it up

Allow each user only the paths and methods listed in a policy written here

Needs key-auth on the same route with _meta.priority 2600, so that it signs the caller in before this plugin decides. The gateway then sets X-Consumer-Username to the consumer's name and overwrites any value the client sent, and the policy's users are the consumers' names. A request without a valid key is refused by key-auth before this plugin runs.

Set Username to X-Consumer-Username, choose Written here, set Model to [request_definition] r = sub, obj, act [policy_definition] p = sub, obj, act [policy_effect] e = some(where (p.eft == allow)) [matchers] m = r.sub == p.sub && r.obj == p.obj && r.act == p.act and set Policy to p, alice, /orders, GET p, alice, /orders, POST p, bob, /orders, GET.

authz-casbin · as the console saves it

{
  "username": "X-Consumer-Username",
  "model": "[request_definition]\nr = sub, obj, act\n\n[policy_definition]\np = sub, obj, act\n\n[policy_effect]\ne = some(where (p.eft == allow))\n\n[matchers]\nm = r.sub == p.sub && r.obj == p.obj && r.act == p.act",
  "policy": "p, alice, /orders, GET\np, alice, /orders, POST\np, bob, /orders, GET"
}

More scenarios

Read the model and the policy from files on the gateway host

Needs key-auth on the same route with _meta.priority 2600, so that it signs the caller in before this plugin decides. The gateway then sets X-Consumer-Username to the consumer's name and overwrites any value the client sent, and the policy's users are the consumers' names. A request without a valid key is refused by key-auth before this plugin runs.

Set Username to X-Consumer-Username, choose Read from files, set Model path to /etc/gateway/casbin/model.conf and set Policy path to /etc/gateway/casbin/policy.csv.

authz-casbin · as the console saves it

{
  "username": "X-Consumer-Username",
  "model_path": "/etc/gateway/casbin/model.conf",
  "policy_path": "/etc/gateway/casbin/policy.csv"
}

Share one model and one policy with every route that names only a username headerenvironment-wide settings

Needs key-auth on the same route with _meta.priority 2600, so that it signs the caller in before this plugin decides. The gateway then sets X-Consumer-Username to the consumer's name and overwrites any value the client sent, and the policy's users are the consumers' names. A request without a valid key is refused by key-auth before this plugin runs.

Set Model to [request_definition] r = sub, obj, act [policy_definition] p = sub, obj, act [policy_effect] e = some(where (p.eft == allow)) [matchers] m = r.sub == p.sub && r.obj == p.obj && r.act == p.act and set Policy to p, alice, /orders, GET p, bob, /invoices, GET.

authz-casbin environment-wide settings · as the console saves it

{
  "model": "[request_definition]\nr = sub, obj, act\n\n[policy_definition]\np = sub, obj, act\n\n[policy_effect]\ne = some(where (p.eft == allow))\n\n[matchers]\nm = r.sub == p.sub && r.obj == p.obj && r.act == p.act",
  "policy": "p, alice, /orders, GET\np, bob, /invoices, GET"
}

Things to know

• Policy — With alice allowed GET and POST on /orders and bob allowed only GET, both read orders, and bob's POST is answered 403 with Access Denied.
• Username — With X-Consumer-Username and key-auth running first, a client that writes that header itself is still judged as the consumer its key names. Bob's POST with alice's name in the header is answered 403.
• Username — With neither pair written the configuration is stored only while this plugin's metadata carries a model and a policy, and every such route reads them.
• On a route that names only the header, the model and the policy of the plugin metadata decide. With alice allowed /orders and bob /invoices, alice's request to /invoices is answered 403.
• Model — Checked only at the first request. A model or policy that cannot be read is saved anyway, and every request then answers 500.
• Policy — Whatever the model defines, the plugin checks three values: the header value, the request path and the method.
• Policy — A model without a policy is refused when you save.
• Model path — Read by each gateway node at the first request. A node that cannot open the file answers 500 to every request.
• Model path — A model path beside a model written here is refused when you save; the two shapes exclude each other.
• AdviceName the header an authentication plugin on the same route writes, never one the client chooses, so that the names in the policy are names the gateway checked.
• On a consumer or a consumer group it runs only after the consumer has been identified by a credential; it does not identify the consumer itself.

Settings

The fields as the console shows them, section by section.

UsernameusernamestringRequired

The request header that carries the user name, such as X-User. A request without it is checked as the user anonymous.

Choose one:

• Written hereKeep the model and the policy in this configuration.
• Read from filesRead the model and the policy from two paths the gateway host can open.

Written here

ModelmodelstringRequired

at least 1 character

PolicypolicystringRequired

One rule per line, such as p, alice, /orders/*, GET: the user from the header, the request path and the method. The fields follow the model's policy definition; the plugin always checks the header value, the request path and the method.

at least 1 character

Read from files

Model pathmodel_pathstringRequired

at least 1 character

Policy pathpolicy_pathstringRequired

at least 1 character

Environment-wide settings

Set once per environment, under Plugins › authz-casbin. Every authz-casbin in the environment uses these.

ModelmodelstringRequired

Read by every route of this plugin whose own configuration carries neither a text nor a path.

at least 1 character

PolicypolicystringRequired

at least 1 character

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.