authz-casbin - Apisix

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:

:::note You can fetch the admin_key from config.yaml and save to an environment variable with the following command:

bash

admin_key=$(yq '.deployment.admin.admin_key[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": "/*"
}'

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:

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": {
            "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.

shell

curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/authz-casbin -H "X-API-KEY: $admin_key" -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.

:::

Example usage

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

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

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.

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
        }
    }
}'