Довідник конфігурації Security (SecurityBundle)

Дата оновлення перекладу 2022-12-16

Довідник конфігурації Security (SecurityBundle)

SecurityBundle інтегрує компонент Security у додатки Symfony. Всі ці опції сконфігуровані під ключем security у конфігурації вашого додатку.

        1
2
3
4
5
        # відображає значення конфігурації за замовчуванням, визначені Symfony
$ php bin/console config:dump-reference security

# відображає реальні значення конфігурації, які використовуються вашим додатком
$ php bin/console debug:config security
    

Note

При використанні XML, вы маєте використовувати простір імен http://symfony.com/schema/dic/security, а пов'язана схема XSD доступна тут: https://symfony.com/schema/dic/services/services-1.0.xsd

Конфігурація

Базові опції:

Просунуті опції:

Деякі з цих опцій визначають десятки підопцій і вони пояснюються в окремих статтях:

access_denied_url

тип: string значення за замовчуванням: null

Визначеє URL, за яким перенаправляється користувач після HTTP-помилки 403 (окрім випадків, коли ви визначаєте користувацький обробник відмови у доступі). Приклад: /no-permission

erase_credentials

тип: boolean значення за замовчуванням: true

Якщо true, метод eraseCredentials() об'єкта користувача викликається після аутентифікації.

hide_user_not_found

тип: boolean значення за замовчуванням: true

Якщо true, і якщо користувача не знайдено, викликається загальне виключення типу BadCredentialsException з повідомленням "Погані ідентифікаційні дані".

Якщо false, викликане виключення буде типу UserNotFoundException і включати в себе заданий ідентифікатор не знайденого користувача.

session_fixation_strategy

тип: string значення за замовчуванням: SessionAuthenticationStrategy::MIGRATE

Фіксація сесії - це атака безпеки, яка дозволяє атакуючому захопити валідну сесію користувача. Додатки, які не призначають нові ID сесії при аутентифікації користувачів, схильні до такої атаки.

Можливі значення цієї опції:

NONE константа з SessionAuthenticationStrategy Не змінюйте сесію після аутентифікації. Це не рекомендується.
MIGRATE константа з SessionAuthenticationStrategy Оновлюється ID сесії, але зберігаються інші атрибути сесії.
INVALIDATE константа з SessionAuthenticationStrategy Повторно генерується вся сесія, тому ID сесії оновлюється, але всі інші атрибути сесії будуть втрачені.

Визначає захист безпеки URL вашого додатку. Використовується, наприклад, для запуску аутентифікації користувача при спробі доступу до бек-енду, щоб дозволити анонімним користувачам доступ до сторінки форми входу.

Ця опція детально пояснюється в Як працює безпека access_control?.

firewalls

Це, можливо, найважливіша опція файлу конфігурації безпеки. Вона визначає механізм аутентифікації, який використовується для кожного URL (або патерну URL) вашого додатку:

YAML
XML
PHP

        1
2
3
4
5
6
7
8
9
10
11
        # config/packages/security.yaml
security:
    # ...
    firewalls:
        # 'main' це ім'я брандмауера (може бути вільно обране)
        main:
            # 'pattern' це регулярний вираз, співставлений з вхідним
            # URL запиту. Якщо є відповідність, запускається аутентифікація
            pattern: ^/admin
            # інші опції залежать від механізмів аутентифікації
            # ...
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
        <!-- config/packages/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
        http://symfony.com/schema/dic/security
        https://symfony.com/schema/dic/security/security-1.0.xsd">

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

        <!-- 'pattern' це регулярний вираз, співставлений з вхідним
             URL запиту. Якщо є відповідність, запускається аутентифікація -->
        <firewall name="main" pattern="^/admin">
            <!-- інші опції залежать від механізмів аутентифікації -->
            <!-- ... -->
        </firewall>
    </config>
</srv:container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        // config/packages/security.php
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security) {
    // ...

    // 'main' це ім'я брандмауера (може бути вільно обране)
    $security->firewall('main')
        // 'pattern' це регулярний вираз, співставлений з вхідним
        // URL запиту. Якщо є відповідність, запускається аутентифікація
        ->pattern('^/admin')
        // інші опції залежать від механізмів аутентифікації
        // ...
    ;
};
    

check_path

тип: string за замовчуванням: /login_check

Це маршрут або шлях, за яким має відправлятися ваша форма входу. Брандмауер буде приймати будь-які запити (за замовчуванням, лише запити POST) по цьому URL, та обробляти відправлені облікові дані входу.

Перконайтеся в тому, що цей URL охоплюється вашим основним брандмауером (тобто, не створюйте окремий брандмауер просто для URL check_path).

failure_path

тип: string за замовчуванням: /login

Це маршрут або шлях, по якому перенаправляється користувач після невдалої спроби входу у систему. Це може бути відносний/абсолютний URL або імʼя маршруту Symfony.

form_only

тип: boolean за замовчуванням: false

Встановіть цю опцію як true, щоб вимагати, щоб дані входу в систему були відправлені з використанням форми (перевіряє, що тип змісту запиту - application/x-www-form-urlencoded). Це корисно, наприклад, для запобігання аутентифікатора форми входу у систему від відповіді на запити, які повинні бути оброблені аутентифікатором входу у систему JSON .

use_forward

тип: boolean за замовчуванням: false

Якщо ви хочете, щоб користувача було надіслано до форми входу замість перенаправлення, встановіть цю опцію як true.

username_parameter

тип: string за замовчуванням: _username

Це ім'я поля, яке вам потрібно дати полю імені користувача вашої форми входу. Коли ви відправляєте форму в check_path, то система безпеки шукатиме параметр POST з цим ім'ям.

password_parameter

тип: string за замовчуванням: _password

Це ім'я поля, яке вам потрібно дати полю паролю вашої форми входу. Коли ви відправляєте форму в check_path, то система безпеки шукатиме параметр POST з цим ім'ям.

post_only

тип: boolean за замовчуванням: true

За замовчуванням, ви маєте відправити вашу форму входу за URL check_path у вигляді запиту POST. Встановивши цю опцію як false, ви можете відправити запит GET за URL check_path.

Опції, пов'язані з перенаправлення після входу в систему

always_use_default_target_path

тип: boolean за замовчуванням: false

Якщо true, то користувачі завдли перенаправляються за цільовим шляхом за замовчуванням, незважаючи на попередній URL, збережений в сесії.

default_target_path

тип: string за замовчуванням: /

Сторінка, на яку перенаправляються користувачі, коли попередня сторінка, збережена в сесії, відсутня (наприклад, коли корситувачі напряму заходять на сторінку входу в систему).

target_path_parameter

тип: string за замовчуванням: _target_path

При використанні форми входу, якщо ви вмикаєте HTML-елемент для установки цільового шляху, ця опція дозволяє вам змінити ім'я самого HTML-елементу.

failure_path_parameter

тип: string за замовчуванням: _failure_path

При використанні форми входу, якщо ви додасте HTML-елемент для установки шляху невдачі, ця опція дозволяє вам змінити ім'я самого HTML-елементу.

use_referer

тип: boolean за замовчуванням: false

Якщо true, то користувач перенаправляється до значення, збереженого у заголовку HTTP_REFERER, коли в сесії не було збережено попередній URL. Якщо реферальний URL такий же, як і згенерований з маршрутом login_path, то користувач перенаправляється за default_target_path, щоб уникнути замкненого перенаправлення.

Note

З історичних причин, і щоб відповідати помилці HTTP-стандарту, опція називається use_referer замість use_referrer.

Опції, пов'язані з конфігурацією виходу з системи

delete_cookies

тип: array за замовчуванням: []

Перераховує імена (та інші необовʼязкові функції) кукі, які треба видалити, коли користувач вийде з системи:

YAML
XML
PHP

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        # config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            logout:
                delete_cookies:
                    cookie1-name: null
                    cookie2-name:
                        path: '/'
                    cookie3-name:
                        path: null
                        domain: example.com
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
        <!-- config/packages/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>
        <!-- ... -->

        <firewall name="main">
            <!-- ... -->
            <logout path="...">
                <delete-cookie name="cookie1-name"/>
                <delete-cookie name="cookie2-name" path="/"/>
                <delete-cookie name="cookie3-name" domain="example.com"/>
            </logout>
        </firewall>
    </config>
</srv:container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
        // config/packages/security.php
$container->loadFromExtension('security', [
    // ...
    'firewalls' => [
        'main' => [
            'logout' => [
                'delete_cookies' => [
                    'cookie1-name' => null,
                    'cookie2-name' => [
                        'path' => '/',
                    ],
                    'cookie3-name' => [
                        'path' => null,
                        'domain' => 'example.com',
                    ],
                ],
            ],
        ],
    ],
]);
    

invalidate_session

тип: boolean за замовчуванням: true

За замовчуванням, коли користувачі виходять з будь-якого брандмауера, їх сесії інвалідуються. Це означає, що вихід з одного брандмауера автомаитчно запускає виходи з усіх інших.

Опція invalidate_session дозволяє вам перевизначити цю поведінку. Встановіть цю опцію як false в кожному брандмауері, і користувач буде виконувати вихід лише з поточного брандмауера, але не інших.

`path`

тип: string за замовчуванням: /logout

Шлях, який запускає вихід з системи. Якщо ви зміните значення за замовчуванням /logout, вам потрібно налаштувати маршрут з відповідним шляхом.

target

тип: string за замовчуванням: /

Відносний шлях (якщо значення починається з /), або абсоолютний URL (якщо воно починається з http:// чи https://) або ім'я маршруту (в інших випадках), щоб перенаправляти після виходу з системи.

enable_csrf

тип: boolean за замовчуванням: null

Встановіть цю опцію як true, щоб включити CSRF-захист під час процесу виходу з
системи, з викоирстанням генератора токенів CSRF Symfony за замовчуванням. Також встановіть опцію csrf_token_generator, якщо вам потрібно було використати користувацький генератор токенів CSRF.

6.2

Опція enable_csrf була представлена в Symfony 6.2.

csrf_parameter

тип: string за замовчуванням: '_csrf_token'

Ім'я параметра, який зберігає значення токена CSRF.

csrf_token_generator

тип: string за замовчуванням: null

id сервісу, який використовується для генерування токенів CSRF. Symfony надає сервіс за замовчуванням з ID security.csrf.token_manager.

csrf_token_id

тип: string за замовчуванням: 'logout'

Довільний рядок, який використовується для ідентифікації токена (і перевірки його валідності після цього).

Аутентифікація входу в систему JSON

check_path

тип: string за замовчуванням: /login_check

Це URL або ім'я маршруту, яке система має опублікувати, щоб аутентифікувати з використанням JSON-аутентифікатора. Шлях має бути охоплений брандмауером, в якому аутентифікується користувач.

username_path

тип: string за замовчуванням: username

Виокристайте це і password_path, щоб змінювати очікувану структуру тіла запиту JSON-аутентіфикатора. Наприклад, якщо JSON-документ має наступну структуру:

        1
2
3
4
5
6
7
8
        {
    "security": {
        "credentials": {
            "login": "dunglas",
            "password": "MyPassword"
        }
    }
}
    

Конфігурація безпеки має бути:

YAML
XML
PHP

        1
2
3
4
5
6
7
8
9
10
11
        # config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            lazy: true
            json_login:
                check_path:    login
                username_path: security.credentials.login
                password_path: security.credentials.password
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        <!-- config/packages/security.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<srv:container xmlns="http://symfony.com/schema/dic/security"
    xmlns:srv="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/security
        https://symfony.com/schema/dic/security/security-1.0.xsd">

    <config>
        <firewall name="main" lazy="true">
            <json-login check-path="login"
                username-path="security.credentials.login"
                password-path="security.credentials.password"/>
        </firewall>
    </config>
</srv:container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
        // config/packages/security.php
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security) {
    $mainFirewall = $security->firewall('main');
    $mainFirewall->lazy(true);
    $mainFirewall->jsonLogin()
        ->checkPath('/login')
        ->usernamePath('security.credentials.login')
        ->passwordPath('security.credentials.password')
    ;
};
    

password_path

тип: string за замовчуванням: password

Використовуйте цю опцію, щоб змінювати очікувану структуру тіла запиту. Див. username_path, щоб дізнатися більше.

Аутентифікація LDAP

Існує декілька опцій для з'єднання з LDAP-сервером, використовуючи провайдерів аутентифікації form_login_ldap, http_basic_ldap та json_login_ldap, або проавайдера користувача ldap.

Щоб дізнатися більше деталей, див. Аутентифікація з LDAP-сервером.

Аутентифікація

Ви можете аутентифікуватися на LDAP-сервері, використовуючи LDAP-варіанти провайдерів аутентифікації form_login, http_basic та json_login. Використовуйте form_login_ldap, http_basic_ldap і json_login_ldap, які намагатимуться bind на LDAP-сервері замість використання порівняння паролей.

Обидва провайдери аутентифікації мають однакові аргументи в якості звичайних двійників, з додаванням двох ключів конфігурації:

service

тип: string за замовчуванням*: ldap

Це ім'я вашого сконфігурованого LDAP-клієнта.

dn_string

тип: string за замовчуванням: {username}

Це рядок, який буде використано як зв'язуючий DN. Заповнювач {username} буде замінено на значення, надане користувачем (його вхід в систему). В залежності від вашої конфігурації LDAP-серверу, вам може знадобитися перевизначити це значення.

query_string

тип: string за замовчуванням*: null

Це рядок, який буде використано для запиту до DN. Заповнювач {username} буде замінено на значення, надане користувачем (його вхід в систему). В залежності від вашої конфігурації LDAP-серверу, вам може знадобитися перевизначити це значення. Це налаштування необхідне лише якщо DN користувача не може бути виведений статично, використовуючи опцію конфігурації dn_string.

Постачальник користувачів

Користувачі все ще будуть добуті із сконфігурованого постачальника користувачів. Якщо ви хочете добути користувачів з LDAP-серверу, вам потрібно буде використати Постачальника користувачів LDAP і будь-який з цих провайдерів аутентифікації: form_login_ldap або http_basic_ldap або json_login_ldap.

Аутентифікація X.509

YAML
XML
PHP

        1
2
3
4
5
6
7
8
9
10
11
        # config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            x509:
                provider:    your_user_provider
                user:        SSL_CLIENT_S_DN_Email
                credentials: SSL_CLIENT_S_DN
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
        <!-- config/packages/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
        http://symfony.com/schema/dic/security
        https://symfony.com/schema/dic/security/security-1.0.xsd">

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

        <firewall name="main">
            <!-- ... -->
            <x509 provider="your_user_provider"
                user="SSL_CLIENT_S_DN_Email"
                credentials="SSL_CLIENT_S_DN"
            />
        </firewall>
    </config>
</srv:container>
    

        1
2
3
4
5
6
7
8
9
10
11
        // config/packages/security.php
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security) {
    $mainFirewall = $security->firewall('main');
    $mainFirewall->x509()
        ->provider('your_user_provider')
        ->user('SSL_CLIENT_S_DN_Email')
        ->credentials('SSL_CLIENT_S_DN')
    ;
};
    

user

тип: string за замовчуванням: SSL_CLIENT_S_DN_Email

Ім'я параметру $_SERVER, який містить ідентифікатор користувача, використовуваний для завантаження користувача в Symfony. Значення за замовчуванням відображається завдяки Apache.

credentials

тип: string за замовчуванням: SSL_CLIENT_S_DN

Якщо параметр user не доступний, ім'я параметру $_SERVER, яке містить повне "розрізнене ім'я" сертифікату (відобраєаться через, наприклад, Nginx).

Symfony ідентифікує значення, слідуючи emailAddress= в цьому параметрі.

Віддалена аутентифікація користувача

YAML
XML
PHP

        1
2
3
4
5
6
7
8
        # config/packages/security.yaml
security:
    firewalls:
        main:
            # ...
            remote_user:
                provider: your_user_provider
                user:     REMOTE_USER
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        <!-- config/packages/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
        http://symfony.com/schema/dic/security
        https://symfony.com/schema/dic/security/security-1.0.xsd">

    <config>
        <firewall name="main">
            <remote-user provider="your_user_provider"
                user="REMOTE_USER"/>
        </firewall>
    </config>
</srv:container>
    

        1
2
3
4
5
6
7
8
9
10
        // config/packages/security.php
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security) {
    $mainFirewall = $security->firewall('main');
    $mainFirewall->remoteUser()
        ->provider('your_user_provider')
        ->user('REMOTE_USER')
    ;
};
    

provider

тип: string

ID сервісу постачальника користувачів, який має бути використаний даним аутентифікатором.

user

тип: string за замовчуванням: REMOTE_USER

Ім'я параметру $_SERVER, який містить ідентифікатор користувача.

Контекст брандмауера

Більшості додатків знадобиться лише один брандмауер . Але якщо вашому додатку потрібно декілька, то ви помітите, що якщо ви аутентифіковані в одному брандмауері, автоматично в інших ви не аутентифікуєтеся. Іншими словами, системи не користуються спільним "контекстом": кожний брандмауер діє як окрема система безпеки.

Однак, кожний брандмауер має необов'язковий ключ context (який за замовчуванням має ім'я брандмауера), який використовується при зберіганні та вилученні даних безпеки з та у сесію. Якщо б цей ключ встановлював однакове значення в декількох брандмауерах, то "контекст" міг би бути спільним:

YAML
XML
PHP

        1
2
3
4
5
6
7
8
9
10
11
        # config/packages/security.yaml
security:
    # ...

    firewalls:
        somename:
            # ...
            context: my_context
        othername:
            # ...
            context: my_context
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        <!-- config/packages/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
        http://symfony.com/schema/dic/security
        https://symfony.com/schema/dic/security/security-1.0.xsd">

    <config>
        <firewall name="somename" context="my_context">
            <!-- ... -->
        </firewall>
        <firewall name="othername" context="my_context">
            <!-- ... -->
        </firewall>
    </config>
</srv:container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        // config/packages/security.php
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security) {
    $security->firewall('somename')
        // ...
        ->context('my_context')
    ;

    $security->firewall('othername')
        // ...
        ->context('my_context')
    ;
};
    

Note

Ключ контексту брандмауера зберігається в сесії, так що кожний браузер, що використовує його, має встановити свою опцію stateless, як false. В іншому випадку, контекст ігнорується, і ви не зможете аутентифікуватися у декількох брандмауерах одночасно.

Перевірники користувачів

Під час аутентифікації користувача, додаткові перевірки можуть бути необхідні для того, щоб переконатися, чи дозволено ідентифікованому користувачу виконувати вхід. Кожний брандмауер може включати в себе опцію user_checker, щоб визначати сервіс, який використовується для проведення таких перевірок.

Дізнайтеся більше про перевірники користувачів у Як створювати та включати користувацькі перевірки користувача.

providers

Ця опція визначає те, як завантажуються користувачі додатку (з бази даних, LDAP-серверу, файлу конфігурації і т.д.). Прочитайте Постачальники користувачів, щоб дізнатися більше про кожний з цих постачальників.

role_hierarchy

Замість асоціювання багатьох ролей з користувачами, ця опція дозволяє вам визначати правила наслідування ролей, шляхом створення ієрархії ролей, як пояснюється у .