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.

Credits

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

License

This project is licensed under the Apache 2.0 license.

Documentation

Index

• type AssertionMap
• type Enforcer
• type Model
• type Role
• type RoleManager

Types

type AssertionMap

type AssertionMap map[string]*assertion

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

type Enforcer

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

Enforcer is the main interface for authorization enforcement and policy management.

type Model

type Model map[string]AssertionMap

Model represents the whole access control 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.