authz-casbin

Summary

Name

authz-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.

Attributes

NameTypeRequirementDefaultValidDescription
model_pathstringrequiredThe path of the Casbin model configuration file.
policy_pathstringrequiredThe path of the Casbin policy file.
modelstringrequiredThe Casbin model configuration in text format.
policystringrequiredThe Casbin policy in text format.
usernamestringrequiredThe 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.

Metadata

NameTypeRequirementDefaultValidDescription
modelstringrequiredThe Casbin model configuration in text format.
policystringrequiredThe Casbin policy in text format.

How To Enable

You 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 paths

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "plugins": {
  4.         "authz-casbin": {
  5.             "model_path": "/path/to/model.conf",
  6.             "policy_path": "/path/to/policy.csv",
  7.             "username": "user"
  8.         }
  9.     },
  10.     "upstream": {
  11.         "nodes": {
  12.             "127.0.0.1:1980": 1
  13.         },
  14.         "type": "roundrobin"
  15.     },
  16.     "uri": "/*"
  17. }'

This will create a Casbin enforcer from the model and policy files at your first request.

By using model/policy text

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "plugins": {
  4.         "authz-casbin": {
  5.             "model": "[request_definition]
  6.             r = sub, obj, act
  9.             [policy_definition]
  10.             p = sub, obj, act
  13.             [role_definition]
  14.             g = _, _
  17.             [policy_effect]
  18.             e = some(where (p.eft == allow))
  21.             [matchers]
  22.             m = (g(r.sub, p.sub) || keyMatch(r.sub, p.sub)) && keyMatch(r.obj, p.obj) && keyMatch(r.act, p.act)",
  25.             "policy": "p, *, /, GET
  26.             p, admin, *, *
  27.             g, alice, admin",
  30.             "username": "user"
  31.         }
  32.     },
  33.     "upstream": {
  34.         "nodes": {
  35.             "127.0.0.1:1980": 1
  36.         },
  37.         "type": "roundrobin"
  38.     },
  39.     "uri": "/*"
  40. }'

This will create a Casbin enforcer from the model and policy text at your first request.

By using model/policy text using plugin metadata

First, 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.

  1. curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/authz-casbin -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -i -X PUT -d '
  2. {
  3. "model": "[request_definition]
  4. r = sub, obj, act
  7. [policy_definition]
  8. p = sub, obj, act
  11. [role_definition]
  12. g = _, _
  15. [policy_effect]
  16. e = some(where (p.eft == allow))
  19. [matchers]
  20. m = (g(r.sub, p.sub) || keyMatch(r.sub, p.sub)) && keyMatch(r.obj, p.obj) && keyMatch(r.act, p.act)",
  23. "policy": "p, *, /, GET
  24. p, admin, *, *
  25. g, alice, admin"
  26. }'

Then add this plugin on a route by sending the following request. Note, there is no requirement for model/policy now.

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "plugins": {
  4.         "authz-casbin": {
  5.             "username": "user"
  6.         }
  7.     },
  8.     "upstream": {
  9.         "nodes": {
  10.             "127.0.0.1:1980": 1
  11.         },
  12.         "type": "roundrobin"
  13.     },
  14.     "uri": "/*"
  15. }'

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 Plugin

We defined the example model as:

  1. [request_definition]
  2. r = sub, obj, act
  5. [policy_definition]
  6. p = sub, obj, act
  9. [role_definition]
  10. g = _, _
  13. [policy_effect]
  14. e = some(where (p.eft == allow))
  17. [matchers]
  18. 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:

  1. p, *, /, GET
  2. p, admin, *, *
  3. 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:

  1. 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:

  1. curl -i http://127.0.0.1:9080/res -H 'user: bob' -X GET
  2. HTTP/1.1 403 Forbidden

But someone with admin permissions like alicecan access it:

  1. curl -i http://127.0.0.1:9080/res -H 'user: alice' -X GET

Disable Plugin

Remove 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.

  1. $ curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "methods": ["GET"],
  4.     "uri": "/*",
  5.     "plugins": {},
  6.     "upstream": {
  7.         "type": "roundrobin",
  8.         "nodes": {
  9.             "127.0.0.1:1980": 1
  10.         }
  11.     }
  12. }'

Examples

Checkout examples for model and policy conguration here.