fastac

README

access control for go, supports RBAC, ABAC and ACL, drop-in replacement for casbin

FastAC is a drop in replacement for Casbin. In some cases, FastAC can improve the performance significantly.

Please refer to the Casbin Docs for explanation of terms.

Getting Started

Installation

go get github.com/abichinger/fastac

First you need to prepare an access control model. The syntax of FastAC models is identical to Casbin models.

An ACL (Access Control List) model looks like this:

#File: model.conf

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
r.sub == p.sub && r.obj == p.obj && r.act == p.act

Next, you need to load some policy rules. To get started you can load your rules from a text file. For production you should use a storage adapter.

#File: policy.csv
p, alice, data1, read
p, alice, data2, read
p, bob, data1, write
p, bob, data2, write

Go code to resolve access requests

//create an enforcer
e, err := fastac.NewEnforcer("model.conf", "policy.csv")

//check if alice is allowed to read data1
if allow, _ := e.Enforce("alice", "data1", "read"); allow == true {
    // permit alice to read data1
} else {
    // deny the request
}

New Features

Policy Indexing

Matchers will be divided into multiple stages. As a result FastAC will index all policy rules, which reduces the search space for access requests. This feature brings the most performance gain.

Advanced Policy Filtering

FastAC can filter the policy rules with matchers. The Filter function also supports filtering grouping rules. The fields of a grouping rule can be accessed by g.user, g.role, g.domain

//Examples

//get all policy rules belonging to domain1
e.Filter(SetMatcher("p.dom == \"domain1\"")

//get all policy rules, which grant alice read access
e.Filter(SetMatcher("g(\"alice\", p.sub) && p.act == \"read\"")

//get all grouping rules for alice
e.Filter(SetMatcher("g.user == \"alice\"")

Supported Models

• ACL - Access Control List
• ACL-su - Access Control List with super user
• ABAC - Attribute Based Access Control
• RBAC - Role Based Access Control
• RBAC-domain - Role Based Access Control with domains/tenants

Adapter List

• File Adapter (built-in) - not recommended for production
• Gorm Adapter

Performance Comparison

More benchmarks

Feature Overview

• Enforcement
• RBAC
• ABAC
• Adapter
• Default Role Manager
• Third Party Role Managers
• Filtered Adapter
• Watcher
• Dispatcher

Documentation

Index

• type Context
  • func NewContext(model model.IModel, options ...ContextOption) (*Context, error)
• type ContextOption
  • func SetEffector(effector interface{}) ContextOption
  • func SetMatcher(matcher interface{}) ContextOption
  • func SetRequestDef(definition interface{}) ContextOption
• type Enforcer
  • func NewEnforcer(model interface{}, adapter interface{}, options ...Option) (*Enforcer, error)
  • func (e *Enforcer) AddRule(rule []string) (bool, error)
  • func (e *Enforcer) AddRules(rules [][]string) error
  • func (e *Enforcer) Enforce(params ...interface{}) (bool, error)
  • func (e *Enforcer) EnforceWithContext(ctx *Context, rvals ...interface{}) (bool, error)
  • func (e *Enforcer) Filter(params ...interface{}) ([][]string, error)
  • func (e *Enforcer) FilterWithContext(ctx *Context, rvals ...interface{}) ([][]string, error)
  • func (e *Enforcer) Flush() error
  • func (e *Enforcer) GetModel() model.IModel
  • func (e *Enforcer) GetStorageController() *storage.StorageController
  • func (e *Enforcer) LoadPolicy() error
  • func (e *Enforcer) RangeMatches(params []interface{}, fn func(rule []string) bool) error
  • func (e *Enforcer) RangeMatchesWithContext(ctx *Context, rvals []interface{}, fn func(rule []string) bool) error
  • func (e *Enforcer) RemoveRule(rule []string) (bool, error)
  • func (e *Enforcer) RemoveRules(rules [][]string) error
  • func (e *Enforcer) SavePolicy() error
  • func (e *Enforcer) SetAdapter(adapter storage.Adapter)
  • func (e *Enforcer) SetOption(option Option) error
• type IEnforcer
• type Option
  • func OptionAutosave(autosave bool) Option
  • func OptionStorage(enable bool) Option

Types

type Context

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

func NewContext

func NewContext(model model.IModel, options ...ContextOption) (*Context, error)

type ContextOption

type ContextOption func(ctx *Context) error

func SetEffector

func SetEffector(effector interface{}) ContextOption

func SetMatcher

func SetMatcher(matcher interface{}) ContextOption

func SetRequestDef

func SetRequestDef(definition interface{}) ContextOption

type Enforcer

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

func NewEnforcer

func NewEnforcer(model interface{}, adapter interface{}, options ...Option) (*Enforcer, error)

NewEnforcer creates a new Enforcer instance. An Enforcer is the main item of FastAC

Without adapter and default options:

NewEnforcer("model.conf", nil)

With adapter and autosave enabled

adapter := gormadapter.NewAdapter(db, tableName)
NewEnforcer("model.conf", adapter, OptionAutosave(true))

func (*Enforcer) AddRule

func (e *Enforcer) AddRule(rule []string) (bool, error)

AddRule adds a rule to the model Returns false, if the rule was already present

Add policy rule:

e.AddRule("p", "alice", "data1", "read")

Add grouping rule:

e.AddRule("g", "alice", "group1")

func (*Enforcer) AddRules

func (e *Enforcer) AddRules(rules [][]string) error

AddRules adds multiple rules to the model

func (*Enforcer) Enforce

func (e *Enforcer) Enforce(params ...interface{}) (bool, error)

Enforce decides whether to allow or deny a request It is possible to pass ContextOptions, everything else will be treated as a request value

func (*Enforcer) EnforceWithContext

func (e *Enforcer) EnforceWithContext(ctx *Context, rvals ...interface{}) (bool, error)

func (*Enforcer) Filter

func (e *Enforcer) Filter(params ...interface{}) ([][]string, error)

Filter will fetch all rules which match the given request It is possible to pass ContextOptions, everything else will be treated as a request value The effect of rules is not considered.

Get all permissons from alice:

e.Filter(SetMatcher("p.user == \"alice\""))

Get all grouping rules in domain1:

e.Filter(SetMatcher("g.domain == \"domain1\""))

func (*Enforcer) FilterWithContext

func (e *Enforcer) FilterWithContext(ctx *Context, rvals ...interface{}) ([][]string, error)

func (*Enforcer) Flush

func (e *Enforcer) Flush() error

Flush sends all the modifications of the rule set to the storage adapter.

store rule, when autosave is disabled:

e.AddRule("g", "alice", "group1")
e.Flush()

func (*Enforcer) GetModel

func (e *Enforcer) GetModel() model.IModel

func (*Enforcer) GetStorageController

func (e *Enforcer) GetStorageController() *storage.StorageController

func (*Enforcer) LoadPolicy

func (e *Enforcer) LoadPolicy() error

LoadPolicy loads all rules from the storage adapter into the model. The model is not cleared before the loading process

func (*Enforcer) RangeMatches

func (e *Enforcer) RangeMatches(params []interface{}, fn func(rule []string) bool) error

func (*Enforcer) RangeMatchesWithContext

func (e *Enforcer) RangeMatchesWithContext(ctx *Context, rvals []interface{}, fn func(rule []string) bool) error

func (*Enforcer) RemoveRule

func (e *Enforcer) RemoveRule(rule []string) (bool, error)

RemoveRule removes a rule from the model Returns false, if the rule was not present

Add policy rule:

e.RemoveRule("p", "alice", "data1", "read")

Add grouping rule:

e.RemoveRule("g", "alice", "group1")

func (*Enforcer) RemoveRules

func (e *Enforcer) RemoveRules(rules [][]string) error

RemoveRules removes multiple rules from the model

func (*Enforcer) SavePolicy

func (e *Enforcer) SavePolicy() error

SavePolicy stores all rules from the model into the storage adapter.

func (*Enforcer) SetAdapter

func (e *Enforcer) SetAdapter(adapter storage.Adapter)

SetAdapter sets the storage adapter

func (*Enforcer) SetOption

func (e *Enforcer) SetOption(option Option) error

SetOption applies an option to the Enforcer

type IEnforcer

type IEnforcer interface {
	GetModel() model.IModel
	SetModel(m model.IModel)
	GetAdapter() *storage.Adapter
	SetAdapter(*storage.Adapter)

	Enforce(rvals ...interface{}) (bool, error)
	EnforceWithMatcher(matcher string, rvals ...interface{}) (bool, error)
	EnforceWithKeys(mKey string, rKey string, eKey string, rvals ...interface{})

	Filter(rvals ...interface{}) (bool, error)
	FilterWithMatcher(matcher string, rvals ...interface{}) (bool, error)
	FilterWithKeys(mKey string, rKey string, rvals ...interface{}) (bool, error)

	AddRule(params ...string) (bool, error)
	RemoveRule(params ...string) (bool, error)
}

type Option

type Option func(*Enforcer) error

func OptionAutosave

func OptionAutosave(autosave bool) Option

Option to disable/enable the autosave feature (default: disabled) If autosave is disabled, Flush needs to be called to save modified rules Enable autosave:

NewEnforcer(model, adapter, OptionAutosave(true))

Or:

e.SetOption(OptionAutosave(true))

func OptionStorage

func OptionStorage(enable bool) Option

Option to disable/enable the storage feature (default: enabled, if an adapter is supplied) If storage is disabled, the StorageController will not listen for rule updates