1) Configure the Login Link Authenticator¶

The login link authenticator is configured using the login_link option under the firewall. You must configure a check_route and signature_properties when enabling this authenticator:

The signature_properties are used to create a signed URL. This must contain at least one property of your User object that uniquely identifies this user (e.g. the user ID). Read more about this setting further down below.

The check_route must be an existing route and it will be used to generate the login link that will authenticate the user. You don’t need a controller (or it can be empty) because the login link authenticator will intercept requests to this route:

2) Generate the Login Link¶

Now that the authenticator is able to check the login links, you must create a page where a user can request a login link and log in to your website.

The login link can be generated using the Symfony\Component\Security\Http\LoginLink\LoginLinkHandlerInterface. The correct login link handler is autowired for you when type-hinting for this interface:

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

use App\Repository\UserRepository;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\Security\Http\LoginLink\LoginLinkHandlerInterface;

class SecurityController extends AbstractController
{
    /**
     * @Route("/login", name="login")
     */
    public function requestLoginLink(LoginLinkHandlerInterface $loginLinkHandler, UserRepository $userRepository, Request $request)
    {
        // check if login form is submitted
        if ($request->isMethod('POST')) {
            // load the user in some way (e.g. using the form input)
            $email = $request->request->get('email');
            $user = $userRepository->findOneBy(['email' => $email]);

            // create a login link for $user this returns an instance
            // of LoginLinkDetails
            $loginLinkDetails = $loginLinkHandler->createLoginLink($user);
            $loginLink = $loginLinkDetails->getUrl();

            // ... send the link and return a response (see next section)
        }

        // if it's not submitted, render the "login" form
        return $this->render('security/login.html.twig');
    }

    // ...
}

1
2
3
4
5
6
7
8
9

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

{% block body %}
<form action="{{ path('login') }}" method="POST">
    <input type="email" name="email">
    <button type="submit">Send Login Link</button>
</form>
{% endblock %}

In this controller, the user is submitting their e-mail address to the controller. Based on this property, the correct user is loaded and a login link is created using createLoginLink().

3) Send the Login Link to the User¶

Now the link is created, it needs to be send to the user. Anyone with the link is able to login as this user, so you need to make sure to send it to a known device of them (e.g. using e-mail or SMS).

You can send the link using any library or method. However the login link authenticator provides integration with the Notifier component. Use the special Symfony\Component\Security\Http\LoginLink\LoginLinkNotification to create a notification and send it to the user’s email address or phone number:

// src/Controller/SecurityController.php

// ...
use Symfony\Component\Notifier\NotifierInterface;
use Symfony\Component\Notifier\Recipient\Recipient;
use Symfony\Component\Security\Http\LoginLink\LoginLinkNotification;

class SecurityController extends AbstractController
{
    /**
     * @Route("/login", name="login")
     */
    public function requestLoginLink(NotifierInterface $notifier, LoginLinkHandlerInterface $loginLinkHandler, UserRepository $userRepository, Request $request)
    {
        if ($request->isMethod('POST')) {
            $email = $request->request->get('email');
            $user = $userRepository->findOneBy(['email' => $email]);

            $loginLinkDetails = $loginLinkHandler->createLoginLink($user);

            // create a notification based on the login link details
            $notification = new LoginLinkNotification(
                $loginLinkDetails,
                'Welcome to MY WEBSITE!' // email subject
            );
            // create a recipient for this user
            $recipient = new Recipient($user->getEmail());

            // send the notification to the user
            $notifier->send($notification, $recipient);

            // render a "Login link is sent!" page
            return $this->render('security/login_link_sent.html.twig');
        }

        return $this->render('security/login.html.twig');
    }

    // ...
}

1
2
3

$ composer require symfony/mailer symfony/notifier \
    symfony/twig-bundle twig/extra-bundle \
    twig/cssinliner-extra twig/inky-extra

This will send an email like this to the user:

// src/Notifier/CustomLoginLinkNotification
namespace App\Notifier;

use Symfony\Component\Security\Http\LoginLink\LoginLinkNotification;

class CustomLoginLinkNotification extends LoginLinkNotification
{
    public function asEmailMessage(EmailRecipientInterface $recipient, string $transport = null): ?EmailMessage
    {
        $emailMessage = parent::asEmailMessage($recipient, $transport);

        // get the NotificationEmail object and override the template
        $email = $emailMessage->getMessage();
        $email->htmlTemplate('emails/custom_login_link_email.html.twig');

        return $emailMessage;
    }
}

Limit Login Link Lifetime¶

It is important for login links to have a limited lifetime. This reduces the risk that someone can intercept the link and use it to login as somebody else. By default, Symfony defines a lifetime of 10 minutes (600 seconds). You can customize this using the lifetime option:

Invalidate Login Links¶

Symfony uses signed URLs to implement login links. The advantage of this is that valid links do not have to be stored in a database. The signed URLs allow Symfony to still invalidate already sent login links when important information changes (e.g. a user’s email address).

The signed URL contains 3 parameters:

expires

The UNIX timestamp when the link expires.

user

The value returned from $user->getUsername() for this user.

hash

A hash of expires, user and any configured signature properties. Whenever these change, the hash changes and previous login links are invalidated.

You can add more properties to the hash by using the signature_properties option:

The properties are fetched from the user object using the PropertyAccess component (e.g. using getEmail() or a public $email property in this example).

Configure a Maximum Use of a Link¶

It is a common characteristic of login links to limit the number of times it can be used. Symfony can support this by storing used login links in the cache. Enable this support by setting the max_uses option:

Make sure there is enough space left in the cache, otherwise invalid links can no longer be stored (and thus become valid again). Expired invalid links are automatically removed from the cache.

The cache pools are not cleared by the cache:clear command, but removing var/cache/ manually may remove the cache if the cache component is configured to store its cache in that location. Read the Cache guide for more information.

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

// ...
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;

class SecurityController extends AbstractController
{
    /**
     * @Route("/login_check", name="login_check")
     */
    public function check(Request $request)
    {
        // get the login link query parameters
        $expires = $request->query->get('expires');
        $username = $request->query->get('user');
        $hash = $request->query->get('hash');

        // and render a template with the button
        return $this->render('security/process_login_link.html.twig', [
            'expires' => $expires,
            'user' => $username,
            'hash' => $hash,
        ]);
    }
}

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

{# templates/security/process_login_link.html.twig #}
{% extends 'base.html.twig' %}

{% block body %}
    <h2>Hi! You are about to login to ...</h2>

    <!-- for instance, use a form with hidden fields to
         create the POST request --->
    <form action="{{ path('login_check') }}" method="POST">
        <input type="hidden" name="expires" value="{{ expires }}">
        <input type="hidden" name="user" value="{{ user }}">
        <input type="hidden" name="hash" value="{{ hash }}">

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