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

Довідник конфігурації Безпеки (SecurityBundle)

SecurityBundle інтегрує компонент Безпека у додатки 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

always_authenticate_before_granting

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

Deprecated since version 5.4: Опція always_authenticate_before_granting застаріла в Symfony 5.4, і буде видалена в Symfony 6.0.

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

anonymous

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

Коли встановлена як lazy, Symfony завантажує користувача (і починає сесію) лише якщо додаток дійсно отримує доступ до об’єкту User (наприклад через виклик is_granted() в шаблоні або isGranted() в контролері чи сервісі).

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 сесії оновлюється, але всі інші атрибути сесії будуть втрачені.

access_control

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

Ця опція детально пояснюється в How Does the Security access_control Work?.

firewalls

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

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

See also

Прочитайте цю статтю, щоб дізнатися про те, як обмежувати брандмауери за хостингом та методами HTTP.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# config/packages/security.yaml
security:
    # ...
    firewalls:
        main:
            # ...
                x509:
                    # ...
                remote_user:
                    # ...
                guard:
                    # ...
                form_login:
                    # ...
                form_login_ldap:
                    # ...
                json_login:
                    # ...
                http_basic:
                    # ...
                http_basic_ldap:
                    # ...
                http_digest:
                    # ...

Ви можете переглянути аткуальну інформацію про брандмауери у вашому додатку за допомогою команди debug:firewall:

1
2
3
4
5
6
7
8
9
# відображає список брандмауерів, сконфігурованих для вашого додатку на даний момент
$ php bin/console debug:firewall

# відображає деталі конкретного брандмауера
$ php bin/console debug:firewall main

# відображає деталі конкретного брандмауера, включно з детальною інформацією
# про слухачів подій для брандмауера
$ php bin/console debug:firewall main --include-listeners

New in version 5.3: Команда debug:firewall була представлена в Symfony 5.3.

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

При використанні слухача аутентифікатора form_login під брандмауером, існує декілька загальних опцій для конфігурації досвіду “форми входу”. Щоб дізнатися ще більше деталей, див. Customizing the Form Login Authenticator Responses.

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

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

Цей шлях мусить бути доступним звичайному, неаутентифікованому користувачу, інакше ви можете створити петлю перенаправлення.

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

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

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

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

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

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

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

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

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

тип: 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.

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

invalidate_session

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

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

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

path

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

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

target

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

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

success_handler

Deprecated since version 5.1: Ця опція застаріла у версії Symfony 5.1. Зареєструйте слухача подій у LogoutEvent замість цього.

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

ID сервісу, який використовується для обробки успішного виходу з системи. Сервіс має реалізовувати LogoutSuccessHandlerInterface.

Якщо встановлена, опція виходу з системи target буде проігнорована.

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
     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
    
  • XML
     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>
    
  • PHP
     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.

Щоб дізнатися більше деталей, див. Authenticating against an LDAP server.

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

Ви можете аутентифікуватися на 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
     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
    
  • XML
     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>
    
  • PHP
     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
    1
    2
    3
    4
    5
    6
    7
    8
    # config/packages/security.yaml
    security:
        firewalls:
            main:
                # ...
                remote_user:
                    provider: your_user_provider
                    user:     REMOTE_USER
    
  • XML
     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>
    
  • PHP
     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
     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
    
  • XML
     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>
    
  • PHP
     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, щоб визначати сервіс, який використовується для проведення таких перевірок.

Дізнайтеся більше про перевірники користувачів у How to Create and Enable Custom User Checkers.

providers

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

role_hierarchy

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

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.