Skip to main content

Get Started

Installation

go get github.com/casbin/casbin/v2

New a Casbin enforcer

Casbin uses configuration files to define the access control model.

There are two configuration files: model.conf and policy.csv. model.conf stores the access model, while policy.csv stores the specific user permission configuration. The usage of Casbin is very straightforward. We only need to create one main structure: enforcer. When constructing this structure, model.conf and policy.csv will be loaded.

In other words, to create a Casbin enforcer, you need to provide a Model and an Adapter.

Casbin provides a FileAdapter that you can use. See Adapter for more information.

  • Example of using the Model file and the default FileAdapter:
import "github.com/casbin/casbin/v2"

e, err := casbin.NewEnforcer("path/to/model.conf", "path/to/policy.csv")
  • Use the Model text with other Adapter:
import (
"log"

"github.com/casbin/casbin/v2"
"github.com/casbin/casbin/v2/model"
xormadapter "github.com/casbin/xorm-adapter/v2"
_ "github.com/go-sql-driver/mysql"
)

// Initialize a Xorm adapter with MySQL database.
a, err := xormadapter.NewAdapter("mysql", "mysql_username:mysql_password@tcp(127.0.0.1:3306)/")
if err != nil {
log.Fatalf("error: adapter: %s", err)
}

m, err := model.NewModelFromString(`
[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

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

[matchers]
m = r.sub == p.sub && r.obj == p.obj && r.act == p.act
`)
if err != nil {
log.Fatalf("error: model: %s", err)
}

e, err := casbin.NewEnforcer(m, a)
if err != nil {
log.Fatalf("error: enforcer: %s", err)
}

Check permissions

Add an enforcement hook into your code right before the access happens:

sub := "alice" // the user that wants to access a resource.
obj := "data1" // the resource that is going to be accessed.
act := "read" // the operation that the user performs on the resource.

ok, err := e.Enforce(sub, obj, act)

if err != nil {
// handle err
}

if ok == true {
// permit alice to read data1
} else {
// deny the request, show an error
}

// You could use BatchEnforce() to enforce some requests in batches.
// This method returns a bool slice, and this slice's index corresponds to the row index of the two-dimensional array.
// e.g. results[0] is the result of {"alice", "data1", "read"}
results, err := e.BatchEnforce([][]interface{}{{"alice", "data1", "read"}, {"bob", "data2", "write"}, {"jack", "data3", "read"}})

Casbin also provides API for permission management at run-time. For example, You can get all the roles assigned to a user as below:

roles, err := e.GetRolesForUser("alice")

See Management API and RBAC API for more usage.

Please refer to the test cases for more usage.