ash

Documentation

Overview

Package ash implements a highly configurable and callback based ACL that can be used to authorize controller operations in a declarative way.

Index

• func C(s *Strategy) *fire.Callback
• type Authorizer
  • func A(name string, m fire.Matcher, h Handler) *Authorizer
  • func And(a, b *Authorizer) *Authorizer
  • func Or(a, b *Authorizer) *Authorizer
  • func Run(enforcers ...*Enforcer) *Authorizer
  • func (a *Authorizer) And(b *Authorizer) *Authorizer
  • func (a *Authorizer) Or(b *Authorizer) *Authorizer
• type Enforcer
  • func AddFilter(filter bson.M) *Enforcer
  • func DenyAccess() *Enforcer
  • func E(name string, m fire.Matcher, h fire.Handler) *Enforcer
  • func GrantAccess() *Enforcer
  • func WhitelistFields(fields ...string) *Enforcer
• type Handler
• type L
• type M
• type S
• type Strategy
  • func (s *Strategy) Callback() *fire.Callback

Functions

func C

func C(s *Strategy) *fire.Callback

C is a short-hand to define a strategy and return its callback.

Types

type Authorizer

type Authorizer struct {
	// The matcher that decides whether the authorizer can be run.
	Matcher fire.Matcher

	// The handler handler that gets executed with the context.
	Handler Handler
}

An Authorizer should inspect the specified context and assesses if it is able to enforce authorization with the data that is available. If yes, the authorizer should return a set of enforcers that will enforce the authorization.

func A

func A(name string, m fire.Matcher, h Handler) *Authorizer

A is a short-hand function to construct an authorizer. It will also add tracing code around the execution of the authorizer.

func And

func And(a, b *Authorizer) *Authorizer

And will match and run both authorizers and return immediately if one does not return a set of enforcers. The two successfully returned enforcer sets are merged into one and returned.

func Or

func Or(a, b *Authorizer) *Authorizer

Or will match and run the first authorizer and return its enforcers on success. If no enforcers are returned it will match and run the second authorizer and return its enforcers.

func Run

func Run(enforcers ...*Enforcer) *Authorizer

Run will authorize immediately and return the provided list of enforcers.

func (*Authorizer) And

func (a *Authorizer) And(b *Authorizer) *Authorizer

And will run And() with the current and specified authorizer.

func (*Authorizer) Or

func (a *Authorizer) Or(b *Authorizer) *Authorizer

Or will run Or() with the current and specified authorizer.

type Enforcer

type Enforcer = fire.Callback

An Enforcer is returned by an Authorizer to enforce the previously inspected Authorization.

Enforcers should only return errors if the operation is clearly not allowed for the presented candidate and that this information is general knowledge (e.g. API documentation). In order to prevent the leakage of implementation details the enforcer should mutate the context's Query field to hide existing data from the candidate.

func AddFilter

func AddFilter(filter bson.M) *Enforcer

AddFilter will enforce the authorization by adding the passed filter to the Filter query of the context. It should be used if the candidate is allowed to access the resource in general, but some records should be filtered out.

func DenyAccess

func DenyAccess() *Enforcer

DenyAccess will enforce the authorization by directly returning an access denied error. It should be used if the operation should not be authorized in any case (.e.g a candidate accessing a resource he has clearly no access to).

Note: Usually access is denied by returning no enforcer. This enforcer should only be returned to immediately stop the authorization process and prevent other enforcers from authorizing the operation.

func E

func E(name string, m fire.Matcher, h fire.Handler) *Enforcer

E is a short-hand function to create an enforcer.

func GrantAccess

func GrantAccess() *Enforcer

GrantAccess will enforce the authorization without any changes to the context. It should be used if the presented candidate has full access to the data (.e.g a superuser).

func WhitelistFields

func WhitelistFields(fields ...string) *Enforcer

WhitelistFields will enforce the authorization by making sure only the specified fields are returned for the client. If fields are existing it will only remove fields not present in the specified list.

type Handler

type Handler func(*fire.Context) ([]*Enforcer, error)

Handler is a function that inspects an operation context and eventually returns a set of enforcers or an error.

type L

type L []*Authorizer

L is a short-hand type to create a list of authorizers.

type M

type M map[string][]*Authorizer

M is a short-hand type to create a map of authorizers.

type S

type S []*Enforcer

S is a short-hand for set of enforcers.

type Strategy

type Strategy struct {
	// Single operations.
	List   []*Authorizer
	Find   []*Authorizer
	Create []*Authorizer
	Update []*Authorizer
	Delete []*Authorizer

	// Single action operations.
	CollectionAction map[string][]*Authorizer
	ResourceAction   map[string][]*Authorizer

	// All action operations.
	CollectionActions []*Authorizer
	ResourceActions   []*Authorizer

	// All List and Find operations.
	Read []*Authorizer

	// All Create, Update and Delete operations.
	Write []*Authorizer

	// All CollectionAction and ResourceAction operations.
	Actions []*Authorizer

	// All operations.
	All []*Authorizer
}

Strategy contains lists of authorizers that are used to authorize operations.

func (*Strategy) Callback

func (s *Strategy) Callback() *fire.Callback

Callback will return a callback that authorizes operations using the strategy.