Page updated with the latest changes

Author: Spomky

security/access_token.rst

@@ -21,15 +21,9 @@ 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.
+The access token authenticator requires a ``token_handler``.
+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::
 
@@ -39,7 +33,7 @@ and return the associated user identifier.
         security:
             firewalls:
                 main:
-                    header_token:
+                    access_token:
                         token_handler: App\Security\AccessTokenHandler
 
 2) Create your Access Token Handler
@@ -58,7 +52,7 @@ using a fictive Doctrine repository.
     .. code-block:: php
 
         // src/Security/AccessTokenHandler.php
-        namespace App\Controller;
+        namespace App\Security;
 
         use App\Repository\AccessTokenRepository;
         use Symfony\Component\Security\Http\Authenticator\AccessTokenHandlerInterface;
@@ -71,46 +65,106 @@ using a fictive Doctrine repository.
 
             public function getUserIdentifierFrom(string $token): string
             {
+                // The handler tries to find the access token.
                 $accessToken = $this->repository->findOneByValue($token);
+
+                // If no access token is found or if it expired, the handler throws and exception.
                 if ($accessToken === null || !$accessToken->isValid()) {
                     throw new BadCredentialsException('Invalid credentials.');
                 }
 
+                // The access token is valid, the handler returned the associated user ID.
                 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.
+    For instance, in the example we call the method ``isValid()`` that should 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`.
 
+3) Access Token Extractors
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, this authenticator will try to extract the access token from the
+request header parameter ``Authorization``.
+You can change the token extractors depending on your needs.
+
+Three extractors are provided. They fulfil with the RFC6750 sections 2.1 to 2.3.
+
+* ``security.access_token_extractor.header``: extracted from the ``Authorization`` request header parameter
+* ``security.access_token_extractor.query_string``: extracted from the ``access_token`` query string
+* ``security.access_token_extractor.request_body``: extracted from the ``access_token`` request body
+
+In the following example, we enable all extractors.
+
+.. caution::
+    Please note that the order is important: extractors are called recursively.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            firewalls:
+                main:
+                    pattern: ^/
+                    access_token:
+                        token_handler: App\Security\AccessTokenHandler
+                        token_extractors:
+                            - security.access_token_extractor.header
+                            - security.access_token_extractor.query_string
+                            - security.access_token_extractor.request_body
+
+
 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
+``security.access_token_extractor.query_string`` and ``security.access_token_extractor.request_body``
+**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 Authenticators
 ------------------------------
 
+You can define a specific extractor by creating a service that implements the interface
+:class:``Symfony\Component\Security\Http\Authenticator\AccessToken\AccessTokenExtractorInterface``::.
+This interface has a unique method ``extractToken(Request $request): ?string`` and shall return the access token
+if any or ``null`` otherwise.
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        // src/Security/CustomExtractor.php
+        namespace App\Security;
+
+        use Symfony\Component\Security\Http\Authenticator\AccessToken\AccessTokenExtractorInterface;
+
+        class CustomExtractor implements AccessTokenExtractorInterface
+        {
+            public function extractToken(Request $request): ?string
+            {
+                ... // Extract the token from the request object or return null
+            }
+        }
 
 
 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).
+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`::
 
@@ -143,7 +197,7 @@ Then, configure this service ID as the ``success_handler``:
         security:
             firewalls:
                 main:
-                    header_token:
+                    access_token:
                         token_handler: App\Security\AccessTokenHandler
                         success_handler: App\Security\Authentication\AuthenticationSuccessHandler