Справочник конфигурацим Безопасности (SecurityBundle)

Дата обновления перевода 2022-01-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

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 вашего приложения. Используется, к примеру, для запуска аутентификации пользователя при попытке доступа к бэкенду, чтобы разрешить анонимным пользователям доступ к странице формы входа.

Эта опция детально разъясняется в Как работает безопасность access_control?.

файерволлы

Это, возможно, наиболее важная опция файла конфигурации безопасности. Она определяет механим аутентификации, используемый для каждого URL (или паттерна URL pattern) вашего приложения:

  • 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
            # другие опции зависят от механизмов аутентификации
            # ...

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

5.3

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

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

При использовании слушателя аутентификатора form_login под файерволлом, существует несколько общих опций для конфигурации опыта "формы входа". Чтобы узнать ещё больше деталей, см. Как настроить ответы аутентификатора формы входа.

login_path

тип: string по умолчанию: /login

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

Этот путь должен быть доступен обычному, неаутентифицированному пользователю, иначе вы можете создать петлю перенаправления.

check_path

тип: string по умолчанию: /login_check

Это маршрут или путь, по которму должна отправляться ваша форма входа. Брандмауэр будет принимать любые запросы (по умолчанию, только запросы POST) по этому URL, и обрабатывать отправленные учётные данные входа.

Убедитесь в том, что этот URL охватывается вашим основным брандмауэром (т.е. не создавайте отдельный брандмауэр просто для URL check_path).

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.

Опции, связанные с конфигурацией выхода из системы

invalidate_session

тип: boolean по умолчанию: true

По умолчанию, когда пользователи выходят из любого брандмауэра, их сессии инвалидируются. Это означает, что выход из одного брандмауэра автоматически запускает выходы из всех других.

Опция invalidate_session позволяет вам переопределить это поведение. Установите эту опцию, как false в каждом брандмауэре, и пользователь будет выполнять выход только из текущего брандмауэра, но не остальных.

path

тип: string по умолчанию: /logout

Путь, который запускает выход из системы. Если вы измените значение по умолчанию /logout, вам нужно настроить маршрут с соответствующим путем.

target

тип: string по умолчанию: /

Относительный путь (если значение начинается с /), или абсоолютный URL (если оно начинается с http:// или https://) или имя маршрута (в других случаях), чтобы перенаправлять после выхода из системы.

success_handler

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
  • 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

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 and 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

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

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

Note

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

Проверщики пользователей

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

Узнайте больше о провершиках пользователей в Как создавать и подключать пользовательские программы проверки пользователя.

providers

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

role_hierarchy

Вместо ассоциирования множества ролей с пользователями, эта опция позволяет вам определять правила наследования ролей, путем создания иерархии ролей, как объясняется в Безопасность.