ORY Oathkeeper reaches decisions to allow or deny access by applying Access
Rules. Access Rules can be stored on the file system, set as an environment
variable, or fetched from HTTP(s) remotes. These repositories can be configured
in the configuration file (
oathkeeper -c ./path/to/config.yml ...)
or by setting the equivalent environment variable:
The repository (file, inline, remote) must be formatted either as a JSON or a YAML array containing the access rules:
Access Rules have four principal keys:
id(string): The unique ID of the Access Rule.
version(string): The version of ORY Oathkeeper this rule targets with out the
+oryOS.<x>appendix. ORY Oathkeeper is able to migrate access rules across versions. If left empty ORY Oathkeeper will assume that the rule is using the same tag as the version that is running.
upstream(object): The location of the server where requests matching this rule should be forwarded to. This only needs to be set when using the ORY Oathkeeper Proxy as the Decision API does not forward the request to the upstream.
url(string): The URL the request will be forwarded to.
preserve_host(bool): If set to
false(default), the forwarded request will include the host and port of the
true, the host and port of the ORY Oathkeeper Proxy will be used instead:
false: Incoming HTTP Header
Host: mydomain.com-> Forwarding HTTP Header
strip_path(string): If set, replaces the provided path prefix when forwarding the requested URL to the upstream URL:
- set to
/api/v1: Incoming HTTP Request at
/api/v1/users-> Forwarding HTTP Request at
- unset: Incoming HTTP Request at
/api/v1/users-> Forwarding HTTP Request at
- set to
match(object): Defines the URL(s) this Access Rule should match.
methods(string): Array of HTTP methods (e.g. GET, POST, PUT, DELETE, ...).
url(string): The URL that should be matched. You can use regular expressions or glob patterns in this field to match more than one url. The matching strategy (glob or regexp) is defined in the global configuration file as
access_rules.matching_strategy. This matcher ignores query parameters. Regular expressions (or glob patterns) are encapsulated in brackets
Regular expressions examples:
https://mydomain.com/and does not match
http://mydomain.com/foo. Does not match:
http://mydomain.com/123and does not match
http://mydomain.com/resourceand does not match
Glob patterns examples:
https://mydomain.com/manand does not match
https://mydomain.com/barand does not match
authenticators: A list of authentication handlers that authenticate the provided credentials. Authenticators are checked iteratively from index
nand 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. For the full list of available authenticators, click here.
authorizer: The authorization handler which will try to authorize the subject ("user") from the previously validated credentials making the request. For example, you could check if the subject ("user") is part of the "admin" group or if he/she has permission to perform that action. For the full list of available authorizers, click here.
mutators: A list of mutation handlers that transform the HTTP request before forwarding it. A common use case is generating a new set of credentials (e.g. JWT) which then will be forwarded to the upstream server. When using ORY Oathkeeper's Decision API, it is expected that the API Gateway forwards the mutated HTTP Headers to the upstream server. For the full list of available mutators, click here.
errors: A list of error handlers that are executed when any of the previous handlers (e.g. authentication) fail. Error handlers define what to do in case of an error, for example redirect the user to the login endpoint when a unauthorized (HTTP Status Code 401) error occurs. If left unspecified, errors will always be handled as JSON responses unless the global configuration key
errors.fallbackwas changed. For more information on error handlers, click here.
Rule in JSON format:
Rule in YAML format:
Handlers (Authenticators, Mutators, Authorizers, Errors) sometimes require configuration. The configuration can be defined globally as well as per Access Rule. The configuration from the Access Rule is overrides values from the global configuration.
Some credentials are scoped. For example, OAuth 2.0 Access Tokens usually are scoped ("OAuth 2.0 Scope"). Scope validation depends on the meaning of the scope. Therefore, wherever ORY Oathkeeper validates a scope, these scope strategies are supported:
none: Scope validation is disabled. If however a scope is configured to be validated, the request will fail with an error message.
With the Regular expression strategy, you can use the extracted groups in
all handlers where the substitutions are supported by using the Go
text/template package, receiving the
If the match URL is
<https|http>://mydomain.com/<.*> and the request is
MatchContext field will contain
RegexpCaptureGroups: ["http", "foo"]