Tipos de token y la entidad ApiToken
Vale, ¿y si necesitas permitir el acceso programático a tu API?
Tipos de tokens de acceso
Cuando hablas con una API mediante código, envías un token de API, comúnmente conocido como token de acceso:
fetch('/api/kittens', {
headers: {
'Authorization': 'Bearer THE-ACCESS-TOKEN',
}
});La forma exacta de obtener ese token varía. Pero hay dos casos principales.
En primer lugar, como usuario del sitio, como un dragón, quieres generar un token de API para poder utilizarlo personalmente en un script que estés escribiendo. Esto es como un token de acceso personal de GitHub. Estos se crean literalmente a través de una interfaz web. Vamos a mostrar esto.
El segundo caso de uso principal es cuando un tercero quiere hacer peticiones a tu API en nombre de un usuario de tu sistema. Por ejemplo, un nuevo sitio llamadoDragonTreasureOrganizer.com quiere hacer una petición a nuestra API en nombre de algunos de nuestros usuarios, por ejemplo, buscar los tesoros de un usuario y mostrarlos artísticamente en su sitio. En esta situación, en lugar de que nuestros usuarios generen tokens manualmente y luego... como... los introduzcan en ese sitio, ofrecerás OAuth. OAuth es básicamente un mecanismo para que los usuarios normales den de forma segura tokens de acceso para su cuenta a un tercero. Y así, tu sitio, o en algún lugar de tu infraestructura tendrás un servidor OAuth.
Eso está fuera del alcance de este tutorial. Pero lo importante es que, una vez hecho el OAuth, el cliente de la API acabará con, lo has adivinado, ¡un token de API! Así que no importa en qué viaje estés, si estás haciendo acceso programático, tus usuarios de la API terminarán con un token de acceso. Y tu trabajo consistirá en leerlo y comprenderlo. Haremos exactamente eso.
¿JWT vs Almacenamiento en Base de Datos?
Como he mencionado, vamos a mostrar un sistema que permite a los usuarios generar sus propios tokens de acceso. ¿Cómo lo hacemos? De nuevo, hay dos formas principales. ¡Muerte por elección!
La primera es generar algo llamado Token Web JSON o JWT. Lo bueno de los JWT es que no necesitan almacenamiento en bases de datos. Son cadenas especiales que en realidad contienen información en su interior. Por ejemplo, puedes crear una cadena JWT que incluya el id de usuario y algunos ámbitos.
Uno de los inconvenientes de los JWT es que no hay una forma fácil de "cerrar sesión"... porque no hay una forma automática de invalidar los JWT. Les das una fecha de caducidad cuando los creas... pero entonces son válidos hasta entonces... pase lo que pase, a menos que añadas alguna complejidad extra... lo que anula un poco el propósito.
Los JWT están de moda, son populares y divertidos Pero... puede que no los necesites. Son geniales cuando tienes un sistema de inicio de sesión único porque, si ese JWT se utiliza para autenticarse con varios sistemas o API, cada API puede validar el JWT por sí misma: sin necesidad de hacer una petición de API a un sistema central de autenticación.
Así que es posible que acabes utilizando JWT, para lo que existe un bundle estupendo llamado LexikJWTAuthenticationBundle. Los JWT son también el tipo de token de acceso que al final te da OpenID.
En lugar de los JWT, la segunda opción principal es muy sencilla: generar una cadena de token aleatoria y almacenarla en la base de datos. Esto también te permite invalidar los tokens de acceso... ¡simplemente borrándolos! Esto es lo que haremos.
Generar la entidad
Así que manos a la obra. Para almacenar los tokens de la API, ¡necesitamos una nueva entidad! Busca tu terminal y ejecuta:
php ./bin/console make:entity
Y llamémosla ApiToken. En teoría, podrías permitir a los usuarios autenticarse a través de un formulario de inicio de sesión o HTTP básico y luego enviar una petición POST para crear tokens de API si quieres... pero no lo haremos.
Añade una propiedad ownedBy. Esto va a ser un ManyToOne a User y no nullable. Y diré "sí" a la inversa. Así que la idea es que cada Userpueda tener muchos tokens de API. Cuando se utiliza un token de API, queremos saber con qué Userestá relacionado. Lo utilizaremos durante la autenticación. Llamar a la propiedadapiTokens está bien y decir no a la eliminación de huérfanos. Siguiente propiedad: expiresAt datetime_immutable y diré que sí a nullable. Tal vez permitamos que los tokens no caduquen nunca dejando este campo en blanco. La siguiente es token, que será una cadena. Voy a establecer la longitud en 68 -veremos por qué en un minuto- y no ennullable. Y por último, añade una propiedad scopes como tipo json. Esto va a ser bastante guay: almacenaremos una matriz de "permisos" que debe tener este token de API. En este caso, tampoco nullable. Pulsa intro para terminar.
Muy bien, gira a tu editor. Sin sorpresas: eso ha creado una entidad ApiToken... y no hay nada muy interesante dentro de ella:
| // ... 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 = []; | |
| // ... lines 28 - 80 | |
| } |
Así que vamos a hacer la migración correspondiente:
symfony console make:migration
Gira y echa un vistazo a ese archivo para asegurarte de que se ve bien. ¡Sí! Crea la tabla api_token:
| // ... 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'); | |
| } | |
| } |
Ejecuta eso con:
symfony console doctrine:migrations:migrate
Y... ¡genial! A continuación: vamos a añadir una forma de generar la cadena de tokens aleatorios. Luego, hablaremos de ámbitos y cargaremos nuestros accesorios con algunos tokens de la API.
12 Comments
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:
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.
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:
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
locatorkey ofApiToken. Then you store the second part (thesecret) on another property ofApiToken- 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-L65Then, when verify if a token is valid, you split the token on
.to get the first and second part. You then query for theApiTokenvia the first part (thelocator). If found, you has the 2nd part that was just sent you to you and see if it equals the hashedsecreton theApiTokenyou just found usinghash_equals- e.g. https://github.com/SymfonyCasts/reset-password-bundle/blob/3e0bb051a514459a3c63a5064be40208e4f34783/src/ResetPasswordHelper.php#L126If anyone has any questions, let me know :)
Cheers!
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!
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
apiTokenproperty to someCompanyentity and allow an admin for aCompanyto 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.
Authorizationheader 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, aUserobject is what you would return from your authenticator... and then anywhere in your code where you say$this->getUser(), it would be aUserobject. But for the company token, your authenticator would return aCompany, and when you use$this->getUser()in your code, that will return aCompanyobject. 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
Useror aCompanyacross your entire application, then be sure to create smart security rules that do no depend on the specificUser/Companyobject. 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!
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!
Yes it should!
I'm curious in this example, why you have potentially one user - many tokens relationship?
Wouldn't one user - one token suffice ?
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!
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 !
Hey @MildDisaster ,
Mostly yes, I suppose, but once again, it depends on your specific use case. But from my experience it seems more like this :)
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!
How to authenticate jwt token string (First Way to make token). I have done react login page. Successfully logged in, But not getting Authenticated.
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
/_profilerto 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
ApiTokenHandleris 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: trueon 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
Userclass, 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:Let me know if this helps!
"Houston: no signs of life"
Start the conversation!