Chapters

37 Chapters | 3:43:31 |

01

API Docs on Production?

8:22
02

API Tokens? Session Cookies?

8:07
03

API Login Form with json_login

5:36
04

Handling Authentication Errors

3:47
05

On Authentication Success

6:03
06

Logout & Passing API Data to JavaScript

5:45
07

Passing Values to Stimulus

4:32
08

Token Types & The ApiToken Entity

5:59
09

Generating the API Token & Fixtures

5:58
10

Access Token Authenticator

8:56
11

Customizing the OpenAPI Docs

7:31
12

API Token Scopes

5:51
13

Deny Access with The "security" Option

7:11
14

Bootstrapping a Killer Test System

8:18
15

JSON Test Assertions & Seeding the Database

3:41
16

Advanced & Flexible JSON Test Assertions

4:04
17

Testing Authentication

4:59
18

Customizing Browser Globally

3:50
19

Testing Token Authentication

3:24
20

New PUT Behavior

4:46
21

Only Allow Owners to Edit

7:49
22

Allow Admin Users to Edit any Treasure

4:11
23

Security Voter

6:13
24

Conditional Fields by User: ApiProperty

5:13
25

User Test + Plain Password

4:21
26

State Processors: Hashing the User Password

6:55
27

Validation Groups & Patch Formats

8:01
28

Dynamic Groups: Context Builder

8:26
29

Custom Normalizer

5:08
30

Normalizer Decoration & "Normalizer Aware"

6:29
31

Totally Custom Fields

3:24
32

Custom Validator

7:58
33

Validating how Values Change

8:30
34

Auto Setting the "owner"

4:19
35

Query Extension: Auto-Filter a Collection

6:15
36

404 On Unpublished Items

8:00
37

Filtering Relation Collection

5:39

> APIs > API Platform 3 Part 2: Security for your Treasures

Buy Access to Course

08.

Token Types & The ApiToken Entity

Autoplay

Previous Chapter

Next Chapter

Okay, so what if you need to allow programmatic access to your API?

The Types of Access Tokens

When you talk to an API via code, you send an API token, commonly known as an access token:

fetch('/api/kittens', {
    headers: {
        'Authorization': 'Bearer THE-ACCESS-TOKEN',
    }
});

Exactly how you get that token will vary. But there are two main cases.

First, as a user on the site, like a dragon, you want to generate an API token so that you can personally use it in a script you're writing. This is like a GitHub personal access token. These are literally created via a web interface. We're going to show this.

The second main use case is when a third party wants to make requests to your API on behalf of a user of your system. Like some new site called DragonTreasureOrganizer.com wants to be able to make an API request to our API on behalf of some of our users - like it will fetch the treasure's for a user and display them artfully on their site. In this situation, instead of our users generating tokens manually and then... like... entering them into that site, you'll offer OAuth. OAuth is basically a mechanism for normal users to securely give access tokens for their account to a third party. And so, your site, or somewhere in your infrastructure you'll have an OAuth server.

That's beyond the scope of this tutorial. But the important thing is that after OAuth is done, the API client wll end up with, you guessed it, an API token! So no matter which journey you're in, if you're doing programmatic access, your API users will end up with an access token. And then your job will be to read and understand that. We'll do exactly that.

JWT vs Database Storage?

So as I mentioned, we're going to show a system where we allow users to generate their own access tokens. So how do we do that? Again, there are two main ways. Death by choices!

The first is to generate something called a JSON Web Token or JWT. The cool thing about JWTs are that no database storage is needed. They're special strings that actually contain info inside of them. For example, you could create a JWT string that includes the user id and some scopes.

One downside of JWTs are that there's no easy way to "log out"... because there's no out-of-the-box way to invalidate JWTs. You give them an expiration when you create them... but then they're valid until then... no matter what, unless you add some extra complexity... which kinda defeats the purpose.

JWT's are trendy, popular and fun! But... you may not need them. They're awesome when you have a single sign-on system because, if that JWT is used to authenticate with multiple systems or APIs, each API can validate the JWT all on their own: without needing to make an API request to a central authentication system.

So you might end up using JWTs and there's a great bundle for them called LexikJWTAuthenticationBundle. JWT's are also the type of access token that OpenID gives you in the end.

Instead of JWTs, the second main option is dead simple: generate a random token string and store it in the database. This also allows you to invalidate access tokens by... just deleting them! This is what we'll do.

Generating the Entity

So let's get to work. To store API tokens, we need a new entity! Find your terminal and run:

php ./bin/console make:entity

And let's call it ApiToken. Say no to making this an API resource. In theory, you could allow users to authenticate via a login form or HTTP basic and then send a POST request to create API tokens if you want to... but we won't.

Add an ownedBy property. This is going to be a ManyToOne to User and not nullable. And I'll say "yes" to the inverse. So the idea is that every User can have many API tokens. When an API token is used, we want to know which User it's related to. We'll use that during authentication. Calling the property apiTokens is fine and say no to orphan removal. Next property: expiresAt, make that a datetime_immutable and I'll say yes to nullable. Maybe we allow tokens to never expire by leaving this field blank. Next up is token, which will be a string. I'm going to set the length to 68 - we'll see why in a minute - not nullable. And finally, add a scopes property as a json type. This is going to be kind of cool: we'll store an array of "permissions" that this API token should have. Say, not nullable on that one as well. Hit enter to finish.

All right, spin over to your editor. No surprises: that created an ApiToken entity... and there's nothing very interesting inside of it:

            Copy Code

                            Show All Lines

                        82 lines
            |
            src/Entity/ApiToken.php
        
                Show Lines

                                                    // ... lines 1 - 2
                            
            namespace App\Entity;
        
            use App\Repository\ApiTokenRepository;
        
            use Doctrine\ORM\Mapping as ORM;
        
            #[ORM\Entity(repositoryClass: ApiTokenRepository::class)]
        
            class ApiToken
        
            {
        
                #[ORM\Id]
        
                #[ORM\GeneratedValue]
        
                #[ORM\Column]
        
                private ?int $id = null;
        
                #[ORM\ManyToOne(inversedBy: 'apiTokens')]
        
                #[ORM\JoinColumn(nullable: false)]
        
                private ?User $ownedBy = null;
        
                #[ORM\Column(nullable: true)]
        
                private ?\DateTimeImmutable $expiresAt = null;
        
                #[ORM\Column(length: 68)]
        
                private string $token = null;
        
                #[ORM\Column]
        
                private array $scopes = [];
        
                Show Lines

                                                    // ... lines 28 - 80
                            
            }

So let's go over and make the migration for it:

symfony console make:migration

Spin over and peek at that file to make sure it looks good. Yup! It creates the api_token table:

            Copy Code

                            Show All Lines

                        39 lines
            |
            migrations/Version20230209183006.php
        
                Show Lines

                                                    // ... lines 1 - 12
                            
            final class Version20230209183006 extends AbstractMigration
        
            {
        
                public function getDescription(): string
        
                {
        
                    return '';
        
                }
        
                public function up(Schema $schema): void
        
                {
        
                    // this up() migration is auto-generated, please modify it to your needs
        
                    $this->addSql('CREATE SEQUENCE api_token_id_seq INCREMENT BY 1 MINVALUE 1 START 1');
        
                    $this->addSql('CREATE TABLE api_token (id INT NOT NULL, owned_by_id INT NOT NULL, expires_at TIMESTAMP(0) WITHOUT TIME ZONE DEFAULT NULL, token VARCHAR(68) NOT NULL, scopes JSON NOT NULL, PRIMARY KEY(id))');
        
                    $this->addSql('CREATE INDEX IDX_7BA2F5EB5E70BCD7 ON api_token (owned_by_id)');
        
                    $this->addSql('COMMENT ON COLUMN api_token.expires_at IS \'(DC2Type:datetime_immutable)\'');
        
                    $this->addSql('ALTER TABLE api_token ADD CONSTRAINT FK_7BA2F5EB5E70BCD7 FOREIGN KEY (owned_by_id) REFERENCES "user" (id) NOT DEFERRABLE INITIALLY IMMEDIATE');
        
                }
        
                public function down(Schema $schema): void
        
                {
        
                    // this down() migration is auto-generated, please modify it to your needs
        
                    $this->addSql('CREATE SCHEMA public');
        
                    $this->addSql('DROP SEQUENCE api_token_id_seq CASCADE');
        
                    $this->addSql('ALTER TABLE api_token DROP CONSTRAINT FK_7BA2F5EB5E70BCD7');
        
                    $this->addSql('DROP TABLE api_token');
        
                }
        
            }

Run that with:

symfony console doctrine:migrations:migrate

And... awesome! Next: let's add a way to generate the random token string. Then, we'll talk about scopes and load up our fixtures with some API tokens.

12 Comments

Sort By

MatthiasN 1 year ago edited HIGHLIGHTED

I understand that one can always argue that things here are meant as examples. But I suppose that people actually implement things as you show here. The problem is that this way of storing API tokens is basically the same as storing passwords in clear text.

While this is an easy solution for demonstration, I strongly suggest to not do it this way on a production system.

It would be better to generate an access token consisting of two parts:

An identifier (either a random string to identify the user or maybe simply the token ID)
A random string (secret) that is hashed using the password hasher.

You would then need to store that hashed secret in the token entity as well of course.

For example, connect the parts with a dot so that it is easy to parse the token.
You can then fetch the token from the database using the identifier and do a „password verification“ using the secret.

I think it is not too complicated to add this. But way more secure.

Of course you need to tell the user that they must immediately save the token somewhere because you can not show it to the user again for security (and because you don’t know the secret in clear text anymore). But I saw this already on other services. So it should be fine.

Or maybe use something like a url signer (which is probably faster).
But however.. do not save API tokens in clear text.

1 | Reply |

weaverryan SFCASTS MatthiasN 1 year ago edited

Hey @MatthiasN!

I think this is really good advice. My intention was to show people that "you can just store tokens in the database". And while that's true (just like how you can "store passwords in a database"), in both cases it shouldn't mean storing in plaintext. So yes, this is definitely a better idea.

Anyway, thank you for posting this - good advice! I'll also add a note to the tutorial about it.

Oh, and let me add some more technical details here to help people, building on what you said:

It would be better to generate an access token consisting of two parts:

An identifier (either a random string to identify the user or maybe simply the token ID)

A random string (secret) that is hashed using the password hasher.

So, for example, you'd generate 2 random strings, separated by a .. This full string would be the API key that you show to the user.
But then, you store the first part (the "locator" or "identifier") in the database on a locator key of ApiToken. Then you store the second part (the secret) on another property of ApiToken - but HASH it first. For example, here is how we generate the random locator and hash the secret in the ResetPasswordBundle - https://github.com/SymfonyCasts/reset-password-bundle/blob/main/src/Generator/ResetPasswordTokenGenerator.php#L52-L65

Then, when verify if a token is valid, you split the token on . to get the first and second part. You then query for the ApiToken via the first part (the locator). If found, you has the 2nd part that was just sent you to you and see if it equals the hashed secret on the ApiToken you just found using hash_equals - e.g. https://github.com/SymfonyCasts/reset-password-bundle/blob/3e0bb051a514459a3c63a5064be40208e4f34783/src/ResetPasswordHelper.php#L126

If anyone has any questions, let me know :)

Cheers!

4 | Reply |

Marko 1 year ago edited

Hello!

Is it possible to have 2 types of tokens in the same app, in API Platform 3 :

a jwt token for the users: this is a 'user specific' token. A user gets a jwt token from the server after successful authentication with his email and password.
an 'api token' that would be used by some cron jobs. This api token would be a way to authenticate the cron job. This token would be a 'company' specific token, not a user token, as the cron job is run for a company not for a user. The api token would be either in the URL of the end point (a string), either (better) in the headers of the request run by the cron job. And basically the api token would not change over time: it is a string, specific to a company, and it never expires, so no need for any refresh token.

So can we have simultaneously 2 differents mechanisms of authentication in the same app : classical jwt/refresh token for the users and api tokens for cron jobs (one api token per company) ?

Thanks!

| Reply |

weaverryan SFCASTS Marko 1 year ago

Hey @Marko!

Sure, I think you could definitely do this :). The easy part is creating the 2 tokens. You can make a JWT after the user authenticates successfully. And you could, for example, add an apiToken property to some Company entity and allow an admin for a Company to see this in some area on your site (where they could then copy and paste this for their CRON jobs).

The trickier part is consuming the tokens, well, maybe not SO tricky I hope :). You could have one authenticator that handles the JWT. This is your normal situation. Then, you could create a 2nd custom authenticator that handles your company token. If these tokens are sent in different ways (e.g. Authorization header for JWT vs some other header for company token), that'll make your job a little easier because each authenticator can figure out "is this a token I should authenticate or is it the other type?". But you could also accomplish this by giving each token some prefix - e.g. company_ - and using that.

Anyway, I think the truly tricky part is this: when using a JWT, you are authenticating as a User. So, a User object is what you would return from your authenticator... and then anywhere in your code where you say $this->getUser(), it would be a User object. But for the company token, your authenticator would return a Company, and when you use $this->getUser() in your code, that will return a Company object. It's THAT difference that could cause some confusion in your code.

I can see two general ideas for solving this:

1) If the company token is only meant to be used for a few specific endpoints, then I might put those few endpoints under their own Symfony firewall. Then, in those endpoints, just be sure that if you're ever referencing the currently authenticated "user", that you know it's the Company.

2) Code carefully :). If you need to be able to support both a User or a Company across your entire application, then be sure to create smart security rules that do no depend on the specific User / Company object. I can give more tips about this if you are going this route and have some questions about how to do some specific things.

Let me know if this helps!

Cheers!

1 | Reply |

Marko weaverryan 1 year ago

Hello! Thanks a lot for your answer. One more question : do you confirm that Company should implement User Interface, as a authenticated 'user'? Or not. Thanks again!

| Reply |

weaverryan SFCASTS Marko 1 year ago

Yes it should!

1 | Reply |

MildDisaster 1 year ago

I'm curious in this example, why you have potentially one user - many tokens relationship?
Wouldn't one user - one token suffice ?

| Reply |

Victor SFCASTS MildDisaster 1 year ago edited

Hey @MildDisaster ,

That's how GitHub access tokens, you can create many tokens on GitHub for your account. First of all, you can create different tokens with different scopes, like some tokens may have access to the private repos while others - only public ones. That's the most common and flexible structure I think :) Moreover, you can use one token e.g. for Composer and another token for your website that sends API requests to GitHub. And it's convenient this way, as you can e.g. remove that second token but the first one will still work.

But of course it depends on your personal use case, and if you're happy with OneToOne relation - go for it, there's nothing wrong with it, just some limitations I mentioned above :)

Cheers!

1 | Reply |

MildDisaster Victor 1 year ago edited

I think I understand. So the relationship is more (but not exclusively) between tokens and apps ( that a user will use to access api with ) ?

What is the preferred way to handle tokens once an associated account is changed, ie (password recovered) ?

Should one invalidate existing tokens, or just let them be ?

I noticed in the symfonycasts github there are projects for account registration and password recovery. Without double checking, don't think there was mention of token cleanup in them.

Thanks !

| Reply |

Victor SFCASTS MildDisaster 1 year ago edited

Hey @MildDisaster ,

I think I understand. So the relationship is more (but not exclusively) between tokens and apps ( that a user will use to access api with ) ?

Mostly yes, I suppose, but once again, it depends on your specific use case. But from my experience it seems more like this :)

What is the preferred way to handle tokens once an associated account is changed, ie (password recovered) ?

Good question. I think it also depends on your specific use case and your strategy. I don't think GitHub invalidate all tokens if you changed password... but in some cases this might be a good idea. It depends on how much your users will be annoyed by it :)

Yeah, we support those bundles. And yeah, probably it's a good use case when you have to clean up password reset tokens on password change :)

Cheers!

1 | Reply |

Someswara-rao-J 1 year ago

How to authenticate jwt token string (First Way to make token). I have done react login page. Successfully logged in, But not getting Authenticated.

| Reply |

weaverryan SFCASTS Someswara-rao-J 1 year ago

Hey @Someswara-rao-J!

Hmm. Did you create an access token authenticator like we did? https://symfonycasts.com/screencast/api-platform-security/access-token-authenticator

If so, here is what I would do to debug:

A) After making the AJAX request to "log in", find the Symfony profiler for that request and open it (reminder: you can always go to /_profiler to see a list of the most recent requests to your site - and you can find the AJAX request you just made there. When you get to the profiler for that request, click on the "Security" tab. Does it show you as authenticated?

B) If it does NOT show you as authenticated, then look more closely at your access token authenticator system: make sure your ApiTokenHandler is being called, etc. If it DOES show that you are authenticated... but then future AJAX requests appear to be not authenticated, it means that you are "losing" authentication between requests.

There are a few things that could cause this:

1) If you have stateless: true on your firewall, this will happen. This is because this tells your firewall to NOT use session/cookie storage.
2) If your frontend and backend are on different subdomains this could happen. For example, if your API is api.example.com and your frontend is just frontend.example.com, by default, Symfony will create a cookie for api.example.com and (iirc) that will not be usable by your frontend. You can adjust your cookie domain in the Symfony settings if this is the cause
3) In some situations, if you've added some custom serialization logic to your User class, you can "lose" authentication on the 2nd request. If you check the logs on the first request after the successful login, you should see something like:

Cannot refresh token because user has changed

Let me know if this helps!

| Reply |

API Platform 3 Symfony 6.2

What PHP libraries does this tutorial use?

// composer.json
{
    "require": {
        "php": ">=8.1",
        "ext-ctype": "*",
        "ext-iconv": "*",
        "api-platform/core": "^3.0", // v3.1.2
        "doctrine/annotations": "^2.0", // 2.0.1
        "doctrine/doctrine-bundle": "^2.8", // 2.8.3
        "doctrine/doctrine-migrations-bundle": "^3.2", // 3.2.2
        "doctrine/orm": "^2.14", // 2.14.1
        "nelmio/cors-bundle": "^2.2", // 2.2.0
        "nesbot/carbon": "^2.64", // 2.66.0
        "phpdocumentor/reflection-docblock": "^5.3", // 5.3.0
        "phpstan/phpdoc-parser": "^1.15", // 1.16.1
        "symfony/asset": "6.2.*", // v6.2.5
        "symfony/console": "6.2.*", // v6.2.5
        "symfony/dotenv": "6.2.*", // v6.2.5
        "symfony/expression-language": "6.2.*", // v6.2.5
        "symfony/flex": "^2", // v2.2.4
        "symfony/framework-bundle": "6.2.*", // v6.2.5
        "symfony/property-access": "6.2.*", // v6.2.5
        "symfony/property-info": "6.2.*", // v6.2.5
        "symfony/runtime": "6.2.*", // v6.2.5
        "symfony/security-bundle": "6.2.*", // v6.2.6
        "symfony/serializer": "6.2.*", // v6.2.5
        "symfony/twig-bundle": "6.2.*", // v6.2.5
        "symfony/ux-react": "^2.6", // v2.7.1
        "symfony/ux-vue": "^2.7", // v2.7.1
        "symfony/validator": "6.2.*", // v6.2.5
        "symfony/webpack-encore-bundle": "^1.16", // v1.16.1
        "symfony/yaml": "6.2.*" // v6.2.5
    },
    "require-dev": {
        "doctrine/doctrine-fixtures-bundle": "^3.4", // 3.4.2
        "mtdowling/jmespath.php": "^2.6", // 2.6.1
        "phpunit/phpunit": "^9.5", // 9.6.3
        "symfony/browser-kit": "6.2.*", // v6.2.5
        "symfony/css-selector": "6.2.*", // v6.2.5
        "symfony/debug-bundle": "6.2.*", // v6.2.5
        "symfony/maker-bundle": "^1.48", // v1.48.0
        "symfony/monolog-bundle": "^3.0", // v3.8.0
        "symfony/phpunit-bridge": "^6.2", // v6.2.5
        "symfony/stopwatch": "6.2.*", // v6.2.5
        "symfony/web-profiler-bundle": "6.2.*", // v6.2.5
        "zenstruck/browser": "^1.2", // v1.2.0
        "zenstruck/foundry": "^1.26" // v1.28.0
    }
}

Previous Chapter

Next Chapter

Token Types & The ApiToken Entity

Share this awesome video!

The Types of Access Tokens

JWT vs Database Storage?

Generating the Entity

12 Comments

Delete comment?

What PHP libraries does this tutorial use?

Show Lines	// ... lines 1 - 2
	namespace App\Entity;

	use App\Repository\ApiTokenRepository;
	use Doctrine\ORM\Mapping as ORM;

	#[ORM\Entity(repositoryClass: ApiTokenRepository::class)]
	class ApiToken
	{
	#[ORM\Id]
	#[ORM\GeneratedValue]
	#[ORM\Column]
	private ?int $id = null;

	#[ORM\ManyToOne(inversedBy: 'apiTokens')]
	#[ORM\JoinColumn(nullable: false)]
	private ?User $ownedBy = null;

	#[ORM\Column(nullable: true)]
	private ?\DateTimeImmutable $expiresAt = null;

	#[ORM\Column(length: 68)]
	private string $token = null;

	#[ORM\Column]
	private array $scopes = [];
Show Lines	// ... lines 28 - 80
	}

Show Lines	// ... lines 1 - 12
	final class Version20230209183006 extends AbstractMigration
	{
	public function getDescription(): string
	{
	return '';
	}

	public function up(Schema $schema): void
	{
	// this up() migration is auto-generated, please modify it to your needs
	$this->addSql('CREATE SEQUENCE api_token_id_seq INCREMENT BY 1 MINVALUE 1 START 1');
	$this->addSql('CREATE TABLE api_token (id INT NOT NULL, owned_by_id INT NOT NULL, expires_at TIMESTAMP(0) WITHOUT TIME ZONE DEFAULT NULL, token VARCHAR(68) NOT NULL, scopes JSON NOT NULL, PRIMARY KEY(id))');
	$this->addSql('CREATE INDEX IDX_7BA2F5EB5E70BCD7 ON api_token (owned_by_id)');
	$this->addSql('COMMENT ON COLUMN api_token.expires_at IS \'(DC2Type:datetime_immutable)\'');
	$this->addSql('ALTER TABLE api_token ADD CONSTRAINT FK_7BA2F5EB5E70BCD7 FOREIGN KEY (owned_by_id) REFERENCES "user" (id) NOT DEFERRABLE INITIALLY IMMEDIATE');
	}

	public function down(Schema $schema): void
	{
	// this down() migration is auto-generated, please modify it to your needs
	$this->addSql('CREATE SCHEMA public');
	$this->addSql('DROP SEQUENCE api_token_id_seq CASCADE');
	$this->addSql('ALTER TABLE api_token DROP CONSTRAINT FK_7BA2F5EB5E70BCD7');
	$this->addSql('DROP TABLE api_token');
	}
	}