casbin

README

casbin

casbin is a powerful and efficient open-source access control library for Golang projects. It provides support for enforcing authorization based on various models like ACL, RBAC, ABAC.

In casbin, an access control model is abstracted into a CONF file based on the PERM metamodel (Policy, Effect, Request, Matchers). So switching or upgrading the authorization mechanism for a project is just as simple as modifying a configuration. A model CONF can be as simple as:

[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

A simple policy for this model is a CSV like:

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

Features

What casbin does:

1. enforce the policy in the classic {subject, object, action} form or a customized form as you defined.
2. handle the storage of the access control model and its policy.
3. manage the role-user mappings and role-role mappings (aka role hierarchy in RBAC).
4. support built-in superuser like root or administrator. A superuser can do anything without explict permissions.
5. multiple built-in operators to support the rule matching. For example, keyMatch can map a resource key /foo/bar to the pattern /foo*.

What casbin does NOT do:

1. authentication (aka verify username and password when a user logs in)
2. manage the list of users or roles. I believe it's more convenient for the project itself to manage these entities. Users usually have their passwords, and casbin is not designed as a password container. However, casbin stores the user-role mapping for the RBAC scenario.

Installation

go get github.com/hsluoyz/casbin

Get started

1. Initialize an enforcer by specifying a model CONF file and the policy file.

e := &Enforcer{}
e.Init("examples/basic_model.conf", "examples/basic_policy.csv")

1. Add the enforcement hook into your code before the access happens.

sub := "alice"
obj := "data1"
act := "read"

if e.Enforce(sub, obj, act) == true {
    // permit alice to read data1
} else {
    // deny the request, show an error
}

1. You can get the roles for a user with our management API.

roles := e.GetRoles("alice")

1. Please refer to the _test.go files for more usage.

Persistence

Both model and policy can be persisted in casbin with the following restrictions:

Persist Method	casbin Model	casbin Policy
File	Load only	Load/Save
Database (RDBMS)	Not supported	Load/Save

We think the model represents the access control model that our customer uses and is not often modified at run-time, so we don't implement an API to modify the current model or save the model into a file. And the model cannot be loaded from or saved into a database. The model file should be in .CONF format.

The policy is much more dynamic than model and can be loaded from a file/database or saved to a file/database at any time. As for file persistence, the policy file should be in .CSV (Comma-Separated Values) format. As for the database backend, casbin should support all relational DBMSs but I only tested with MySQL. casbin has no built-in database with it, you have to setup a database on your own. Let me know if there are any compatibility issues here. casbin will automatically create a database named casbin and use it for policy storage. So make sure your provided credential has the related privileges for the database you use.

Below shows how to initialize an enforcer from file:

e := &Enforcer{}
// Initialize an enforcer with a model file and a policy file.
e.InitWithFile("examples/basic_model.conf", "examples/basic_policy.csv")

Below shows how to initialize an enforcer from database. it connects to a MySQL DB on 127.0.0.1:3306 with root and blank password.

e := &Enforcer{}
// Initialize an enforcer with a model file and a policy from database.
e.InitWithDB("examples/basic_model.conf", "mysql", "root:@tcp(127.0.0.1:3306)/")

You may also want to reload the model, reload the policy or save the policy after initialization:

// Reload the model from the model CONF file.
e.LoadModel()

// Reload the policy from file/database.
e.LoadPolicy()

// Save the current policy (usually after changed with casbin API) back to file/database.
e.SavePolicy()

Examples

Model	Model file	Policy file
basic	basic_model.conf	basic_policy.csv
basic with root	basic_model_with_root.conf	basic_policy.csv
RESTful	keymatch_model.conf	keymatch_policy.csv
RBAC	rbac_model.conf	rbac_policy.csv
RBAC with resource roles	rbac_model_with_resource_roles.conf	rbac_policy_with_resource_roles.csv
ABAC	abac_model.conf	N/A

Credits

• github.com/lxmgo/config
• github.com/Knetic/govaluate

License

This project is licensed under the Apache 2.0 license.

Documentation

Index

• type Assertion
• type AssertionMap
• type Function
• type FunctionMap
  • func LoadFunctionMap() FunctionMap
  • func (fm FunctionMap) AddFunction(name string, function Function)
• type Model
  • func LoadModel(path string) Model
  • func (model Model) AddPolicy(sec string, ptype string, policy []string) bool
  • func (model Model) BuildRoleLinks()
  • func (model Model) ClearPolicy()
  • func (model Model) GetFilteredPolicy(sec string, ptype string, fieldIndex int, fieldValue string) [][]string
  • func (model Model) GetPolicy(sec string, ptype string) [][]string
  • func (model Model) GetValuesForFieldInPolicy(sec string, ptype string, fieldIndex int) []string
  • func (model Model) HasPolicy(sec string, ptype string, policy []string) bool
  • func (model Model) PrintModel()
  • func (model Model) PrintPolicy()
  • func (model Model) RemovePolicy(sec string, ptype string, policy []string) bool
• type Role
• type RoleManager
  • func (rm *RoleManager) GetRoles(name string) []string
  • func (rm *RoleManager) HasLink(name1 string, name2 string) bool

Types

type Assertion

type Assertion struct {
	Key    string
	Value  string
	Tokens []string
	Policy [][]string
	RM     *RoleManager
}

type AssertionMap

type AssertionMap map[string]*Assertion

AssertionMap is the collection of assertions, can be "r", "p", "g", "e", "m".

type Function

type Function func(args ...interface{}) (interface{}, error)

Function represents a function that is used in the matchers, used to get attributes in ABAC.

type FunctionMap

type FunctionMap map[string]func(args ...interface{}) (interface{}, error)

FunctionMap represents the collection of Function.

func LoadFunctionMap

func LoadFunctionMap() FunctionMap

Load an initial function map.

func (FunctionMap) AddFunction

func (fm FunctionMap) AddFunction(name string, function Function)

Add an expression function.

type Model

type Model map[string]AssertionMap

Model represents the whole access control model.

func LoadModel

func LoadModel(path string) Model

Load the model from model CONF file.

func (Model) AddPolicy

func (model Model) AddPolicy(sec string, ptype string, policy []string) bool

Add a policy to the model.

func (Model) BuildRoleLinks

func (model Model) BuildRoleLinks()

Initialize the roles in RBAC.

func (Model) ClearPolicy

func (model Model) ClearPolicy()

Clear all current policy.

func (Model) GetFilteredPolicy

func (model Model) GetFilteredPolicy(sec string, ptype string, fieldIndex int, fieldValue string) [][]string

Get rules based on a field filter from a policy.

func (Model) GetPolicy

func (model Model) GetPolicy(sec string, ptype string) [][]string

Get all rules in a policy.

func (Model) GetValuesForFieldInPolicy

func (model Model) GetValuesForFieldInPolicy(sec string, ptype string, fieldIndex int) []string

Get all values for a field for all rules in a policy, duplicated values are removed.

func (Model) HasPolicy

func (model Model) HasPolicy(sec string, ptype string, policy []string) bool

Determine whether a model has the specified policy.

func (Model) PrintModel

func (model Model) PrintModel()

Print the model.

func (Model) PrintPolicy

func (model Model) PrintPolicy()

Print the policy.

func (Model) RemovePolicy

func (model Model) RemovePolicy(sec string, ptype string, policy []string) bool

Remove a policy from the model.

type Role

type Role struct {
	// contains filtered or unexported fields
}

Role is the data structure for a role in RBAC.

type RoleManager

type RoleManager struct {
	// contains filtered or unexported fields
}

RoleManager is the interface to manage the roles in RBAC.

func (*RoleManager) GetRoles

func (rm *RoleManager) GetRoles(name string) []string

Get the roles that a subject has (aka inherits).

func (*RoleManager) HasLink

func (rm *RoleManager) HasLink(name1 string, name2 string) bool

Whether role: name1 has (aka inherits) role: name2.