authelia/docs/configuration/access-control.md

layout	title	parent	nav_order
default	Access Control	Configuration	1

Access Control

{: .no_toc }

Policies

With Authelia you can define a list of rules that are going to be evaluated in sequential order when authorization is delegated to Authelia.

The first matching rule of the list defines the policy applied to the resource, if no rule matches the resource a customizable default policy is applied.

deny

This is the policy applied by default, and is what we recommend as the default policy for all installs. Its effect is literally to deny the user access to the resource. Additionally you can use this policy to conditionally deny access in desired situations. Examples include denying access to an API that has no authentication mechanism built in.

bypass

This policy skips all authentication and allows anyone to use the resource. This policy is not available with a rule that includes a subject restriction because the minimum authentication level required to obtain information about the subject is one_factor.

one_factor

This policy requires the user at minimum complete 1FA successfully (username and password). This means if they have performed 2FA then they will be allowed to access the resource.

two_factor

This policy requires the user to complete 2FA successfully. This is currently the highest level of authentication policy available.

Default Policy

The default policy is the policy applied when no other rule matches. It is recommended that this is configured to deny for security reasons. Sites which you do not wish to secure with Authelia should not be configured to perform authentication with Authelia at all.

See Policies for more information.

Network Aliases

The main networks section defines a list of network aliases, where the name matches a list of networks. These names can be used in any rule instead of a literal network. This makes it easier to define a group of networks multiple times.

You can combine both literal networks and these aliases inside the networks section of a rule. See this section for more details.

Rules

A rule defines two things:

• the matching criteria of the request presented to the reverse proxy
• the policy applied when all criteria match.

The criteria are:

• domain: domain or list of domains targeted by the request.
• resources: pattern or list of patterns that the path should match.
• subject: the user or group of users to define the policy for.
• networks: the network addresses, ranges (CIDR notation) or groups from where the request originates.
• methods: the http methods used in the request.

A rule is matched when all criteria of the rule match. Rules are evaluated in sequential order, and this is particularly important for bypass rules. Bypass rules should generally appear near the top of the rules list.

Policy

A policy represents the level of authentication the user needs to pass before being authorized to request the resource.

See Policies for more information.

Domains

The domains defined in rules must obviously be either a subdomain of the domain protected by Authelia or the protected domain itself. In order to match multiple subdomains, the wildcard matcher character *. can be used as prefix of the domain. For instance, to define a rule for all subdomains of example.com, one would use *.example.com in the rule. A single rule can define multiple domains for matching. These domains can be either listed in YAML-short form ["example1.com", "example2.com"] or in YAML long-form as dashed list.

Domain prefixes can also be dynamically match users or groups. For example you can have a specific policy adjustment if the user or group matches the subdomain. For example {user}.example.com or {group}.example.com check the users name or groups against the subdomain.

Resources

A rule can define multiple regular expressions for matching the path of the resource similar to the list of domains. If any one of them matches, the resource criteria of the rule matches.

Note that regular expressions can be used to match a given path. However prior to 4.27.0, they do not match the query parameters in the URL, only the path. If you're upgrading to 4.27.0+ you may have to alter some resource rules to get them to work as they previously did.

You might also face some escaping issues preventing Authelia to start. Please make sure that when you are using regular expressions, you enclose them between quotes. It's optional but it will likely save you a lot of debugging time.

Subjects

A subject is a representation of a user or a group of user for who the rule should apply.

For a user with unique identifier john, the subject should be user:john and for a group uniquely identified by developers, the subject should be group:developers. Similar to resources and domains you can define multiple subjects in a single rule.

If you want a combination of subjects to be matched at once using a logical AND, you can specify a nested list of subjects like - ["group:developers", "group:admins"]. In summary, the first list level of subjects are evaluated using a logical OR, whereas the second level by a logical AND. The last example below reads as: the group is dev AND the username is john OR the group is admins.

Combining subjects and the bypass policy

A subject cannot be combined with the bypass policy since the minimum authentication level to identify a subject is one_factor. Combining the one_factor policy with a subject is effectively the same as setting the policy to bypass in the past. We have taken an opinionated stance on preventing this configuration as it could result in problematic security scenarios with badly thought out configurations and cannot see a likely configuration scenario that would require users to do this. If you have a scenario in mind please open an issue on GitHub.

Networks

A list of network addresses, ranges (CIDR notation) or groups can be specified in a rule in order to apply different policies when requests originate from different networks. This list can contain both literal definitions of networks and network aliases.

Network addresses specified will be matched against the first IP in the X-Forwarded-For, and if there is none it will fall back to the IP address of the request. If using Authelia with a reverse proxy, additional configuration may be required on the reverse proxy to ensure these headers are present and correct.

Main use cases for this rule option is to adjust the security requirements of a resource based on the location of the user. For example lets say a resource should be exposed both on the Internet and from an authenticated VPN for instance. Passing a second factor a first time to get access to the VPN and a second time to get access to the application can sometimes be cumbersome if the endpoint is not considered overly sensitive.

An additional situation where this may be useful is if there is a specific network you wish to deny access or require a higher level of authentication for; like a public machine network vs a company device network, or a BYOD network.

Even if Authelia provides this flexibility, you might prefer a higher level of security and avoid this option entirely. You and only you can define your security policy and it's up to you to configure Authelia accordingly.

Methods

A list of HTTP request methods to apply the rule to. Valid values are GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, and TRACE. Additional information about HTTP request methods can be found on the MDN.

It's important to note this policy type is primarily intended for use when you wish to bypass authentication for a specific request method. This is because there are several key limitations in what is possible to accomplish without Authelia being a reverse proxy server. This rule type is discouraged unless you really know what you're doing or you wish to setup a rule to bypass CORS preflight requests by bypassing for the OPTIONS method.

For example, if you require authentication only for write events (POST, PATCH, DELETE, PUT), when a user who is not currently authenticated tries to do one of these actions, they will be redirected to Authelia. Authelia will decide what level is required for authentication, and then after the user authenticates it will redirect them to the original URL where Authelia decided they needed to authenticate. So if the endpoint they are redirected to originally had data sent as part of the request, this data is completely lost. Further if the endpoint expects the data or doesn't allow GET request types, the user may be presented with an error leading to a bad user experience.

Complete example

Here is a complete example of complex access control list that can be defined in Authelia.

access_control:
  default_policy: deny
  networks:
    - name: internal
      networks:
        - 10.10.0.0/16
        - 192.168.2.0/24
    - name: VPN
      networks: 10.9.0.0/16
  rules:
    - domain: public.example.com
      policy: bypass

    - domain: "*.example.com"
      policy: bypass
      methods:
        - OPTIONS

    - domain: secure.example.com
      policy: one_factor
      networks:
        - internal
        - VPN
        - 192.168.1.0/24
        - 10.0.0.1

    - domain:
      - secure.example.com
      - private.example.com
      policy: two_factor

    - domain: singlefactor.example.com
      policy: one_factor

    - domain: "mx2.mail.example.com"
      subject: "group:admins"
      policy: deny

    - domain: "*.example.com"
      subject:
        - "group:admins"
        - "group:moderators"
      policy: two_factor

    - domain: dev.example.com
      resources:
      - "^/groups/dev/.*$"
      subject: "group:dev"
      policy: two_factor

    - domain: dev.example.com
      resources:
      - "^/users/john/.*$"
      subject: 
      - ["group:dev", "user:john"]
      - "group:admins"
      policy: two_factor

    - domain: "{user}.example.com"
      policy: bypass