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

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?.

файерволлы

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

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