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.
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.