Project: APISIX (Orchestration & Management / API Gateway)
File: authz-casbin.md

title: authz-casbin keywords: Apache APISIX API Gateway Plugin Authz Casbin authz-casbin description: This document contains information about the Apache APISIX authz-casbin Plugin. <!-- --> The `authz-casbin` Plugin is an authorization Plugin based on . This Plugin supports powerful authorization scenarios based on various . | Name | Type | Required | Description | |-|--|-|-| | model_path | string | True | Path of the Casbin model configuration file. | | policy_path | string | True | Path of the Casbin policy file. | | model | string | True | Casbin model configuration in text format. | | policy | string | True | Casbin policy in text format. | | username | string | True | Header in the request that will be used in the request to pass the username (subject). | :::note You must either specify the `modelpath`, `policypath`, and the `username` attributes or specify the `model`, `policy` and the `username` attributes in the Plugin configuration for it to be valid. If you wish to use a global Casbin configuration, you can first specify `model` and `policy` attributes in the Plugin metadata and only the `username` attribute in the Plugin configuration. All Routes will use the Plugin configuration this way. ::: | Name | Type | Required | Description | |--|--|-|--| | model | string | True | Casbin model configuration in text format. | | policy | string | True | Casbin policy in text format. | You can enable the Plugin on a Route by either using the model/policy file paths or using the model/policy text in Plugin configuration/metadata. The example below shows setting up Casbin authentication from your model/policy configuration file: :::note You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command: ```bash adminkey=$(yq '.deployment.admin.adminkey[0].key' conf/config.yaml | sed 's/"//g') ``` ::: ```shell curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -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": "/*" }' ``` The example below shows setting up Casbin authentication from your model/policy text in your Plugin configuration: ```shell curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -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": {

1 }, "type": "roundrobin" }, "uri": "/*" }' ``` First, you need to send a `PUT` request to the Admin API to add the `model` and `policy` text to the Plugin metadata. All Routes configured this way will use a single Casbin enforcer with the configured Plugin metadata. You can also update the model/policy in this way and the Plugin will automatically update to the new configuration. ```shell curl http://127.0.0.1:9180/apisix/admin/pluginmetadata/authz-casbin -H "X-API-KEY: $adminkey" -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, *, /, GET p, admin, , g, alice, admin" }' ``` Once you have updated the Plugin metadata, you can add the Plugin to a specific Route: ```shell curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -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. If the model/policy configuration is present in the Plugin Route configuration, it is used instead of the metadata configuration. ::: We define the example model as: ```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.sub, p.sub)) && keyMatch(r.obj, p.obj) && keyMatch(r.act, p.act) ``` And the example policy as: ```conf p, *, /, GET p, admin, , g, alice, admin ``` See for more policy and model configurations. The above configuration will let anyone access the homepage (`/`) using a `GET` request while only users with admin permissions can access other pages and use other request methods. So if we make a get request to the homepage: ```shell curl -i http://127.0.0.1:9080/ -X GET ``` But if an unauthorized user tries to access any other page, they will get a 403 error: ```shell curl -i http://127.0.0.1:9080/res -H 'user: bob' -X GET HTTP/1.1 403 Forbidden ``` And only users with admin privileges can access the endpoints: ```shell curl -i http://127.0.0.1:9080/res -H 'user: alice' -X GET ``` To remove the `authz-casbin` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. ```shell curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' { "methods": ["GET"], "uri": "/*", "plugins": {}, "upstream": { "type": "roundrobin", "nodes": { "127.0.0.1:1980": 1 } } }' ```