RBAC
Role Definition
The [role_definition]
is used to define the RBAC role inheritance relations. Casbin supports multiple instances of RBAC systems, where users can have roles and their inheritance relations, and resources can have roles and their inheritance relations too. These two RBAC systems won't interfere with each other.
此部分是可选的。 如果在模型中不使用 RBAC 角色, 则省略此部分。
[role_definition]
g = _, _
g2 = _, _
The above role definition shows that g
is an RBAC system, and g2
is another RBAC system. _,_
means there are two parties involved in an inheritance relation. In the most common case, you usually use g
alone if you only need roles for users. You can also use both g
and g2
when you need roles (or groups) for both users and resources. 请参见 rbac_model 和 rbac_model_with_resource_roles 的示例。
Casbin stores the actual user-role mapping (or resource-role mapping if you are using roles on resources) in the policy. For example:
p, data2_admin, data2, read
g, alice, data2_admin
It means that alice
inherits/is a member of the role data2_admin
. Here, alice
can be a user, a resource, or a role. Cabin 只是将其识别为一个字符串。
Then, in a matcher, you should check the role as shown below:
[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act
It means that the sub
in the request should have the role sub
in the policy.
- Casbin 只存储用户角色的映射关系。
- Casbin doesn't verify whether a user is a valid user or a role is a valid role. 这应该通过认证来解决。
- Do not use the same name for a user and a role inside an RBAC system, because Casbin recognizes users and roles as strings, and there's no way for Casbin to know whether you are specifying user
alice
or rolealice
. 这时,使用明确的role_alice
,问题便可迎刃而解。 - If
A
has roleB
, andB
has roleC
, thenA
has roleC
. 这种传递性在当前版本会造成死循环。
Conventionally, the subject token name in the policy definition is sub
and placed at the beginning. Now, Golang Casbin supports customized token names and places. If the subject token name is sub
, the subject token can be placed at an arbitrary place without any extra action needed. If the subject token name is not sub
, e.SetFieldIndex()
for constant.SubjectIndex
should be called after the enforcer is initialized, regardless of its position.
# `subject` here is for sub
[policy_definition]
p = obj, act, subject
e.SetFieldIndex("p", constant.SubjectIndex, 2) // index starts from 0
ok, err := e.DeleteUser("alice") // without SetFieldIndex, it will raise an error
Role Hierarchy
Casbin's RBAC supports RBAC1's role hierarchy feature, which means that if alice
has role1
, and role1
has role2
, then alice
will also have role2
and inherit its permissions.
Here, we have a concept called a hierarchy level. So, in this example, the hierarchy level is 2. For the built-in role manager in Casbin, you can specify the maximum hierarchy level. 默认值为10。 This means that an end user like alice
can only inherit 10 levels of roles.
// NewRoleManager is the constructor for creating an instance of the
// default RoleManager implementation.
func NewRoleManager(maxHierarchyLevel int) rbac.RoleManager {
rm := RoleManager{}
rm.allRoles = &sync.Map{}
rm.maxHierarchyLevel = maxHierarchyLevel
rm.hasPattern = false
return &rm
}
How to Distinguish Role from User?
Casbin doesn't distinguish between roles and users in its RBAC. They are both treated as strings. If you only use a single-level RBAC (where a role will never be a member of another role), you can use e.GetAllSubjects()
to get all users and e.GetAllRoles()
to get all roles. They will list all u
and all r
, respectively, in all g, u, r
rules.
But if you are using a multi-level RBAC (with role hierarchy) and your application doesn't record whether a name (string) is a user or a role, or you have a user and a role with the same name, you can add a prefix to the role like role::admin
before passing it to Casbin. This way, you will know if it's a role by checking this prefix.
How to Query Implicit Roles or Permissions?
When a user inherits a role or permission via RBAC hierarchy instead of being directly assigned them in a policy rule, we call this type of assignment "implicit". To query such implicit relations, you need to use these two APIs: GetImplicitRolesForUser()
and GetImplicitPermissionsForUser()
instead of GetRolesForUser()
and GetPermissionsForUser()
. 有关详情,请参阅 this GitHub issue。
Using Pattern Matching in RBAC
详情请参阅 RBAC with Pattern
Role Manager
See the Role Managers section for details.