From 246b988d9d41718d668ed9fdde44ce8e28e91f7f Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 9 Oct 2017 16:11:11 +0200 Subject: [PATCH 1/2] Updated Guard article for the GuardAuthenticatorInterface deprecation --- security/guard_authentication.rst | 56 +++++++++++++++++++++---------- 1 file changed, 38 insertions(+), 18 deletions(-) diff --git a/security/guard_authentication.rst b/security/guard_authentication.rst index a857446c8e4..fba1c21b85b 100644 --- a/security/guard_authentication.rst +++ b/security/guard_authentication.rst @@ -146,9 +146,9 @@ on each request with their API token. Your job is to read this and find the asso user (if any). To create a custom authentication system, just create a class and make it implement -:class:`Symfony\\Component\\Security\\Guard\\GuardAuthenticatorInterface`. Or, extend +:class:`Symfony\\Component\\Security\\Guard\\AuthenticatorInterface`. Or, extend the simpler :class:`Symfony\\Component\\Security\\Guard\\AbstractGuardAuthenticator`. -This requires you to implement seven methods:: +This requires you to implement several methods:: // src/AppBundle/Security/TokenAuthenticator.php namespace AppBundle\Security; @@ -165,10 +165,19 @@ This requires you to implement seven methods:: class TokenAuthenticator extends AbstractGuardAuthenticator { /** - * Called on every request. Return whatever credentials you want to - * be passed to getUser(). Returning null will cause this authenticator + * Called on every request to decide if this authenticator should be + * used for the request. Returning false will cause this authenticator * to be skipped. */ + public function supports(Request $request) + { + return true; + } + + /** + * Called on every request. Return whatever credentials you want to + * be passed to getUser(). + */ public function getCredentials(Request $request) { if (!$token = $request->headers->get('X-AUTH-TOKEN')) { @@ -240,6 +249,10 @@ This requires you to implement seven methods:: } } +.. versionadded:: 3.4 + ``AuthenticatorInterface`` was introduced in Symfony 3.4. In previous Symfony + versions, authenticators needed to implement ``GuardAuthenticatorInterface``. + Nice work! Each method is explained below: :ref:`The Guard Authenticator Methods`. Step 2) Configure the Authenticator @@ -352,19 +365,27 @@ The Guard Authenticator Methods Each authenticator needs the following methods: +**supports(Request $request)** + This will be called on *every* request and your job is to decide if the + authenticator should be used for this request (return ``true``) or if it + should be skipped (return ``false``). + +.. versionadded:: 3.4 + The ``supports()`` method was introduced in Symfony 3.4. In previous Symfony + versions, the authenticator could be skipped returning ``null`` in the + ``getCredentials()`` method. + **getCredentials(Request $request)** This will be called on *every* request and your job is to read the token (or whatever your "authentication" information is) from the request and return it. - If you return ``null``, the rest of the authentication process is skipped. Otherwise, - ``getUser()`` will be called and the return value is passed as the first argument. + These credentials are later passed as the first argument ot ``getUser()``. **getUser($credentials, UserProviderInterface $userProvider)** - If ``getCredentials()`` returns a non-null value, then this method is called - and its return value is passed here as the ``$credentials`` argument. Your job - is to return an object that implements ``UserInterface``. If you do, then - ``checkCredentials()`` will be called. If you return ``null`` (or throw an - :ref:`AuthenticationException `) - authentication will fail. + The ``$credentials`` argument is the value returned by ``getCredentials()``. + Your job is to return an object that implements ``UserInterface``. If you do, + then ``checkCredentials()`` will be called. If you return ``null`` (or throw + an :ref:`AuthenticationException `) authentication + will fail. **checkCredentials($credentials, UserInterface $user)** If ``getUser()`` returns a User object, this method is called. Your job is to @@ -390,8 +411,7 @@ Each authenticator needs the following methods: **start(Request $request, AuthenticationException $authException = null)** This is called if the client accesses a URI/resource that requires authentication, - but no authentication details were sent (i.e. you returned ``null`` from - ``getCredentials()``). Your job is to return a + but no authentication details were sent. Your job is to return a :class:`Symfony\\Component\\HttpFoundation\\Response` object that helps the user authenticate (e.g. a 401 response that says "token is missing!"). @@ -400,9 +420,9 @@ Each authenticator needs the following methods: You will still need to active ``remember_me`` under your firewall for it to work. Since this is a stateless API, you do not want to support "remember me" functionality in this example. - + **createAuthenticatedToken(UserInterface $user, string $providerKey)** - If you are implementing the :class:`Symfony\\Component\\Security\\Guard\\GuardAuthenticatorInterface` + If you are implementing the :class:`Symfony\\Component\\Security\\Guard\\AuthenticatorInterface` instead of extending the :class:`Symfony\\Component\\Security\\Guard\\AbstractGuardAuthenticator` class, you have to implement this method. It will be called after a successful authentication to create and return the token @@ -502,11 +522,11 @@ and add the following logic:: public function getCredentials(Request $request) { $csrfToken = $request->request->get('_csrf_token'); - + if (false === $this->csrfTokenManager->isTokenValid(new CsrfToken('authenticate', $csrfToken))) { throw new InvalidCsrfTokenException('Invalid CSRF token.'); } - + // ... all your normal logic } From f1131f36d0a7d04f6db35eb1349ad80eec05d10e Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 10 Oct 2017 10:59:37 +0200 Subject: [PATCH 2/2] Indented the versionadded directive --- security/guard_authentication.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/security/guard_authentication.rst b/security/guard_authentication.rst index fba1c21b85b..a4fe034a735 100644 --- a/security/guard_authentication.rst +++ b/security/guard_authentication.rst @@ -370,10 +370,10 @@ Each authenticator needs the following methods: authenticator should be used for this request (return ``true``) or if it should be skipped (return ``false``). -.. versionadded:: 3.4 - The ``supports()`` method was introduced in Symfony 3.4. In previous Symfony - versions, the authenticator could be skipped returning ``null`` in the - ``getCredentials()`` method. + .. versionadded:: 3.4 + The ``supports()`` method was introduced in Symfony 3.4. In previous Symfony + versions, the authenticator could be skipped returning ``null`` in the + ``getCredentials()`` method. **getCredentials(Request $request)** This will be called on *every* request and your job is to read the token (or