auth

Documentation

Index

• Constants
• Variables
• func AddClearIfDeniedToContext(subject Subject, accessPermission AccessPermissions, ...) *structs.ToolContext
• func AddCopyProvidedToContext(fromStruct reflect.Value, tcs ...*structs.ToolContext) *structs.ToolContext
• func NewAccessTool(dp structs.DirectiveProvider) *structs.Tool
• func NewSubject(principals ...Principal) *basicSubject
• func RegisterFieldAccessPrincipals(accessPrincipals ...AccessPrincipal)
• type AccessPermissions
• type AccessPrincipal
  • func NewFieldAccessPrincipal(name string) AccessPrincipal
  • func (p AccessPrincipal) Id() string
  • func (p AccessPrincipal) Release(bool) gomerr.Gomerr
  • func (p AccessPrincipal) Type() PrincipalType
• type Principal
• type PrincipalType
• type Subject

Constants

const (
	ReadWriteAll = "ReadWriteAll"
	ReadAll      = "ReadAll"
	NoAccess     = "NoAccess"
)

Reserved AccessPrincipal names

const (
	ReadPermission AccessPermissions = 1 << iota // = 0b00000001 (1)

	CreatePermission // = 0b00001000 (8)
	UpdatePermission // = 0b00010000 (16)

	WritePermissions     = CreatePermission | UpdatePermission
	LifecyclePermissions = WritePermissions | deletePermission
	NoPermissions        = 0b00000000
	AllPermissions       = ^NoPermissions // 0b11111111

)

const (
	ReadChar     = 'r' // ReadPermission
	WriteChar    = 'w' // CreatePermission | UpdatePermission
	CreateChar   = 'c' // CreatePermission
	UpdateChar   = 'u' // UpdatePermission
	ProvidedChar = 'p' // Provided (field's value is provided by and should be ignored)
	DenyChar     = '-' // No access
)

Variables

var (
	ReadWriteAllFields = AccessPrincipal{ReadWriteAll, fieldAccessPrincipal}
	ReadAllFields      = AccessPrincipal{ReadAll, fieldAccessPrincipal}
	NoFieldAccess      = AccessPrincipal{NoAccess, fieldAccessPrincipal}
)

Built-in, field-scoped AccessPrincipals. Additional principals can be specified by calling RegisterFieldAccessPrincipals

var (
	DefaultAccessTool = NewAccessTool(structs.StructTagDirectiveProvider{"access"})
)

Functions

func AddClearIfDeniedToContext

func AddClearIfDeniedToContext(subject Subject, accessPermission AccessPermissions, tcs ...*structs.ToolContext) *structs.ToolContext

func AddCopyProvidedToContext

func AddCopyProvidedToContext(fromStruct reflect.Value, tcs ...*structs.ToolContext) *structs.ToolContext

func NewAccessTool

func NewAccessTool(dp structs.DirectiveProvider) *structs.Tool

NewAccessTool provides a tool is used to validate that a principal performing an action against the fields of a struct has permissions that grant it. For example, an application may define three AccessPrincipal types: 'admin', 'user', and 'guest', and each has a different set of fields that they can read or write to. An 'admin' may be able to read and write any field, whereas a 'guest' may not be able to write to any fields and can read only a subset of attributes. A 'user' may be able to read and write a set of values, but may still not have permissions to modify certain field values.

Indicating the permissions per principal is done by a Unix filesystem-like 'mode' string (e.g. "rw-r-r-"). While a 'mode' string uses three characters per principal, the FieldAccessTool only uses two. The first indicates whether a field is readable (r) or not (-), and the second character indicates whether the field is writable during create (c), update (u), both (w), or neither (-). As an example, an application with the three principals from above may define a field's access permissions as "rwrcr-", meaning the 'admin' principal can read and write its value, a 'user' can specify the field's value when the struct is created but not change it afterwards, and a 'guest' principal can only read the value.

A special type of permission is used to indicate a field that is not writable, but is instead provided (p) by the application itself in some way and so its value can be ignored. For example, a field that contains a struct's identifier may be auto-populated by the application (e.g. via a path parameter), so it doesn't make sense to describe the value as writable by any of the principals. Note that if there was some special case where, say, an identifier value needed to be updated, the application could use the predefined ReadWriteAll principal to do so.

We don't currently see a use case for allowing some principals to treat an attribute as provided and others not to. To keep the door open for this, though, we require that to specify a field is provided, the 'p' must be set in the leftmost permissions group's write location, and the other permission groups set their write permission value to '-'.

func NewSubject

func NewSubject(principals ...Principal) *basicSubject

func RegisterFieldAccessPrincipals

func RegisterFieldAccessPrincipals(accessPrincipals ...AccessPrincipal)

RegisterFieldAccessPrincipals allows the application to define named principals with different levels of access to the fields that comprise that application's domain entities.

Types

type AccessPermissions

type AccessPermissions uint8

type AccessPrincipal

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

AccessPrincipal corresponds to a named Principal that can be associated with permissions to grant CRUD (extensible to others) abilities on different things w/in an application.

func NewFieldAccessPrincipal

func NewFieldAccessPrincipal(name string) AccessPrincipal

func (AccessPrincipal) Id

func (p AccessPrincipal) Id() string

func (AccessPrincipal) Release

func (p AccessPrincipal) Release(bool) gomerr.Gomerr

func (AccessPrincipal) Type

func (p AccessPrincipal) Type() PrincipalType

type Principal

type Principal interface {
	Id() string
	Type() PrincipalType
	Release(errored bool) gomerr.Gomerr
}

type PrincipalType

type PrincipalType string

const (
	Account PrincipalType = "Account"
	Role    PrincipalType = "Role"
	User    PrincipalType = "User"
	Group   PrincipalType = "Group"
	Request PrincipalType = "Request"
)

type Subject

type Subject interface {
	Principal(principalType PrincipalType) Principal
	Release(errored bool) gomerr.Gomerr
}