basculechecks

Documentation

Index

• Constants
• Variables
• func DeterminePartnerMetric(partners []string) string
• func Metrics() []xmetrics.Metric
• func PartnerKeys() []string
• func ProvideMetrics() fx.Option
• func ProvideMetricsVec() fx.Option
• type AlwaysCheck
  • func (a AlwaysCheck) Authorized(_, _, _ string) bool
• type AuthCapabilityCheckMeasures
  • func NewAuthCapabilityCheckMeasures(p provider.Provider) *AuthCapabilityCheckMeasures
• type BaseMeasuresIn
• type CapabilitiesChecker
• type CapabilitiesMap
  • func (c CapabilitiesMap) Check(auth bascule.Authentication, vs ParsedValues) (string, error)
• type CapabilitiesValidator
  • func (c CapabilitiesValidator) Check(auth bascule.Authentication, _ ParsedValues) (string, error)
  • func (c CapabilitiesValidator) CreateValidator(errorOut bool) bascule.ValidatorFunc
• type CapabilityChecker
• type ConstCheck
  • func (c ConstCheck) Authorized(capability, _, _ string) bool
• type EndpointRegexCheck
  • func NewEndpointRegexCheck(prefix string, acceptAllMethod string) (EndpointRegexCheck, error)
  • func (e EndpointRegexCheck) Authorized(capability string, urlToMatch string, methodToMatch string) bool
• type MeasuresFactory
  • func (m MeasuresFactory) Annotated() fx.Annotated
  • func (m MeasuresFactory) NewMeasures(in BaseMeasuresIn) (*AuthCapabilityCheckMeasures, error)
• type MetricValidator
  • func (m MetricValidator) CreateValidator(errorOut bool) bascule.ValidatorFunc
• type ParsedValues

Constants

const (
	OutcomeLabel   = "outcome"
	ReasonLabel    = "reason"
	ClientIDLabel  = "clientid"
	EndpointLabel  = "endpoint"
	PartnerIDLabel = "partnerid"
	ServerLabel    = "server"
)

labels

const (
	RejectedOutcome = "rejected"
	AcceptedOutcome = "accepted"
	// reasons
	TokenMissing             = "auth_missing"
	UndeterminedPartnerID    = "undetermined_partner_ID"
	UndeterminedCapabilities = "undetermined_capabilities"
	EmptyCapabilitiesList    = "empty_capabilities_list"
	TokenMissingValues       = "auth_is_missing_values"
	NoCapabilityChecker      = "no_capability_checker"
	NoCapabilitiesMatch      = "no_capabilities_match"
	EmptyParsedURL           = "empty_parsed_URL"
)

outcomes

const (
	AuthCapabilityCheckOutcome = "auth_capability_check"
)

Names for our metrics

const (
	CapabilityKey = "capabilities"
)

Variables

var (
	ErrNilDefaultChecker = errors.New("default checker cannot be nil")
	ErrEmptyEndpoint     = errors.New("endpoint provided is empty")
)

var (
	ErrNoVals                 = errors.New("expected at least one value")
	ErrNoAuth                 = errors.New("couldn't get request info: authorization not found")
	ErrNoToken                = errors.New("no token found in Auth")
	ErrNoValidCapabilityFound = errors.New("no valid capability for endpoint")
	ErrNilAttributes          = errors.New("nil attributes interface")
	ErrNoURL                  = errors.New("invalid URL found in Auth")
)

Functions

func DeterminePartnerMetric

func DeterminePartnerMetric(partners []string) string

DeterminePartnerMetric takes a list of partners and decides what the partner metric label should be.

func Metrics

func Metrics() []xmetrics.Metric

Metrics returns the Metrics relevant to this package targeting our older non uber/fx applications. To initialize the metrics, use NewAuthCapabilityCheckMeasures().

func PartnerKeys

func PartnerKeys() []string

func ProvideMetrics

func ProvideMetrics() fx.Option

ProvideMetrics provides the metrics relevant to this package as uber/fx options. This is now deprecated in favor of ProvideMetricsVec.

func ProvideMetricsVec

func ProvideMetricsVec() fx.Option

ProvideMetricsVec provides the metrics relevant to this package as uber/fx options. The provided metrics are prometheus vectors which gives access to more advanced operations such as CurryWith(labels).

Types

type AlwaysCheck

type AlwaysCheck bool

AlwaysCheck is a CapabilityChecker that always returns either true or false.

func (AlwaysCheck) Authorized

func (a AlwaysCheck) Authorized(_, _, _ string) bool

Authorized returns the saved boolean value, rather than checking the parameters given.

type AuthCapabilityCheckMeasures

type AuthCapabilityCheckMeasures struct {
	CapabilityCheckOutcome metrics.Counter
}

AuthCapabilityCheckMeasures describes the defined metrics that will be used by clients

func NewAuthCapabilityCheckMeasures

func NewAuthCapabilityCheckMeasures(p provider.Provider) *AuthCapabilityCheckMeasures

NewAuthCapabilityCheckMeasures realizes desired metrics. It's intended to be used alongside Metrics() for our older non uber/fx applications.

type BaseMeasuresIn

type BaseMeasuresIn struct {
	fx.In
	Logger                 log.Logger
	CapabilityCheckOutcome *prometheus.CounterVec `name:"auth_capability_check"`
}

BaseMeasuresIn is an uber/fx parameter with base metrics ready to be curried into child metrics based on custom labels.

type CapabilitiesChecker

type CapabilitiesChecker interface {
	Check(auth bascule.Authentication, vals ParsedValues) (string, error)
}

CapabilitiesChecker is an object that can determine if a request is authorized given a bascule.Authentication object. If it's not authorized, a reason and error are given for logging and metrics.

type CapabilitiesMap

type CapabilitiesMap struct {
	Checkers       map[string]CapabilityChecker
	DefaultChecker CapabilityChecker
}

CapabilitiesMap runs a capability check based on the value of the parsedURL, which is the key to the CapabilitiesMap's map. The parsedURL is expected to be some regex values, allowing for bucketing of urls that contain some kind of ID or otherwise variable portion of a URL.

func (CapabilitiesMap) Check

func (c CapabilitiesMap) Check(auth bascule.Authentication, vs ParsedValues) (string, error)

Check uses the parsed endpoint value to determine which CapabilityChecker to run against the capabilities in the auth provided. If there is no CapabilityChecker for the endpoint, the default is used. As long as one capability is found to be authorized by the CapabilityChecker, no error is returned.

type CapabilitiesValidator

type CapabilitiesValidator struct {
	Checker CapabilityChecker
}

CapabilitiesValidator checks the capabilities provided in a bascule.Authentication object to determine if a request is authorized. It can also provide a function to be used in authorization middleware that pulls the Authentication object from a context before checking it.

func (CapabilitiesValidator) Check

func (c CapabilitiesValidator) Check(auth bascule.Authentication, _ ParsedValues) (string, error)

Check takes the needed values out of the given Authentication object in order to determine if a request is authorized. It determines this through iterating through each capability and calling the CapabilityChecker. If no capability authorizes the client for the given endpoint and method, it is unauthorized.

func (CapabilitiesValidator) CreateValidator

func (c CapabilitiesValidator) CreateValidator(errorOut bool) bascule.ValidatorFunc

CreateValidator creates a function that determines whether or not a client is authorized to make a request to an endpoint. It uses the bascule.Authentication from the context to get the information needed by the CapabilityChecker to determine authorization.

type CapabilityChecker

type CapabilityChecker interface {
	Authorized(string, string, string) bool
}

CapabilityChecker is an object that can determine if a capability provides authorization to the endpoint.

type ConstCheck

type ConstCheck string

ConstCheck is a basic capability checker that determines a capability is authorized if it matches the ConstCheck's string.

func (ConstCheck) Authorized

func (c ConstCheck) Authorized(capability, _, _ string) bool

Authorized validates the capability provided against the stored string.

type EndpointRegexCheck

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

EndpointRegexCheck uses a regular expression to validate an endpoint and method provided in a capability against the endpoint hit and method used for the request.

func NewEndpointRegexCheck

func NewEndpointRegexCheck(prefix string, acceptAllMethod string) (EndpointRegexCheck, error)

NewEndpointRegexCheck creates an object that implements the CapabilityChecker interface. It takes a prefix that is expected at the beginning of a capability and a string that, if provided in the capability, authorizes all methods for that endpoint. After the prefix, the EndpointRegexCheck expects there to be an endpoint regular expression and an http method - separated by a colon. The expected format of a capability is: <prefix><endpoint regex>:<method>

func (EndpointRegexCheck) Authorized

func (e EndpointRegexCheck) Authorized(capability string, urlToMatch string, methodToMatch string) bool

Authorized checks the capability against the endpoint hit and method used. If the capability has the correct prefix and is meant to be used with the method provided to access the endpoint provided, it is authorized.

type MeasuresFactory

type MeasuresFactory struct {
	ServerName string
}

MeasuresFactory facilitates the creation of child metrics based on server labels.

func (MeasuresFactory) Annotated

func (m MeasuresFactory) Annotated() fx.Annotated

Annotated provides the measures as an annotated component with the name "[SERVER]_bascule_capability_measures"

func (MeasuresFactory) NewMeasures

func (m MeasuresFactory) NewMeasures(in BaseMeasuresIn) (*AuthCapabilityCheckMeasures, error)

NewMeasures builds the metric listener from the provided raw metrics.

type MetricValidator

type MetricValidator struct {
	C         CapabilitiesChecker
	Measures  *AuthCapabilityCheckMeasures
	Endpoints []*regexp.Regexp
}

MetricValidator determines if a request is authorized and then updates a metric to show those results.

func (MetricValidator) CreateValidator

func (m MetricValidator) CreateValidator(errorOut bool) bascule.ValidatorFunc

CreateValidator provides a function for authorization middleware. The function parses the information needed for the CapabilitiesChecker, calls it to determine if the request is authorized, and maintains the results in a metric. The function can actually mark the request as unauthorized or just update the metric and allow the request, depending on configuration. This allows for monitoring before being more strict with authorization.

type ParsedValues

type ParsedValues struct {
	// Endpoint is the string representation of a regular expression that
	// matches the URL for the request.  The main benefit of this string is it
	// most likely won't include strings that change from one request to the
	// next (ie, device ID).
	Endpoint string
	// Partner is a string representation of the list of partners found in the
	// JWT, where:
	//   - any list including "*" as a partner is determined to be "wildcard".
	//   - when the list is <1 item, the partner is determined to be "none".
	//   - when the list is >1 item, the partner is determined to be "many".
	//   - when the list is only one item, that is the partner value.
	Partner string
}

ParsedValues are values determined from the bascule Authentication.