authz-casbin.md

title	keywords	description
authz-casbin	Apache APISIX API Gateway Plugin Authz Casbin authz-casbin	This document contains information about the Apache APISIX authz-casbin Plugin.

Description

The authz-casbin Plugin is an authorization Plugin based on Lua Casbin. This Plugin supports powerful authorization scenarios based on various access control models.

Attributes

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 model_path, policy_path, 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.

:::

Metadata

Name	Type	Required	Description
model	string	True	Casbin model configuration in text format.
policy	string	True	Casbin policy in text format.

Enable Plugin

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.

By using model/policy file paths

The example below shows setting up Casbin authentication from your model/policy configuration file:

curl http://127.0.0.1:9180/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": "/*"
}'

By using model/policy text in Plugin configuration

The example below shows setting up Casbin authentication from your model/policy text in your Plugin configuration:

curl http://127.0.0.1:9180/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": "/*"
}'

By using model/policy text in Plugin metadata

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.

curl http://127.0.0.1:9180/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, *, /, GET
p, admin, *, *
g, alice, admin"
}'

Once you have updated the Plugin metadata, you can add the Plugin to a specific Route:

curl http://127.0.0.1:9180/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. If the model/policy configuration is present in the Plugin Route configuration, it is used instead of the metadata configuration.

:::

Example usage

We define 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, *, /, GET
p, admin, *, *
g, alice, admin

See examples 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:

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:

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:

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

Delete Plugin

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.

curl http://127.0.0.1:9180/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
        }
    }
}'