rule

Documentation

Overview

Package rule implements management capabilities for rules

A rule is used to decide what to do with requests that are hitting the ORY Oathkeeper proxy server. A rule must define the HTTP methods and the URL under which it will apply. A URL may not have more than one rule. If a URL has no rule applied, the proxy server will return a 404 not found error.

ORY Oathkeeper stores as many rules as required and iterates through them on every request. Rules are essential to the way ORY Oathkeeper works.

Index

• Variables
• type ErrorHandler
• type Fetcher
• type FetcherDefault
  • func NewFetcherDefault(c configuration.Provider, r fetcherRegistry) *FetcherDefault
  • func (f *FetcherDefault) Watch(ctx context.Context) error
• type Handler
• type Match
• type Matcher
• type MatchingEngine
• type OnErrorRequest
• type Registry
• type Repository
• type RepositoryMemory
  • func NewRepositoryMemory(r repositoryMemoryRegistry) *RepositoryMemory
  • func (m *RepositoryMemory) Count(ctx context.Context) (int, error)
  • func (m *RepositoryMemory) Get(ctx context.Context, id string) (*Rule, error)
  • func (m *RepositoryMemory) List(ctx context.Context, limit, offset int) ([]Rule, error)
  • func (m *RepositoryMemory) Match(_ context.Context, method string, u *url.URL) (*Rule, error)
  • func (m *RepositoryMemory) MatchingStrategy(_ context.Context) (configuration.MatchingStrategy, error)
  • func (m *RepositoryMemory) Set(ctx context.Context, rules []Rule) error
  • func (m *RepositoryMemory) SetMatchingStrategy(_ context.Context, ms configuration.MatchingStrategy) error
  • func (m *RepositoryMemory) WithRules(rules []Rule)
• type Rule
  • func (r *Rule) ExtractRegexGroups(strategy configuration.MatchingStrategy, u *url.URL) ([]string, error)
  • func (r *Rule) GetID() string
  • func (r *Rule) IsMatching(strategy configuration.MatchingStrategy, method string, u *url.URL) (bool, error)
  • func (r *Rule) ReplaceAllString(strategy configuration.MatchingStrategy, input, replacement string) (string, error)
  • func (r *Rule) UnmarshalJSON(raw []byte) error
• type Upstream
• type Validator
• type ValidatorDefault
  • func NewValidatorDefault(r validatorRegistry) *ValidatorDefault
  • func (v *ValidatorDefault) Validate(r *Rule) error

Variables

var (
	ErrUnbalancedPattern       = errors.New("unbalanced pattern")
	ErrMethodNotImplemented    = errors.New("the method is not implemented")
	ErrUnknownMatchingStrategy = errors.New("unknown matching strategy")
)

common errors for MatchingEngine.

Types

type ErrorHandler

type ErrorHandler struct {
	// Handler identifies the implementation which will be used to handle this specific request. Please read the user
	// guide for a complete list of available handlers.
	Handler string `json:"handler"`

	// Config defines additional configuration for the response handler.
	Config json.RawMessage `json:"config"`
}

type Fetcher

type Fetcher interface {
	Watch(ctx context.Context) error
}

type FetcherDefault

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

func NewFetcherDefault

func NewFetcherDefault(
	c configuration.Provider,
	r fetcherRegistry,
) *FetcherDefault

func (*FetcherDefault) Watch

func (f *FetcherDefault) Watch(ctx context.Context) error

type Handler

type Handler struct {
	// Handler identifies the implementation which will be used to handle this specific request. Please read the user
	// guide for a complete list of available handlers.
	Handler string `json:"handler"`

	// Config contains the configuration for the handler. Please read the user
	// guide for a complete list of each handler's available settings.
	Config json.RawMessage `json:"config"`
}

type Match

type Match struct {
	// An array of HTTP methods (e.g. GET, POST, PUT, DELETE, ...). When ORY Oathkeeper searches for rules
	// to decide what to do with an incoming request to the proxy server, it compares the HTTP method of the incoming
	// request with the HTTP methods of each rules. If a match is found, the rule is considered a partial match.
	// If the matchesUrl field is satisfied as well, the rule is considered a full match.
	Methods []string `json:"methods"`

	// This field represents the URL pattern this rule matches. When ORY Oathkeeper searches for rules
	// to decide what to do with an incoming request to the proxy server, it compares the full request URL
	// (e.g. https://mydomain.com/api/resource) without query parameters of the incoming
	// request with this field. If a match is found, the rule is considered a partial match.
	// If the matchesMethods field is satisfied as well, the rule is considered a full match.
	//
	// You can use regular expressions or glob patterns in this field to match more than one url.
	// The matching strategy is determined by configuration parameter MatchingStrategy.
	// Regular expressions and glob patterns are encapsulated in brackets < and >.
	// The following regexp example matches all paths of the domain `mydomain.com`: `https://mydomain.com/<.*>`.
	// The glob equivalent of the above regexp example is `https://mydomain.com/<*>`.
	URL string `json:"url"`
}

type Matcher

type Matcher interface {
	Match(ctx context.Context, method string, u *url.URL) (*Rule, error)
}

type MatchingEngine

type MatchingEngine interface {
	IsMatching(pattern, matchAgainst string) (bool, error)
	ReplaceAllString(pattern, input, replacement string) (string, error)
	FindStringSubmatch(pattern, matchAgainst string) ([]string, error)
	Checksum() uint64
}

MatchingEngine describes an interface of matching engine such as regexp or glob.

type OnErrorRequest

type OnErrorRequest struct {
	// ContentType defines the content type(s) that should match. Wildcards such as `application/*` are supported.
	ContentType []string `json:"content_type"`

	// Accept defines the accept header that should match. Wildcards such as `application/*` are supported.
	Accept []string `json:"accept"`
}

type Registry

type Registry interface {
	RuleValidator() Validator
	RuleFetcher() Fetcher
	RuleRepository() Repository
	RuleMatcher() Matcher
}

type Repository

type Repository interface {
	List(ctx context.Context, limit, offset int) ([]Rule, error)
	Set(context.Context, []Rule) error
	Get(context.Context, string) (*Rule, error)
	Count(context.Context) (int, error)
	MatchingStrategy(context.Context) (configuration.MatchingStrategy, error)
	SetMatchingStrategy(context.Context, configuration.MatchingStrategy) error
}

type RepositoryMemory

type RepositoryMemory struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

func NewRepositoryMemory

func NewRepositoryMemory(r repositoryMemoryRegistry) *RepositoryMemory

func (*RepositoryMemory) Count

func (m *RepositoryMemory) Count(ctx context.Context) (int, error)

func (*RepositoryMemory) Get

func (m *RepositoryMemory) Get(ctx context.Context, id string) (*Rule, error)

func (*RepositoryMemory) List

func (m *RepositoryMemory) List(ctx context.Context, limit, offset int) ([]Rule, error)

func (*RepositoryMemory) Match

func (m *RepositoryMemory) Match(_ context.Context, method string, u *url.URL) (*Rule, error)

func (*RepositoryMemory) MatchingStrategy

func (m *RepositoryMemory) MatchingStrategy(_ context.Context) (configuration.MatchingStrategy, error)

MatchingStrategy returns current MatchingStrategy.

func (*RepositoryMemory) Set

func (m *RepositoryMemory) Set(ctx context.Context, rules []Rule) error

func (*RepositoryMemory) SetMatchingStrategy

func (m *RepositoryMemory) SetMatchingStrategy(_ context.Context, ms configuration.MatchingStrategy) error

SetMatchingStrategy updates MatchingStrategy.

func (*RepositoryMemory) WithRules

func (m *RepositoryMemory) WithRules(rules []Rule)

WithRules sets rules without validation. For testing only.

type Rule

type Rule struct {
	// ID is the unique id of the rule. It can be at most 190 characters long, but the layout of the ID is up to you.
	// You will need this ID later on to update or delete the rule.
	ID string `json:"id"`

	// Version represents the access rule version. Should match one of ORY Oathkeepers release versions. Supported since
	// v0.20.0-beta.1+oryOS.14.
	Version string `json:"version"`

	// Description is a human readable description of this rule.
	Description string `json:"description"`

	// Match defines the URL that this rule should match.
	Match *Match `json:"match"`

	// Authenticators is a list of authentication handlers that will try and authenticate the provided credentials.
	// Authenticators are checked iteratively from index 0 to n and if the first authenticator to return a positive
	// result will be the one used.
	//
	// If you want the rule to first check a specific authenticator  before "falling back" to others, have that authenticator
	// as the first item in the array.
	Authenticators []Handler `json:"authenticators"`

	// Authorizer is the authorization handler which will try to authorize the subject (authenticated using an Authenticator)
	// making the request.
	Authorizer Handler `json:"authorizer"`

	// Mutators is a list of mutation handlers that transform the HTTP request. A common use case is generating a new set
	// of credentials (e.g. JWT) which then will be forwarded to the upstream server.
	//
	// Mutations are performed iteratively from index 0 to n and should all succeed in order for the HTTP request to be forwarded.
	Mutators []Handler `json:"mutators"`

	// Errors is a list of error handlers. These will be invoked if any part of the system returns an error. You can
	// configure error matchers to listen on certain errors (e.g. unauthorized) and execute specific logic (e.g. redirect
	// to the login endpoint, return with an XML error, return a json error, ...).
	Errors []ErrorHandler `json:"errors"`

	// Upstream is the location of the server where requests matching this rule should be forwarded to.
	Upstream Upstream `json:"upstream"`
	// contains filtered or unexported fields
}

Rule is a single rule that will get checked on every HTTP request.

func (*Rule) ExtractRegexGroups

func (r *Rule) ExtractRegexGroups(strategy configuration.MatchingStrategy, u *url.URL) ([]string, error)

ExtractRegexGroups returns the values matching the rule pattern

func (*Rule) GetID

func (r *Rule) GetID() string

GetID returns the rule's ID.

func (*Rule) IsMatching

func (r *Rule) IsMatching(strategy configuration.MatchingStrategy, method string, u *url.URL) (bool, error)

IsMatching checks whether the provided url and method match the rule. An error will be returned if a regexp matching strategy is selected and regexp timeout occurs.

func (*Rule) ReplaceAllString

func (r *Rule) ReplaceAllString(strategy configuration.MatchingStrategy, input, replacement string) (string, error)

ReplaceAllString searches the input string and replaces each match (with the rule's pattern) found with the replacement text.

func (*Rule) UnmarshalJSON

func (r *Rule) UnmarshalJSON(raw []byte) error

type Upstream

type Upstream struct {
	// PreserveHost, if false (the default), tells ORY Oathkeeper to set the upstream request's Host header to the
	// hostname of the API's upstream's URL. Setting this flag to true instructs ORY Oathkeeper not to do so.
	PreserveHost bool `json:"preserve_host"`

	// StripPath if set, replaces the provided path prefix when forwarding the requested URL to the upstream URL.
	StripPath string `json:"strip_path"`

	// URL is the URL the request will be proxied to.
	URL string `json:"url"`
}

type Validator

type Validator interface {
	Validate(r *Rule) error
}

type ValidatorDefault

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

func NewValidatorDefault

func NewValidatorDefault(r validatorRegistry) *ValidatorDefault

func (*ValidatorDefault) Validate

func (v *ValidatorDefault) Validate(r *Rule) error