permission

Documentation

Overview

Package permission handles checking and granting of permissions using context.Context.

A context can be granted User, System, or Service privileges using UserContext, SystemContext, or ServiceContext, respectively.

Data can be extracted using the appropriate method (e.g. UserID, ServiceID, etc...)

Context can then be validated using Checkers (e.g. like the User function) or by using LimitCheckAny and a number of Checkers together.

Index

• func Admin(ctx context.Context) bool
• func All(ctx context.Context) bool
• func AuthCheckCount(ctx context.Context) (value, max uint64)
• func AuthCheckCountContext(ctx context.Context, max uint64) context.Context
• func IsPermissionError(err error) bool
• func IsUnauthorized(err error) bool
• func LimitCheckAny(ctx context.Context, checks ...Checker) error
• func NewAccessDenied(reason string) error
• func Service(ctx context.Context) bool
• func ServiceContext(ctx context.Context, serviceID string) context.Context
• func ServiceID(ctx context.Context) string
• func ServiceSourceContext(ctx context.Context, id string, src *SourceInfo) context.Context
• func SourceContext(ctx context.Context, src *SourceInfo) context.Context
• func SudoContext(ctx context.Context, f func(context.Context))
• func System(ctx context.Context) bool
• func SystemComponentName(ctx context.Context) string
• func SystemContext(ctx context.Context, componentName string) context.Context
• func Team(ctx context.Context) bool
• func TeamContext(ctx context.Context, teamID string) context.Context
• func TeamID(ctx context.Context) string
• func Unauthorized() error
• func User(ctx context.Context) bool
• func UserContext(ctx context.Context, id string, r Role) context.Context
• func UserID(ctx context.Context) string
• func UserSourceContext(ctx context.Context, id string, r Role, src *SourceInfo) context.Context
• func WithoutAuth(ctx context.Context) context.Context
• type Checker
  • func MatchService(serviceID string) Checker
  • func MatchTeam(teamID string) Checker
  • func MatchUser(userID string) Checker
• type Error
• type Role
  • func (r *Role) Scan(value interface{}) error
  • func (r Role) Value() (driver.Value, error)
• type SourceInfo
  • func Source(ctx context.Context) *SourceInfo
  • func (s SourceInfo) String() string
• type SourceType
  • func (i SourceType) String() string

Examples

• SudoContext
• UserContext

Functions

func Admin

func Admin(ctx context.Context) bool

Admin is a Checker that determines if a context has the Admin or System role.

func All

func All(ctx context.Context) bool

All is a Checker that checks against ALL providers, returning true if any are found.

func AuthCheckCount

func AuthCheckCount(ctx context.Context) (value, max uint64)

AuthCheckCount will return the current number of authorization checks as well as the maximum.

func AuthCheckCountContext

func AuthCheckCountContext(ctx context.Context, max uint64) context.Context

AuthCheckCountContext will return a new context with the AuthCheckCount maximum set to the provided value. If max is 0, there will be no limit.

func IsPermissionError

func IsPermissionError(err error) bool

IsPermissionError will determine if the root error cause is a permission error.

func IsUnauthorized

func IsUnauthorized(err error) bool

IsUnauthorized will determine if the root error cause is an unauthorized permission error.

func LimitCheckAny

func LimitCheckAny(ctx context.Context, checks ...Checker) error

LimitCheckAny will return a permission error if none of the checks pass, or if the auth check limit is reached. If no checks are provided, only the limit check, and a check that the context has SOME type authorization is performed. nil can be passed as an always-fail check option (useful to prevent the no-check behavior, if required).

func NewAccessDenied

func NewAccessDenied(reason string) error

NewAccessDenied will return a new generic access denied error.

func Service

func Service(ctx context.Context) bool

Service is a Checker that determines if a context has a serviceID.

func ServiceContext

func ServiceContext(ctx context.Context, serviceID string) context.Context

ServiceContext will return a new context with privileges for the given service.

func ServiceID

func ServiceID(ctx context.Context) string

ServiceID will return the ServiceID associated with a context.

func ServiceSourceContext

func ServiceSourceContext(ctx context.Context, id string, src *SourceInfo) context.Context

ServiceSourceContext behaves like ServiceContext, but provides SourceInfo about the authorization.

func SourceContext

func SourceContext(ctx context.Context, src *SourceInfo) context.Context

SourceContext will return a context with the provided SourceInfo.

func SudoContext

func SudoContext(ctx context.Context, f func(context.Context))

SudoContext elevates an existing context to system level. The elevated context is automatically canceled as soon as the callback returns.

Example

ExampleSudoContext shows how to use SudoContext.

// the original context could be from anywhere (req.Context() in an http.Handler for example)
ctx := context.Background()
SudoContext(ctx, func(ctx context.Context) {
	// within this function scope, ctx now has System privileges
})
// once the function returns, the elevated context is canceled, but the original ctx is still valid

func System

func System(ctx context.Context) bool

System is a Checker that determines if a context has system privileges.

func SystemComponentName

func SystemComponentName(ctx context.Context) string

SystemComponentName will return the component name used to initiate a context.

func SystemContext

func SystemContext(ctx context.Context, componentName string) context.Context

SystemContext will return a new context with the system privileges. Name must be alphanumeric.

func Team

func Team(ctx context.Context) bool

Team is a Checker that determines if a context has team privileges.

func TeamContext

func TeamContext(ctx context.Context, teamID string) context.Context

TeamContext will return a new context with privileges for the given team.

func TeamID

func TeamID(ctx context.Context) string

TeamID will return the TeamID associated with a context.

func Unauthorized

func Unauthorized() error

Unauthorized will return an unauthorized error.

func User

func User(ctx context.Context) bool

User is a Checker that determines if a context has the User, Admin or System role.

func UserContext

func UserContext(ctx context.Context, id string, r Role) context.Context

UserContext will return a context authenticated with the users privileges.

Example

// start with any context
ctx := context.Background()

// pass it through UserContext to assign a user ID and Role
ctx = UserContext(ctx, "user-id-here", RoleAdmin)

// later on it can be checked anywhere; this example will satisfy the Admin role requirement
err := LimitCheckAny(ctx, Admin)

fmt.Println(err)

Output:

<nil>

func UserID

func UserID(ctx context.Context) string

UserID will return the UserID associated with a context.

func UserSourceContext

func UserSourceContext(ctx context.Context, id string, r Role, src *SourceInfo) context.Context

UserSourceContext behaves like UserContext, but provides SourceInfo about the authorization.

func WithoutAuth

func WithoutAuth(ctx context.Context) context.Context

WithoutAuth returns a context will all auth info stripped out.

Types

type Checker

type Checker func(context.Context) bool

A Checker is used to give a pass-or-fail result for a given context.

func MatchService

func MatchService(serviceID string) Checker

MatchService will return a Checker that ensures the context has the given ServiceID.

func MatchTeam

func MatchTeam(teamID string) Checker

MatchTeam will return a Checker that ensures the context has the given TeamID.

func MatchUser

func MatchUser(userID string) Checker

MatchUser will return a Checker that ensures the context has the given UserID.

type Error

type Error interface {
	error
	Permission() bool // Is the error permission denied?
	Unauthorized() bool
}

Error represents an auth error where the context does not have a sufficient role for the operation.

type Role

type Role string

Role represents a users access level

const (
	RoleUser    Role = "user"
	RoleAdmin   Role = "admin"
	RoleUnknown Role = "unknown"
)

Available roles

func (*Role) Scan

func (r *Role) Scan(value interface{}) error

Scan handles reading a Role from the DB format

func (Role) Value

func (r Role) Value() (driver.Value, error)

Value converts the Role to the DB representation

type SourceInfo

type SourceInfo struct {
	Type SourceType
	ID   string
}

SourceInfo provides information about the source of a context's authorization.

func Source

func Source(ctx context.Context) *SourceInfo

Source will return the SourceInfo associated with a context.

func (SourceInfo) String

func (s SourceInfo) String() string

type SourceType

type SourceType int

SourceType describes a type of authentication used to authorize a context.

const (
	// SourceTypeNotificationCallback is set when a context is authenticated via the response to an outgoing notification.
	SourceTypeNotificationCallback SourceType = iota

	// SourceTypeIntegrationKey is set when an integration key is used to provide permission on a context.
	SourceTypeIntegrationKey

	// SourceTypeAuthProvider is set when a provider from the auth package is used (e.g. the web UI).
	SourceTypeAuthProvider

	// SourceTypeContactMethod is set when a context is authorized for use of a user's contact method.
	SourceTypeContactMethod

	// SourceTypeHeartbeat is set when a context is authorized for use of a service's heartbeat.
	SourceTypeHeartbeat

	// SourceTypeNotificationChannel is set when a context is authorized for use of a notification channel.
	SourceTypeNotificationChannel

	// SourceTypeCalendarSubscription is set when a context is authorized for use of a calendar subscription.
	SourceTypeCalendarSubscription

	// SourceTypeGQLAPIKey is set when a context is authorized for use of the GraphQL API.
	SourceTypeGQLAPIKey
)

func (SourceType) String

func (i SourceType) String() string