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

• func ValidateRule(enabledAuthenticators []string, availableAuthenticators []string, ...) func(r *Rule) error
• type CachedMatcher
  • func NewCachedMatcher(m Manager) *CachedMatcher
  • func (m *CachedMatcher) MatchRule(method string, u *url.URL) (*Rule, error)
  • func (m *CachedMatcher) Refresh() error
• type HTTPMatcher
  • func NewHTTPMatcher(u *url.URL) *HTTPMatcher
  • func (m *HTTPMatcher) Refresh() error
• type Handler
  • func NewHandler(h herodot.Writer, m Manager, v func(*Rule) error) *Handler
  • func (h *Handler) Create(w http.ResponseWriter, r *http.Request, _ httprouter.Params)
  • func (h *Handler) Delete(w http.ResponseWriter, r *http.Request, ps httprouter.Params)
  • func (h *Handler) Get(w http.ResponseWriter, r *http.Request, ps httprouter.Params)
  • func (h *Handler) List(w http.ResponseWriter, r *http.Request, _ httprouter.Params)
  • func (h *Handler) SetRoutes(r *httprouter.Router)
  • func (h *Handler) Update(w http.ResponseWriter, r *http.Request, ps httprouter.Params)
• type Manager
• type Matcher
• type MemoryManager
  • func NewMemoryManager() *MemoryManager
  • func (m *MemoryManager) CreateRule(rule *Rule) error
  • func (m *MemoryManager) DeleteRule(id string) error
  • func (m *MemoryManager) GetRule(id string) (*Rule, error)
  • func (m *MemoryManager) ListRules(limit, offset int) ([]Rule, error)
  • func (m *MemoryManager) UpdateRule(rule *Rule) error
• type Refresher
• type Rule
  • func NewRule() *Rule
  • func (r *Rule) CompileURL() (*regexp.Regexp, error)
  • func (r *Rule) IsMatching(method string, u *url.URL) error
• type RuleHandler
• type RuleMatch
• type SQLManager
  • func NewSQLManager(db *sqlx.DB) *SQLManager
  • func (s *SQLManager) CreateRule(rule *Rule) error
  • func (s *SQLManager) CreateSchemas() (int, error)
  • func (s *SQLManager) DeleteRule(id string) error
  • func (s *SQLManager) GetRule(id string) (*Rule, error)
  • func (s *SQLManager) ListRules(limit, offset int) ([]Rule, error)
  • func (s *SQLManager) UpdateRule(rule *Rule) error
• type Upstream

Functions

func ValidateRule

func ValidateRule(
	enabledAuthenticators []string, availableAuthenticators []string,
	enabledAuthorizers []string, availableAuthorizers []string,
	enabledCredentialsIssuers []string, availableCredentialsIssuers []string,
) func(r *Rule) error

Types

type CachedMatcher

type CachedMatcher struct {
	Rules   map[string]Rule
	Manager Manager
	sync.RWMutex
}

func NewCachedMatcher

func NewCachedMatcher(m Manager) *CachedMatcher

func (*CachedMatcher) MatchRule

func (m *CachedMatcher) MatchRule(method string, u *url.URL) (*Rule, error)

func (*CachedMatcher) Refresh

func (m *CachedMatcher) Refresh() error

type HTTPMatcher

type HTTPMatcher struct {
	*CachedMatcher
	// contains filtered or unexported fields
}

func NewHTTPMatcher

func NewHTTPMatcher(u *url.URL) *HTTPMatcher

func (*HTTPMatcher) Refresh

func (m *HTTPMatcher) Refresh() error

type Handler

type Handler struct {
	H herodot.Writer
	M Manager
	V func(*Rule) error
}

func NewHandler

func NewHandler(
	h herodot.Writer,
	m Manager,
	v func(*Rule) error,
) *Handler

func (*Handler) Create

func (h *Handler) Create(w http.ResponseWriter, r *http.Request, _ httprouter.Params)

swagger:route POST /rules rule createRule

Create a rule

This method allows creation of rules. If a rule id exists, you will receive an error.

Consumes:
- application/json

Produces:
- application/json

Schemes: http, https

Responses:
  201: rule
  401: genericError
  403: genericError
  500: genericError

func (*Handler) Delete

func (h *Handler) Delete(w http.ResponseWriter, r *http.Request, ps httprouter.Params)

swagger:route DELETE /rules/{id} rule deleteRule

Delete a rule

Use this endpoint to delete a rule.

Consumes:
- application/json

Produces:
- application/json

Schemes: http, https

Responses:
  204: emptyResponse
  401: genericError
  403: genericError
  404: genericError
  500: genericError

func (*Handler) Get

func (h *Handler) Get(w http.ResponseWriter, r *http.Request, ps httprouter.Params)

swagger:route GET /rules/{id} rule getRule

Retrieve a rule

Use this method to retrieve a rule from the storage. If it does not exist you will receive a 404 error.

Consumes:
- application/json

Produces:
- application/json

Schemes: http, https

Responses:
  200: rule
  401: genericError
  403: genericError
  404: genericError
  500: genericError

func (*Handler) List

func (h *Handler) List(w http.ResponseWriter, r *http.Request, _ httprouter.Params)

swagger:route GET /rules rule listRules

List all rules

This method returns an array of all rules that are stored in the backend. This is useful if you want to get a full view of what rules you have currently in place.

Consumes:
- application/json

Produces:
- application/json

Schemes: http, https

Responses:
  200: rules
  401: genericError
  403: genericError
  500: genericError

func (*Handler) SetRoutes

func (h *Handler) SetRoutes(r *httprouter.Router)

func (*Handler) Update

func (h *Handler) Update(w http.ResponseWriter, r *http.Request, ps httprouter.Params)

swagger:route PUT /rules/{id} rule updateRule

Update a rule

Use this method to update a rule. Keep in mind that you need to send the full rule payload as this endpoint does not support patching.

Consumes:
- application/json

Produces:
- application/json

Schemes: http, https

Responses:
  200: rule
  401: genericError
  403: genericError
  404: genericError
  500: genericError

type Manager

type Manager interface {
	ListRules(limit, offset int) ([]Rule, error)
	CreateRule(*Rule) error
	GetRule(id string) (*Rule, error)
	DeleteRule(id string) error
	UpdateRule(*Rule) error
}

type Matcher

type Matcher interface {
	MatchRule(method string, u *url.URL) (*Rule, error)
	Refresh() error
}

type MemoryManager

type MemoryManager struct {
	Rules map[string]Rule
}

func NewMemoryManager

func NewMemoryManager() *MemoryManager

func (*MemoryManager) CreateRule

func (m *MemoryManager) CreateRule(rule *Rule) error

func (*MemoryManager) DeleteRule

func (m *MemoryManager) DeleteRule(id string) error

func (*MemoryManager) GetRule

func (m *MemoryManager) GetRule(id string) (*Rule, error)

func (*MemoryManager) ListRules

func (m *MemoryManager) ListRules(limit, offset int) ([]Rule, error)

func (*MemoryManager) UpdateRule

func (m *MemoryManager) UpdateRule(rule *Rule) error

type Refresher

type Refresher interface {
	Refresh() error
}

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" db:"surrogate_id"`

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

	// Match defines the URL that this rule should match.
	Match RuleMatch `json:"match" db:"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 []RuleHandler `json:"authenticators" db:"authenticators"`

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

	// CredentialsIssuer is the handler which will issue the credentials which will be used when ORY Oathkeeper
	// forwards a granted request to the upstream server.
	CredentialsIssuer RuleHandler `json:"credentials_issuer" db:"credentials_issuer"`

	// Upstream is the location of the server where requests matching this rule should be forwarded to.
	Upstream Upstream `json:"upstream" db:"upstream"`
}

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

func NewRule

func NewRule() *Rule

func (*Rule) CompileURL

func (r *Rule) CompileURL() (*regexp.Regexp, error)

func (*Rule) IsMatching

func (r *Rule) IsMatching(method string, u *url.URL) error

IsMatching returns an error if the provided method and URL do not match the rule.

type RuleHandler

type RuleHandler 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" db:"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" db:"config"`
}

type RuleMatch

type RuleMatch 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" db:"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 in this field to match more than one url. Regular expressions are encapsulated in
	// brackets < and >. The following example matches all paths of the domain `mydomain.com`: `https://mydomain.com/<.*>`.
	URL string `json:"url" db:"url"`
	// contains filtered or unexported fields
}

type SQLManager

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

func NewSQLManager

func NewSQLManager(db *sqlx.DB) *SQLManager

func (*SQLManager) CreateRule

func (s *SQLManager) CreateRule(rule *Rule) error

func (*SQLManager) CreateSchemas

func (s *SQLManager) CreateSchemas() (int, error)

func (*SQLManager) DeleteRule

func (s *SQLManager) DeleteRule(id string) error

func (*SQLManager) GetRule

func (s *SQLManager) GetRule(id string) (*Rule, error)

func (*SQLManager) ListRules

func (s *SQLManager) ListRules(limit, offset int) ([]Rule, error)

func (*SQLManager) UpdateRule

func (s *SQLManager) UpdateRule(rule *Rule) 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"`
}