Skip to main content

RBAC API

A more friendly API for RBAC. This API is a subset of Management API. The RBAC users could use this API to simplify the code.

Reference

global variable e is Enforcer instance.

e, err := NewEnforcer("examples/rbac_model.conf", "examples/rbac_policy.csv")

GetRolesForUser()

GetRolesForUser gets the roles that a user has.

For example:

res := e.GetRolesForUser("alice")

GetUsersForRole()

GetUsersForRole gets the users that has a role.

For example:

res := e.GetUsersForRole("data1_admin")

HasRoleForUser()

HasRoleForUser determines whether a user has a role.

For example:

res := e.HasRoleForUser("alice", "data1_admin")

AddRoleForUser()

AddRoleForUser adds a role for a user. Returns false if the user already has the role (aka not affected).

For example:

e.AddRoleForUser("alice", "data2_admin")

AddRolesForUser()

AddRolesForUser adds multiple roles for a user. Returns false if the user already has one of these roles (aka not affected).

For example:

var roles = []string{"data2_admin", "data1_admin"}
e.AddRolesForUser("alice", roles)

DeleteRoleForUser()

DeleteRoleForUser deletes a role for a user. Returns false if the user does not have the role (aka not affected).

For example:

e.DeleteRoleForUser("alice", "data1_admin")

DeleteRolesForUser()

DeleteRolesForUser deletes all roles for a user. Returns false if the user does not have any roles (aka not affected).

For example:

e.DeleteRolesForUser("alice")

DeleteUser()

DeleteUser deletes a user. Returns false if the user does not exist (aka not affected).

For example:

e.DeleteUser("alice")

DeleteRole()

DeleteRole deletes a role.

For example:

e.DeleteRole("data2_admin")

DeletePermission()

DeletePermission deletes a permission. Returns false if the permission does not exist (aka not affected).

For example:

e.DeletePermission("read")

AddPermissionForUser()

AddPermissionForUser adds a permission for a user or role. Returns false if the user or role already has the permission (aka not affected).

For example:

e.AddPermissionForUser("bob", "read")

AddPermissionsForUser()

AddPermissionsForUser adds multiple permissions for a user or role. Returns false if the user or role already has one of the permissions (aka not affected).

For example:

var permissions = [][]string{{"data1", "read"},{"data2","write"}}
for i := 0; i < len(permissions); i++ {
e.AddPermissionsForUser("alice", permissions[i])
}

DeletePermissionForUser()

DeletePermissionForUser deletes a permission for a user or role. Returns false if the user or role does not have the permission (aka not affected).

For example:

e.DeletePermissionForUser("bob", "read")

DeletePermissionsForUser()

DeletePermissionsForUser deletes permissions for a user or role. Returns false if the user or role does not have any permissions (aka not affected).

For example:

e.DeletePermissionsForUser("bob")

GetPermissionsForUser()

GetPermissionsForUser gets permissions for a user or role.

For example:

e.GetPermissionsForUser("bob")

HasPermissionForUser()

HasPermissionForUser determines whether a user has a permission.

For example:

e.HasPermissionForUser("alice", []string{"read"})

GetImplicitRolesForUser()

GetImplicitRolesForUser gets implicit roles that a user has. Compared to GetRolesForUser(), this function retrieves indirect roles besides direct roles.

For example:
g, alice, role:admin
g, role:admin, role:user

GetRolesForUser("alice") can only get: ["role:admin"].
But GetImplicitRolesForUser("alice") will get: ["role:admin", "role:user"].

For example:

e.GetImplicitRolesForUser("alice")

GetImplicitUsersForRole()

GetImplicitUsersForRole gets all users inheriting the role. Compared to GetUsersForRole(), this function retrieves indirect users.

For example:
g, alice, role:admin
g, role:admin, role:user

GetUsersForRole("role:user") can only get: ["role:admin"].
But GetImplicitUesrsForRole("role:user") will get: ["role:admin", "alice"].

For example:

users := e.GetImplicitUsersForRole("role:user")

GetImplicitPermissionsForUser()

GetImplicitPermissionsForUser gets implicit permissions for a user or role.
Compared to GetPermissionsForUser(), this function retrieves permissions for inherited roles.

For example:
p, admin, data1, read
p, alice, data2, read
g, alice, admin

GetPermissionsForUser("alice") can only get: [["alice", "data2", "read"]].
But GetImplicitPermissionsForUser("alice") will get: [["admin", "data1", "read"], ["alice", "data2", "read"]].

For example:

e.GetImplicitPermissionsForUser("alice")

GetNamedImplicitPermissionsForUser()

GetNamedImplicitPermissionsForUser gets implicit permissions for a user or role by named policy Compared to GetImplicitPermissionsForUser(), this function allow you to specify the policy name.

For example: p, admin, data1, read p2, admin, create g, alice, admin

GetImplicitPermissionsForUser("alice") only get: [["admin", "data1", "read"]], whose policy is default "p"

But you can specify the policy as "p2" to get: [["admin", "create"]] by GetNamedImplicitPermissionsForUser("p2","alice")

For example:

e.GetNamedImplicitPermissionsForUser("p2","alice")

GetDomainsForUser()

GetDomainsForUser gets all domains which a user has.

For example: p, admin, domain1, data1, read p, admin, domain2, data2, read p, admin, domain2, data2, write g, alice, admin, domain1 g, alice, admin, domain2

GetDomainsForUser("alice") could get ["domain1", "domain2"]

For example:

result, err := e.GetDomainsForUser("alice")

GetImplicitResourcesForUser()

GetImplicitResourcesForUser returns all policies that should be true for user.

For example:

p, alice, data1, read
p, bob, data2, write
p, data2_admin, data2, read
p, data2_admin, data2, write

g, alice, data2_admin

GetImplicitResourcesForUser("alice") will return [[alice data1 read] [alice data2 read] [alice data2 write]]

resources, err := e.GetImplicitResourcesForUser("alice")

GetImplicitUsersForPermission()

GetImplicitUsersForPermission gets implicit users for a permission.

For example:

p, admin, data1, read
p, bob, data1, read
g, alice, admin

GetImplicitUsersForPermission("data1", "read") will return: ["alice", "bob"].

Note: only users will be returned, roles (2nd arg in "g") will be excluded.

users, err := e.GetImplicitUsersForPermission("data1", "read")

GetAllowedObjectConditions()

GetAllowedObjectConditions returns a string array of object conditions that the user can access.

For example:

p, alice, r.obj.price < 25, read
p, admin, r.obj.category_id = 2, read
p, bob, r.obj.author = bob, write

g, alice, admin

e.GetAllowedObjectConditions("alice", "read", "r.obj.") will return ["price < 25", "category_id = 2"], nil

Note:

  1. prefix: You can customize the prefix of the object conditions, and "r.obj." is commonly used as a prefix. After removing the prefix, the remaining part is the condition of the object. If there is an obj policy that does not meet the prefix requirement, an errors.ERR_OBJ_CONDITION will be returned.

  2. If the 'objectConditions' array is empty, return errors.ERR_EMPTY_CONDITION This error is returned because some data adapters' ORM return full table data by default when they receive an empty condition, which tends to behave contrary to expectations.(e.g. GORM) If you are using an adapter that does not behave like this, you can choose to ignore this error.

conditions, err := e.GetAllowedObjectConditions("alice", "read", "r.obj.")

GetImplicitUsersForResource()

GetImplicitUsersForResource return implicit user based on resource.

For example:

p, alice, data1, read
p, bob, data2, write
p, data2_admin, data2, read
p, data2_admin, data2, write
g, alice, data2_admin

GetImplicitUsersForResource("data2") will return [["bob", "data2", "write"], ["alice", "data2", "read"] ["alice", "data2", "write"]], nil.

GetImplicitUsersForResource("data1") will return [["alice", "data1", "read"]], nil.

ImplicitUsers, err := e.GetImplicitUsersForResource("data2")
note

Only users will be returned, roles (2nd arg in "g") will be excluded.