authz-casbin
#
Summary#
Nameauthz-casbin
is an authorization plugin based on Lua Casbin. This plugin supports powerful authorization scenarios based on various access control models.
For detailed documentation on how to create model and policy, refer Casbin.
#
AttributesName | Type | Requirement | Default | Valid | Description |
---|---|---|---|---|---|
model_path | string | required | The path of the Casbin model configuration file. | ||
policy_path | string | required | The path of the Casbin policy file. | ||
model | string | required | The Casbin model configuration in text format. | ||
policy | string | required | The Casbin policy in text format. | ||
username | string | required | The header you will be using in request to pass the username (subject). |
NOTE: You must either specify model_path
, policy_path
and username
in plugin config or specify model
, policy
and username
in the plugin config for the configuration to be valid. Or if you wish to use a global Casbin configuration, you can first specify model
and policy
in the plugin metadata and only username
in the plugin configuration, all routes will use the plugin metadata configuration in this way.
#
MetadataName | Type | Requirement | Default | Valid | Description |
---|---|---|---|---|---|
model | string | required | The Casbin model configuration in text format. | ||
policy | string | required | The Casbin policy in text format. |
#
How To EnableYou can enable the plugin on any route either by using the model/policy file paths or directly using the model/policy text.
#
By using file pathscurl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{ "plugins": { "authz-casbin": { "model_path": "/path/to/model.conf", "policy_path": "/path/to/policy.csv", "username": "user" } }, "upstream": { "nodes": { "127.0.0.1:1980": 1 }, "type": "roundrobin" }, "uri": "/*"}'
This will create a Casbin enforcer from the model and policy files at your first request.
#
By using model/policy textcurl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{ "plugins": { "authz-casbin": { "model": "[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.sub, p.sub)) && keyMatch(r.obj, p.obj) && keyMatch(r.act, p.act)",
"policy": "p, *, /, GET p, admin, *, * g, alice, admin",
"username": "user" } }, "upstream": { "nodes": { "127.0.0.1:1980": 1 }, "type": "roundrobin" }, "uri": "/*"}'
This will create a Casbin enforcer from the model and policy text at your first request.
#
By using model/policy text using plugin metadataFirst, send a PUT
request to add the model and policy text to the plugin's metadata using the Admin API. All routes configured in this way will use a single Casbin enforcer with plugin metadata configuration. You can also update the model/policy this way, the plugin will automatically update itself with the updated configuration.
curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/authz-casbin -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '{"model": "[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.sub, p.sub)) && keyMatch(r.obj, p.obj) && keyMatch(r.act, p.act)",
"policy": "p, *, /, GETp, admin, *, *g, alice, admin"}'
Then add this plugin on a route by sending the following request. Note, there is no requirement for model/policy now.
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{ "plugins": { "authz-casbin": { "username": "user" } }, "upstream": { "nodes": { "127.0.0.1:1980": 1 }, "type": "roundrobin" }, "uri": "/*"}'
NOTE: The plugin route configuration has a higher precedence than the plugin metadata configuration. Hence if the model/policy configuration is present in the plugin route config, the plugin will use that instead of the metadata config.
#
Test PluginWe defined the example model as:
[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.sub, p.sub)) && keyMatch(r.obj, p.obj) && keyMatch(r.act, p.act)
And the example policy as:
p, *, /, GETp, admin, *, *g, alice, admin
This means that anyone can access the homepage (/
) using GET
request method while only users with admin permissions can access other pages and use other request methods.
For example, here anyone can access the homepage with the GET request method and the request proceeds normally:
curl -i http://127.0.0.1:9080/ -X GET
If some unauthorized user bob
tries to access any other page, they will get a 403 error:
curl -i http://127.0.0.1:9080/res -H 'user: bob' -X GETHTTP/1.1 403 Forbidden
But someone with admin permissions like alice
can access it:
curl -i http://127.0.0.1:9080/res -H 'user: alice' -X GET
#
Disable PluginRemove the corresponding json configuration in the plugin configuration to disable the authz-casbin
plugin.
APISIX plugins are hot-reloaded, therefore no need to restart APISIX.
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{ "methods": ["GET"], "uri": "/*", "plugins": {}, "upstream": { "type": "roundrobin", "nodes": { "127.0.0.1:1980": 1 } }}'
#
ExamplesCheckout examples for model and policy conguration here.