README

goRBAC V1

Build Status GoDoc

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

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

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

    Variables

    This section is empty.

    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.

                                                                  Directories

                                                                  Path Synopsis
                                                                  examples
                                                                  http
                                                                  possum & gorbac example
                                                                  possum & gorbac example
                                                                  user-defined
                                                                  User-defined gorbac example
                                                                  User-defined gorbac example