title | keywords | description | ||||
---|---|---|---|---|---|---|
authz-casbin |
|
This document contains information about the Apache APISIX authz-casbin Plugin. |
The authz-casbin
Plugin is an authorization Plugin based on Lua Casbin. This Plugin supports powerful authorization scenarios based on various access control models.
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.
:::
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:
curl http://127.0.0.1:9080/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": "/*"
}'
The example below shows setting up Casbin authentication from your model/policy text in your Plugin configuration:
curl http://127.0.0.1:9080/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": "/*"
}'
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:9080/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:9080/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.
:::
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
To disable 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:9080/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
}
}
}'