-
Notifications
You must be signed in to change notification settings - Fork 26
Access Control Lists
Access Control Lists (ACLs) are the main tool Rails::Auth provides for AuthZ. ACLs use a set of route-by-route matchers to control access to particular resources.
Rails::Auth encourages the use of YAML files for storing ACL definitions, although the use of YAML is not mandatory and the corresponding object structure output from YAML.load
can be passed in instead. The following is an example of an ACL definition in YAML:
---
- resources:
- method: ALL
path: /foo/bar/.*
allow_x509_subject:
ou: ponycopter
allow_claims:
groups: ["example"]
- resources:
- method: ALL
path: /_admin/?.*
allow_claims:
groups: ["admins"]
- resources:
- method: GET
path: /internal/frobnobs/.*
allow_x509_subject:
ou: frobnobber
- resources:
- method: GET
path: /
allow_all: true
An ACL consists of a list of guard expressions, each of which contains a list of resources and a set of matchers which can authorize access to those resources. Access will be authorized if any of the matchers for a given resource are a match (i.e. matchers have "or"-like behavior, not "and"-like behavior). Requiring more than one credential to access a resource is not supported directly, but can be accomplished by having credential-extracting middleware check for credentials from previous middleware before adding new credentials to the Rack environment.
Resources are defined by the following constraints:
-
method: The requested HTTP method, or
"ALL"
to allow any method -
path: A regular expression to match the path.
\A
and\z
are added by default to the beginning and end of the regex to ensure the entire path and not a substring is matched. -
host (optional): a regular expression to match the
Host:
header passed by the client. Useful if your app services traffic for more than one hostname and you'd like to restrict ACLs by host.
The following matchers are built-in and always available:
-
allow_all: (options:
true
orfalse
) always allow requests to the given resources (so long astrue
is passed as the option)
Rails::Auth also ships with matchers for X.509 certificates.