Creative Commons License
This work is licensed under a
Creative Commons
Attribution-Share Alike 3.0
Unported License.

Master Symfony2 fundamentals

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

Discover the SensioLabs Support

Access to the SensioLabs Competency Center for an exclusive and tailor-made support on Symfony
sensiolabs.com
Caution: You are browsing the documentation for Symfony version 2.1 which is not maintained anymore. If some of your projects are still using this version, consider upgrading.

Security Configuration Reference

The security system is one of the most powerful parts of Symfony2, 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
    # 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
            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
    
            # Example options/values for what a custom encoder might look like
            Acme\DemoBundle\Entity\User3:
                id:                   my.encoder.id
    
        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
    
            # 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: .*
                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
                http_basic:
                    provider: some_key_from_above
                http_digest:
                    provider: some_key_from_above
                form_login:
                    # submit the login form here
                    check_path: /login_check
    
                    # the user is redirected here when he/she needs to login
                    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_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
                    intention:      authenticate
                    csrf_provider:  my.csrf_provider.id
    
                    # by default, the login form *must* be a POST, not a GET
                    post_only:      true
                    remember_me:    false
                remember_me:
                    token_provider: name
                    key: someS3cretKey
                    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_provider:        ~
                    intention:            logout
                    path:                 /logout
                    target:               /
                    success_handler:      ~
                    invalidate_session:   true
                    delete_cookies:
    
                        # Prototype
                        name:
                            path:                 ~
                            domain:               ~
                    handlers:             []
                anonymous:
                    key:                  4f954a0667e01
                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:                 ~
            ip:                   ~
            methods:              []
            roles:                []
        role_hierarchy:
            ROLE_ADMIN:      [ROLE_ORGANIZER, ROLE_USER]
            ROLE_SUPERADMIN: [ROLE_ADMIN]
    

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 your 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 he/she tries 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)
  • default_target_path (type: string, default: /)
  • target_path_parameter (type: string, default: _target_path)
  • use_referer (type: Boolean, default: false)

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
    <!-- app/config/security.xml -->
    <security:config>
       <firewall name="somename" context="my_context">
         <! ... ->
       </firewall>
       <firewall name="othername" context="my_context">
         <! ... ->
       </firewall>
    </security:config>
    
  • 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'
             ),
         ),
    ));
    

HTTP-Digest Authentication

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

  • YAML
    1
    2
    3
    4
    5
    6
    7
    # app/config/security.yml
    security:
       firewalls:
          somename:
            http_digest:
             key: "a_random_string"
             realm: "secure-api"
    
  • XML
    1
    2
    3
    4
    5
    6
    <!-- app/config/security.xml -->
    <security:config>
       <firewall name="somename">
          <http-digest key="a_random_string" realm="secure-api" />
       </firewall>
    </security:config>
    
  • 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(
                     'key'   => 'a_random_string',
                     'realm' => 'secure-api',
                 ),
             ),
         ),
    ));