rbac

package module
Version: v0.0.0-...-d2c4f05 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 29, 2018 License: MIT Imports: 5 Imported by: 15

README

RBAC

MIT License Go Report Card Go Doc

Overview

RBAC is a package that makes it easy to implement Role Based Access Control (RBAC) models in Go applications.

Download

To download this package, run:

go get github.com/zpatrick/rbac

Getting Started

This section will go over some of the basic concepts and an example of how to use rbac in an application. For more advanced usage, please see the examples directory.

  • Action: An action is a string that represents some desired operation. Actions are typically expressed as a verb or a verb-object combination, but it is ultimately up to the user how actions are expressed. Some examples are: "Upvote", "ReadArticle", or "EditComment".
  • Target: A target is a string that represents what the action is trying to operate on. Targets are typically expressed as an object's unique identifier, but it is ultimately up to the user how targets are expressed. An example is passing an articleID as the target for a "ReadArticle" action. Not all actions require a target.
  • Matcher: A matcher is a function that returns a bool representing whether or not the target matches some pre-defined pattern. This repo comes with some builtin matchers: GlobMatch, RegexMatch, and StringMatch. Please see the complex blog example to see how one can implement custom matchers for their applications.
  • Permission: A permission is a function that takes an action and a target, and returns true if and only if the action is allowed on the target. A permission should always allow (as opposed to deny) action(s) to be made on target(s), since nothing is allowed by default.
  • Role: A role is essentially a grouping of permissions. The role.Can function should be used to determine whether or not a role can do an action on a target. A role is only allowed to do something if it has at least one permission that allows it.

Usage

package main

import (
        "fmt"

        "github.com/zpatrick/rbac"
)

func main() {
        roles := []rbac.Role{
                {
                        RoleID: "Adult",
                        Permissions: []rbac.Permission{
                                rbac.NewGlobPermission("watch", "*"),
                        },
                },
                {
                        RoleID: "Teenager",
                        Permissions: []rbac.Permission{
                                rbac.NewGlobPermission("watch", "pg-13"),
                                rbac.NewGlobPermission("watch", "g"),
                        },
                },
                {
                        RoleID: "Child",
                        Permissions: []rbac.Permission{
                                rbac.NewGlobPermission("watch", "g"),
                        },
                },
        }

        for _, role := range roles {
                fmt.Println("Role:", role.RoleID)
                for _, rating := range []string{"g", "pg-13", "r"} {
                        canWatch, _ := role.Can("watch", rating)
                        fmt.Printf("Can watch %s? %t\n", rating, canWatch)
                }
        }
}

Output:

Role: Adult
Can watch g? true
Can watch pg-13? true
Can watch r? true
Role: Teenager
Can watch g? true
Can watch pg-13? true
Can watch r? false
Role: Child
Can watch g? true
Can watch pg-13? false
Can watch r? false

License

This work is published under the MIT license.

Please see the LICENSE file for details.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AllowAll

func AllowAll(action, target string) (bool, error)

AllowAll is a Permission that always returns true

func Anything

func Anything(target string) (bool, error)

Anything is a Matcher that always returns true

func DefaultPermissionConstructors

func DefaultPermissionConstructors() map[string]PermissionConstructor

DefaultPermissionConstructors returns a mapping of constructor names to PermissionConstructor functions for each of the builtin PermissionConstructors:

"glob":   NewGlobPermission
"regex":  NewRegexPermission
"string": NewStringPermission

Types

type Matcher

type Matcher func(target string) (bool, error)

A Matcher is a function that returns a bool representing whether or not the target matches some pre-defined pattern.

func GlobMatch

func GlobMatch(pattern string) Matcher

GlobMatch returns a Matcher that returns true if the target glob matches the specified pattern.

func MatchAll

func MatchAll(matchers ...Matcher) Matcher

MatchAll will convert a slice of Matchers into a single Matcher that returns true if and only if all of the specified matchers returns true.

func MatchAny

func MatchAny(matchers ...Matcher) Matcher

MatchAny will convert a slice of Matchers into a single Matcher that returns true if and only if at least one of the specified matchers returns true.

func RegexMatch

func RegexMatch(pattern string) Matcher

RegexMatch returns a Matcher that returns true if the target regular expression matches the specified pattern.

func StringMatch

func StringMatch(s string) Matcher

StringMatch returns a Matcher that returns true if the target string matches s.

type Permission

type Permission func(action string, target string) (bool, error)

A Permission is a function that returns true if the action is allowed on the target

func NewGlobPermission

func NewGlobPermission(actionPattern, targetPattern string) Permission

NewGlobPermission returns a Permission that uses GlobMatchers for the specified action and target patterns.

func NewPermission

func NewPermission(actionMatcher, targetMatcher Matcher) Permission

NewPermission returns a Permission that will return true if the actionMatcher returns true for the given action, and if the targetMatcher returns true the given target.

func NewRegexPermission

func NewRegexPermission(actionPattern, targetPattern string) Permission

NewRegexPermission returns a Permission that uses RegexMatchers for the specified action and target patterns.

func NewStringPermission

func NewStringPermission(action, target string) Permission

NewStringPermission returns a Permission that uses StringMatchers for the specified action and target.

type PermissionConstructor

type PermissionConstructor func(action, target string) Permission

A PermissionConstructor is a function that creates a new Permission from the specified action and target strings.

type PermissionTemplate

type PermissionTemplate struct {
	Constructor string `json:"constructor"`
	Action      string `json:"action"`
	Target      string `json:"target"`
}

A PermissionTemplate holds information about a permission in templated format.

type Permissions

type Permissions []Permission

The Permissions type is an adapter to allow helper functions to execute on a slice of Permissions

func (Permissions) Can

func (p Permissions) Can(action string, target string) (bool, error)

Can returns true if at least one of the permissions in p allows the action on the target

type PolicyTemplate

type PolicyTemplate struct {
	RoleID              string               `json:"role_id"`
	PermissionTemplates []PermissionTemplate `json:"permissions"`
	// contains filtered or unexported fields
}

A PolicyTemplate holds information about a Role in a templated format. This format can be encoded to and from JSON.

func NewPolicyTemplate

func NewPolicyTemplate(roleID string) *PolicyTemplate

NewPolicyTemplate generates a new PolicyTemplate with the specified roleID and default constructors.

func (*PolicyTemplate) AddPermission

func (p *PolicyTemplate) AddPermission(constructor, action, target string)

AddPermission adds a new PermissionTemplate to p.PermissionTemplates.

func (*PolicyTemplate) DeleteConstructor

func (p *PolicyTemplate) DeleteConstructor(name string)

DeleteConstructor will remove the constructor mapping at the specified name if it exists.

func (*PolicyTemplate) Role

func (p *PolicyTemplate) Role(replacer *strings.Replacer) (*Role, error)

Role converts the PolicyTemplate to a Role. Replacer can be used to replace variables within the Action and Target fields in the PermissionTemplates. An error will be returned if a PermissionTemplate.Constructor does not have a corresponding PermissionConstructor.

func (*PolicyTemplate) SetConstructor

func (p *PolicyTemplate) SetConstructor(name string, constructor PermissionConstructor)

SetConstructor updates the mapping of a constructor name to a PermissionConstructor. If a mapping for the specified same name already exists, it will be overwritten.

func (*PolicyTemplate) UnmarshalJSON

func (p *PolicyTemplate) UnmarshalJSON(data []byte) error

UnmarshalJSON allows a *PolicyTemplate to implement the json.Unmarshaler interface. We do this to set the default constructors on p after the unmarshalling.

type Role

type Role struct {
	RoleID      string
	Permissions Permissions
}

A Role is a grouping of permissions.

func (Role) Can

func (r Role) Can(action, target string) (bool, error)

Can returns true if the Role is allowed to perform the action on the target.

type Roles

type Roles []Role

The Roles type is an adapter to allow helper functions to execute on a slice of Roles

func (Roles) Can

func (r Roles) Can(action, target string) (bool, error)

Can returns true if at least one of the roles in r allows the action on the target

Directories

Path Synopsis
examples
iam

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL