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