What is RBAC? Role-Based Access Control in Casbin

What is RBAC?

Role-based access control (RBAC) grants permissions to roles instead of to individual users, and gives each user one or more roles. To let a new employee do their job you assign them a role such as editor or billing; to change what all editors can do you change the role once.

RBAC has three parts:

• Users: people or services that make requests.
• Roles: named job functions, such as admin, editor or viewer.
• Permissions: an action on a resource, such as edit on /articles.

A request is allowed when one of the user's roles holds the permission. Roles can also inherit from other roles: if editor inherits from viewer, editors get everything viewers can do. RBAC was formalized by NIST in the 1990s, and the RBAC96 family of models describes the variants: flat roles, role hierarchies and constraints. See RBAC vs. RBAC96 for how Casbin maps to them.

A minimal RBAC model and policy in Casbin:

[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

p, editor, article, edit
p, viewer, article, read

g, editor, viewer
g, alice, editor
g, bob, viewer

alice may edit and read articles (editor inherits viewer); bob may only read them.

RBAC vs ABAC: RBAC is easy to audit but cannot say "only their own records" without creating a role per record. ABAC adds conditions on attributes such as the owner or the time of day, and most applications combine both. Choosing an access control model compares ACL, RBAC, ABAC and ReBAC on one example.

Tutorials: add RBAC to a web API in Go with Gin, Node.js with Express, NestJS, Python with FastAPI, Java with Spring Boot, Rust or gRPC. You can also try the RBAC examples in the online editor.

Role definition

The [role_definition] section defines RBAC role (inheritance) relationships. Casbin can run several RBAC systems at once: one for users (with role inheritance) and optionally one for resources. Each is independent.

This section is optional; omit it if you are not using RBAC.

[role_definition]
g = _, _
g2 = _, _

Here g and g2 are two role systems; _, _ means each has two sides (e.g. user and role). Use only g for user roles; add g2 when resources have roles too. Examples: rbac_model.conf, rbac_with_resource_roles_model.conf.

User–role (and resource–role) mappings are stored in the policy, for example:

p, data2_admin, data2, read
g, alice, data2_admin

So alice has role data2_admin. Casbin treats all names as strings (user, resource, or role).

Use the role in a matcher:

[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act

So the request is allowed only if the request subject has the role given in the policy.

ملاحظة

1. Casbin only stores and evaluates user–role (and resource–role) mappings; it does not validate that users or roles exist. That is the job of authentication.
2. Do not reuse the same name for a user and a role (e.g. user alice and role alice), since Casbin cannot tell them apart. Use a prefix (e.g. role_alice) if needed.
3. Role inheritance is transitive and unbounded: if A has role B and B has role C, then A effectively has role C.

Token name convention

The subject in the policy is usually named sub and listed first. In Go Casbin you can use other names and order; then you must call e.SetFieldIndex("p", constant.SubjectIndex, index) after creating the enforcer so that APIs like DeleteUser use the correct column.

# `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

Named role systems and permission dependencies

g, g2, g3, ... are independent role systems. Each one defines a graph that the matcher calls by the same name; g2 is not a built-in "permission depends on permission" relation. A row such as g2, edit, read is only an edge — it changes a decision only if the matcher asks g2(...).

That matters when your permission catalog has dependencies, for example "edit implies read", so a role that may edit must also be allowed to read. There are two clean ways to model it.

Use role inheritance when the dependency is part of authorization. Give each bundle a role and let the roles inherit:

p, editor, article, edit
p, viewer, article, read

g, editor, viewer
g, alice, editor

alice can read because editor inherits viewer; no g2 is involved.

Use a separate g2 graph when the dependency itself should be in the policy. The matcher defines the meaning:

[role_definition]
g = _, _
g2 = _, _

[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && (r.act == p.act || g2(p.act, r.act))

p, admin, article, write
g2, write, read
g, alice, admin

The request alice, article, read matches the p, admin, article, write row because g2(write, read) is true: write is a child of read, the same direction as g edges. g2 rows grant nothing on their own and are not validated by Casbin; you own the direction and the meaning of each edge, while Casbin applies the same transitive inheritance as g.

If the dependency is only catalog metadata — say, a role editor should pre-select "read" in the admin UI when someone ticks "edit" — keep it in the permission catalog and expand it into p, g or g2 rows when you generate the policy. Casbin does not need to store data that is never evaluated. The policy does not have to live in a CSV file either: an adapter can load the generated rows from a database or from your YAML/JSON catalog, so the catalog stays the source of truth. See Adapters for the adapter API.

Role hierarchy

Casbin implements RBAC1-style role hierarchy: if alice has role1 and role1 has role2, then alice effectively has role2 and its permissions.

The hierarchy depth is how many levels of inheritance you allow. The default role manager uses a maximum depth of 10 (configurable), so a user can inherit up to 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
}

Distinguishing users from roles

In Casbin, users and roles are both strings. In flat RBAC (no role hierarchy), GetAllSubjects() and GetAllRoles() return the left and right sides of g rules (often users and roles). With a hierarchy, the same name can appear as both user and role; if your app does not track which is which, use a naming convention (e.g. prefix role::) and check it when interpreting results.

Implicit roles and permissions

Roles and permissions inherited through the hierarchy (not only direct assignments) are called implicit. Use GetImplicitRolesForUser() and GetImplicitPermissionsForUser() to include them; GetRolesForUser() and GetPermissionsForUser() return only direct assignments. See GitHub #137.

Pattern matching in RBAC

See RBAC with pattern.

Role manager

See Role managers for custom role management.

Related models

• ABAC
• ReBAC
• Super administrator
• Access control models compared