Page updated to reflect the last changes

Author: Spomky

security/access_token.rst

@@ -21,14 +21,8 @@ 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...)
+To use the access token authenticator, you must configure a ``token_handler``.
+The token handler is a service that is able to load and verify the access token (e.g. expiration, digital signature...)
 and return the associated user identifier.
 
 .. configuration-block::
@@ -42,16 +36,10 @@ and return the associated user identifier.
                     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.
+using a fictive repository.
 
 .. configuration-block::
 
@@ -101,13 +89,54 @@ where participating browsers do not have access to the "Authorization" request h
 
 In other words: ``query_token`` and ``body_token` authenticators are not recommended.
 
-Customizing the Authenticators
-------------------------------
+Customizing the Authenticator
+-----------------------------
+
+1) Access Token Extractors
+
+By default, the access token is read from the request header parameter ``Authorization`` with the scheme `Bearer``.
+You can change the behavior and send the access token through different ways.
+
+This authenticator provides services able to extract the access token as per the RFC6750:
+
+- ``security.access_token_extractor.header``: the token is sent through the request header. Usually ``Authorization`` with the ``Bearer`` scheme.
+- ``security.access_token_extractor.query_string``: the token is part of the query string. Usually ``access_token``.
+- ``security.access_token_extractor.request_body``: the token is part of the request body during a POST request. Usually ``access_token``.
+
+You can also create a custom extractor. The class shall implement the interface
+:class:`Symfony\\Component\\Security\\Http\\Authenticator\\AccessToken\\AccessTokenExtractorInterface`.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            firewalls:
+                main:
+                    header_token:
+                        token_handler: App\Security\AccessTokenHandler
+                        token_extractors: 'my_custom_access_token_extractor'
+
+It is possible to set multiple extractors.
+In this case, the order is important: the first in the list is called first.
 
+.. configuration-block::
 
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        security:
+            firewalls:
+                main:
+                    header_token:
+                        token_handler: App\Security\AccessTokenHandler
+                        token_extractors:
+                            - 'security.access_token_extractor.header'
+                            - 'security.access_token_extractor.request_body'
+                            - 'security.access_token_extractor.query_string'
 
-Customizing the Success Handler
--------------------------------
+2) 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).