First words about the access tokens

Author: Spomky

security.rst

@@ -1174,6 +1174,15 @@ website.
 
 You can learn all about this authenticator in :doc:`/security/login_link`.
 
+Access Tokens
+~~~~~~~~~~~~~~
+
+Access Tokens are often used in API contexts.
+The user will receive a short-lived token from an authorization server
+which will authenticate them.
+
+You can learn all about this authenticator in :doc:`/security/access_token`.
+
 X.509 Client Certificates
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

security/access_token.rst

@@ -0,0 +1,148 @@
+.. index::
+   single: Security; Access Token
+
+How to use Access Token Authentication
+======================================
+
+Access tokens are commonly used in API contexts. The access token is is obtained
+through an authorization server (or similar) whose role is to verify the user identity
+and receive consent before the token is issued.
+
+Access Tokens can be of any kind: opaque strings, Json Web Tokens (JWT) or SAML2 (XML structures).
+
+Using the Access Token Authenticator
+----------------------------------
+
+This guide assumes you have setup security and have created a user object
+in your application. Follow :doc:`the main security guide </security>` if
+this is not yet the case.
+
+1) Configure the Access Token Authenticator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The access token authenticator can  be configured using three different options:
+
+* ``header_token``: the token is sent through the request header. Usually ``Authorization`` with the ``Bearer`` scheme.
+* ``query_token``: the token is part of the query string. Usually ``access_token``.
+* ``body_token``: the token is part of the request body during a POST request. Usually ``access_token``.
+
+You must configure a ``token_handler`` when enabling this authenticator.
+The token handler is a service that is able to load and verify the token (e.g. expiration, digital signature...)
+and return the associated user identifier.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            firewalls:
+                main:
+                    header_token:
+                        token_handler: App\Security\AccessTokenHandler
+
+2) Create your Access Token Handler
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now that the authenticator is able to check the access tokens, you must
+create your access token handler.
+
+This handler shall implement the interface
+:class:`Symfony\\Component\\Security\\Http\\Authenticator\\AccessTokenHandlerInterface`.
+In the following example, the handler will retrieve the token from a database
+using a fictive Doctrine repository.
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        // src/Security/AccessTokenHandler.php
+        namespace App\Controller;
+
+        use App\Repository\AccessTokenRepository;
+        use Symfony\Component\Security\Http\Authenticator\AccessTokenHandlerInterface;
+
+        class AccessTokenHandler implements AccessTokenHandlerInterface
+        {
+            public function __construct(private readonly AccessTokenRepository $repository)
+            {
+            }
+
+            public function getUserIdentifierFrom(string $token): string
+            {
+                $accessToken = $this->repository->findOneByValue($token);
+                if ($accessToken === null || !$accessToken->isValid()) {
+                    throw new BadCredentialsException('Invalid credentials.');
+                }
+
+                return $accessToken->getUserId();
+            }
+        }
+
+.. caution::
+
+    It is important to check the token is valid.
+    For instance, in the example we verify the token has not expired.
+    With self-contained access tokens such as JWT, the handler is required to
+    verify the digital signature and understand all claims,
+    especially `iat`, `nbf` and `exp`.
+
+Important Security Considerations
+---------------------------------
+
+Because of the security weaknesses associated with the URI method,
+including the high likelihood that the URL containing the access token will be logged,
+it **SHOULD NOT** be used unless it is impossible to transport the access token in the
+request header field or the HTTP request entity-body.
+
+The request body method **SHOULD NOT** be used except in application contexts
+where participating browsers do not have access to the "Authorization" request header field.
+
+In other words: ``query_token`` and ``body_token` authenticators are not recommended.
+
+Customizing the Success Handler
+-------------------------------
+
+Sometimes, the default success handling does not fit your use-case (e.g.
+when you need to generate and return additional response header parameters).
+To customize how the success handler behaves, create your own handler as a class that implements
+:class:`Symfony\\Component\\Security\\Http\\Authentication\\AuthenticationSuccessHandlerInterface`::
+
+    // src/Security/Authentication/AuthenticationSuccessHandler.php
+    namespace App\Security\Authentication;
+
+    use Symfony\Component\HttpFoundation\JsonResponse;
+    use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
+    use Symfony\Component\Security\Http\Authentication\AuthenticationSuccessHandlerInterface;
+
+    class AuthenticationSuccessHandler implements AuthenticationSuccessHandlerInterface
+    {
+        public function onAuthenticationSuccess(Request $request, TokenInterface $token): JsonResponse
+        {
+            $user = $token->getUser();
+            $userApiToken = $user->getApiToken();
+
+            return new JsonResponse(['apiToken' => $userApiToken]);
+        }
+    }
+
+Then, configure this service ID as the ``success_handler``:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            firewalls:
+                main:
+                    header_token:
+                        token_handler: App\Security\AccessTokenHandler
+                        success_handler: App\Security\Authentication\AuthenticationSuccessHandler
+
+.. tip::
+
+    If you want to customize the default failure handling, use the
+    ``failure_handler`` option and create a class that implements
+    :class:`Symfony\\Component\\Security\\Http\\Authentication\\AuthenticationFailureHandlerInterface`.