basculehelper

Documentation

Index

• Constants
• Variables
• func DeterminePartnerMetric(partners []string) string
• func Metrics() []xmetrics.Metric
• func PartnerKeys() []string
• type AlwaysCheck
  • func (a AlwaysCheck) Authorized(_, _, _ string) bool
• type AuthCapabilityCheckMeasures
  • func NewAuthCapabilityCheckMeasures(p provider.Provider) *AuthCapabilityCheckMeasures
• type AuthValidationMeasures
  • func NewAuthValidationMeasures(r xmetrics.Registry) *AuthValidationMeasures
• type CapabilitiesChecker
• type CapabilitiesError
  • func NewCapabilitiesError(capabilities []string, reqUrl string, method string) *CapabilitiesError
  • func (c *CapabilitiesError) Error() string
• 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 MetricListener
  • func NewMetricListener(m *AuthValidationMeasures, options ...Option) *MetricListener
  • func (m *MetricListener) OnAuthenticated(auth bascule.Authentication)
  • func (m *MetricListener) OnErrorResponse(e basculehttp.ErrorResponseReason, _ error)
• type MetricValidator
  • func (m MetricValidator) CreateValidator(errorOut bool) bascule.ValidatorFunc
• type Option
• type ParsedValues

Constants

const (
	CapabilityKey = "capabilities"

	RejectedOutcome = "rejected"
	AcceptedOutcome = "accepted"
	// reasons
	TokenMissing               = "auth_missing"
	UndeterminedPartnerID      = "undetermined_partner_ID"
	NoCapabilityChecker        = "no_capability_checker"
	EmptyParsedURL             = "empty_parsed_URL"
	AuthCapabilityCheckOutcome = "auth_capability_check"
	AuthValidationOutcome      = "auth_validation"

	EmptyCapabilitiesList    = "empty_capabilities_list"
	MissingValues            = "auth_is_missing_values"
	UndeterminedCapabilities = "undetermined_capabilities"
	NoCapabilitiesMatch      = "no_capabilities_match"
	//nolint:gosec
	TokenMissingValues = "auth_is_missing_values"

	//labels
	OutcomeLabel   = "outcome"
	ReasonLabel    = "reason"
	ClientIDLabel  = "clientid"
	EndpointLabel  = "endpoint"
	PartnerIDLabel = "partnerid"
	ServerLabel    = "server"
)

Variables

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

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 AuthValidationMeasures

type AuthValidationMeasures struct {
	NBFHistogram      metrics.Histogram
	ExpHistogram      metrics.Histogram
	ValidationOutcome metrics.Counter
}

AuthValidationMeasures describes the defined metrics that will be used by clients

func NewAuthValidationMeasures

func NewAuthValidationMeasures(r xmetrics.Registry) *AuthValidationMeasures

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

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 CapabilitiesError

type CapabilitiesError struct {
	CapabilitiesFound []string
	UrlToMatch        string
	MethodToMatch     string
}

func NewCapabilitiesError

func NewCapabilitiesError(capabilities []string, reqUrl string, method string) *CapabilitiesError

func (*CapabilitiesError) Error

func (c *CapabilitiesError) Error() string

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 MetricListener

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

Metrics Listener

func NewMetricListener

func NewMetricListener(m *AuthValidationMeasures, options ...Option) *MetricListener

func (*MetricListener) OnAuthenticated

func (m *MetricListener) OnAuthenticated(auth bascule.Authentication)

func (*MetricListener) OnErrorResponse

func (m *MetricListener) OnErrorResponse(e basculehttp.ErrorResponseReason, _ error)

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 Option

type Option func(m *MetricListener)

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.