Security Configuration Reference (SecurityBundle)

strategy

type: string default: affirmative

Defines the strategy used by the access decision manager to decide whether access should be granted. Read about all the available strategies.

allow_if_all_abstain

type: boolean default: false

If true, access is granted when all voters abstain (no voter explicitly grants or denies access). If false (the default), access is denied when all voters abstain.

allow_if_equal_granted_denied

type: boolean default: true

This option is only used by the consensus strategy. If the number of voters granting access is equal to the number of voters denying access, this option determines the final decision. If true (the default), access is granted in case of a tie.

service

type: string default: null

Defines a custom access decision manager service to replace the default one entirely. The service must implement the AccessDecisionManagerInterface.

When this option is set, the strategy, allow_if_all_abstain and allow_if_equal_granted_denied options are ignored.

strategy_service

type: string default: null

Defines a custom strategy service to use instead of one of the built-in strategies. The service must implement the AccessDecisionStrategyInterface.

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 Customizing the Form Login Authenticator Responses.

login_path

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 aren't fully authenticated.

This path must be accessible by a normal, unauthenticated user, else you might create a redirect loop.

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

failure_path

type: string default: /login

This is the route or path that the user is redirected to after a failed login attempt. It can be a relative/absolute URL or a Symfony route name.

form_only

type: boolean default: false

Set this option to true to require that the login data is sent using a form (it checks that the request content-type is application/x-www-form-urlencoded or multipart/form-data). This is useful for example to prevent the form login authenticator from responding to requests that should be handled by the JSON login authenticator.

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 name of 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 name of 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 too.

Options Related to Redirecting after Login

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.

failure_path_parameter

type: string default: _failure_path

When using a login form, if you include an HTML element to set the failure 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.

delete_cookies

type: array default: []

Lists the names (and other optional features) of the cookies to delete when the user logs out:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'logout' => [
                    'delete_cookies' => [
                        'cookie1-name' => null,
                        'cookie2-name' => [
                            'path' => '/',
                        ],
                        'cookie3-name' => [
                            'path' => null,
                            'domain' => 'example.com',
                        ],
                    ],
                ],
            ],
        ],
    ],
]);

clear_site_data

type: array default: []

The Clear-Site-Data HTTP header clears browsing data (cookies, storage, cache) associated with the requesting website. It allows web developers to have more control over the data stored by a client browser for their origins.

Allowed values are cache, cookies, storage and executionContexts. It's also possible to use * as a wildcard for all directives:

1
2
3
4
5
6
7
8
9
10
11

# config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            logout:
                clear_site_data:
                    - cookies
                    - storage

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'logout' => [
                    'clear_site_data' => ['cookies', 'storage'],
                ],
            ],
        ],
    ],
]);

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

path

type: string default: /logout

The path or route name that triggers the logout. If the value starts with a / character, it's treated as a path; otherwise, it's treated as a route name. If you use a path, make sure to also define a route that matches it.

target

type: string default: /

The relative path (if the value starts with /), or absolute URL (if it starts with http:// or https://) or the route name (otherwise) to redirect after logout.

enable_csrf

type: boolean default: null

Set this option to true to enable CSRF protection in the logout process using Symfony's default CSRF token manager. Set also the csrf_token_manager option if you need to use a custom CSRF token manager.

csrf_parameter

type: string default: _csrf_token

The name of the parameter that stores the CSRF token value.

csrf_token_manager

type: string default: null

The id of the service used to generate the CSRF tokens. Symfony provides a default service whose ID is security.csrf.token_manager.

csrf_token_id

type: string default: logout

An arbitrary string used to identify the token (and check its validity afterwards).

check_path

type: string default: /login_check

This is the URL or route name the system must post to authenticate using the JSON authenticator. The path must be covered by the firewall to which the user will authenticate.

username_path

type: string default: username

Use this and password_path to modify the expected request body structure of the JSON authenticator. For instance, if the JSON document has the following structure:

1
2
3
4
5
6
7
8

{
    "security": {
        "credentials": {
            "login": "dunglas",
            "password": "MyPassword"
        }
    }
}

The security configuration should be:

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

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'lazy' => true,
                'json_login' => [
                    'check_path' => '/login',
                    'username_path' => 'security.credentials.login',
                    'password_path' => 'security.credentials.password',
                ],
            ],
        ],
    ],
]);

password_path

type: string default: password

Use this option to modify the expected request body structure. See username_path for more details.

service

type: string default: ldap

This is the name of your configured LDAP client.

dn_string

type: string default: {user_identifier}

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

query_string

type: string default: null

This is the string which will be used to query for the DN. The {user_identifier} placeholder will be replaced with the user-provided value (their login). Depending on your LDAP server's configuration, you will need to override this value. This setting is only necessary if the user's DN cannot be derived statically using the dn_string config option.

User provider

Users will still be fetched from the configured user provider. If you wish to fetch your users from an LDAP server, you will need to use the LDAP User Provider and any of these authentication providers: form_login_ldap or http_basic_ldap or json_login_ldap.

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

# config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            x509:
                provider:        your_user_provider
                user:            SSL_CLIENT_S_DN_Email
                credentials:     SSL_CLIENT_S_DN
                user_identifier: emailAddress

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'x509' => [
                    'provider' => 'your_user_provider',
                    'user' => 'SSL_CLIENT_S_DN_Email',
                    'credentials' => 'SSL_CLIENT_S_DN',
                    'user_identifier' => 'emailAddress',
                ],
            ],
        ],
    ],
]);

user

type: string default: SSL_CLIENT_S_DN_Email

The name of the $_SERVER parameter containing the user identifier used to load the user in Symfony. The default value is exposed by Apache.

credentials

type: string default: SSL_CLIENT_S_DN

If the user parameter is not available, the name of the $_SERVER parameter containing the full "distinguished name" of the certificate (exposed by e.g. Nginx).

By default, Symfony identifies the value following emailAddress= in this parameter. This can be changed using the user_identifier option.

user_identifier

type: string default: emailAddress

The value of this option tells Symfony which parameter to use to find the user identifier in the "distinguished name".

For example, if the "distinguished name" is Subject: C=FR, O=My Organization, CN=user1, emailAddress=user1@myorg.fr, and the value of this option is 'CN', the user identifier will be '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

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'remote_user' => [
                    'provider' => 'your_user_provider',
                    'user' => 'REMOTE_USER',
                ],
            ],
        ],
    ],
]);

provider

type: string

The service ID of the user provider that should be used by this authenticator.

user

type: string default: REMOTE_USER

The name of the $_SERVER parameter holding the user identifier.

token_handler

type: string | array

The service id of the token handler or an array of options for a built-in handler (e.g. oidc, oidc_user_info). This option is required.

token_extractors

type: array default: ['security.access_token_extractor.header']

The list of service ids used to extract the token from the request. By default, the token is extracted from the Authorization request header.

realm

type: string default: null

The "realm" for the WWW-Authenticate response header returned when authentication fails.

provider

type: string

The service id of the user provider that should be used by this authenticator.

success_handler

type: string

The service id of a service that implements AuthenticationSuccessHandlerInterface.

failure_handler

type: string

The service id of a service that implements AuthenticationFailureHandlerInterface.

check_route

type: string

The route name that the login link URL will point to. This option is required.

check_post_only

type: boolean default: false

If true, the login link is only accepted via POST requests.

signature_properties

type: array

An array of user properties used to create the login link signature. This option is required and must contain at least one property (e.g. ['email']).

lifetime

type: integer default: 600

The lifetime of the login link in seconds.

max_uses

type: integer default: null

The maximum number of times a login link can be used. null means unlimited.

used_link_cache

type: string

The service id of the cache pool used to track used login links. This is required when max_uses is set.

secret

type: string default: %kernel.secret%

The secret used to sign the login link URL.

provider

type: string

The service id of the user provider that should be used by this authenticator.

success_handler

type: string

The service id of a service that implements AuthenticationSuccessHandlerInterface.

failure_handler

type: string

The service id of a service that implements AuthenticationFailureHandlerInterface.

limiter

type: string

The service id of a custom rate limiter implementing RequestRateLimiterInterface. When set, all other options below are ignored because the provided limiter is used directly.

max_attempts

type: integer default: 5

The maximum number of failed login attempts before the login is throttled.

interval

type: string default: '1 minute'

The period of time in which the max_attempts are counted (e.g. '1 minute', '30 seconds').

lock_factory

type: string default: null

The service id of the lock factory used by the rate limiter. Set to null to disable locking.

cache_pool

type: string default: 'cache.rate_limiter'

The cache pool service id used to store the rate limiter state.

storage_service

type: string default: null

The service id of a custom storage service for the rate limiter. When set, this takes precedence over cache_pool.

secret

type: string default: %kernel.secret%

The secret used to encode the cookie content. It's common to use the kernel.secret parameter.

service

type: string

The service id of a custom remember-me handler implementing RememberMeHandlerInterface.

token_provider

type: string | array

A service id (as a string) or an array with the following sub-options:

• service (type: string): the service id of a custom token provider.
• doctrine (type: array): enables the Doctrine token provider with an optional connection sub-option (type: string, default: null) to define the Doctrine connection to use.

token_verifier

type: string

The service id of a custom token verifier service.

signature_properties

type: array default: ['password']

An array of user properties used to verify the remember-me cookie. At least one property is required. When any of these properties change, existing remember-me cookies are invalidated automatically.

catch_exceptions

type: boolean default: true

If true, exceptions thrown during the remember-me authentication are caught and the user is not authenticated (instead of returning a server error).

Cookie Options

name

type: string default: 'REMEMBERME'

The name of the cookie used for the remember-me feature.

lifetime

type: integer default: 31536000

The lifetime of the cookie in seconds (31536000 is one year).

path

type: string default: '/'

The path of the cookie.

domain

type: string default: null

The domain of the cookie. If null, the current domain from the request is used.

secure

type: boolean | string default: false

If true, the cookie is only sent over HTTPS. Set to 'auto' to use the same value as the session cookie.

httponly

type: boolean default: true

If true, the cookie is accessible only through the HTTP protocol (it can't be accessed by scripting languages like JavaScript).

samesite

type: string default: null

If set, the SameSite attribute of the cookie is set with this value. Valid values are 'lax', 'strict' and 'none'.

always_remember_me

type: boolean default: false

If true, the remember-me feature is always active, regardless of whether the user checks a "remember me" checkbox in the login form.

remember_me_parameter

type: string default: '_remember_me'

The name of the form field or request parameter checked to determine whether the "remember me" feature should be activated.

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

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'somename' => [
                'context' => 'my_context',
            ],
            'othername' => [
                'context' => 'my_context',
            ],
        ],
    ],
]);

1
2
3
4
5
6
7
8

# config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            stateless: true

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'stateless' => true,
            ],
        ],
    ],
]);

1
2
3
4
5
6
7
8

# config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            lazy: true

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'lazy' => true,
            ],
        ],
    ],
]);

1
2
3
4
5
6
7
8

# config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            required_badges: ['CsrfTokenBadge', 'My\Badge']

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

// config/packages/security.php
namespace Symfony\Component\DependencyInjection\Loader\Configurator;

return App::config([
    'security' => [
        'firewalls' => [
            'main' => [
                'required_badges' => ['CsrfTokenBadge', 'My\Badge'],
            ],
        ],
    ],
]);

algorithm

type: string

The hashing algorithm to use. The available algorithms depend on your PHP installation. The most common values are:

• auto: automatically selects the best available hasher (currently Bcrypt);
• bcrypt: uses the bcrypt algorithm;
• sodium: uses the Argon2 algorithm via the libsodium extension;
• pbkdf2: uses the PBKDF2 algorithm (no longer recommended).

You can also set this to the id of a service to use a custom password hasher (see the id option below).

cost

type: integer default: null

This option is only available for the bcrypt algorithm. It defines the value of the cost used to hash the password. The allowed range is 4 to 31. Each single increment of the cost doubles the time it takes to hash a password.

memory_cost

type: integer default: null

This option is only available for the sodium (Argon2) algorithm. It defines the amount of memory (in KiB) the algorithm may consume.

time_cost

type: integer default: null

This option is only available for the sodium (Argon2) algorithm. It defines the number of iterations used to hash the password.

hash_algorithm

type: string default: sha512

The hash algorithm used by the pbkdf2 hasher. You can use any algorithm returned by the hash_algos() PHP function (e.g. sha256, sha512, etc.).

key_length

type: integer default: 40

The length of the generated hash for the pbkdf2 hasher.

iterations

type: integer default: 5000

The number of iterations used by the pbkdf2 hasher to generate the hash.

encode_as_base64

type: boolean default: true

Whether to encode the generated hash in base64 for the pbkdf2 hasher.

ignore_case

type: boolean default: false

Whether to ignore case when comparing the password for the pbkdf2 hasher.

id

type: string

The service id of a custom password hasher. This option can be used to configure a custom hasher service instead of using a built-in algorithm.

migrate_from

type: array

A list of previous hasher configurations to migrate from. When a password is verified, Symfony checks if it was hashed with one of these previous algorithms. If so, the password is automatically rehashed using the current algorithm the next time the user logs in.