跳到主要内容

**Model** 语法

每个 Model CONF 文件必须定义以下四个部分：[request_definition]、[policy_definition]、[policy_effect] 和 [matchers]。

  • 对于 RBAC，请添加 [role_definition] 部分。
  • 对于带约束的 RBAC（例如职责分离），您可以添加 [constraint_definition]。
  • 以 # 开头的行是注释；该行的其余部分将被忽略。

请求定义​

[request_definition] 部分定义了传递给 e.Enforce(...) 的参数。

[request_definition]
r = sub, obj, act

在这里，sub、obj 和 act 是标准的三元组：主体、对象和操作。您可以更改格式——例如，在没有资源时使用 sub, act，或在涉及两个主体时使用 sub, sub2, obj, act。

策略定义​

[policy_definition] 部分描述了策略规则的结构。例如：

[policy_definition]
p = sub, obj, act
p2 = sub, act

策略文件如下所示：

p, alice, data1, read
p2, bob, write-all-objects

策略文件中的每一行是一条规则。第一个标记是策略类型（p、p2 等），并且必须与某个策略定义匹配。上面的示例为匹配器生成了以下绑定：

(alice, data1, read) -> (p.sub, p.obj, p.act)
(bob, write-all-objects) -> (p2.sub, p2.act)
提示

策略规则元素始终被视为字符串。有关讨论，请参阅 casbin/casbin#113。

策略效果​

[policy_effect] 部分定义了当多个策略匹配时如何组合结果（例如，一个允许，另一个拒绝）。

[policy_effect]
e = some(where (p.eft == allow))

这实现了 allow-override：如果任何匹配的策略的效果为 allow，则结果为允许。p.eft 字段是策略效果（allow 或 deny）。它是可选的，省略时默认为 allow。

这里有一个替代的策略效果：

[policy_effect]
e = !some(where (p.eft == deny))

这实现了 deny-override：仅当没有匹配的策略的效果为 deny 时，结果才为允许。您可以使用逻辑运算符组合表达式：

[policy_effect]
e = some(where (p.eft == allow)) && !some(where (p.eft == deny))

该表达式要求至少有一个 allow 且没有 deny。Casbin 同时支持 allow 和 deny；当两者都匹配时，deny 胜出。

备注

策略效果必须是以下内置效果之一。当前实现不支持自定义效果表达式。

可用的内置策略效果：

策略效果含义示例
some(where (p.eft == allow))allow-overrideACL, RBAC, etc.
!some(where (p.eft == deny))deny-overrideDeny-override
some(where (p.eft == allow)) && !some(where (p.eft == deny))allow-and-denyAllow-and-deny
priority(p.eft) || denypriorityPriority
subjectPriority(p.eft)基于角色的优先级Subject-Priority

约束定义​

可选的 [constraint_definition] 部分为 RBAC 定义不变量（例如职责分离）。在角色分配变更时会检查约束。要使用约束，必须具有 [role_definition]。

[constraint_definition]
c = sod("finance_requester", "finance_approver")
c2 = sodMax(["payroll_view", "payroll_edit", "payroll_approve"], 1)
c3 = roleMax("superadmin", 2)
c4 = rolePre("db_admin", "security_trained")

约束类型​

职责分离 (sod) — 用户不能同时拥有这两个角色。如果 Alice 拥有 finance_requester，她就不能被分配 finance_approver。

c = sod("finance_requester", "finance_approver")

最大职责分离 (sodMax) — 限制用户可以从一组角色中拥有的数量。对薪资角色使用 sodMax(..., 1) 时，用户最多只能拥有 view、edit 或 approve 中的一个。

c2 = sodMax(["payroll_view", "payroll_edit", "payroll_approve"], 1)

角色基数 (roleMax) — 限制可以拥有某个角色的用户数量。例如，最多两个用户可以拥有 superadmin。

c3 = roleMax("superadmin", 2)

前置角色 (rolePre) — 必须先拥有一个角色才能拥有另一个角色。例如，用户在获得 db_admin 之前必须拥有 security_trained。

c4 = rolePre("db_admin", "security_trained")

约束的工作方式​

当分组策略发生变化时（例如 AddGroupingPolicy()、RemoveGroupingPolicy()），会强制执行约束。如果更改会违反约束，操作将失败并返回错误，且策略不会更新。

加载模型时，会根据当前策略检查所有约束。无效的约束（错误的语法、缺少 RBAC 设置或当前数据已违反约束）会导致加载失败并返回清晰的错误信息。

Matchers​

[matchers] 部分定义了如何将请求与策略规则进行匹配评估。

[matchers]
m = r.sub == p.sub && r.obj == p.obj && r.act == p.act

此 matcher 要求请求的主体 (subject)、对象 (object) 和操作 (action) 必须与策略字段完全匹配。

Matchers 支持算术运算符 (+, -, *, /) 和逻辑运算符 (&&, ||, !)。

Matcher 中的表达式顺序​

Matcher 中表达式的顺序可能会显著影响性能。示例如下：

const rbac_models = `
[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) && r.obj == p.obj && r.act == p.act
`

func TestManyRoles(t *testing.T) {

    m, _ := model.NewModelFromString(rbac_models)
    e, _ := NewEnforcer(m, false)

    roles := []string{"admin", "manager", "developer", "tester"}

    // 2500 projects
    for nbPrj := 1; nbPrj < 2500; nbPrj++ {
        // 4 objects and 1 role per object (so 4 roles)
        for _, role := range roles {
            roleDB := fmt.Sprintf("%s_project:%d", role, nbPrj)
            objectDB := fmt.Sprintf("/projects/%d", nbPrj)
            e.AddPolicy(roleDB, objectDB, "GET")
        }
        jasmineRole := fmt.Sprintf("%s_project:%d", roles[1], nbPrj)
        e.AddGroupingPolicy("jasmine", jasmineRole)
    }

    e.AddGroupingPolicy("abu", "manager_project:1")
    e.AddGroupingPolicy("abu", "manager_project:2499")

    // With same number of policies
    // User 'abu' has only two roles
    // User 'jasmine' has many roles (1 role per policy, here 2500 roles)

    request := func(subject, object, action string) {
        t0 := time.Now()
        resp, _ := e.Enforce(subject, object, action)
        tElapse := time.Since(t0)
        t.Logf("RESPONSE %-10s %s\t %s : %5v IN: %+v", subject, object, action, resp, tElapse)
        if tElapse > time.Millisecond*100 {
            t.Errorf("More than 100 milliseconds for %s %s %s : %+v", subject, object, action, tElapse)
        }
    }

    request("abu", "/projects/1", "GET")        // really fast because only 2 roles in all policies and at the beginning of the casbin_rule table
    request("abu", "/projects/2499", "GET")     // fast because only 2 roles in all policies
    request("jasmine", "/projects/1", "GET")    // really fast at the beginning of the casbin_rule table

    request("jasmine", "/projects/2499", "GET") // slow and fails the only 1st time   <<<< pb here
    request("jasmine", "/projects/2499", "GET") // fast maybe due to internal cache mechanism

    // same issue with non-existing roles
    // request("jasmine", "/projects/999999", "GET") // slow fails the only 1st time   <<<< pb here
    // request("jasmine", "/projects/999999", "GET") // fast maybe due to internal cache mechanism
}

执行时长可能达到 6 秒。

go test -run ^TestManyRoles$ github.com/casbin/casbin/v3 -v

=== RUN   TestManyRoles
    rbac_api_test.go:598: RESPONSE abu        /projects/1        GET :  true IN: 438.379µs
    rbac_api_test.go:598: RESPONSE abu        /projects/2499     GET :  true IN: 39.005173ms
    rbac_api_test.go:598: RESPONSE jasmine    /projects/1        GET :  true IN: 1.774319ms
    rbac_api_test.go:598: RESPONSE jasmine    /projects/2499     GET :  true IN: 6.164071648s
    rbac_api_test.go:600: More than 100 milliseconds for jasmine /projects/2499 GET : 6.164071648s
    rbac_api_test.go:598: RESPONSE jasmine    /projects/2499     GET :  true IN: 12.164122ms
--- FAIL: TestManyRoles (6.24s)
FAIL
FAIL    github.com/casbin/casbin/v3     6.244s
FAIL

将开销较小的条件放在前面，开销较大的条件（例如角色查找）放在后面。将上述示例中的 matcher 重新排序为：

[matchers]
m = r.obj == p.obj && g(r.sub, p.sub) && r.act == p.act
go test -run ^TestManyRoles$ github.com/casbin/casbin/v3 -v
=== RUN   TestManyRoles
    rbac_api_test.go:599: RESPONSE abu        /projects/1        GET :  true IN: 786.635µs
    rbac_api_test.go:599: RESPONSE abu        /projects/2499     GET :  true IN: 4.933064ms
    rbac_api_test.go:599: RESPONSE jasmine    /projects/1        GET :  true IN: 2.908534ms
    rbac_api_test.go:599: RESPONSE jasmine    /projects/2499     GET :  true IN: 7.292963ms
    rbac_api_test.go:599: RESPONSE jasmine    /projects/2499     GET :  true IN: 6.168307ms
--- PASS: TestManyRoles (0.05s)
PASS
ok      github.com/casbin/casbin/v3     0.053s

多种部分类型​

你可以定义多个带有后缀的请求、策略、效果或 matcher 部分，如 r2、p2、e2、m2。它们通过后缀配对：r2 通过 m2 与 p2 匹配，并与 e2 结合。

要使用非默认集，请将 EnforceContext 作为第一个参数传递给 enforce。结构如下：

EnforceContext{"r2","p2","e2","m2"}
type EnforceContext struct {
    RType string
    PType string
    EType string
    MType string
}

示例用法（参见 model 和 policy 示例）：

// Pass in a suffix as a parameter to NewEnforceContext, such as 2 or 3, and it will create r2, p2, etc.
enforceContext := NewEnforceContext("2")
// You can also specify a certain type individually
enforceContext.EType = "e"
// Don't pass in EnforceContext; the default is r, p, e, m
e.Enforce("alice", "data2", "read")        // true
// Pass in EnforceContext
e.Enforce(enforceContext, struct{ Age int }{Age: 70}, "/data1", "read")        //false
e.Enforce(enforceContext, struct{ Age int }{Age: 30}, "/data1", "read")        //true

特殊语法：in 运算符​

in 运算符检查右侧数组是否包含左侧的值（使用 == 相等性比较，不进行类型转换）。左侧可以是任何值；右侧必须是相同类型的数组。在 Go 语言中，数组必须是 []interface{}。

参考示例：rbac_model_matcher_using_in_op、keyget2_model 和 keyget_model。

示例：

[request_definition]
r = sub, obj
...
[matchers]
m = r.sub.Name in (r.obj.Admins)
e.Enforce(Sub{Name: "alice"}, Obj{Name: "a book", Admins: []interface{}{"alice", "bob"}})

表达式求值器​

Matchers 由特定语言的表达式引擎进行评估。Casbin 使用这些引擎来提供统一的 PERM 语法。某些引擎支持超出文档语法的额外功能；这些功能在其他语言中可能不可用。如果需要跨语言兼容性，请仅使用文档中记录的语法。

各实现使用的表达式求值器：

实现语言表达式求值器
CasbinGolanghttps://github.com/apache/casbin-govaluate
jCasbinJavahttps://github.com/killme2008/aviatorscript
Node-CasbinNode.jshttps://github.com/donmccurdy/expression-eval
PHP-CasbinPHPhttps://github.com/symfony/expression-language
PyCasbinPythonhttps://github.com/danthedeckie/simpleeval
Casbin.NETC#https://github.com/davideicardi/DynamicExpresso
Casbin4DDelphihttps://github.com/casbin4d/Casbin4D/tree/master/SourceCode/Common/Third%20Party/TExpressionParser
casbin-rsRusthttps://github.com/jonathandturner/rhai
casbin-cppC++https://github.com/ArashPartow/exprtk
备注

如果执行速度慢，表达式求值器通常是瓶颈。请参阅 Benchmarks 页面，并考虑向 Casbin 或求值器项目报告问题。

Comments are powered by giscus and GitHub Discussions. They load from giscus.app and GitHub only after you click the button below.