gorbac

README

goRBAC V1

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).

Install

Install the package:

$ go get gopkg.in/mikespook/gorbac.v1

Usage

Import the package:

import gopkg.in/mikespook/gorbac.v1

Get a goRBAC instance:

rbac := gorbac.New()

gorbac.Role is an interface. That is you can use your own data structure to satisfy this interface.

rbac := gorbac.NewWithFactory(YourOwnFactory)

However, YourOwnFactory should match the declaration of gorabc.RoleFactoryFunc.

Specified permissions and parent roles for a role. If the role is not existing, new one will be created:

rbac.Add("editor", []string{"edit.article"}, nil)	
rbac.Set("master", []string{"del.article"}, []string{"editor"})

The main difference between Add and Set is:

• Add keeps original permissions and parents which are already existed;
• Set covers them with new permissions and parents.

Remove a role:

rbac.Remove("guest")

Get a role for more fine-grained controls:

rbac.Get("admin")

Check if a role has a permission:

rbac.IsGranted("editor", "edit.article", nil)

The 3rd param, Assertion function is used for more fine-grained testing:

rbac.IsGranted("editor", "edit.article", 
	func(role, permission string, rbac* Rbac) bool {
		return article.Owner == User.Id
})

Revoke a permission from a role:

rbac.Get("master").RevokePermission("del.article")

Remove a role's parent:

rbac.Get("editor").RemoveParent("auth-user")

In a real case, it is good for checking if a role existed:

if role := rbac.Get("not-exists"); role == nil {
	// Not exists;
} else {
	// Exists. 	
}

Dump and Restore help for data persistence:

m := rbac.Dump()
data, err := json.Marshal(m)
// Handling error or save data

var m gorbac.Map
err := json.Unmarshal(data, &m)
rbac = gorbac.Restore(m)

If you want use user-defined data structures in data persistence, RestoreWithFactory would help you building RBAC instance with your own data structures.

var m gorbac.Map
err := json.Unmarshal(data, &m)
rbac = gorbac.RestoreWithFactory(m, YourOwnFactory)

For more details, please see example_test.go. Also, there are two independent examples. example/http shows accessing RBAC instance through HTTP, and another illustrates how user-defined roles work.

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

• Constants
• func AllGranted(rbac *RBAC, roles []string, permission string, assert AssertionFunc) bool
• func AnyGranted(rbac *RBAC, roles []string, permission string, assert AssertionFunc) bool
• func InherCircle(rbac *RBAC) error
• type AssertionFunc
• type BaseRole
  • func (role *BaseRole) AddParent(name string)
  • func (role *BaseRole) AddPermission(permission string)
  • func (role *BaseRole) HasPermission(permission string) bool
  • func (role *BaseRole) Name() string
  • func (role *BaseRole) Parents() []string
  • func (role *BaseRole) Permissions() []string
  • func (role *BaseRole) RemoveParent(name string)
  • func (role *BaseRole) Reset()
  • func (role *BaseRole) RevokePermission(permission string)
• type Map
• type RBAC
  • func New() *RBAC
  • func NewWithFactory(factory RoleFactoryFunc) *RBAC
  • func Restore(data Map) *RBAC
  • func RestoreWithFactory(data Map, factory RoleFactoryFunc) *RBAC
  • func (rbac *RBAC) Add(name string, permissions []string, parents []string)
  • func (rbac *RBAC) Dump() Map
  • func (rbac *RBAC) Get(name string) Role
  • func (rbac *RBAC) IsGranted(name, permission string, assert AssertionFunc) bool
  • func (rbac *RBAC) Remove(name string)
  • func (rbac *RBAC) Set(name string, permissions []string, parents []string)
• type Role
  • func NewBaseRole(rbac *RBAC, name string) Role
• type RoleFactoryFunc
• type RoleMap
  • func RoleToMap(role Role) RoleMap

Constants

const (
	// ParentKey exports parents into RoleMap
	ParentKey = "parents"
	// PermissionKey exports permissions into RoleMap
	PermissionKey = "permissions"
	// NameKey exports name into RoleMap
	NameKey = "name"
)

Functions

func AllGranted

func AllGranted(rbac *RBAC, roles []string, permission string,
	assert AssertionFunc) bool

AllGranted checks if all roles have the permission.

func AnyGranted

func AnyGranted(rbac *RBAC, roles []string, permission string,
	assert AssertionFunc) bool

AnyGranted checks if any role has the permission.

func InherCircle

func InherCircle(rbac *RBAC) error

InherCircle returns an error when detecting any circle inheritance.

Types

type AssertionFunc

type AssertionFunc func(string, string, *RBAC) bool

AssertionFunc supplies more fine-grained permission controls.

type BaseRole

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

BaseRole is the default role implement. You can combine this struct into your own Role implement.

func (*BaseRole) AddParent

func (role *BaseRole) AddParent(name string)

AddParent adds a parent to the role.

func (*BaseRole) AddPermission

func (role *BaseRole) AddPermission(permission string)

AddPermission adds a permission to the role.

func (*BaseRole) HasPermission

func (role *BaseRole) HasPermission(permission string) bool

HasPermission returns true if the role has specific permission.

func (*BaseRole) Name

func (role *BaseRole) Name() string

Name returns the role's identity name.

func (*BaseRole) Parents

func (role *BaseRole) Parents() []string

Parents returns all parents into a slice.

func (*BaseRole) Permissions

func (role *BaseRole) Permissions() []string

Permissions returns all permissions into a slice.

func (*BaseRole) RemoveParent

func (role *BaseRole) RemoveParent(name string)

RemoveParent deletes the specific parent from the role.

func (*BaseRole) Reset

func (role *BaseRole) Reset()

Reset cleans all permissions and parents.

func (*BaseRole) RevokePermission

func (role *BaseRole) RevokePermission(permission string)

RevokePermission remove the specific permission.

type Map

type Map map[string]RoleMap

Map exports RBAC to a structure data

type RBAC

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

RBAC object, in most cases it should be used as a singleton.

func New

func New() *RBAC

New returns a RBAC structure. The default role structure will be used.

func NewWithFactory

func NewWithFactory(factory RoleFactoryFunc) *RBAC

NewWithFactory returns a RBAC structure with a specific factory function. Role structure will be generated by the function.

func Restore

func Restore(data Map) *RBAC

Restore loads control data from a Map, and the default Role will be used.

func RestoreWithFactory

func RestoreWithFactory(data Map, factory RoleFactoryFunc) *RBAC

RestoreWithFactory loads control data from a Map. User-defined type can be created by factory.

func (*RBAC) Add

func (rbac *RBAC) Add(name string, permissions []string, parents []string)

Add a role with `name`. It has `permissions` and `parents`. If the role is not existing, a new one will be created. This function will add new permissions and parents to the role, and keep orignals.

func (*RBAC) Dump

func (rbac *RBAC) Dump() Map

Dump RBAC

func (*RBAC) Get

func (rbac *RBAC) Get(name string) Role

Get returns a role or nil if not exists.

func (*RBAC) IsGranted

func (rbac *RBAC) IsGranted(name, permission string,
	assert AssertionFunc) bool

IsGranted tests if the `name` has `permission` in the `assert` condition.

func (*RBAC) Remove

func (rbac *RBAC) Remove(name string)

Remove a role.

func (*RBAC) Set

func (rbac *RBAC) Set(name string, permissions []string, parents []string)

Set a role with `name`. It has `permissions` and `parents`. If the role is not existing, a new one will be created. This function will cover role's orignal permissions and parents.

type Role

type Role interface {
	Name() string
	AddPermission(string)
	HasPermission(string) bool
	RevokePermission(string)
	Permissions() []string
	AddParent(string)
	RemoveParent(string)
	Parents() []string
	Reset()
}

Role is an interface. You should implement this interface for your own role structures.

func NewBaseRole

func NewBaseRole(rbac *RBAC, name string) Role

NewBaseRole is the default role factory function. It matches the declaration to RoleFactoryFunc.

type RoleFactoryFunc

type RoleFactoryFunc func(*RBAC, string) Role

RoleFactoryFunc is used for a custom role structure. You could define your own role factory function through this factory function.

type RoleMap

type RoleMap map[string][]string

RoleMap exports roles data.

func RoleToMap

func RoleToMap(role Role) RoleMap

RoleToMap converts interface Role into RoleMap.