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

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

Довідник конфігурації 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

delete_cookies

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

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

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

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

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

firewalls

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

1
2
3
4
5
6
7
8
9
10
11
# config/packages/security.yaml
security:
    # ...
    firewalls:
        # 'main' це ім'я брандмауера (може бути вільно обране)
        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

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

При використанні слухача аутентифікатора form_login під брандмауером, існує декілька загальних опцій для конфігурації досвіду "форми входу". Щоб дізнатися ще більше деталей, див. Як налаштувати відповіді аутентифікатора форми входу.

login_path

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

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

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

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.

logout

Ви можете сконфігурувати опції виходу з системи.

delete_cookies

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

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

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

clear_site_data

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

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

Допустимими значеннями є cache, cookies, storage і executionContexts. Також можна використовувати * як підставний знак для всіх директив:

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

    firewalls:
        main:
            # ...
            logout:
                clear_site_data:
                    - cookies
                    - storage

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.

csrf_parameter

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

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

csrf_token_generator

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

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

csrf_token_id

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

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

Аутентифікація входу в систему 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"
        }
    }
}

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

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

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

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

user

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

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

credentials

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

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

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

user_identifier

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

Значення цієї опції повідомляє Symfony, який параметр використати для пошуку ідентифікатора користувача у "distinguished name".

Наприклад, якщо "distinguished name" - Subject: C=FR, O=My Organization, CN=user1, emailAddress=user1@myorg.fr, а значення цієї опції - 'CN', ідентифікатор користувача буде 'user1'.

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

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

provider

тип: string

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

user

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

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

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

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

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

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

Note

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

stateless

Брандмауери можуть сконфігурувати булеву опцію stateless, щоб оголосити, що сесію не слід використовувати для аутентифікації користувачів:

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

    firewalls:
        main:
            # ...
            stateless: true

Маршрути під цим брандмауером будуть сконфігуровані без стану , коли вони не будуть явно сконфігуровані як без стану чи ні.

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

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

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

Обовʼязкові бейджі

Брандмауери можуть сконфігурувати список обовʼязкових бейджів, які мають бути наявними в аутентифікованому паспорті:

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

    firewalls:
        main:
            # ...
            required_badges: ['CsrfTokenBadge', 'My\Badge']

providers

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

role_hierarchy

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