[Security] Add documentation for programmatic login

Author: johnkrovitch

security.rst

@@ -656,6 +656,95 @@ many other authenticators:
 
 .. _security-form-login:
 
+Login Programmatically
+----------------------
+
+.. versionadded:: 6.2
+
+    The :class:`Symfony\\Bundle\\SecurityBundle\\Security\\Security` class
+    was introduced in Symfony 6.2.
+    The :method:`Symfony\\Bundle\\SecurityBundle\\Security\\Security::login` method
+    was introduced in Symfony 6.2.
+
+You can log in an user programmatically using the `login()` method of the
+:class:`Symfony\\Bundle\\SecurityBundle\\Security\\Security` helper::
+
+
+use Symfony\Bundle\SecurityBundle\Security\Security;
+
+class ExampleController
+{
+    public function __construct(private Security $security)
+    {}
+
+    public function someMethod(): Response
+    {
+        $user = ... // Get the user to be authenticated
+
+        $this->security->login($user);
+
+        // Redirect the user to its account page for instance
+        // ...
+    }
+}
+
+The previous example only works if you have only one authenticator configured on the current firewall so if you have more than one authenticator, you need to specify which authenticator should be used.
+If the firewall is not explicitly passed, the method will
+be retrieved from the request. If the current request is not under any firewall an
+`Symfony\\Component\\Security\\Core\\Exception\\LogicException` exception will be thrown.
+
+You can also pass the authenticator on which the user will
+be authenticated against. For built-in authenticators, you can pass an authenticator name like ``form_login``,
+``http_basic``... For custom authenticators, you can pass the service id of the authenticator
+(i.e. `App\\Security\\Authenticator\\ExampleAuthenticator`)::
+
+use App\Security\Authenticator\ExampleAuthenticator;
+use Symfony\Bundle\SecurityBundle\Security\Security;
+
+class ExampleController
+{
+    public function __construct(private Security $security)
+    {
+    }
+
+    public function someMethod(): Response
+    {
+        $user = ... // Get the user to be authenticated
+
+        // You can use the authenticator name for built-in authenticator (like "form_login", "http_basic"...)
+        $this->security->login($user, 'form_login');
+
+        // Or the service id of your custom authenticator
+        $this->security->login($user, ExampleAuthenticator::class);
+
+        // Redirect the user to its account page for instance
+        // ...
+    }
+}
+
+Previous examples retrieves the firewall name according to the current request. But you can also pass a firewall
+name to be authenticated against::
+
+use App\Security\Authenticator\ExampleAuthenticator;
+use Symfony\Bundle\SecurityBundle\Security\Security;
+
+class ExampleController
+{
+    public function __construct(private Security $security)
+    {
+    }
+
+    public function someMethod(): Response
+    {
+        $user = ... // Get the user to be authenticated
+
+        $this->security->login($user, 'form_login', 'another_firewall');
+
+        // Redirect the user to its account page for instance
+        // ...
+    }
+}
+
 Form Login
 ~~~~~~~~~~