permissions

Documentation

Overview

Package permissions implements an echo middleware to simplify checking permission checks in downstream handlers by adding a checking function to the context which may later be called to check permissions.

Index

• Variables
• func CheckAccess(ctx context.Context, resource gidx.PrefixedID, action string) error
• func CheckAll(ctx context.Context, requests ...AccessRequest) error
• func CreateAuthRelationships(ctx context.Context, topic string, resourceID gidx.PrefixedID, ...) error
• func DeleteAuthRelationships(ctx context.Context, topic string, resourceID gidx.PrefixedID, ...) error
• func MustViperFlags(v *viper.Viper, flags *pflag.FlagSet)
• type AccessRequest
• type AuthRelationshipRequestHandler
• type Checker
• type Config
• type Option
  • func WithDefaultChecker(checker Checker) Option
  • func WithEventsPublisher(publisher events.AuthRelationshipPublisher) Option
  • func WithHTTPClient(client *http.Client) Option
  • func WithLogger(logger *zap.SugaredLogger) Option
  • func WithSkipper(skipper middleware.Skipper) Option
• type Permissions
  • func New(config Config, options ...Option) (*Permissions, error)
  • func (p *Permissions) CreateAuthRelationships(ctx context.Context, topic string, resourceID gidx.PrefixedID, ...) error
  • func (p *Permissions) DeleteAuthRelationships(ctx context.Context, topic string, resourceID gidx.PrefixedID, ...) error
  • func (p *Permissions) Middleware() echo.MiddlewareFunc

Variables

var (
	// Error is the root error for all permissions related errors.
	Error = errors.New("permissions error")

	// AuthError is the root error all auth related errors stem from.
	AuthError = fmt.Errorf("%w: auth", Error) //nolint:revive,stylecheck // not returned directly, but used as a root error.

	// ErrNoAuthToken is the error returned when there is no auth token provided for the API request
	ErrNoAuthToken = echo.ErrBadRequest.WithInternal(fmt.Errorf("%w: no auth token provided for client", AuthError))

	// ErrInvalidAuthToken is the error returned when the auth token is not the expected value
	ErrInvalidAuthToken = echo.ErrBadRequest.WithInternal(fmt.Errorf("%w: invalid auth token", AuthError))

	// ErrPermissionDenied is the error returned when permission is denied to a call
	ErrPermissionDenied = echo.ErrUnauthorized.WithInternal(fmt.Errorf("%w: subject doesn't have access", AuthError))

	// ErrBadResponse is the error returned when we receive a bad response from the server
	ErrBadResponse = fmt.Errorf("%w: bad response from server", Error)

	// ErrCheckerNotFound is the error returned when CheckAccess does not find the appropriate checker context
	ErrCheckerNotFound = fmt.Errorf("%w: no checker found in context", Error)

	// ErrPermissionsMiddlewareMissing is returned when a permissions method has been called but the middleware is missing.
	ErrPermissionsMiddlewareMissing = fmt.Errorf("%w: permissions middleware missing", Error)
)

var (
	// AuthRelationshipRequestHandlerCtxKey is the context key used to set the auth relationship request handler.
	AuthRelationshipRequestHandlerCtxKey = authRelationshipRequestHandlerCtxKey{}
)

Functions

func CheckAccess

func CheckAccess(ctx context.Context, resource gidx.PrefixedID, action string) error

CheckAccess runs the checker function to check if the provided resource and action are supported.

func CheckAll

func CheckAll(ctx context.Context, requests ...AccessRequest) error

CheckAll runs the checker function to check if all the provided resources and actions are permitted.

func CreateAuthRelationships

func CreateAuthRelationships(ctx context.Context, topic string, resourceID gidx.PrefixedID, relations ...events.AuthRelationshipRelation) error

CreateAuthRelationships publishes a create auth relationship request, blocking until a response has been received.

func DeleteAuthRelationships

func DeleteAuthRelationships(ctx context.Context, topic string, resourceID gidx.PrefixedID, relations ...events.AuthRelationshipRelation) error

DeleteAuthRelationships publishes a delete auth relationship request, blocking until a response has been received.

func MustViperFlags

func MustViperFlags(v *viper.Viper, flags *pflag.FlagSet)

MustViperFlags adds permissions config flags and viper bindings

Types

type AccessRequest

type AccessRequest struct {
	ResourceID gidx.PrefixedID `json:"resource_id"`
	Action     string          `json:"action"`
}

AccessRequest defines the required fields to check permissions access.

type AuthRelationshipRequestHandler

type AuthRelationshipRequestHandler interface {
	CreateAuthRelationships(ctx context.Context, topic string, resourceID gidx.PrefixedID, relations ...events.AuthRelationshipRelation) error
	DeleteAuthRelationships(ctx context.Context, topic string, resourceID gidx.PrefixedID, relations ...events.AuthRelationshipRelation) error
}

AuthRelationshipRequestHandler defines the required methods to create or update an auth relationship.

type Checker

type Checker func(ctx context.Context, requests ...AccessRequest) error

Checker defines the checker function definition

var (
	// CheckerCtxKey is the context key used to set the checker handling function
	CheckerCtxKey = checkerCtxKey{}

	// DefaultAllowChecker defaults to allow when checker is disabled or skipped
	DefaultAllowChecker Checker = func(_ context.Context, _ ...AccessRequest) error {
		return nil
	}

	// DefaultDenyChecker defaults to denied when checker is disabled or skipped
	DefaultDenyChecker Checker = func(_ context.Context, _ ...AccessRequest) error {
		return ErrPermissionDenied
	}
)

type Config

type Config struct {
	// URL should point to a permissions-api authorization API route, such as https://example.com/api/v1/allow.
	// If not set, all permissions checks will be denied by default. To override this behavior, set DefaultAllow
	// to true.
	URL string

	// IgnoreNoResponders will ignore no responder errors when auth relationship requests are published.
	IgnoreNoResponders bool

	// DefaultAllow if set to true, will allow all permissions checks when URL is not set.
	DefaultAllow bool
}

Config defines the permissions configuration structure

type Option

type Option func(p *Permissions) error

Option defines an option configurator

func WithDefaultChecker

func WithDefaultChecker(checker Checker) Option

WithDefaultChecker sets the default checker if the middleware is skipped

func WithEventsPublisher

func WithEventsPublisher(publisher events.AuthRelationshipPublisher) Option

WithEventsPublisher sets the underlying event publisher the auth handler uses

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sets the underlying http client the auth handler uses

func WithLogger

func WithLogger(logger *zap.SugaredLogger) Option

WithLogger sets the logger for the auth handler

func WithSkipper

func WithSkipper(skipper middleware.Skipper) Option

WithSkipper sets the echo middleware skipper function

type Permissions

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

Permissions handles supporting authorization checks

func New

func New(config Config, options ...Option) (*Permissions, error)

New creates a new Permissions instance

func (*Permissions) CreateAuthRelationships

func (p *Permissions) CreateAuthRelationships(ctx context.Context, topic string, resourceID gidx.PrefixedID, relations ...events.AuthRelationshipRelation) error

CreateAuthRelationships publishes a create auth relationship request, blocking until a response has been received.

func (*Permissions) DeleteAuthRelationships

func (p *Permissions) DeleteAuthRelationships(ctx context.Context, topic string, resourceID gidx.PrefixedID, relations ...events.AuthRelationshipRelation) error

DeleteAuthRelationships publishes a delete auth relationship request, blocking until a response has been received.

func (*Permissions) Middleware

func (p *Permissions) Middleware() echo.MiddlewareFunc

Middleware produces echo middleware to handle authorization checks