Skip to content

Commit 88e824d

Browse files
authored
Page updated with the latest changes
1 parent c1f5e44 commit 88e824d

File tree

1 file changed

+72
-18
lines changed

1 file changed

+72
-18
lines changed

security/access_token.rst

Lines changed: 72 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -21,15 +21,9 @@ this is not yet the case.
2121
1) Configure the Access Token Authenticator
2222
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2323

24-
The access token authenticator can be configured using three different options:
25-
26-
* ``header_token``: the token is sent through the request header. Usually ``Authorization`` with the ``Bearer`` scheme.
27-
* ``query_token``: the token is part of the query string. Usually ``access_token``.
28-
* ``body_token``: the token is part of the request body during a POST request. Usually ``access_token``.
29-
30-
You must configure a ``token_handler`` when enabling this authenticator.
31-
The token handler is a service that is able to load and verify the token (e.g. expiration, digital signature...)
32-
and return the associated user identifier.
24+
The access token authenticator requires a ``token_handler``.
25+
The token handler is a service that is able to load and verify the token
26+
(e.g. expiration, digital signature...) and return the associated user identifier.
3327

3428
.. configuration-block::
3529

@@ -39,7 +33,7 @@ and return the associated user identifier.
3933
security:
4034
firewalls:
4135
main:
42-
header_token:
36+
access_token:
4337
token_handler: App\Security\AccessTokenHandler
4438
4539
2) Create your Access Token Handler
@@ -58,7 +52,7 @@ using a fictive Doctrine repository.
5852
.. code-block:: php
5953
6054
// src/Security/AccessTokenHandler.php
61-
namespace App\Controller;
55+
namespace App\Security;
6256
6357
use App\Repository\AccessTokenRepository;
6458
use Symfony\Component\Security\Http\Authenticator\AccessTokenHandlerInterface;
@@ -71,46 +65,106 @@ using a fictive Doctrine repository.
7165
7266
public function getUserIdentifierFrom(string $token): string
7367
{
68+
// The handler tries to find the access token.
7469
$accessToken = $this->repository->findOneByValue($token);
70+
71+
// If no access token is found or if it expired, the handler throws and exception.
7572
if ($accessToken === null || !$accessToken->isValid()) {
7673
throw new BadCredentialsException('Invalid credentials.');
7774
}
7875
76+
// The access token is valid, the handler returned the associated user ID.
7977
return $accessToken->getUserId();
8078
}
8179
}
8280
8381
.. caution::
8482

8583
It is important to check the token is valid.
86-
For instance, in the example we verify the token has not expired.
84+
For instance, in the example we call the method ``isValid()`` that should verify
85+
the token has not expired.
8786
With self-contained access tokens such as JWT, the handler is required to
8887
verify the digital signature and understand all claims,
8988
especially `iat`, `nbf` and `exp`.
9089

90+
3) Access Token Extractors
91+
~~~~~~~~~~~~~~~~~~~~~~~~~~
92+
93+
By default, this authenticator will try to extract the access token from the
94+
request header parameter ``Authorization``.
95+
You can change the token extractors depending on your needs.
96+
97+
Three extractors are provided. They fulfil with the RFC6750 sections 2.1 to 2.3.
98+
99+
* ``security.access_token_extractor.header``: extracted from the ``Authorization`` request header parameter
100+
* ``security.access_token_extractor.query_string``: extracted from the ``access_token`` query string
101+
* ``security.access_token_extractor.request_body``: extracted from the ``access_token`` request body
102+
103+
In the following example, we enable all extractors.
104+
105+
.. caution::
106+
Please note that the order is important: extractors are called recursively.
107+
108+
.. configuration-block::
109+
110+
.. code-block:: yaml
111+
112+
# config/packages/security.yaml
113+
security:
114+
firewalls:
115+
main:
116+
pattern: ^/
117+
access_token:
118+
token_handler: App\Security\AccessTokenHandler
119+
token_extractors:
120+
- security.access_token_extractor.header
121+
- security.access_token_extractor.query_string
122+
- security.access_token_extractor.request_body
123+
124+
91125
Important Security Considerations
92126
---------------------------------
93127

94128
Because of the security weaknesses associated with the URI method,
95129
including the high likelihood that the URL containing the access token will be logged,
96-
it **SHOULD NOT** be used unless it is impossible to transport the access token in the
130+
``security.access_token_extractor.query_string`` and ``security.access_token_extractor.request_body``
131+
**SHOULD NOT** be used unless it is impossible to transport the access token in the
97132
request header field or the HTTP request entity-body.
98133

99134
The request body method **SHOULD NOT** be used except in application contexts
100135
where participating browsers do not have access to the "Authorization" request header field.
101136

102-
In other words: ``query_token`` and ``body_token` authenticators are not recommended.
103-
104137
Customizing the Authenticators
105138
------------------------------
106139

140+
You can define a specific extractor by creating a service that implements the interface
141+
:class:``Symfony\Component\Security\Http\Authenticator\AccessToken\AccessTokenExtractorInterface``::.
142+
This interface has a unique method ``extractToken(Request $request): ?string`` and shall return the access token
143+
if any or ``null`` otherwise.
144+
145+
.. configuration-block::
146+
147+
.. code-block:: php
148+
149+
// src/Security/CustomExtractor.php
150+
namespace App\Security;
151+
152+
use Symfony\Component\Security\Http\Authenticator\AccessToken\AccessTokenExtractorInterface;
153+
154+
class CustomExtractor implements AccessTokenExtractorInterface
155+
{
156+
public function extractToken(Request $request): ?string
157+
{
158+
... // Extract the token from the request object or return null
159+
}
160+
}
107161
108162
109163
Customizing the Success Handler
110164
-------------------------------
111165

112-
Sometimes, the default success handling does not fit your use-case (e.g.
113-
when you need to generate and return additional response header parameters).
166+
Sometimes, the default success handling does not fit your use-case
167+
(e.g. when you need to generate and return additional response header parameters).
114168
To customize how the success handler behaves, create your own handler as a class that implements
115169
:class:`Symfony\\Component\\Security\\Http\\Authentication\\AuthenticationSuccessHandlerInterface`::
116170

@@ -143,7 +197,7 @@ Then, configure this service ID as the ``success_handler``:
143197
security:
144198
firewalls:
145199
main:
146-
header_token:
200+
access_token:
147201
token_handler: App\Security\AccessTokenHandler
148202
success_handler: App\Security\Authentication\AuthenticationSuccessHandler
149203

0 commit comments

Comments
 (0)