API Token Authenticator

Keep on Learning!

If you liked what you've learned so far, dive in!
Subscribe to get access to this tutorial plus
video, code and script downloads.

Start your All-Access Pass
Buy just this tutorial for $12.00

With a Subscription, click any sentence in the script to jump to that part of the video!

Login Subscribe

Time to put some code in our ApiTokenAuthenticator! Woo! I'm going to use Postman to help make test API requests. The only thing better than using Postman is creating functional tests in your own app. But that's the topic for another tutorial.

Let's make a GET request to http://localhost:8000/api/account. Next, how should we send the API token? As a query parameter? As a header? Well, you can do whatever you want - but using a header is pretty standard. Great! And um... what should we call that header? Postman has a nice system to help configure common authentication types. Choose something called "Bearer token". I'll show you what that means in a minute.

But first, move over to your terminal: we need to find a valid API key! Run:

php bin/console doctrine:query:sql 'SELECT * FROM api_token'

Authorization: Bearer

Copy one of these long strings, move back to Postman and paste! To see what this Auth stuff does, hit "Preview Request".

Request headers were successfully updated.

Cool! Click back to "Headers". Ahh! This "Auth" section is just a shortcut to add a request header called Authorization. Hey! Go away tooltip! Anyways, the Authorization header is set to the word "Bearer", a space, and then our token.

Honestly, you can name this header whatever you want - like SEND-ME-YOUR-TOKEN, WHATS-THE-MAGIC-WORD or I-LIKE-DINOSAURS. The name Authorization is just a standard, yea, and I guess... it does sound a bit more professional than my other ideas. There's also nothing significant about that "Bearer" part. That's another standard that's commonly used when your token is what's known as a "Bearer token": a fancy term that means whoever "bears" this token - so, whoever "possesses" this token - can use it to authenticate, without needing to provide any other types of authentication, like a master key or a password. Most API tokens, also known as "access tokens" are "bearer" tokens. And this is a standard way of attaching them to a request.

supports()

Back to work! Open ApiTokenAuthenticator. Ok: this is our second authenticator, so it's time to use our existing knowledge to kick some security butt! For supports(), our authenticator should only become active if the request has an Authorization header whose value starts with the word "Bearer". No problem: return $request->headers->has('Authorization') to make sure that header is set and also check that 0 is the position inside $request->headers->get('Authorization') where the string Bearer and a space appears:

... lines 1 - 11
class ApiTokenAuthenticator extends AbstractGuardAuthenticator
{
public function supports(Request $request)
{
// look for header "Authorization: Bearer <token>"
return $request->headers->has('Authorization')
&& 0 === strpos($request->headers->get('Authorization'), 'Bearer ');
}
... lines 20 - 57
}

I know: weird-looking code. But it does exactly what we need! If the Authorization Bearer header isn't there, supports() will return false and no other methods will be called.

getCredentials()

Next: getCredentials(). Our job is to read the token string and return it. Start with $authorizationHeader = $request->headers->get('Authorization'):

... lines 1 - 11
class ApiTokenAuthenticator extends AbstractGuardAuthenticator
{
... lines 14 - 20
public function getCredentials(Request $request)
{
$authorizationHeader = $request->headers->get('Authorization');
... lines 24 - 26
}
... lines 28 - 57
}

But, instead of returning that whole value, skip the Bearer part. So, return a sub-string of $authorizationHeader where we start at the 7th character:

... lines 1 - 11
class ApiTokenAuthenticator extends AbstractGuardAuthenticator
{
... lines 14 - 20
public function getCredentials(Request $request)
{
$authorizationHeader = $request->headers->get('Authorization');
// skip beyond "Bearer "
return substr($authorizationHeader, 7);
}
... lines 28 - 57
}

Ok. Deep breath: let's see if this is working so far. In getUser(), dump($credentials) and die:

... lines 1 - 11
class ApiTokenAuthenticator extends AbstractGuardAuthenticator
{
... lines 14 - 28
public function getUser($credentials, UserProviderInterface $userProvider)
{
dump($credentials);die;
}
... lines 33 - 57
}

This should be the API token string. Oh, and notice that this is different than LoginFormAuthenticator: we returned an array from getCredentials() there:

... lines 1 - 19
class LoginFormAuthenticator extends AbstractFormLoginAuthenticator
{
... lines 22 - 43
public function getCredentials(Request $request)
{
$credentials = [
'email' => $request->request->get('email'),
'password' => $request->request->get('password'),
'csrf_token' => $request->request->get('_csrf_token'),
];
... lines 51 - 56
return $credentials;
}
... lines 59 - 87
}

But that's the beauty of the authenticators: you can return whatever you want from getCredentials(). The only thing we need is the token string... so, we just return that.

Try it! Find Postman and... send! Nice! I mean, it looks terrible, but go to Preview. Yes! There is our API token string.

getUser()

Next up: getUser(). First, we need to query for the ApiToken entity. At the top of this class, make an __construct function and give it an ApiTokenRepository $apiTokenRepo argument. I'll hit Alt+Enter to initialize that:

... lines 1 - 4
use App\Repository\ApiTokenRepository;
... lines 6 - 12
class ApiTokenAuthenticator extends AbstractGuardAuthenticator
{
private $apiTokenRepo;
public function __construct(ApiTokenRepository $apiTokenRepo)
{
$this->apiTokenRepo = $apiTokenRepo;
}
... lines 21 - 73
}

Then, back in getUser(), get that token: $token = $this->apiTokenRepo->findOneBy() to query where the token property is set to the $credentials string:

... lines 1 - 12
class ApiTokenAuthenticator extends AbstractGuardAuthenticator
{
... lines 15 - 36
public function getUser($credentials, UserProviderInterface $userProvider)
{
$token = $this->apiTokenRepo->findOneBy([
'token' => $credentials
]);
... lines 42 - 47
}
... lines 49 - 73
}

If we do not find an ApiToken, return null. That will make authentication fail. If we do find one, we need to return the User, not the token. So, return $token->getUser():

... lines 1 - 12
class ApiTokenAuthenticator extends AbstractGuardAuthenticator
{
... lines 15 - 36
public function getUser($credentials, UserProviderInterface $userProvider)
{
$token = $this->apiTokenRepo->findOneBy([
'token' => $credentials
]);
if (!$token) {
return;
}
return $token->getUser();
}
... lines 49 - 73
}

Finally, if you return a User object from getUser(), Symfony calls checkCredentials(). Let's dd('checking credentials') to see if we continue to be lucky:

... lines 1 - 12
class ApiTokenAuthenticator extends AbstractGuardAuthenticator
{
... lines 15 - 49
public function checkCredentials($credentials, UserInterface $user)
{
dd('checking credentials');
}
... lines 54 - 73
}

Move back over to Postman, Send and... yes! Checking credentials.

We're almost done! But before we handle success, I want to see what happens with a bad API key. And learn how we can send back the perfect error response.

Leave a comment!

  • 2020-04-30 Victor Bocharsky

    Hey Lex,

    We're talking about a completely new tutorial, like a separate one where would be covered this complex topic. Unfortunately, we don't have it yet. The only tutorials about testing we have are:

    - https://symfonycasts.com/sc...
    - https://symfonycasts.com/sc...

    We do cover functional tests there, but not API token auth.

    Cheers!

  • 2020-04-29 Lex Hartman

    Hi, big thanks for all the awesome vids! I was trying to create a functional test for the authentication. You say; "The only thing better than using Postman is creating functional tests in your own app. But that's the topic for another tutorial.". What tutorial are you referring to?

  • 2020-02-04 weaverryan

    Hey Niki!

    Unfortunately, not soon - it may be something we talk about in the Symfony 5 security tutorial, but that is months away. Fortunately, I've had this conversation with someone before ;). And it includes some pointers on how to make this happen: https://symfonycasts.com/sc...

    If you have any questions about that process, feel free to ask them here or there.

    Cheers!

  • 2020-02-02 Niki

    Will there be any tutorial about Two-Factor Authentication with sf4/sf5 soon?

  • 2019-11-11 Victor Bocharsky

    Hey Stephansav,

    to understand this line you need to understand how the strpos() function works. Here's the link to PHP docs about it: https://www.php.net/manual/... . So, this function returns the position of the substring we're looking for inside the given string. So, basically, if the Authorization header string contains "Bearer" subsctring in it - the strpos() function will return its position. Ans so, if the Authorization header *starts* with "Bearer" - it will return 0, i.e. 0 is the position where "Bearer" string is found in the Authorization header string. And then we just compare its position with 0.

    So, in short, if the "Bearer" string is a substring of the Authorization header and it's position starts with 0, i.e Authorization header literally start with "Bearer" string - then that check (0 === strpos($request->headers->get('Authorization'), 'Bearer ')) will return true.

    I hope it's clearer to you now.

    Cheers!

  • 2019-11-10 stephansav

    Hi,
    In the supports function of the class ApiTokenAuthenticator, there is this line which I don't really understand:
    0 === strpos($request->headers->get('Authorization'), 'Bearer ');
    Can you explain me please?

  • 2019-11-08 Lesley Fernandes Moreira

    Thanks, man! That saved my time debugging things.

  • 2019-08-16 Diego Aguiar

    Yep! And when you are ready to deploy to production, you can follow this guide to configure your web server and speed up your application
    https://symfony.com/doc/cur...

    Cheers!

  • 2019-08-16 Duilio Palacios

    As mentioned below, when using Apache it is necessary to execute composer require apache-pack to get a proper .htaccess file to support the Authorization header, otherwise it won't be set in the headers object and the authorisation will fail, of course.

  • 2019-06-11 Victor Bocharsky

    Hey Kamil,

    Hm, do you mean invalid bearer token was caused "could not get any response"? Are you using SSL from Symfony Client? Actually, below the "Could not get any response" error there's a few ideas what could cause it:

    Why this might have happened:
    - The server couldn't send a response: Ensure that the backend is working properly
    - Self-signed SSL certificates are being blocked: Fix this by turning off 'SSL certificate verification' in Settings > General
    - Proxy configured incorrectly: Ensure that proxy is configured correctly in Settings > Proxy
    - Request timeout: Change request timeout in Settings > General"

    I just double checked HTTPS URL by running the project with "symfony serve" command and it failed with the exact "Could not get any response" error. But after I turned on CA certs in config and specify path to it as "/Users/victor/.symfony/certs/rootCA.pem" - it works for me and I can send requests from Postman to the project HTTPS URL.

    I hope this helps!

    Cheers!

  • 2019-06-10 Kamil Kaślikowski

    It was first thing i have checked. I started web server and i have written correct url. I have response when i change barear token.

  • 2019-06-10 Victor Bocharsky

    Hey Kamil,

    Yes, I can :) It looks like you forgot to start the web server, or the host in your request URI is incorrect :) Please, double check it and make sure you can access that URI in the browser first.

    Cheers!

  • 2019-06-08 Kamil Kaślikowski

    Can you tell me why I have an error in postman like "could not get any response"?

  • 2019-03-12 Diego Aguiar

    Yep, that's correct. Unless the very first authenticator supports your request, then the next one won't be called.

  • 2019-03-12 Mike

    The same question came to my mind :) Then I realised that both authenticators 'support' method will get called before the controller logic is executed.
    So the APITokenAuthenticator will get called on every request (even for regular users, by example when they hit the front page) it seems.

  • 2019-03-01 Diego Aguiar

    Hey Cyril Lopez

    > 1. Since you have set the token property in ApiToken entity constructor, how is it not returning it instead of the value in the database?

    Because of Doctrine, Doctrine create your objects based on the data from the DB, that's why you fetch them through a repository

    > 2. Also, how does the ApiToken repository knows to pass the User entity to the ApiToken constructor?

    Because of the same reason :) That's just how Doctrine works. IIRC, when you fetch an object from the DB, Doctrine never executes your constructor

    Cheers!

  • 2019-03-01 Cyril Lopez

    $token = $this->apiTokenRepo->findOneBy([
    'token' => $credentials
    ]);

    Hi Ryan,
    We struggle with two things :

    1. Since you have set the token property in ApiToken entity constructor, how is it not returning it instead of the value in the database?
    2. Also, how does the ApiToken repository knows to pass the User entity to the ApiToken constructor?
    Thanks for the great screencasts!

  • 2018-12-18 Diego Aguiar

    Hey Usuri

    You can define multiple authenticators and for each its support method will be called, if it returns true, then that's the authenticator that should return a response object.

    Cheers!

  • 2018-12-18 Usuri

    Did I miss something? When symfony knows which "Security" class should be fired? Or both are fired and conditions are checking in both support methods?

  • 2018-10-26 Matt Johnson

    Hey, nifty!

  • 2018-10-26 Victor Bocharsky

    Hey Matt,

    Thanks for sharing it, though Symfony suggest a bit different rules:


    # Sets the HTTP_AUTHORIZATION header removed by Apache
    RewriteCond %{HTTP:Authorization} .
    RewriteRule ^ - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

    See https://github.com/symfony/... . Actually, you can require symfony/apache-pack to get a complete .htaccess file for Symfony applications.

    But, isn't it useful for HTTP Basic Auth only?

    Cheers!

  • 2018-10-26 Matt Johnson

    If using apache don't forget to add the following to your rewrite rules:


    RewriteCond %{HTTP:Authorization} ^(.*)
    RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]