README
¶
RBAC
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
articleIDas 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.Canfunction 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 ¶
- func AllowAll(action, target string) (bool, error)
- func Anything(target string) (bool, error)
- func DefaultPermissionConstructors() map[string]PermissionConstructor
- type Matcher
- type Permission
- type PermissionConstructor
- type PermissionTemplate
- type Permissions
- type PolicyTemplate
- func (p *PolicyTemplate) AddPermission(constructor, action, target string)
- func (p *PolicyTemplate) DeleteConstructor(name string)
- func (p *PolicyTemplate) Role(replacer *strings.Replacer) (*Role, error)
- func (p *PolicyTemplate) SetConstructor(name string, constructor PermissionConstructor)
- func (p *PolicyTemplate) UnmarshalJSON(data []byte) error
- type Role
- type Roles
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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 ¶
A Matcher is a function that returns a bool representing whether or not the target matches some pre-defined pattern.
func GlobMatch ¶
GlobMatch returns a Matcher that returns true if the target glob matches the specified pattern.
func MatchAll ¶
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 ¶
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 ¶
RegexMatch returns a Matcher that returns true if the target regular expression matches the specified pattern.
func StringMatch ¶
StringMatch returns a Matcher that returns true if the target string matches s.
type Permission ¶
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
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.
Source Files
Directories