Security Configuration Reference (SecurityBundle)

access_denied_url

type: string default: null

Defines the URL where the user is redirected after a 403 HTTP error (unless you define a custom access deny handler). Example: /no-permission

always_authenticate_before_granting

type: boolean default: false

If true, the user is asked to authenticate before each call to the isGranted() method in services and controllers or is_granted() from templates.

erase_credentials

type: boolean default: true

If true, the eraseCredentials() method of the user object is called after authentication.

hide_user_not_found

type: boolean default: true

If true, when a user is not found a generic exception of type BadCredentialsException is thrown with the message "Bad credentials".

If false, the exception thrown is of type UsernameNotFoundException and it includes the given not found username.

session_fixation_strategy

type: string default: SessionAuthenticationStrategy::MIGRATE

Session Fixation is a security attack that permits an attacker to hijack a valid user session. Applications that don't assign new session IDs when authenticating users are vulnerable to this attack.

The possible values of this option are:

• NONE constant from SessionAuthenticationStrategy Don't change the session after authentication. This is not recommended.
• MIGRATE constant from SessionAuthenticationStrategy The session ID is updated, but the rest of session attributes are kept.
• INVALIDATE constant from SessionAuthenticationStrategy The entire session is regenerated, so the session ID is updated but all the other session attributes are lost.

Using the Argon2i Password Encoder

It uses the Argon2 key derivation function and it's the encoder recommended by Symfony. Argon2 support was introduced in PHP 7.2, but if you use an earlier PHP version, you can install the libsodium PHP extension.

The encoded passwords are 96 characters long, but due to the hashing requirements saved in the resulting hash this may change in the future, so make sure to allocate enough space for them to be persisted. Also, passwords include the cryptographic salt inside them (it's generated automatically for each new password) so you don't have to deal with it.

Using the Bcrypt Password Encoder

It uses the bcrypt password hashing function and it's recommended to use it when it's not possible to use Argon2i. The encoded passwords are 60 characters long, so make sure to allocate enough space for them to be persisted. Also, passwords include the cryptographic salt inside them (it's generated automatically for each new password) so you don't have to deal with it.

Its only configuration option is cost, which is an integer in the range of 4-31 (by default, 13). Each single increment of the cost doubles the time it takes to encode a password. It's designed this way so the password strength can be adapted to the future improvements in computation power.

You can change the cost at any time — even if you already have some passwords encoded using a different cost. New passwords will be encoded using the new cost, while the already encoded ones will be validated using a cost that was used back when they were encoded.

Using the PBKDF2 Encoder

Using the PBKDF2 encoder is no longer recommended since PHP added support for Argon2i and bcrypt. Legacy application still using it are encouraged to upgrade to those newer encoding algorithms.

form_login Authentication

When using the form_login authentication listener beneath a firewall, there are several common options for configuring the "form login" experience. For even more details, see How to Customize Redirect After Form Login.

invalidate_session

type: boolean default: true

By default, when users log out from any firewall, their sessions are invalidated. This means that logging out from one firewall automatically logs them out from all the other firewalls.

The invalidate_session option allows to redefine this behavior. Set this option to false in every firewall and the user will only be logged out from the current firewall and not the other ones.

logout_on_user_change

type: boolean default: false

If true this option makes Symfony to trigger a logout when the user has changed. Not doing that is deprecated, so this option should be set to true to avoid getting deprecation messages.

The user is considered to have changed when the user class implements EquatableInterface and the isEqualTo() method returns false. Also, when any of the properties required by the UserInterface (like the username, password or salt) changes.

path

type: string default: /logout

The path which triggers logout. If you change it from the default value /logout, you need to set up a route with a matching path.

success_handler

type: string default: 'security.logout.success_handler'

The service ID used for handling a successful logout. The service must implement LogoutSuccessHandlerInterface.

LDAP Authentication

There are several options for connecting against an LDAP server, using the form_login_ldap and http_basic_ldap authentication providers or the ldap user provider.

For even more details, see Authenticating against an LDAP server.

Authentication

You can authenticate to an LDAP server using the LDAP variants of the form_login and http_basic authentication providers. Simply use form_login_ldap and http_basic_ldap, which will attempt to bind against an LDAP server instead of using password comparison.

Both authentication providers have the same arguments as their normal counterparts, with the addition of two configuration keys:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# app/config/security.yml
security:
    # ...

    providers:
        my_ldap_users:
            ldap:
                service: ldap
                base_dn: 'dc=symfony,dc=com'
                search_dn: '%ldap.search_dn%'
                search_password: '%ldap.search_password%'
                default_roles: ''
                uid_key: 'uid'
                filter: '(&({uid_key}={username})(objectclass=person)(ou=Users))'

HTTP-Digest Authentication

To use HTTP-Digest authentication you need to provide a realm and a secret:

1
2
3
4
5
6
7

# app/config/security.yml
security:
    firewalls:
        somename:
            http_digest:
                secret: '%secret%'
                realm: 'secure-api'

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<!-- app/config/security.xml -->
<?xml version="1.0" charset="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">

    <config>
        <firewall name="somename">
            <http-digest secret="%secret%" realm="secure-api"/>
        </firewall>
    </config>
</srv:container>

1
2
3
4
5
6
7
8
9
10
11

// app/config/security.php
$container->loadFromExtension('security', [
    'firewalls' => [
        'somename' => [
            'http_digest' => [
                'secret' => '%secret%',
                'realm'  => 'secure-api',
            ],
        ],
    ],
]);

Firewall Context

Most applications will only need one firewall. But if your application does use multiple firewalls, you'll notice that if you're authenticated in one firewall, you're not automatically authenticated in another. In other words, the systems don't share a common "context": each firewall acts like a separate security system.

However, each firewall has an optional context key (which defaults to the name of the firewall), which is used when storing and retrieving security data to and from the session. If this key were set to the same value across multiple firewalls, the "context" could actually be shared:

1
2
3
4
5
6
7
8
9
10
11

# app/config/security.yml
security:
    # ...

    firewalls:
        somename:
            # ...
            context: my_context
        othername:
            # ...
            context: my_context

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<!-- app/config/security.xml -->
<?xml version="1.0" charset="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">

    <config>
        <firewall name="somename" context="my_context">
            <!-- ... -->
        </firewall>
        <firewall name="othername" context="my_context">
            <!-- ... -->
        </firewall>
    </config>
</srv:container>

1
2
3
4
5
6
7
8
9
10
11
12
13

// app/config/security.php
$container->loadFromExtension('security', [
    'firewalls' => [
        'somename' => [
            // ...
            'context' => 'my_context',
        ],
        'othername' => [
            // ...
            'context' => 'my_context',
        ],
    ],
]);

User Checkers

During the authentication of a user, additional checks might be required to verify if the identified user is allowed to log in. Each firewall can include a user_checker option to define the service used to perform those checks.

Learn more about user checkers in How to Create and Enable Custom User Checkers.