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 Whitelist(m Matrix) []*Authorizer
  • func WhitelistFields(readable, writable []string) *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 WhitelistReadableFields(fields ...string) *Enforcer
  • func WhitelistWritableFields(fields ...string) *Enforcer
• type Handler
• type L
• type M
• type Matrix
  • func (m *Matrix) Collect(i int, tag string) []string
• 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 Whitelist

func Whitelist(m Matrix) []*Authorizer

Whitelist will return a list of authorizers that will authorize field access for the specified candidates in the matrix. Access is evaluated by checking for the "R" (readable) and "W" (writable) tag in the proper row and column of the matrix. It is recommended to authorize field access in a separate strategy following general resource access as the returned enforcers will always authorize the request:

ash.C(&ash.Strategy{
	All: ash.Whitelist(ash.Matrix{
		Model: &Post{},
		Candidates: ash.L{User(), Admin()},
		Access: map[string][]string{
			"Title": {"R", "RW"},
			"Body":  {"R", "RW"},
		},
	}),
}

func WhitelistFields

func WhitelistFields(readable, writable []string) *Authorizer

WhitelistFields is an authorizer that will whitelist the readable and writable fields on the context using enforcers. It is recommended to authorize field access in a separate strategy following general resource access as the returned enforcers will always authorize the request. Furthermore, the easiest is to implement a custom candidate authorizer with which this authorizer can be chained together:

User().And(WhitelistFields(
	[]string{"foo", "bar"},
	[]string{"foo"},
))

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 documents should be filtered out.

Note: This enforcer cannot be used to authorize Create and CollectionAction operations.

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 stand-alone if the presented candidate has full access to the data (.e.g a superuser) or in an authorizer chain to delegate authorization to the next authorizer.

func WhitelistReadableFields

func WhitelistReadableFields(fields ...string) *Enforcer

WhitelistReadableFields will enforce the authorization by making sure only the specified fields are returned for the client.

Note: This enforcer cannot be used to authorize Delete, ResourceAction and CollectionAction operations.

func WhitelistWritableFields

func WhitelistWritableFields(fields ...string) *Enforcer

WhitelistWritableFields will enforce the authorization by making sure only the specified fields can be changed by the client.

Note: This enforcer can only be used to authorize Create and Update operations.

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 Matrix

type Matrix struct {
	// Model is the model being authorized.
	Model coal.Model

	// Candidates are the authorizers that establish individual candidate
	// authorization.
	Candidates []*Authorizer

	// Access is the matrix that specifies read and write access per and field
	// and candidate using the tags "R" and "W".
	Access map[string][]string
}

Matrix is used declaratively specify field access of multiple candidates.

func (*Matrix) Collect

func (m *Matrix) Collect(i int, tag string) []string

Collect will return a list of fields for the specified column and tag in the matrix.

type S

type S []*Enforcer

S is a short-hand for a 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.