From b63ccf7639de34e379cf82b6b980d07a9467ae86 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arnaud=20Fr=C3=A9zet?= <arnaud@les-tilleuls.coop>
Date: Wed, 21 Sep 2022 11:55:04 +0200
Subject: [PATCH] [Security] Add documentation for programmatic login

---
 security.rst | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/security.rst b/security.rst
index c70b01d8652..e098fa864e1 100644
--- a/security.rst
+++ b/security.rst
@@ -1599,6 +1599,52 @@ and set the ``limiter`` option to its service ID:
             ;
         };
 
+Login Programmatically
+----------------------
+
+.. versionadded:: 6.2
+
+    The :class:`Symfony\Bundle\SecurityBundle\Security\Security <Symfony\\Bundle\\SecurityBundle\\Security\\Security>`
+    class was introduced in Symfony 6.2. Prior to 6.2, it was called
+    ``Symfony\Component\Security\Core\Security``.
+
+.. versionadded:: 6.2
+
+    The :method:`Symfony\\Bundle\\SecurityBundle\\Security\\Security::login`
+    method was introduced in Symfony 6.2.
+
+You can log in a user programmatically using the `login()` method of the
+:class:`Symfony\\Bundle\\SecurityBundle\\Security\\Security` helper::
+
+    // src/Controller/SecurityController.php
+    namespace App\Controller\SecurityController;
+
+    use App\Security\Authenticator\ExampleAuthenticator;
+    use Symfony\Bundle\SecurityBundle\Security\Security;
+
+    class SecurityController
+    {
+        public function someAction(Security $security): Response
+        {
+            // get the user to be authenticated
+            $user = ...;
+
+            // log the user in on the current firewall
+            $this->security->login($user);
+
+            // if the firewall has more than one authenticator, you must pass it explicitly
+            // by using the name of built-in authenticators...
+            $this->security->login($user, 'form_login');
+            // ...or the service id of custom authenticators
+            $this->security->login($user, ExampleAuthenticator::class);
+
+            // you can also log in on a different firewall
+            $this->security->login($user, 'form_login', 'other_firewall');
+
+            // ... redirect the user to its account page for instance
+        }
+    }
+
 .. _security-logging-out:
 
 Logging Out