SecurityBundle Configuration ("security")
SecurityBundle Configuration ("security")¶
The security system is one of the most powerful parts of Symfony and can largely be controlled via its configuration.
Full Default Configuration¶
The following is the full default configuration for the security system. Each part will be explained in the next section.
- YAML
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291
# app/config/security.yml security: access_denied_url: ~ # Example: /foo/error403 # strategy can be: none, migrate, invalidate session_fixation_strategy: migrate hide_user_not_found: true always_authenticate_before_granting: false erase_credentials: true access_decision_manager: strategy: affirmative # One of affirmative, consensus, unanimous allow_if_all_abstain: false allow_if_equal_granted_denied: true acl: # any name configured in doctrine.dbal section connection: ~ cache: id: ~ prefix: sf2_acl_ provider: ~ tables: class: acl_classes entry: acl_entries object_identity: acl_object_identities object_identity_ancestors: acl_object_identity_ancestors security_identity: acl_security_identities voter: allow_if_object_identity_unavailable: true encoders: # Examples: Acme\DemoBundle\Entity\User1: sha512 Acme\DemoBundle\Entity\User2: algorithm: sha512 encode_as_base64: true iterations: 5000 # PBKDF2 encoder # see the note about PBKDF2 below for details on security and speed Acme\Your\Class\Name: algorithm: pbkdf2 hash_algorithm: sha512 encode_as_base64: true iterations: 1000 key_length: 40 # Example options/values for what a custom encoder might look like Acme\DemoBundle\Entity\User3: id: my.encoder.id # BCrypt encoder # see the note about bcrypt below for details on specific dependencies Acme\DemoBundle\Entity\User4: algorithm: bcrypt cost: 13 # Plaintext encoder # it does not do any encoding Acme\DemoBundle\Entity\User5: algorithm: plaintext ignore_case: false providers: # Required # Examples: my_in_memory_provider: memory: users: foo: password: foo roles: ROLE_USER bar: password: bar roles: [ROLE_USER, ROLE_ADMIN] my_entity_provider: entity: class: SecurityBundle:User property: username # name of a non-default entity manager manager_name: ~ my_ldap_provider: ldap: service: ~ base_dn: ~ search_dn: ~ search_password: ~ default_roles: 'ROLE_USER' uid_key: 'sAMAccountName' filter: '({uid_key}={username})' # Example custom provider my_some_custom_provider: id: ~ # Chain some providers my_chain_provider: chain: providers: [ my_in_memory_provider, my_entity_provider ] firewalls: # Required # Examples: somename: pattern: .* # restrict the firewall to a specific host host: admin\.example\.com # restrict the firewall to specific HTTP methods methods: [GET, POST] request_matcher: some.service.id access_denied_url: /foo/error403 access_denied_handler: some.service.id entry_point: some.service.id provider: some_key_from_above # manages where each firewall stores session information # See "Firewall Context" below for more details context: context_key stateless: false x509: provider: some_key_from_above remote_user: provider: some_key_from_above http_basic: provider: some_key_from_above http_basic_ldap: provider: some_key_from_above service: ldap dn_string: '{username}' http_digest: provider: some_key_from_above guard: # A key from the "providers" section of your security config, in case your user provider is different than the firewall provider: ~ # A service id (of one of your authenticators) whose start() method should be called when an anonymous user hits a page that requires authentication entry_point: null # An array of service ids for all of your "authenticators" authenticators: [] form_login: # submit the login form here check_path: /login_check # the user is redirected here when they need to log in login_path: /login # if true, forward the user to the login form instead of redirecting use_forward: false # login success redirecting options (read further below) always_use_default_target_path: false default_target_path: / target_path_parameter: _target_path use_referer: false # login failure redirecting options (read further below) failure_path: /foo failure_forward: false failure_path_parameter: _failure_path failure_handler: some.service.id success_handler: some.service.id # field names for the username and password fields username_parameter: _username password_parameter: _password # csrf token options csrf_parameter: _csrf_token csrf_token_id: authenticate csrf_token_generator: my.csrf_token_generator.id # by default, the login form *must* be a POST, not a GET post_only: true remember_me: false # by default, a session must exist before submitting an authentication request # if false, then Request::hasPreviousSession is not called during authentication # new in Symfony 2.3 require_previous_session: true form_login_ldap: # submit the login form here check_path: /login_check # the user is redirected here when they need to log in login_path: /login # if true, forward the user to the login form instead of redirecting use_forward: false # login success redirecting options (read further below) always_use_default_target_path: false default_target_path: / target_path_parameter: _target_path use_referer: false # login failure redirecting options (read further below) failure_path: /foo failure_forward: false failure_path_parameter: _failure_path failure_handler: some.service.id success_handler: some.service.id # field names for the username and password fields username_parameter: _username password_parameter: _password # csrf token options csrf_parameter: _csrf_token csrf_token_id: authenticate csrf_token_generator: my.csrf_token_generator.id # by default, the login form *must* be a POST, not a GET post_only: true remember_me: false # by default, a session must exist before submitting an authentication request # if false, then Request::hasPreviousSession is not called during authentication # new in Symfony 2.3 require_previous_session: true service: ~ dn_string: '{username}' remember_me: token_provider: name secret: "%secret%" name: NameOfTheCookie lifetime: 3600 # in seconds path: /foo domain: somedomain.foo secure: false httponly: true always_remember_me: false remember_me_parameter: _remember_me logout: path: /logout target: / invalidate_session: false delete_cookies: a: { path: null, domain: null } b: { path: null, domain: null } handlers: [some.service.id, another.service.id] success_handler: some.service.id anonymous: ~ # Default values and options for any firewall some_firewall_listener: pattern: ~ security: true request_matcher: ~ access_denied_url: ~ access_denied_handler: ~ entry_point: ~ provider: ~ stateless: false context: ~ logout: csrf_parameter: _csrf_token csrf_token_generator: ~ csrf_token_id: logout path: /logout target: / success_handler: ~ invalidate_session: true delete_cookies: # Prototype name: path: ~ domain: ~ handlers: [] anonymous: secret: "%secret%" switch_user: provider: ~ parameter: _switch_user role: ROLE_ALLOWED_TO_SWITCH access_control: requires_channel: ~ # use the urldecoded format path: ~ # Example: ^/path to resource/ host: ~ ips: [] methods: [] roles: [] role_hierarchy: ROLE_ADMIN: [ROLE_ORGANIZER, ROLE_USER] ROLE_SUPERADMIN: [ROLE_ADMIN]
New in version 2.8: The secret option of anonymous and remember_me was introduced
in Symfony 2.8. Prior to 2.8, it was called key.
New in version 2.8: The http_basic_ldap and form_login_ldap authentication providers
were introduced in Symfony 2.8.
New in version 2.8: The ldap user provider was introduced in Symfony 2.8
Form Login Configuration¶
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.
The Login Form and Process¶
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 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.
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.
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.
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:
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).
- YAML
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.
- YAML
1 2 3 4 5 6 7 8
# app/config/security.yml security: # ... encoders: Symfony\Component\Security\Core\User\User: algorithm: bcrypt cost: 15
- XML
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>
- PHP
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:
- YAML
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
- XML
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>
- PHP
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.
HTTP-Digest Authentication¶
To use HTTP-Digest authentication you need to provide a realm and a secret:
- YAML
1 2 3 4 5 6 7
# app/config/security.yml security: firewalls: somename: http_digest: secret: '%secret%' realm: 'secure-api'
- XML
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>
- PHP
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', ), ), ), ));
New in version 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.