Loading the User: The User Provider

Besides creating the entity, the make:user command also adds config for a user provider in your security configuration:

1
2
3
4
5
6
7
8
9

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

    providers:
        app_user_provider:
            entity:
                class: App\Entity\User
                property: email

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: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>
        <!-- ... -->

        <provider name="app_user_provider">
            <entity class="App\Entity\User" property="email"/>
        </provider>
    </config>
</srv:container>

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

// config/packages/security.php
use App\Entity\User;
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security) {
    // ...

    $security->provider('app_user_provider')
        ->entity()
            ->class(User::class)
            ->property('email')
    ;
};

This user provider knows how to (re)load users from a storage (e.g. a database) based on a "user identifier" (e.g. the user's email address or username). The configuration above uses Doctrine to load the User entity using the email property as "user identifier".

User providers are used in a couple places during the security lifecycle:

Load the User based on an identifier

During login (or any other authenticator), the provider loads the user based on the user identifier. Some other features, like user impersonation and Remember Me also use this.

Reload the User from the session

At the beginning of each request, the user is loaded from the session (unless your firewall is stateless). The provider "refreshes" the user (e.g. the database is queried again for fresh data) to make sure all user information is up to date (and if necessary, the user is de-authenticated/logged out if something changed). See Security for more information about this process.

Symfony comes with several built-in user providers:

Entity User Provider

Loads users from a database using Doctrine;

LDAP User Provider

Loads users from a LDAP server;

Memory User Provider

Loads users from a configuration file;

Chain User Provider

Merges two or more user providers into a new user provider. Since each firewall has exactly one user provider, you can use this to chain multiple providers together.

The built-in user providers cover the most common needs for applications, but you can also create your own custom user provider.

Registering the User: Hashing Passwords

Many applications require a user to log in with a password. For these applications, the SecurityBundle provides password hashing and verification functionality.

First, make sure your User class implements the PasswordAuthenticatedUserInterface:

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

// src/Entity/User.php

// ...
use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;

class User implements UserInterface, PasswordAuthenticatedUserInterface
{
    // ...

    /**
     * @return string the hashed password for this user
     */
    public function getPassword(): string
    {
        return $this->password;
    }
}

Then, configure which password hasher should be used for this class. If your security.yaml file wasn't already pre-configured, then make:user should have done this for you:

1
2
3
4
5
6
7

# config/packages/security.yaml
security:
    # ...
    password_hashers:
        # Use native password hasher, which auto-selects and migrates the best
        # possible hashing algorithm (which currently is "bcrypt")
        Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface: 'auto'

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>
        <!-- ... -->
        <!-- Use native password hasher, which auto-selects and migrates the best
             possible hashing algorithm (currently this is "bcrypt") -->
        <password-hasher class="Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface" algorithm="auto"/>
    </config>
</srv:container>

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

// config/packages/security.php
use App\Entity\User;
use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;

return static function (SecurityConfig $security) {
    // ...

    // Use native password hasher, which auto-selects and migrates the best
    // possible hashing algorithm (currently this is "bcrypt")
    $security->passwordHasher(PasswordAuthenticatedUserInterface::class)
        ->algorithm('auto')
    ;
};

Now that Symfony knows how you want to hash the passwords, you can use the UserPasswordHasherInterface service to do this before saving your users to the database:

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

// src/Controller/RegistrationController.php
namespace App\Controller;

// ...
use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;

class RegistrationController extends AbstractController
{
    public function index(UserPasswordHasherInterface $passwordHasher)
    {
        // ... e.g. get the user data from a registration form
        $user = new User(...);
        $plaintextPassword = ...;

        // hash the password (based on the security.yaml config for the $user class)
        $hashedPassword = $passwordHasher->hashPassword(
            $user,
            $plaintextPassword
        );
        $user->setPassword($hashedPassword);

        // ...
    }
}

1
2

$ composer require symfonycasts/verify-email-bundle
$ php bin/console make:registration-form

You can also manually hash a password by running:

1

$ php bin/console security:hash-password

Read more about all available hashers and password migration in Password Hashing and Verification.

Form Login

Most websites have a login form where users authenticate using an identifier (e.g. email address or username) and a password. This functionality is provided by the form login authenticator.

First, create a controller for the login form:

1
2
3
4

$ php bin/console make:controller Login

 created: src/Controller/LoginController.php
 created: templates/login/index.html.twig

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

// src/Controller/LoginController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class LoginController extends AbstractController
{
    #[Route('/login', name: 'app_login')]
    public function index(): Response
    {
        return $this->render('login/index.html.twig', [
            'controller_name' => 'LoginController',
        ]);
    }
}

Then, enable the form login authenticator using the form_login setting:

1
2
3
4
5
6
7
8
9
10
11

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

    firewalls:
        main:
            # ...
            form_login:
                # "app_login" is the name of the route created previously
                login_path: app_login
                check_path: app_login

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">
            <!-- "app_login" is the name of the route created previously -->
            <form-login login-path="app_login" check-path="app_login"/>
        </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) {
    // ...

    $mainFirewall = $security->firewall('main');

    // "app_login" is the name of the route created previously
    $mainFirewall->formLogin()
        ->loginPath('app_login')
        ->checkPath('app_login')
    ;
};

Once enabled, the security system redirects unauthenticated visitors to the login_path when they try to access a secured place (this behavior can be customized using authentication entry points).

Edit the login controller to render the login form:

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

// ...
+ use Symfony\Component\Security\Http\Authentication\AuthenticationUtils;

  class LoginController extends AbstractController
  {
      #[Route('/login', name: 'app_login')]
-     public function index(): Response
+     public function index(AuthenticationUtils $authenticationUtils): Response
      {
+         // get the login error if there is one
+         $error = $authenticationUtils->getLastAuthenticationError();
+
+         // last username entered by the user
+         $lastUsername = $authenticationUtils->getLastUsername();
+
          return $this->render('login/index.html.twig', [
-             'controller_name' => 'LoginController',
+             'last_username' => $lastUsername,
+             'error'         => $error,
          ]);
      }
  }

Don't let this controller confuse you. Its job is only to render the form: the form_login authenticator will handle the form submission automatically. If the user submits an invalid email or password, that authenticator will store the error and redirect back to this controller, where we read the error (using AuthenticationUtils) so that it can be displayed back to the user.

Finally, create or update the template:

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

{# templates/login/index.html.twig #}
{% extends 'base.html.twig' %}

{# ... #}

{% block body %}
    {% if error %}
        <div>{{ error.messageKey|trans(error.messageData, 'security') }}</div>
    {% endif %}

    <form action="{{ path('app_login') }}" method="post">
        <label for="username">Email:</label>
        <input type="text" id="username" name="_username" value="{{ last_username }}">

        <label for="password">Password:</label>
        <input type="password" id="password" name="_password">

        {# If you want to control the URL the user is redirected to on success
        <input type="hidden" name="_target_path" value="/account"> #}

        <button type="submit">login</button>
    </form>
{% endblock %}

The form can look like anything, but it usually follows some conventions:

• The <form> element sends a POST request to the app_login route, since that's what you configured as the check_path under the form_login key in security.yaml;
• The username (or whatever your user's "identifier" is, like an email) field has the name _username and the password field has the name _password.

And that's it! When you submit the form, the security system automatically reads the _username and _password POST parameter, loads the user via the user provider, checks the user's credentials and either authenticates the user or sends them back to the login form where the error can be displayed.

To review the whole process:

1. The user tries to access a resource that is protected (e.g. /admin);
2. The firewall initiates the authentication process by redirecting the user to the login form (/login);
3. The /login page renders login form via the route and controller created in this example;
4. The user submits the login form to /login;
5. The security system (i.e. the form_login authenticator) intercepts the request, checks the user's submitted credentials, authenticates the user if they are correct, and sends the user back to the login form if they are not.

1
2
3
4
5
6
7
8
9
10

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

    firewalls:
        secured_area:
            # ...
            form_login:
                # ...
                enable_csrf: true

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="secured_area">
            <!-- ... -->
            <form-login enable-csrf="true"/>
        </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->formLogin()
        // ...
        ->enableCsrf(true)
    ;
};

1
2
3
4
5
6
7
8
9
10

{# templates/login/index.html.twig #}

{# ... #}
<form action="{{ path('app_login') }}" method="post">
    {# ... the login fields #}

    <input type="hidden" name="_csrf_token" value="{{ csrf_token('authenticate') }}">

    <button type="submit">login</button>
</form>

JSON Login

Some applications provide an API that is secured using tokens. These applications may use an endpoint that provides these tokens based on a username (or email) and password. The JSON login authenticator helps you create this functionality.

Enable the authenticator using the json_login setting:

1
2
3
4
5
6
7
8
9
10

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

    firewalls:
        main:
            # ...
            json_login:
                # api_login is a route we will create below
                check_path: api_login

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: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">
            <json-login check-path="api_login"/>
        </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->jsonLogin()
        ->checkPath('api_login')
    ;
};

The authenticator runs when a client requests the check_path. First, create a controller for this path:

1
2
3

$ php bin/console make:controller --no-template ApiLogin

 created: src/Controller/ApiLoginController.php

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

// src/Controller/ApiLoginController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class ApiLoginController extends AbstractController
{
    #[Route('/api/login', name: 'api_login')]
    public function index(): Response
    {
        return $this->json([
            'message' => 'Welcome to your new controller!',
            'path' => 'src/Controller/ApiLoginController.php',
        ]);
    }
}

This login controller will be called after the authenticator successfully authenticates the user. You can get the authenticated user, generate a token (or whatever you need to return) and return the JSON response:

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

// ...
+ use App\Entity\User;
+ use Symfony\Component\Security\Http\Attribute\CurrentUser;

  class ApiLoginController extends AbstractController
  {
      #[Route('/api/login', name: 'api_login')]
-     public function index(): Response
+     public function index(#[CurrentUser] ?User $user): Response
      {
+         if (null === $user) {
+             return $this->json([
+                 'message' => 'missing credentials',
+             ], Response::HTTP_UNAUTHORIZED);
+         }
+
+         $token = ...; // somehow create an API token for $user
+
          return $this->json([
-             'message' => 'Welcome to your new controller!',
-             'path' => 'src/Controller/ApiLoginController.php',
+             'user'  => $user->getUserIdentifier(),
+             'token' => $token,
          ]);
      }
  }

That's it! To summarize the process:

1. A client (e.g. the front-end) makes a POST request with the Content-Type: application/json header to /api/login with username (even if your identifier is actually an email) and password keys:

   1
   2
   3
   4

   {
       "username": "dunglas@example.com",
       "password": "MyPassword"
   }

2. The security system intercepts the request, checks the user's submitted credentials and authenticates the user. If the credentials are incorrect, an HTTP 401 Unauthorized JSON response is returned, otherwise your controller is run;

3. Your controller creates the correct response:

   1
   2
   3
   4

   {
       "user": "dunglas@example.com",
       "token": "45be42..."
   }

HTTP Basic

HTTP Basic authentication is a standardized HTTP authentication framework. It asks credentials (username and password) using a dialog in the browser and the HTTP basic authenticator of Symfony will verify these credentials.

Add the http_basic key to your firewall to enable HTTP Basic authentication:

1
2
3
4
5
6
7
8
9

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

    firewalls:
        main:
            # ...
            http_basic:
                realm: Secured Area

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">
            <http-basic realm="Secured Area"/>
        </firewall>
    </config>
</srv:container>

1
2
3
4
5
6
7
8
9

// config/packages/security.php
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security) {
    $mainFirewall = $security->firewall('main');
    $mainFirewall->httpBasic()
        ->realm('Secured Area')
    ;
};

That's it! Whenever an unauthenticated user tries to visit a protected page, Symfony will inform the browser that it needs to start HTTP basic authentication (using the WWW-Authenticate response header). Then, the authenticator verifies the credentials and authenticates the user.

Login Link

Login links are a passwordless authentication mechanism. The user will receive a short-lived link (e.g. via email) which will authenticate them to the website.

You can learn all about this authenticator in How to use Passwordless Login Link Authentication.

X.509 Client Certificates

When using client certificates, your web server does all the authentication itself. The X.509 authenticator provided by Symfony extracts the email from the "distinguished name" (DN) of the client certificate. Then, it uses this email as user identifier in the user provider.

First, configure your web server to enable client certificate verification and to expose the certificate's DN to the Symfony application:

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

server {
    # ...

    ssl_client_certificate /path/to/my-custom-CA.pem;

    # enable client certificate verification
    ssl_verify_client optional;
    ssl_verify_depth 1;

    location / {
        # pass the DN as "SSL_CLIENT_S_DN" to the application
        fastcgi_param SSL_CLIENT_S_DN $ssl_client_s_dn;

        # ...
    }
}

1
2
3
4
5
6
7

# ...
SSLCACertificateFile "/path/to/my-custom-CA.pem"
SSLVerifyClient optional
SSLVerifyDepth 1

# pass the DN to the application
SSLOptions +StdEnvVars

Then, enable the X.509 authenticator using x509 on your firewall:

1
2
3
4
5
6
7
8
9

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

    firewalls:
        main:
            # ...
            x509:
                provider: your_user_provider

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="main">
            <!-- ... -->
            <x509 provider="your_user_provider"/>
        </firewall>
    </config>
</srv:container>

1
2
3
4
5
6
7
8
9

// config/packages/security.php
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security) {
    $mainFirewall = $security->firewall('main');
    $mainFirewall->x509()
        ->provider('your_user_provider')
    ;
};

By default, Symfony extracts the email address from the DN in two different ways:

1. First, it tries the SSL_CLIENT_S_DN_Email server parameter, which is exposed by Apache;
2. If it is not set (e.g. when using Nginx), it uses SSL_CLIENT_S_DN and matches the value following emailAddress=.

You can customize the name of both parameters under the x509 key. See the configuration reference for more details.

Remote Users

Besides client certificate authentication, there are more web server modules that pre-authenticate a user (e.g. kerberos). The remote user authenticator provides a basic integration for these services.

These modules often expose the authenticated user in the REMOTE_USER environment variable. The remote user authenticator uses this value as the user identifier to load the corresponding user.

Enable remote user authentication using the remote_user key:

1
2
3
4
5
6
7

# config/packages/security.yaml
security:
    firewalls:
        main:
            # ...
            remote_user:
                provider: your_user_provider

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: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"/>
        </firewall>
    </config>
</srv:container>

1
2
3
4
5
6
7
8
9

// config/packages/security.php
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security) {
    $mainFirewall = $security->firewall('main');
    $mainFirewall->remoteUser()
        ->provider('your_user_provider')
    ;
};

Limiting Login Attempts

Symfony provides basic protection against brute force login attacks. You must enable this using the login_throttling setting:

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

# config/packages/security.yaml
security:

    firewalls:
        # ...

        main:
            # ...

            # by default, the feature allows 5 login attempts per minute
            login_throttling: null

            # configure the maximum login attempts
            login_throttling:
                max_attempts: 3          # per minute ...
                # interval: '15 minutes' # ... or in a custom period

            # use a custom rate limiter via its service ID
            login_throttling:
                limiter: app.my_login_rate_limiter

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

<!-- 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">

    <!-- you must use the authenticator manager -->
    <config enable-authenticator-manager="true">
        <!-- ... -->

        <firewall name="main">
            <!-- by default, the feature allows 5 login attempts per minute
                 max-attempts: (optional) You can configure the maximum attempts ...
                 interval:     (optional) ... and the period of time. -->
            <login-throttling max-attempts="3" interval="15 minutes"/>

            <!-- use a custom rate limiter via its service ID -->
            <login-throttling limiter="app.my_login_rate_limiter"/>
        </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->enableAuthenticatorManager(true);

    $mainFirewall = $security->firewall('main');

    // by default, the feature allows 5 login attempts per minute
    $mainFirewall->loginThrottling()
        // ->maxAttempts(3)         // Optional: You can configure the maximum attempts ...
        // ->interval('15 minutes') // ... and the period of time.
    ;
};

Internally, Symfony uses the Rate Limiter component which by default uses Symfony's cache to store the previous login attempts. However, you can implement a custom storage.

Login attempts are limited on max_attempts (default: 5) failed requests for IP address + username and 5 * max_attempts failed requests for IP address. The second limit protects against an attacker using multiple usernames from bypassing the first limit, without disrupting normal users on big networks (such as offices).

If you need a more complex limiting algorithm, create a class that implements RequestRateLimiterInterface (or use DefaultLoginRateLimiter) and set the limiter option to its service ID:

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

# config/packages/security.yaml
framework:
    rate_limiter:
        # define 2 rate limiters (one for username+IP, the other for IP)
        username_ip_login:
            policy: token_bucket
            limit: 5
            rate: { interval: '5 minutes' }

        ip_login:
            policy: sliding_window
            limit: 50
            interval: '15 minutes'

services:
    # our custom login rate limiter
    app.login_rate_limiter:
        class: Symfony\Component\Security\Http\RateLimiter\DefaultLoginRateLimiter
        arguments:
            # globalFactory is the limiter for IP
            $globalFactory: '@limiter.ip_login'
            # localFactory is the limiter for username+IP
            $localFactory: '@limiter.username_ip_login'

security:
    firewalls:
        main:
            # use a custom rate limiter via its service ID
            login_throttling:
                limiter: app.login_rate_limiter

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

<!-- 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:framework="http://symfony.com/schema/dic/symfony"
    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/symfony
        https://symfony.com/schema/dic/symfony/symfony-1.0.xsd
        http://symfony.com/schema/dic/security
        https://symfony.com/schema/dic/security/security-1.0.xsd">

    <framework:config>
        <framework:rate-limiter>
            <!-- define 2 rate limiters (one for username+IP, the other for IP) -->
            <framework:limiter name="username_ip_login"
                policy="token_bucket"
                limit="5"
            >
                <framework:rate interval="5 minutes"/>
            </framework:limiter>

            <framework:limiter name="ip_login"
                policy="sliding_window"
                limit="50"
                interval="15 minutes"
            />
        </framework:rate-limiter>
    </framework:config>

    <srv:services>
        <!-- our custom login rate limiter -->
        <srv:service id="app.login_rate_limiter"
            class="Symfony\Component\Security\Http\RateLimiter\DefaultLoginRateLimiter"
        >
            <!-- 1st argument is the limiter for IP -->
            <srv:argument type="service" id="limiter.ip_login"/>
            <!-- 2nd argument is the limiter for username+IP -->
            <srv:argument type="service" id="limiter.username_ip_login"/>
        </srv:service>
    </srv:services>

    <config>
        <firewall name="main">
            <!-- use a custom rate limiter via its service ID -->
            <login-throttling limiter="app.login_rate_limiter"/>
        </firewall>
    </config>
</srv:container>

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

// config/packages/security.php
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Reference;
use Symfony\Component\Security\Http\RateLimiter\DefaultLoginRateLimiter;
use Symfony\Config\FrameworkConfig;
use Symfony\Config\SecurityConfig;

return static function (ContainerBuilder $containerBuilder, FrameworkConfig $framework, SecurityConfig $security) {
    $framework->rateLimiter()
        ->limiter('username_ip_login')
            ->policy('token_bucket')
            ->limit(5)
            ->rate()
                ->interval('5 minutes')
    ;

    $framework->rateLimiter()
        ->limiter('ip_login')
            ->policy('sliding_window')
            ->limit(50)
            ->interval('15 minutes')
    ;

    $containerBuilder->register('app.login_rate_limiter', DefaultLoginRateLimiter::class)
        ->setArguments([
            // 1st argument is the limiter for IP
            new Reference('limiter.ip_login'),
            // 2nd argument is the limiter for username+IP
            new Reference('limiter.username_ip_login'),
        ]);

    $security->firewall('main')
        ->loginThrottling()
            ->limiter('app.login_rate_limiter')
    ;
};

Customizing Logout

In some cases you need to run extra logic upon logout (e.g. invalidate some tokens) or want to customize what happens after a logout. During logout, a LogoutEvent is dispatched. Register an event listener or subscriber to execute custom logic:

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

// src/EventListener/LogoutSubscriber.php
namespace App\EventListener;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Symfony\Component\Security\Http\Event\LogoutEvent;

class LogoutSubscriber implements EventSubscriberInterface
{
    public function __construct(
        private UrlGeneratorInterface $urlGenerator
    ) {
    }

    public static function getSubscribedEvents(): array
    {
        return [LogoutEvent::class => 'onLogout'];
    }

    public function onLogout(LogoutEvent $event): void
    {
        // get the security token of the session that is about to be logged out
        $token = $event->getToken();

        // get the current request
        $request = $event->getRequest();

        // get the current response, if it is already set by another listener
        $response = $event->getResponse();

        // configure a custom logout response to the homepage
        $response = new RedirectResponse(
            $this->urlGenerator->generate('homepage'),
            RedirectResponse::HTTP_SEE_OTHER
        );
        $event->setResponse($response);
    }
}

Fetching the User from a Service

If you need to get the logged in user from a service, use the Security service:

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

// src/Service/ExampleService.php
// ...

use Symfony\Component\Security\Core\Security;

class ExampleService
{
    private $security;

    public function __construct(Security $security)
    {
        // Avoid calling getUser() in the constructor: auth may not
        // be complete yet. Instead, store the entire Security object.
        $this->security = $security;
    }

    public function someMethod()
    {
        // returns User object or null if not authenticated
        $user = $this->security->getUser();

        // ...
    }
}

Fetch the User in a Template

In a Twig Template the user object is available via the app.user variable thanks to the Twig global app variable:

1
2
3

{% if is_granted('IS_AUTHENTICATED_FULLY') %}
    <p>Email: {{ app.user.email }}</p>
{% endif %}

Roles

When a user logs in, Symfony calls the getRoles() method on your User object to determine which roles this user has. In the User class that was generated earlier, the roles are an array that's stored in the database and every user is always given at least one role: ROLE_USER:

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

// src/Entity/User.php

// ...
class User
{
    #[ORM\Column(type: 'json')]
    private $roles = [];

    // ...
    public function getRoles(): array
    {
        $roles = $this->roles;
        // guarantee every user at least has ROLE_USER
        $roles[] = 'ROLE_USER';

        return array_unique($roles);
    }
}

This is a nice default, but you can do whatever you want to determine which roles a user should have. The only rule is that every role must start with the ROLE_ prefix - otherwise, things won't work as expected. Other than that, a role is just a string and you can invent whatever you need (e.g. ROLE_PRODUCT_ADMIN).

You'll use these roles next to grant access to specific sections of your site.

1
2
3
4
5
6
7

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

    role_hierarchy:
        ROLE_ADMIN:       ROLE_USER
        ROLE_SUPER_ADMIN: [ROLE_ADMIN, ROLE_ALLOWED_TO_SWITCH]

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

        <role id="ROLE_ADMIN">ROLE_USER</role>
        <role id="ROLE_SUPER_ADMIN">ROLE_ADMIN, ROLE_ALLOWED_TO_SWITCH</role>
    </config>
</srv:container>

1
2
3
4
5
6
7
8
9

// config/packages/security.php
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security) {
    // ...

    $security->roleHierarchy('ROLE_ADMIN', ['ROLE_USER']);
    $security->roleHierarchy('ROLE_SUPER_ADMIN', ['ROLE_ADMIN', 'ROLE_ALLOWED_TO_SWITCH']);
};

1
2
3
4
5
6

// BAD - $user->getRoles() will not know about the role hierarchy
$hasAccess = in_array('ROLE_ADMIN', $user->getRoles());

// GOOD - use of the normal security methods
$hasAccess = $this->isGranted('ROLE_ADMIN');
$this->denyAccessUnlessGranted('ROLE_ADMIN');

Add Code to Deny Access

There are two ways to deny access to something:

1. access_control in security.yaml allows you to protect URL patterns (e.g. /admin/*). Simpler, but less flexible;
2. in your controller (or other code).

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

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

    firewalls:
        # ...
        main:
            # ...

    access_control:
        # require ROLE_ADMIN for /admin*
        - { path: '^/admin', roles: ROLE_ADMIN }

        # or require ROLE_ADMIN or IS_AUTHENTICATED_FULLY for /admin*
        - { path: '^/admin', roles: [IS_AUTHENTICATED_FULLY, ROLE_ADMIN] }

        # the 'path' value can be any valid regular expression
        # (this one will match URLs like /api/post/7298 and /api/comment/528491)
        - { path: ^/api/(post|comment)/\d+$, roles: ROLE_USER }

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

<!-- 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">
            <!-- ... -->
        </firewall>

        <!-- require ROLE_ADMIN for /admin* -->
        <rule path="^/admin" role="ROLE_ADMIN"/>

        <!-- require ROLE_ADMIN or IS_AUTHENTICATED_FULLY for /admin* -->
        <rule path="^/admin">
            <role>ROLE_ADMIN</role>
            <role>IS_AUTHENTICATED_FULLY</role>
        </rule>

        <!-- the 'path' value can be any valid regular expression
             (this one will match URLs like /api/post/7298 and /api/comment/528491) -->
        <rule path="^/api/(post|comment)/\d+$" role="ROLE_USER"/>
    </config>
</srv:container>

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

// config/packages/security.php
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security) {
    $security->enableAuthenticatorManager(true);

    // ...
    $security->firewall('main')
    // ...
    ;

    // require ROLE_ADMIN for /admin*
    $security->accessControl()
        ->path('^/admin')
        ->roles(['ROLE_ADMIN']);

    // require ROLE_ADMIN or IS_AUTHENTICATED_FULLY for /admin*
    $security->accessControl()
        ->path('^/admin')
        ->roles(['ROLE_ADMIN', 'IS_AUTHENTICATED_FULLY']);

    // the 'path' value can be any valid regular expression
    // (this one will match URLs like /api/post/7298 and /api/comment/528491)
    $security->accessControl()
        ->path('^/api/(post|comment)/\d+$')
        ->roles(['ROLE_USER']);
};

1
2
3
4
5
6
7
8
9
10

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

    access_control:
        # matches /admin/users/*
        - { path: '^/admin/users', roles: ROLE_SUPER_ADMIN }

        # matches /admin/* except for anything matching the above rule
        - { path: '^/admin', roles: ROLE_ADMIN }

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

        <rule path="^/admin/users" role="ROLE_SUPER_ADMIN"/>
        <rule path="^/admin" role="ROLE_ADMIN"/>
    </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->accessControl()
        ->path('^/admin/users')
        ->roles(['ROLE_SUPER_ADMIN']);

    $security->accessControl()
        ->path('^/admin')
        ->roles(['ROLE_ADMIN']);
};

1
2
3
4
5
6
7
8
9
10

// src/Controller/AdminController.php
// ...

public function adminDashboard(): Response
{
    $this->denyAccessUnlessGranted('ROLE_ADMIN');

    // or add an optional message - seen by developers
    $this->denyAccessUnlessGranted('ROLE_ADMIN', null, 'User tried to access a page without having ROLE_ADMIN');
}

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

// src/Controller/AdminController.php
// ...

use Sensio\Bundle\FrameworkExtraBundle\Configuration\IsGranted;

/**
 * Require ROLE_ADMIN for all the actions of this controller
 */
#[IsGranted('ROLE_ADMIN')]
class AdminController extends AbstractController
{
    /**
     * Require ROLE_SUPER_ADMIN only for this action
     */
    #[IsGranted('ROLE_SUPER_ADMIN')]
    public function adminDashboard(): Response
    {
        // ...
    }
}

1
2
3

{% if is_granted('ROLE_ADMIN') %}
    <a href="...">Delete</a>
{% endif %}

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

// src/SalesReport/SalesReportManager.php

  // ...
  use Symfony\Component\Security\Core\Exception\AccessDeniedException;
+ use Symfony\Component\Security\Core\Security;

  class SalesReportManager
  {
+     private $security;

+     public function __construct(Security $security)
+     {
+         $this->security = $security;
+     }

      public function generateReport()
      {
          $salesData = [];

+         if ($this->security->isGranted('ROLE_SALES_ADMIN')) {
+             $salesData['top_secret_numbers'] = rand();
+         }

          // ...
      }

      // ...
  }

Allowing Unsecured Access (i.e. Anonymous Users)

When a visitor isn't yet logged in to your website, they are treated as "unauthenticated" and don't have any roles. This will block them from visiting your pages if you defined an access_control rule.

In the access_control configuration, you can use the PUBLIC_ACCESS security attribute to exclude some routes for unauthenticated access (e.g. the login page):

1
2
3
4
5
6
7
8
9
10

# config/packages/security.yaml
security:

    # ...
    access_control:
        # allow unauthenticated users to access the login form
        - { path: ^/admin/login, roles: PUBLIC_ACCESS }

        # but require authentication for all other admin routes
        - { path: ^/admin, roles: ROLE_ADMIN }

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 enable-authenticator-manager="true">
        <!-- ... -->

        <access-control>
            <!-- allow unauthenticated users to access the login form -->
            <rule path="^/admin/login" role="PUBLIC_ACCESS"/>

            <!-- but require authentication for all other admin routes -->
            <rule path="^/admin" role="ROLE_ADMIN"/>
        </access-control>
    </config>
</srv:container>

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

// config/packages/security.php
use Symfony\Component\Security\Core\Authorization\Voter\AuthenticatedVoter;
use Symfony\Config\SecurityConfig;

return static function (SecurityConfig $security) {
    $security->enableAuthenticatorManager(true);
    // ....

    // allow unauthenticated users to access the login form
    $security->accessControl()
        ->path('^/admin/login')
        ->roles([AuthenticatedVoter::PUBLIC_ACCESS])
    ;

    // but require authentication for all other admin routes
    $security->accessControl()
        ->path('^/admin')
        ->roles(['ROLE_ADMIN'])
    ;
};

Granting Anonymous Users Access in a Custom Voter

If you're using a custom voter, you can allow anonymous users access by checking if there is no user set on the token:

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

// src/Security/PostVoter.php
namespace App\Security;

// ...
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Authentication\User\UserInterface;
use Symfony\Component\Security\Core\Authorization\Voter\Voter;

class PostVoter extends Voter
{
    // ...

    protected function voteOnAttribute(string $attribute, $subject, TokenInterface $token): bool
    {
        // ...

        if (!$token->getUser() instanceof UserInterface) {
            // the user is not authenticated, e.g. only allow them to
            // see public posts
            return $subject->isPublic();
        }
    }
}

Setting Individual User Permissions

Most applications require more specific access rules. For instance, a user should be able to only edit their own comments on a blog. Voters allow you to write whatever business logic you need to determine access. Using these voters is similar to the role-based access checks implemented in the previous chapters. Read How to Use Voters to Check User Permissions to learn how to implement your own voter.

Checking to see if a User is Logged In (IS_AUTHENTICATED_FULLY)

If you only want to check if a user is logged in (you don't care about roles), you have the following two options.

Firstly, if you've given every user ROLE_USER, you can check for that role.

Secondly, you can use a special "attribute" in place of a role:

1
2
3
4
5
6
7
8

// ...

public function adminDashboard(): Response
{
    $this->denyAccessUnlessGranted('IS_AUTHENTICATED_FULLY');

    // ...
}

You can use IS_AUTHENTICATED_FULLY anywhere roles are used: like access_control or in Twig.

IS_AUTHENTICATED_FULLY isn't a role, but it kind of acts like one, and every user that has logged in will have this. Actually, there are some special attributes like this:

• IS_AUTHENTICATED_REMEMBERED: All logged in users have this, even if they are logged in because of a "remember me cookie". Even if you don't use the remember me functionality, you can use this to check if the user is logged in.
• IS_AUTHENTICATED_FULLY: This is similar to IS_AUTHENTICATED_REMEMBERED, but stronger. Users who are logged in only because of a "remember me cookie" will have IS_AUTHENTICATED_REMEMBERED but will not have IS_AUTHENTICATED_FULLY.
• IS_REMEMBERED: Only users authenticated using the remember me functionality, (i.e. a remember-me cookie).
• IS_IMPERSONATOR: When the current user is impersonating another user in this session, this attribute will match.

Comparing Users Manually with EquatableInterface

Or, if you need more control over the "compare users" process, make your User class implement EquatableInterface. Then, your isEqualTo() method will be called when comparing users instead of the core logic.

Authentication Events

CheckPassportEvent

Dispatched after the authenticator created the security passport. Listeners of this event do the actual authentication checks (like checking the passport, validating the CSRF token, etc.)

AuthenticationTokenCreatedEvent

Dispatched after the passport was validated and the authenticator created the security token (and user). This can be used in advanced use-cases where you need to modify the created token (e.g. for multi factor authentication).

AuthenticationSuccessEvent

Dispatched when authentication is nearing success. This is the last event that can make an authentication fail by throwing an AuthenticationException.

LoginSuccessEvent

Dispatched after authentication was fully successful. Listeners to this event can modify the response sent back to the user.

LoginFailureEvent

Dispatched after an AuthenticationException was thrown during authentication. Listeners to this event can modify the error response sent back to the user.

Other Events

LogoutEvent

Dispatched just before a user logs out of your application. See Security.

TokenDeauthenticatedEvent

Dispatched when a user is deauthenticated, for instance because the password was changed. See Security.

SwitchUserEvent

Dispatched after impersonation is completed. See How to Impersonate a User.

Authentication (Identifying/Logging in the User)

Authorization (Denying Access)