ash

package
v0.34.4 Latest Latest
Warning

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

 Go to latest Published: Mar 12, 2024 License: MIT Imports: 10 Imported by: 0

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

Constants

View Source 
const IdentityDataKey = "ash:identity"

IdentityDataKey is the key used to store the identity.

View Source 
const PolicyDataKey = "ash:policy"

PolicyDataKey is the key used to store policies.

Variables

This section is empty.

Functions

func C added in v0.12.2 

func C(s *Strategy) *fire.Callback

C is a shorthand to define a strategy and return its callback.

func Execute added in v0.32.0 

func Execute() *fire.Callback

Execute will execute the selected policy or deny access.

func Identify added in v0.32.0 

func Identify(identifier Identifier) *fire.Callback

Identify will run the provided identifier for all requests to establish the requesters' identity.

func IdentifyPublic added in v0.32.0 

func IdentifyPublic() *fire.Callback

IdentifyPublic will identify public access.

func IdentifyToken added in v0.32.0 

func IdentifyToken(scope []string, identity func(*flame.AuthInfo) Identity) *fire.Callback

IdentifyToken will identity token access.

func Select added in v0.32.0 

func Select(selector Selector) *fire.Callback

Select will run the provided function to select a policy for the supplied identity.

func SelectMatch added in v0.32.0 

func SelectMatch(identity Identity, policy func(Identity) *Policy) *fire.Callback

SelectMatch will match the provided identity and on success use the provided factory to create a policy.

func SelectPublic added in v0.32.0 

func SelectPublic(fn func() *Policy) *fire.Callback

SelectPublic will match the public identity and use the provided factory to create a policy.

Types

type Access added in v0.32.0 

type Access int

Access defines access levels. 

const (
	None Access = 0
	List Access = 1 << iota
	Find
	Create
	Update
	Delete
	Read  = List | Find
	Write = Create | Update | Delete
	Full  = Read | Write
)

The available access levels.

type AccessMatrix added in v0.32.0 

type AccessMatrix map[string][]string

AccessMatrix defines a string based access matrix.

func (AccessMatrix) Compile added in v0.32.0 

func (m AccessMatrix) Compile(columns ...int) AccessTable

Compile return an access table for the provided column.

type AccessTable added in v0.32.0 

type AccessTable map[string]Access

AccessTable defines a string based access table.

func (AccessTable) Collect added in v0.32.0 

func (t AccessTable) Collect(match Access) []string

Collect will return all strings with a matching access level.

type Authorizer 

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

	// The 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 non-zero set of enforcers that will enforce the authorization.

func A added in v0.12.0 

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

A is a shorthand 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 Filter added in v0.29.0 

func Filter(filter bson.M) *Authorizer

Filter will authorize the request by enforcing the provided filter.

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 on success.

func Public added in v0.29.0 

func Public() *Authorizer

Public will authorize the request if nobody is authenticated.

Note: This authorizer requires preliminary un-forced authorization using flame.Callback().

func Token added in v0.29.0 

func Token(scope ...string) *Authorizer

Token will authorize the request if a token with the specified scope has been authenticated.

Note: This authorizer requires preliminary authorization using flame.Callback().

func Whitelist added in v0.21.1 

func Whitelist(m Matrix) []*Authorizer

Whitelist will return a list of authorizers that will authorize field access for the specified candidates in the matrix. Fields is evaluated by checking for the "R" (readable), "C" (creatable), "U" (updatable) 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{Public(), Token("user")},
		Fields: map[string][]string{
			"Title": {"R", "RC"},
			"Body":  {"R", "RW"},
		},
		Properties: map[string][]bool{
			"Info": {false, true},
		},
	}),
}

func WhitelistFields added in v0.14.1 

func WhitelistFields(fields Fields) *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: 

Token("user").And(WhitelistFields(Fields{
	Readable: []string{"Title", "Body"},
	Writable: []string{"Body"},
}))

func WhitelistProperties added in v0.31.0 

func WhitelistProperties(readable []string) *Authorizer

WhitelistProperties is an authorizer that will whitelist the readable properties on the context using enforcers. It is recommended to authorize property 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: 

Token("user").And(WhitelistProperties([]string{"Info"})

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 filter list to hide existing data from the candidate.

func AddFilter added in v0.11.0 

func AddFilter(filter bson.M) *Enforcer

AddFilter will enforce the authorization by adding the passed filter to the Filter list 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 AddRelationshipFilter added in v0.26.1 

func AddRelationshipFilter(rel string, filter bson.M) *Enforcer

AddRelationshipFilter will enforce the authorization by adding the passed relationship filter to the RelationshipFilter field of the context. It should be used if the candidate is allowed to access the relationship in general, but some documents should be filtered out.

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

func DenyAccess added in v0.12.0 

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 enforcers. This enforcer should only be returned to immediately stop the authorization process and prevent other enforcers from authorizing the operation.

func E added in v0.12.0 

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

E is a shorthand function to create an enforcer.

func GrantAccess added in v0.12.0 

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 SetReadableFieldsGetter added in v0.32.0 

func SetReadableFieldsGetter(fn func(ctx *fire.Context, model coal.Model) []string) *Enforcer

SetReadableFieldsGetter will enforce the authorization by setting the specified readable fields getter.

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

func SetReadablePropertiesGetter added in v0.32.0 

func SetReadablePropertiesGetter(fn func(ctx *fire.Context, model coal.Model) []string) *Enforcer

SetReadablePropertiesGetter will enforce the authorization by setting the specified readable properties getter.

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

func SetWritableFieldsGetter added in v0.32.0 

func SetWritableFieldsGetter(fn func(ctx *fire.Context, model coal.Model) []string) *Enforcer

SetWritableFieldsGetter will enforce the authorization by setting the specified writable fields getter.

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

func WhitelistReadableFields added in v0.15.0 

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 WhitelistReadableProperties added in v0.31.0 

func WhitelistReadableProperties(fields ...string) *Enforcer

WhitelistReadableProperties will enforce the authorization by making sure only the specified properties are returned for the client.

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

func WhitelistWritableFields added in v0.15.0 

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 Fields added in v0.25.3 

type Fields struct {
	Readable  []string
	Writable  []string
	Creatable []string
	Updatable []string
}

Fields defines the readable and writable fields.

type Handler added in v0.12.0 

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

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

type Identifier added in v0.32.0 

type Identifier func(ctx *fire.Context) (Identity, error)

Identifier is the function run establish an identity.

type Identity added in v0.32.0 

type Identity interface{}

Identity describes the common interface for identities which currently allows for any value to represent an identity.

type L 

type L = []*Authorizer

L is a shorthand type to create a list of authorizers.

type M added in v0.10.0 

type M = map[string][]*Authorizer

M is a shorthand type to create a map of authorizers.

type Matrix added in v0.21.1 

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

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

	// Fields is the matrix that specifies read and write permissions per field
	// and candidate using the tags "R", "C", "U" and "W".
	Fields map[string][]string

	// Properties is the matrix that specifies read permissions per property and
	// candidate.
	Properties map[string][]bool
}

Matrix is used for declarative specification of field and property access for multiple candidates.

func (*Matrix) CollectFields added in v0.31.0 

func (m *Matrix) CollectFields(i int, tags ...string) []string

CollectFields will return a list of fields for the specified column in the matrix which match at least one of the provided tags.

func (*Matrix) CollectProperties added in v0.31.0 

func (m *Matrix) CollectProperties(i int) []string

CollectProperties will return a list of properties for the specified column in the matrix.

type NamedAccessMatrix added in v0.32.0 

type NamedAccessMatrix struct {
	Columns []string
	Matrix  AccessMatrix
}

NamedAccessMatrix defines a named string based access matrix.

func (NamedAccessMatrix) Compile added in v0.32.0 

func (m NamedAccessMatrix) Compile(columns ...string) AccessTable

Compile return an access table for the provided column.

type Policy added in v0.32.0 

type Policy struct {
	// Access defines the general access.
	Access Access

	// Actions defines the allowed actions.
	Actions map[string]bool

	// The default fields used to determine the field access level. If the
	// getter is set, these will only be used to establish valid filters and
	// sorters during the fire.List operation authorizer stage, as well as the
	// writable fields during the fire.Create operation, otherwise the model
	// specific fields are used instead.
	Fields AccessTable

	// GetFilter is called to obtain the general resource access filter. This
	// filter is used to narrow down accessible resources in all operations
	// except fire.Create and fire.CollectionAction operations.
	GetFilter func(ctx *fire.Context) bson.M

	// VerifyID is called to for every direct model lookup to verify resource
	// level access. This function is called for all operations except fire.List,
	// fire.Create and fire.CollectionAction.
	VerifyID func(ctx *fire.Context, id coal.ID) Access

	// VerifyModel is called for every model load from the database to determine
	// resource level access. This function is called for all operations except
	// fire.Create and fire.CollectionAction.
	//
	// Note: The verification is deferred to the fire.Verifier stage.
	VerifyModel func(ctx *fire.Context, model coal.Model) Access

	// VerifyCreate and VerifyUpdate determine resource level access after all
	// modification have been applied. This function is called for the
	// fire.Create and fire.Update operation.
	//
	// Note: The verification is deferred to the fire.Validator stage.
	VerifyCreate func(ctx *fire.Context, model coal.Model) bool
	VerifyUpdate func(ctx *fire.Context, model coal.Model) bool

	// GetFields and GetProperties is called for every model to determine the
	// field and property level access. The function is called for all operations
	// except fire.Delete, fire.CollectionAction and fire.ResourceAction.
	//
	// Note: The policy should refrain from creating a new map for every request
	// and instead pre-allocate possible combinations and return those.
	GetFields     func(ctx *fire.Context, model coal.Model) AccessTable
	GetProperties func(ctx *fire.Context, model coal.Model) AccessTable
}

Policy defines an authorization policy.

type PublicIdentity added in v0.32.0 

type PublicIdentity struct{}

PublicIdentity is a generic public identity.

type S added in v0.13.0 

type S = []*Enforcer

S is a shorthand for a set of enforcers.

type Selector added in v0.32.0 

type Selector func(Identity) *Policy

Selector is the function run to select a policy.

type Strategy 

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

	// individual 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. The authorizes are run in order beginning with the most specific authorizer. The first authorizer that returns no error and a non-empty set of enforcers has its enforcers applied to the request. If the enforcers do not return and error the access is granted.

func (*Strategy) Callback added in v0.12.2 

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

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.