How Does the Security access_control Work?

1. Matching Options

Symfony creates an instance of RequestMatcher for each access_control entry, which determines whether or not a given access control should be used on this request. The following access_control options are used for matching:

• path: a regular expression (without delimiters)
• ip or ips: netmasks are also supported
• host: a regular expression
• methods: one or many methods

Take the following access_control entries as an example:

1
2
3
4
5
6
7
8
9

# app/config/security.yml
security:
    # ...
    access_control:
        - { path: '^/admin', roles: ROLE_USER_IP, ip: 127.0.0.1 }
        - { path: '^/admin', roles: ROLE_USER_HOST, host: symfony\.com$ }
        - { path: '^/admin', roles: ROLE_USER_METHOD, methods: [POST, PUT] }
        # when defining multiple roles, users must have at least one of them (it's like an OR condition)
        - { path: '^/admin', roles: [ROLE_MANAGER, ROLE_ADMIN] }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<!-- app/config/security.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:srv="http://symfony.com/schema/dic/services"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <config>
        <!-- ... -->
        <rule path="^/admin" role="ROLE_USER_IP" ip="127.0.0.1"/>
        <rule path="^/admin" role="ROLE_USER_HOST" host="symfony\.com$"/>
        <rule path="^/admin" role="ROLE_USER_METHOD" methods="POST, PUT"/>
        <!-- when defining multiple roles, users must have at least one of them (it's like an OR condition) -->
        <rule path="^/admin" roles="ROLE_ADMIN, ROLE_MANAGER"/>
    </config>
</srv:container>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// app/config/security.php
$container->loadFromExtension('security', [
    // ...
    'access_control' => [
        [
            'path' => '^/admin',
            'roles' => 'ROLE_USER_IP',
            'ips' => '127.0.0.1',
        ],
        [
            'path' => '^/admin',
            'roles' => 'ROLE_USER_HOST',
            'host' => 'symfony\.com$',
        ],
        [
            'path' => '^/admin',
            'roles' => 'ROLE_USER_METHOD',
            'methods' => 'POST, PUT',
        ],
        [
            'path' => '^/admin',
            // when defining multiple roles, users must have at least one of them (it's like an OR condition)
            'roles' => ['ROLE_MANAGER', 'ROLE_ADMIN'],
        ],
    ],
]);

For each incoming request, Symfony will decide which access_control to use based on the URI, the client's IP address, the incoming host name, and the request method. Remember, the first rule that matches is used, and if ips, host or methods are not specified for an entry, that access_control will match any ips, host or methods:

2. Access Enforcement

Once Symfony has decided which access_control entry matches (if any), it then enforces access restrictions based on the roles, allow_if and requires_channel options:

• roles If the user does not have the given role, then access is denied (internally, an AccessDeniedException is thrown). If this value is an array of multiple roles, the user must have at least one of them.
• allow_if If the expression returns false, then access is denied;
• requires_channel If the incoming request's channel (e.g. http) does not match this value (e.g. https), the user will be redirected (e.g. redirected from http to https, or vice versa).

Matching access_control By IP

Certain situations may arise when you need to have an access_control entry that only matches requests coming from some IP address or range. For example, this could be used to deny access to a URL pattern to all requests except those from a trusted, internal server.

Here is an example of how you configure some example /internal* URL pattern so that it is only accessible by requests from the local server itself:

1
2
3
4
5
6
7
8

# app/config/security.yml
security:
    # ...
    access_control:
        #
        # the 'ips' option supports IP addresses and subnet masks
        - { path: '^/internal', roles: IS_AUTHENTICATED_ANONYMOUSLY, ips: [127.0.0.1, ::1, 192.168.0.1/24] }
        - { path: '^/internal', roles: ROLE_NO_ACCESS }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<!-- app/config/security.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:srv="http://symfony.com/schema/dic/services"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <config>
        <!-- ... -->

        <!-- the 'ips' option supports IP addresses and subnet masks -->
        <rule path="^/internal" role="IS_AUTHENTICATED_ANONYMOUSLY">
            <ip>127.0.0.1</ip>
            <ip>::1</ip>
        </rule>

        <rule path="^/internal" role="ROLE_NO_ACCESS"/>
    </config>
</srv:container>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// app/config/security.php
$container->loadFromExtension('security', [
    // ...
    'access_control' => [
        [
            'path' => '^/internal',
            'roles' => 'IS_AUTHENTICATED_ANONYMOUSLY',
            // the 'ips' option supports IP addresses and subnet masks
            'ips' => ['127.0.0.1', '::1'],
        ],
        [
            'path' => '^/internal',
            'roles' => 'ROLE_NO_ACCESS',
        ],
    ],
]);

Here is how it works when the path is /internal/something coming from the external IP address 10.0.0.1:

• The first access control rule is ignored as the path matches but the IP address does not match either of the IPs listed;
• The second access control rule is enabled (the only restriction being the path) and so it matches. If you make sure that no users ever have ROLE_NO_ACCESS, then access is denied (ROLE_NO_ACCESS can be anything that does not match an existing role, it just serves as a trick to always deny access).

But if the same request comes from 127.0.0.1 or ::1 (the IPv6 loopback address):

• Now, the first access control rule is enabled as both the path and the ip match: access is allowed as the user always has the IS_AUTHENTICATED_ANONYMOUSLY role.
• The second access rule is not examined as the first rule matched.

1
2
3
4
5
6
7
8
9
10

# app/config/security.yml
security:
    # ...
    access_control:
        -
            path: ^/_internal/secure
            # the 'role' and 'allow-if' options work like an OR expression, so
            # access is granted if the expression is TRUE or the user has ROLE_ADMIN
            roles: 'ROLE_ADMIN'
            allow_if: "'127.0.0.1' == request.getClientIp() or request.headers.has('X-Secure-Access')"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<!-- app/config/security.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:srv="http://symfony.com/schema/dic/services"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <config>
        <!-- the 'role' and 'allow-if' options work like an OR expression, so
             access is granted if the expression is TRUE or the user has ROLE_ADMIN -->
        <rule path="^/_internal/secure"
            role="ROLE_ADMIN"
            allow-if="'127.0.0.1' == request.getClientIp() or request.headers.has('X-Secure-Access')"/>
    </config>
</srv:container>

1
2
3
4
5
6
7
8
9

'access_control' => [
    [
        'path' => '^/_internal/secure',
        // the 'role' and 'allow-if' options work like an OR expression, so
        // access is granted if the expression is TRUE or the user has ROLE_ADMIN
        'roles' => 'ROLE_ADMIN',
        'allow_if' => '"127.0.0.1" == request.getClientIp() or request.headers.has("X-Secure-Access")',
    ],
],

Forcing a Channel (http, https)

You can also require a user to access a URL via SSL; just use the requires_channel argument in any access_control entries. If this access_control is matched and the request is using the http channel, the user will be redirected to https:

1
2
3
4
5

# app/config/security.yml
security:
    # ...
    access_control:
        - { path: ^/cart/checkout, roles: IS_AUTHENTICATED_ANONYMOUSLY, requires_channel: https }

1
2
3
4
5
6
7
8
9
10
11
12
13

<!-- app/config/security.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:srv="http://symfony.com/schema/dic/services"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <rule path="^/cart/checkout"
        role="IS_AUTHENTICATED_ANONYMOUSLY"
        requires-channel="https"
    />
</srv:container>

1
2
3
4
5
6
7
8
9
10

// app/config/security.php
$container->loadFromExtension('security', [
    'access_control' => [
        [
            'path' => '^/cart/checkout',
            'roles' => 'IS_AUTHENTICATED_ANONYMOUSLY',
            'requires_channel' => 'https',
        ],
    ],
]);