Security Configuration Reference (SecurityBundle)

Warning: You are browsing the documentation for Symfony 2.x, which is no longer maintained.

Read the updated version of this page for Symfony 7.1 (the current stable version).

The SecurityBundle integrates the Security component in Symfony applications. All these options are configured under the security key in your application configuration.

        1
2
3
4
5
        # displays the default config values defined by Symfony
$ php app/console config:dump-reference security

# displays the actual config values used by your application
$ php app/console debug:config security
    

Note

When using XML, you must use the http://symfony.com/schema/dic/security namespace and the related XSD schema is available at: http://symfony.com/schema/dic/services/services-1.0.xsd

2.8

The secret option of anonymous and remember_me was introduced in Symfony 2.8. Prior to 2.8, it was called key.

2.8

The http_basic_ldap and form_login_ldap authentication providers were introduced in Symfony 2.8.

2.8

The ldap user provider was introduced in Symfony 2.8

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.

type: string default: /login

This is the route or path that the user will be redirected to (unless use_forward is set to true) when they try to access a protected resource but isn't fully authenticated.

This path must be accessible by a normal, un-authenticated user, else you may create a redirect loop. For details, see "Avoid Common Pitfalls".

check_path

type: string default: /login_check

This is the route or path that your login form must submit to. The firewall will intercept any requests (POST requests only, by default) to this URL and process the submitted login credentials.

Be sure that this URL is covered by your main firewall (i.e. don't create a separate firewall just for check_path URL).

use_forward

type: boolean default: false

If you'd like the user to be forwarded to the login form instead of being redirected, set this option to true.

username_parameter

type: string default: _username

This is the field name that you should give to the username field of your login form. When you submit the form to check_path, the security system will look for a POST parameter with this name.

password_parameter

type: string default: _password

This is the field name that you should give to the password field of your login form. When you submit the form to check_path, the security system will look for a POST parameter with this name.

post_only

type: boolean default: true

By default, you must submit your login form to the check_path URL as a POST request. By setting this option to false, you can send a GET request to the check_path URL.

always_use_default_target_path

type: boolean default: false

If true, users are always redirected to the default target path regardless of the previous URL that was stored in the session.

default_target_path

type: string default: /

The page users are redirected to when there is no previous page stored in the session (for example, when the users browse the login page directly).

target_path_parameter

type: string default: _target_path

When using a login form, if you include an HTML element to set the target path, this option lets you change the name of the HTML element itself.

use_referer

type: boolean default: false

If true, the user is redirected to the value stored in the HTTP_REFERER header when no previous URL was stored in the session. If the referrer URL is the same as the one generated with the login_path route, the user is redirected to the default_target_path to avoid a redirection loop.

Note

For historical reasons, and to match the misspelling of the HTTP standard, the option is called use_referer instead of use_referrer.

Logout Configuration

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.

success_handler

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

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

LDAP functionality

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 a 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:

service

type: string default: ldap

This is the name of your configured LDAP client.

dn_string

type: string default: {username}

This is the string which will be used as the bind DN. The {username} placeholder will be replaced with the user-provided value (his login). Depending on your LDAP server's configuration, you may need to override this value.

User provider

Users will still be fetched from the configured user provider. If you wish to fetch your users from a LDAP server, you will need to use the ldap user provider, in addition to one of the two authentication providers (form_login_ldap or http_basic_ldap).

        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))'
    

Using the PBKDF2 Encoder: Security and Speed

The PBKDF2 encoder provides a high level of Cryptographic security, as recommended by the National Institute of Standards and Technology (NIST).

You can see an example of the pbkdf2 encoder in the YAML block on this page.

But using PBKDF2 also warrants a warning: using it (with a high number of iterations) slows down the process. Thus, PBKDF2 should be used with caution and care.

A good configuration lies around at least 1000 iterations and sha512 for the hash algorithm.

Using the BCrypt Password Encoder

Caution

To use this encoder, you either need to use PHP Version 5.5 or install the ircmaxell/password-compat library via Composer.

        1
2
3
4
5
6
7
8
        # app/config/security.yml
security:
    # ...

    encoders:
        Symfony\Component\Security\Core\User\User:
            algorithm: bcrypt
            cost:      15
    

        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
        http://symfony.com/schema/dic/services/services-1.0.xsd">

    <config>
        <!-- ... -->
        <encoder
            class="Symfony\Component\Security\Core\User\User"
            algorithm="bcrypt"
            cost="15"
        />
    </config>
</srv:container>
    

        1
2
3
4
5
6
7
8
9
10
11
12
        // app/config/security.php
use Symfony\Component\Security\Core\User\User;

$container->loadFromExtension('security', array(
    // ...
    'encoders' => array(
        User::class => array(
            'algorithm' => 'bcrypt',
            'cost'      => 15,
        ),
    ),
));
    

The cost can be in the range of 4-31 and determines how long a password will be encoded. Each increment of cost doubles the time it takes to encode a password.

If you don't provide the cost option, the default cost of 13 is used.

Note

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.

A salt for each new password is generated automatically and need not be persisted. Since an encoded password contains the salt used to encode it, persisting the encoded password alone is enough.

Note

All the encoded passwords are 60 characters long, so make sure to allocate enough space for them to be persisted.

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
        http://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', array(
    'firewalls' => array(
        'somename' => array(
            // ...
            'context' => 'my_context',
        ),
        'othername' => array(
            // ...
            'context' => 'my_context',
        ),
    ),
));
    

Note

The firewall context key is stored in session, so every firewall using it must set its stateless option to false. Otherwise, the context is ignored and you won't be able to authenticate on multiple firewalls at the same time.

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.

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
        http://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', array(
    'firewalls' => array(
        'somename' => array(
            'http_digest' => array(
                'secret' => '%secret%',
                'realm'  => 'secure-api',
            ),
        ),
    ),
));
    

2.8

The secret option was introduced in Symfony 2.8. Prior to 2.8, it was called key.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.

TOC

Version

Check Code Performance in Dev, Test, Staging & Production

Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).