README
¶
goRBAC
goRBAC provides a lightweight role-based access control implementation in Golang.
For the purposes of this package:
* an identity has one or more roles.
* a role requests access to a permission.
* a permission is given to a role.
Thus, RBAC has the following model:
* many to many relationship between identities and roles.
* many to many relationship between roles and permissions.
* roles can have a parent role (inheriting permissions).
Version
Currently, goRBAC has two versions:
Version 1 is the original design which will only be mantained to fix bugs.
Version 2 is the new design which will be continually mantained with a stable API.
The master branch will be under development with a new API and can be changed without notice.
Install
Install the package:
$ go get gopkg.in/mikespook/gorbac.v2
Usage
Although you can adjust the RBAC instance anytime and it's absolutely safe, the library is designed for use with two phases:
-
Preparing
-
Checking
Preparing
Import the library:
import "github.com/mikespook/gorbac"
Get a new instance of RBAC:
rbac := gorbac.New()
Get some new roles:
rA := gorbac.NewStdRole("role-a")
rB := gorbac.NewStdRole("role-b")
rC := gorbac.NewStdRole("role-c")
rD := gorbac.NewStdRole("role-d")
rE := gorbac.NewStdRole("role-e")
Get some new permissions:
pA := gorbac.NewStdPermission("permission-a")
pB := gorbac.NewStdPermission("permission-b")
pC := gorbac.NewStdPermission("permission-c")
pD := gorbac.NewStdPermission("permission-d")
pE := gorbac.NewStdPermission("permission-e")
Add the permissions to roles:
rA.Assign(pA)
rB.Assign(pB)
rC.Assign(pC)
rD.Assign(pD)
rE.Assign(pE)
Also, you can implement gorbac.Role and gorbac.Permission for your own data structure.
After initialization, add the roles to the RBAC instance:
rbac.Add(rA)
rbac.Add(rB)
rbac.Add(rC)
rbac.Add(rD)
rbac.Add(rE)
And set the inheritance:
rbac.SetParent("role-a", "role-b")
rbac.SetParents("role-b", []string{"role-c", "role-d"})
rbac.SetParent("role-e", "role-d")
Checking
Checking the permission is easy:
if rbac.IsGranted("role-a", pA, nil) &&
rbac.IsGranted("role-a", pB, nil) &&
rbac.IsGranted("role-a", pC, nil) &&
rbac.IsGranted("role-a", pD, nil) {
fmt.Println("The role-a has been granted permis-a, b, c and d.")
}
And there are some built-in util-functions: InherCircle, AnyGranted, AllGranted. Please open an issue for the new built-in requirement.
E.g.:
rbac.SetParent("role-c", "role-a")
if err := gorbac.InherCircle(rbac); err != nil {
fmt.Println("A circle inheratance occurred.")
}
Persistence
The most asked question is how to persist the goRBAC instance. Please check the post HOW TO PERSIST GORBAC INSTANCE for the details.
Patches
2016-03-03
gofmt -w -r 'AssignPermission -> Assign' .
gofmt -w -r 'RevokePermission -> Revoke' .
Authors
- Xing Xing mikespook@gmail.com Blog @Twitter
Open Source - MIT Software License
See LICENSE.
Documentation
¶
Overview ¶
Package gorbac provides a lightweight role-based access control implementation in Golang.
For the purposes of this package:
- an identity has one or more roles.
- a role requests access to a permission.
- a permission is given to a role.
Thus, RBAC has the following model:
- many to many relationship between identities and roles.
- many to many relationship between roles and permissions.
- roles can have parent roles.
Index ¶
- Variables
- func AllGranted(rbac *RBAC, roles []string, permission Permission, assert AssertionFunc) (rslt bool)
- func AnyGranted(rbac *RBAC, roles []string, permission Permission, assert AssertionFunc) (rslt bool)
- func InherCircle(rbac *RBAC) (err error)
- func Walk(rbac *RBAC, h WalkHandler) (err error)
- type AssertionFunc
- type LayerPermission
- type Permission
- type Permissions
- type RBAC
- func (rbac *RBAC) Add(r Role) (err error)
- func (rbac *RBAC) Get(id string) (r Role, parents []string, err error)
- func (rbac *RBAC) GetParents(id string) ([]string, error)
- func (rbac *RBAC) IsGranted(id string, p Permission, assert AssertionFunc) (rslt bool)
- func (rbac *RBAC) Remove(id string) (err error)
- func (rbac *RBAC) RemoveParent(id string, parent string) error
- func (rbac *RBAC) SetParent(id string, parent string) error
- func (rbac *RBAC) SetParents(id string, parents []string) error
- type Role
- type Roles
- type StdPermission
- type StdRole
- type WalkHandler
Constants ¶
This section is empty.
Variables ¶
var ( // ErrRoleNotExist occurred if a role cann't be found ErrRoleNotExist = errors.New("Role does not exist") // ErrRoleExist occurred if a role shouldn't be found ErrRoleExist = errors.New("Role has already existed") )
var (
ErrFoundCircle = fmt.Errorf("Found circle")
)
Functions ¶
func AllGranted ¶
func AllGranted(rbac *RBAC, roles []string, permission Permission, assert AssertionFunc) (rslt bool)
AllGranted checks if all roles have the permission.
func AnyGranted ¶
func AnyGranted(rbac *RBAC, roles []string, permission Permission, assert AssertionFunc) (rslt bool)
AnyGranted checks if any role has the permission.
func InherCircle ¶
InherCircle returns an error when detecting any circle inheritance.
Types ¶
type AssertionFunc ¶
type AssertionFunc func(*RBAC, string, Permission) bool
AssertionFunc supplies more fine-grained permission controls.
type LayerPermission ¶
LayerPermission firstly checks the Id of permission. If the Id is matched, it can be considered having the permission. Otherwise, it checks every layers of permission. A role which has an upper layer granted, will be granted sub-layers permissions.
func (*LayerPermission) ID ¶
func (p *LayerPermission) ID() string
ID returns the identity of permission
func (*LayerPermission) Match ¶
func (p *LayerPermission) Match(a Permission) bool
Match another permission
type Permission ¶
type Permission interface {
ID() string
Match(Permission) bool
}
Permission exports `Id` and `Match`
func NewLayerPermission ¶
func NewLayerPermission(id string) Permission
NewLayerPermission returns an instance of layered permission with `id`
func NewStdPermission ¶
func NewStdPermission(id string) Permission
NewStdPermission returns a Permission instance with `id`
type RBAC ¶
type RBAC struct {
// contains filtered or unexported fields
}
RBAC object, in most cases it should be used as a singleton.
func (*RBAC) GetParents ¶
GetParents return `parents` of the role `id`. If the role is not existing, an error will be returned. Or the role doesn't have any parents, a nil slice will be returned.
func (*RBAC) IsGranted ¶
func (rbac *RBAC) IsGranted(id string, p Permission, assert AssertionFunc) (rslt bool)
IsGranted tests if the role `id` has Permission `p` with the condition `assert`.
func (*RBAC) RemoveParent ¶
RemoveParent unbind the `parent` with the role `id`. If the role or the parent is not existing, an error will be returned.
type Role ¶
type Role interface {
ID() string
Permit(Permission) bool
}
Role is an interface. You should implement this interface for your own role structures.
type StdPermission ¶
type StdPermission struct {
IDStr string
}
StdPermission only checks if the Ids are fully matching.
func (StdPermission) Match ¶
func (p StdPermission) Match(a Permission) bool
Match another permission
type StdRole ¶
type StdRole struct {
sync.RWMutex
// IDStr is the identity of role
IDStr string `json:"id"`
// contains filtered or unexported fields
}
StdRole is the default role implement. You can combine this struct into your own Role implement.
func NewStdRole ¶
NewStdRole is the default role factory function. It matches the declaration to RoleFactoryFunc.
func (*StdRole) Assign ¶
func (role *StdRole) Assign(p Permission) error
Assign a permission to the role.
func (*StdRole) Permissions ¶
func (role *StdRole) Permissions() []Permission
Permissions returns all permissions into a slice.
func (*StdRole) Permit ¶
func (role *StdRole) Permit(p Permission) (rslt bool)
Permit returns true if the role has specific permission.
func (*StdRole) Revoke ¶
func (role *StdRole) Revoke(p Permission) error
Revoke the specific permission.
type WalkHandler ¶
WalkHandler is a function defined by user to handle role
Source Files