Security Configuration Reference (SecurityBundle)
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 bin/console config:dump-reference security
# displays the actual config values used by your application
$ php bin/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:
https://symfony.com/schema/dic/services/services-1.0.xsd
Configuration
Basic Options:
- access_denied_url
- always_authenticate_before_granting
- delete_cookies
- erase_credentials
- hide_user_not_found
- session_fixation_strategy
Advanced Options:
Some of these options define tens of sub-options and they are explained in separate articles:
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 denial handler). Example: /no-permission
always_authenticate_before_granting
type: boolean
default: false
5.4
The always_authenticate_before_granting
option was deprecated in
Symfony 5.4 and it will be removed in Symfony 6.0.
If true
, the user is asked to authenticate before each call to the
isGranted()
method in services and controllers or is_granted()
from
templates.
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
<!-- 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">
<config>
<!-- ... -->
<firewall name="main">
<!-- ... -->
<logout path="...">
<delete-cookie name="cookie1-name"/>
<delete-cookie name="cookie2-name" path="/"/>
<delete-cookie name="cookie3-name" domain="example.com"/>
</logout>
</firewall>
</config>
</srv:container>
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
// config/packages/security.php
// ...
return static function (SecurityConfig $securityConfig): void {
// ...
$securityConfig->firewall('main')
->logout()
->deleteCookie('cookie1-name')
->deleteCookie('cookie2-name')
->path('/')
->deleteCookie('cookie3-name')
->path(null)
->domain('example.com');
};
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
UserNotFoundException
and it includes the given not found user identifier.
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.
access_control
Defines the security protection of the URLs of your application. It's used for example to trigger the user authentication when trying to access to the backend and to allow unauthenticated users to the login form page.
This option is explained in detail in How Does the Security access_control Work?.
firewalls
This is arguably the most important option of the security config file. It defines the authentication mechanism used for each URL (or URL pattern) of your application:
1 2 3 4 5 6 7 8 9 10 11
# config/packages/security.yaml
security:
# ...
firewalls:
# 'main' is the name of the firewall (can be chosen freely)
main:
# 'pattern' is a regular expression matched against the incoming
# request URL. If there's a match, authentication is triggered
pattern: ^/admin
# the rest of options depend on the authentication mechanism
# ...
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' is a regular expression matched against the incoming
request URL. If there's a match, authentication is triggered -->
<firewall name="main" pattern="^/admin">
<!-- the rest of options depend on the authentication mechanism -->
<!-- ... -->
</firewall>
</config>
</srv:container>
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' is the name of the firewall (can be chosen freely)
$security->firewall('main')
// 'pattern' is a regular expression matched against the incoming
// request URL. If there's a match, authentication is triggered
->pattern('^/admin')
// the rest of options depend on the authentication mechanism
// ...
;
};
See also
Read this article to learn about how to restrict firewalls by host and HTTP methods.
In addition to some common config options, the most important firewall options depend on the authentication mechanism, which can be any of these:
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:
# ...
You can view actual information about the firewalls in your application with
the debug:firewall
command:
1 2 3 4 5 6 7 8 9
# displays a list of firewalls currently configured for your application
$ php bin/console debug:firewall
# displays the details of a specific firewall
$ php bin/console debug:firewall main
# displays the details of a specific firewall, including detailed information
# about the event listeners for the firewall
$ php bin/console debug:firewall main --events
5.3
The debug:firewall
command was introduced in Symfony 5.3.
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 may 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.
5.4
The form_only
option was introduced in Symfony 5.4.
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.
Note
For historical reasons, and to match the misspelling of the HTTP standard,
the option is called use_referer
instead of use_referrer
.
logout
You can configure logout options.
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.
path
type: string
default: /logout
The path which triggers logout. You need to set up a route with a matching path.
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.
success_handler
5.1
This option is deprecated since Symfony 5.1. Register an event listener on the LogoutEvent instead.
type: string
default: security.logout.success_handler
The service ID used for handling a successful logout. The service must implement LogoutSuccessHandlerInterface.
If it is set, the logout target
option will be ignored.
csrf_parameter
type: string
default: _csrf_token
The name of the parameter that stores the CSRF token value.
csrf_token_generator
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).
JSON Login Authentication
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 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>
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
type: string
default: password
Use this option to modify the expected request body structure. See username_path for more details.
LDAP Authentication
There are several options for connecting against an LDAP server,
using the form_login_ldap
, http_basic_ldap
and json_login_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
, http_basic
and json_login
authentication providers. Use
form_login_ldap
, http_basic_ldap
and json_login_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:
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 (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 {username}
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
.
X.509 Authentication
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
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>
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
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).
Symfony identifies the value following emailAddress=
in this parameter.
Remote User Authentication
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 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>
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
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.
Firewall Context
If your application uses 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
# 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 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>
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
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.
stateless
Firewalls can configure a stateless
boolean option in order to declare that
the session must not be used when authenticating users:
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 13 14 15 16
<!-- 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" stateless="true">
<!-- ... -->
</firewall>
</config>
</srv:container>
1 2 3 4 5 6 7 8
// config/packages/security.php
use Symfony\Config\SecurityConfig;
return static function (SecurityConfig $security) {
$mainFirewall = $security->firewall('main');
$mainFirewall->stateless(true);
// ...
};
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.
Required Badges
Firewalls can configure a list of required badges that must be present on the authenticated passport:
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 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">
<!-- ... -->
<required_badge>CsrfTokenBadge</required_badge>
<required_badge>My\Badge</required_badge>
</firewall>
</config>
</srv:container>
1 2 3 4 5 6 7 8
// config/packages/security.php
use Symfony\Config\SecurityConfig;
return static function (SecurityConfig $security) {
$mainFirewall = $security->firewall('main');
$mainFirewall->requiredBadges(['CsrfTokenBadge', 'My\Badge']);
// ...
};
5.3
The required_badges
option was introduced in Symfony 5.3.
providers
This option defines how the application users are loaded (from a database, an LDAP server, a configuration file, etc.) Read User Providers to learn more about each of those providers.
role_hierarchy
Instead of associating many roles to users, this option allows you to define role inheritance rules by creating a role hierarchy, as explained in Security.