bascule

README

comcast-bascule

The library for authorization: both acquiring and validating.

Summary

This library provides validation of Tokens used for authorization as well as a way to acquire Authorization header values. Tokens can be parsed and validated from http requests. Bascule provides a generic framework that can be configured, but currently can support basic and jwt authorization.

Table of Contents

• Code of Conduct
• Acquiring Authorization
• Validating Authorization
• Install
• Contributing

Code of Conduct

This project and everyone participating in it are governed by the XMiDT Code Of Conduct. By participating, you agree to this Code.

Acquiring Authorization

The acquire subpackage handles getting the value for an Authorization header of an http request. The JWT acquirer gets a JWT from a configurable endpoint, caches it, and will get a new JWT at a configurable time before the current JWT expires.

Validating Authorization

Validation of Tokens happens once an authorization value has been parsed into something that implements the Token interface.
The basculehttp subpackage provides http decorators/middleware that will parse an http request into a Token and validate it with configurable rules.

Read more about the basculehttp subpackage in its README.

Install

This repo is a library of packages used for the authorization. There is no installation.

Contributing

Refer to CONTRIBUTING.md.

Documentation

Overview

package bascule provides a token interface and basic implementation, which can be validated and added and taken from a context. Some basic checks which can be used to validate are also provided.

Index

• Variables
• func NonEmptyStringListCheck(_ context.Context, vals []interface{}) error
• func WithAuthentication(ctx context.Context, auth Authentication) context.Context
• type Attributes
  • func NewAttributes() Attributes
  • func NewAttributesFromMap(m map[string]interface{}) Attributes
  • func NewAttributesWithOptions(o AttributesOptions) Attributes
• type AttributesOptions
• type Authentication
  • func FromContext(ctx context.Context) (Authentication, bool)
• type Authorization
• type ClaimsWithLeeway
  • func (c *ClaimsWithLeeway) GetMap() (map[string]interface{}, error)
  • func (c *ClaimsWithLeeway) UnmarshalJSON(data []byte) error
  • func (c *ClaimsWithLeeway) Valid() error
• type Error
• type Errors
  • func (e Errors) Error() string
  • func (e Errors) Errors() []error
• type JWTParser
• type Leeway
• type Logger
  • func GetDefaultLoggerFunc(ctx context.Context) Logger
  • func NewDefaultLogger() Logger
• type MultiError
• type Request
• type Token
  • func NewToken(tokenType, principal string, attributes Attributes) Token
• type Validator
• type ValidatorFunc
  • func CreateAllowAllCheck() ValidatorFunc
  • func CreateListAttributeCheck(key string, checks ...func(context.Context, []interface{}) error) ValidatorFunc
  • func CreateNonEmptyPrincipalCheck() ValidatorFunc
  • func CreateNonEmptyTypeCheck() ValidatorFunc
  • func CreateValidTypeCheck(validTypes []string) ValidatorFunc
  • func (vf ValidatorFunc) Check(ctx context.Context, t Token) error
• type Validators
  • func (v Validators) Check(ctx context.Context, t Token) error

Variables

var (
	ErrorKey interface{} = "error"
)

Functions

func NonEmptyStringListCheck

func NonEmptyStringListCheck(_ context.Context, vals []interface{}) error

NonEmptyStringListCheck checks that the list of values given are a list of one or more nonempty strings.

func WithAuthentication

func WithAuthentication(ctx context.Context, auth Authentication) context.Context

WithAuthentication adds the auth given to the context given, provided a way for other users of the context to get the authentication.

Types

type Attributes

type Attributes interface {
	Get(key string) (interface{}, bool)
	GetBool(key string) (bool, bool)
	GetDuration(key string) (time.Duration, bool)
	GetFloat64(key string) (float64, bool)
	GetInt64(key string) (int64, bool)
	GetIntSlice(key string) ([]int, bool)
	GetString(key string) (string, bool)
	GetStringMap(key string) (map[string]interface{}, bool)
	GetStringSlice(key string) ([]string, bool)
	GetTime(key string) (time.Time, bool)
	IsSet(key string) bool
	FullView() map[string]interface{}
}

Attributes is the interface that wraps methods which dictate how to interact with a token's attributes. Getter functions return a boolean as second element which indicates that a value of the requested type exists at the given key path. Key path separators are configurable through AttributeOptions

func NewAttributes

func NewAttributes() Attributes

NewAttributes builds an empty Attributes instance.

func NewAttributesFromMap

func NewAttributesFromMap(m map[string]interface{}) Attributes

NewAttributesFromMap builds an Attributes instance with the given map as datasource. Default AttributeOptions are used.

func NewAttributesWithOptions

func NewAttributesWithOptions(o AttributesOptions) Attributes

NewAttributesWithOptions builds an Attributes instance from the given options. Zero value options are ok.

type AttributesOptions

type AttributesOptions struct {
	//KeyDelimiter configures the separator for building key paths
	//for the Attributes getter functions. Defaults to '.'
	KeyDelimiter string

	//AttributesMap is used as the initial attributes datasource
	AttributesMap map[string]interface{}
}

AttributesOptions allows customizing Attributes initialization

type Authentication

type Authentication struct {
	Authorization Authorization
	Token         Token
	Request       Request
}

Authentication represents the output of a security pipeline.

func FromContext

func FromContext(ctx context.Context) (Authentication, bool)

FromContext gets the Authentication from the context provided.

type Authorization

type Authorization string

Authorization represents the authorization mechanism performed on the token, e.g. "Basic", "Bearer", etc for HTTP security environments.

type ClaimsWithLeeway

type ClaimsWithLeeway struct {
	jwt.MapClaims
	Leeway Leeway
}

func (*ClaimsWithLeeway) GetMap

func (c *ClaimsWithLeeway) GetMap() (map[string]interface{}, error)

GetMap returns a map of string to interfaces of the values in the ClaimsWithLeeway

func (*ClaimsWithLeeway) UnmarshalJSON

func (c *ClaimsWithLeeway) UnmarshalJSON(data []byte) error

func (*ClaimsWithLeeway) Valid

func (c *ClaimsWithLeeway) Valid() error

Valid implements the jwt.Claims interface, ensuring that the token claism are valid. This implementation checks the time based claims: exp, iat, nbf.

type Error

type Error interface {
	Cause() error
	Reason() string
}

Error is an optional interface to be implemented by security related errors

type Errors

type Errors []error

Errors is a Multierror that also acts as an error, so that a log-friendly string can be returned but each error in the list can also be accessed.

func (Errors) Error

func (e Errors) Error() string

Error concatenates the list of error strings to provide a single string that can be used to represent the errors that occurred.

func (Errors) Errors

func (e Errors) Errors() []error

Errors returns the list of errors.

type JWTParser

type JWTParser interface {
	ParseJWT(string, jwt.Claims, jwt.Keyfunc) (*jwt.Token, error)
}

JWTParser parses raw Tokens into JWT objects

var DefaultJWTParser JWTParser = defaultJWTParser{}

DefaultJWTParser is the parser implementation that simply delegates to the jwt-go library's jws.ParseJWT function.

type Leeway

type Leeway struct {
	EXP int64 `json:"expLeeway"`
	NBF int64 `json:"nbfLeeway"`
	IAT int64 `json:"iatLeeway"`
}

Leeway is the amount of buffer to include with the time, to allow for clock skew.

type Logger

type Logger interface {
	Log(keyvals ...interface{}) error
}

logger we expect for the decorators

func GetDefaultLoggerFunc

func GetDefaultLoggerFunc(ctx context.Context) Logger

GetDefaultLoggerFunc a function that returns the default logger, which doesn't do anything

func NewDefaultLogger

func NewDefaultLogger() Logger

NewDefaultLogger returns the default logger, which doesn't do anything.

type MultiError

type MultiError interface {
	Errors() []error
}

MultiError is an interface that provides a list of errors.

type Request

type Request struct {
	URL    *url.URL
	Method string
}

Request holds request information that may be useful for validating the token.

type Token

type Token interface {
	// Type is the custom token type assigned by plugin code
	Type() string

	// Principal is the security principal, e.g. the user name or client id
	Principal() string

	// Attributes are an arbitrary set of name/value pairs associated with the token.
	// Typically, these will be filled with information supplied by the user, e.g. the claims of a JWT.
	Attributes() Attributes
}

Token is the behavior supplied by all secure tokens

func NewToken

func NewToken(tokenType, principal string, attributes Attributes) Token

NewToken creates a Token from basic information. Many secure pipelines can use the returned value as their token. Specialized pipelines can create additional interfaces and augment the returned Token as desired. Alternatively, some pipelines can simply create their own Tokens out of whole cloth.

type Validator

type Validator interface {
	Check(context.Context, Token) error
}

Validator is the rule type that determines if a Token is valid. Each rule should do exactly (1) thing, and then be composed by application-layer code. Validators are invoked for both authentication and authorization. We may need to have different rule types for those two things, but for now this works.

type ValidatorFunc

type ValidatorFunc func(context.Context, Token) error

ValidatorFunc is the Check function that a Validator has.

func CreateAllowAllCheck

func CreateAllowAllCheck() ValidatorFunc

CreateAllowAllCheck returns a Validator that never returns an error.

func CreateListAttributeCheck

func CreateListAttributeCheck(key string, checks ...func(context.Context, []interface{}) error) ValidatorFunc

CreateListAttributeCheck returns a Validator that runs checks against the content found in the key given. It runs every check and returns all errors it finds.

func CreateNonEmptyPrincipalCheck

func CreateNonEmptyPrincipalCheck() ValidatorFunc

CreateNonEmptyPrincipalCheck returns a Validator that checks that the token's Principal isn't an empty string.

func CreateNonEmptyTypeCheck

func CreateNonEmptyTypeCheck() ValidatorFunc

CreateNonEmptyTypeCheck returns a Validator that checks that the token's type isn't an empty string.

func CreateValidTypeCheck

func CreateValidTypeCheck(validTypes []string) ValidatorFunc

CreateValidTypeCheck returns a Validator that checks that the token's type is one of the given valid types.

func (ValidatorFunc) Check

func (vf ValidatorFunc) Check(ctx context.Context, t Token) error

Check runs the validatorFunc, making a ValidatorFunc also a Validator.

type Validators

type Validators []Validator

Validators are a list of objects that implement the Validator interface.

func (Validators) Check

func (v Validators) Check(ctx context.Context, t Token) error

Check runs through the list of validator Checks and adds any errors returned to the list of errors, which is an Errors type.