Skip to content

Latest commit

 

History

History
263 lines (201 loc) · 7.87 KB

authz-casbin.md

File metadata and controls

263 lines (201 loc) · 7.87 KB
Raw
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:

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

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

:::

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:

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.

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:

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:

[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: $admin_key" -X PUT -d '
{
    "methods": ["GET"],
    "uri": "/*",
    "plugins": {},
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'