Skip to content

Commit 26e89cc

Browse files
committed
minor #20090 [Security] Authenticator methods description (smnandre)
This PR was submitted for the 7.1 branch but it was squashed and merged into the 6.4 branch instead. Discussion ---------- [Security] Authenticator methods description At first i just wanted to reword this sentence i found missleading.. in the [Custom Authenticator](https://symfony.com/doc/current/security/custom_authenticator.html) page. > If ``null`` is returned, the request continues like normal (i.e. the controller matching the login route is called). I think it should be: ```diff - (i.e. the controller matching the login route is called) + (i.e. the controller matching the current route is called) ``` Because it _can_ be the login route for _some_ Authenticators, but it's not for stateless requests, Header tokens, remember me... I then realize the "if / if" was the reason I found things a bit unclear at first sight. ``` onAuthenticationSuccess(Request $request, ...) If the user is authenticated, (...) If ``null`` is returned, (...) ``` I read this as some sort of "if / else" ... but the first "if" englobes the whole paragraph (it's true again in the second one). So i tried to rewrite a bit (using the docblocks from the [AuthenticatorInterface](https://github.com/symfony/symfony/blob/7.2/src/Symfony/Component/Security/Http/Authenticator/AuthenticatorInterface.php) as inspiration) Commits ------- 236e419 [Security] Authenticator methods description
2 parents 36bef93 + 236e419 commit 26e89cc

File tree

1 file changed

+15
-12
lines changed

1 file changed

+15
-12
lines changed

security/custom_authenticator.rst

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -153,22 +153,25 @@ or there was something wrong (e.g. incorrect password). The authenticator
153153
can define what happens in these cases:
154154

155155
``onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewallName): ?Response``
156-
If the user is authenticated, this method is called with the
157-
authenticated ``$token``. This method can return a response (e.g.
158-
redirect the user to some page).
156+
If authentication is successful, this method is called with the
157+
authenticated ``$token``.
159158

160-
If ``null`` is returned, the request continues like normal (i.e. the
161-
controller matching the login route is called). This is useful for API
162-
routes where each route is protected by an API key header.
159+
This method can return a response (e.g. redirect the user to some page).
160+
161+
If ``null`` is returned, the current request will continue (and the
162+
user will be authenticated). This is useful for API routes where each
163+
route is protected by an API key header.
163164

164165
``onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response``
165-
If an ``AuthenticationException`` is thrown during authentication, the
166-
process fails and this method is called. This method can return a
167-
response (e.g. to return a 401 Unauthorized response in API routes).
166+
If authentication failed (e. g. wrong username password), this method
167+
is called with the ``AuthenticationException`` thrown.
168+
169+
This method can return a response (e.g. send a 401 Unauthorized in API
170+
routes).
168171

169-
If ``null`` is returned, the request continues like normal. This is
170-
useful for e.g. login forms, where the login controller is run again
171-
with the login errors.
172+
If ``null`` is returned, the request continues (but the user will **not**
173+
be authenticated). This is useful for login forms, where the login
174+
controller is run again with the login errors.
172175

173176
If you're using :ref:`login throttling <security-login-throttling>`,
174177
you can check if ``$exception`` is an instance of

0 commit comments

Comments
 (0)