Tokens

Imagine que ha creado la tienda online de una tienda de ropa. Quiere mostrar en el sitio web que ven sus clientes los productos que tiene registrados en el estudio de contenidos. Pero ese sitio no es una persona, sino un programa. No puede iniciar sesión con un usuario y una contraseña como lo haría una persona. Para estos casos, un token es la llave secreta que se emite para que un sitio o un programa pueda acceder al contenido en lugar de una persona.

Piense en un token como en una única llave que abre una cerradura. Quien tiene esa llave puede trabajar con el contenido dentro de un alcance determinado sin necesidad de iniciar sesión. Por eso un token debe tratarse igual que una contraseña. No debe mostrarse a cualquiera y, si se filtra, quien lo tenga puede usar ese permiso tal cual.

WEEGLOO tiene dos tipos de llaves con usos distintos. Una es una llave potente ligada a una cuenta (Personal Access Token) y la otra es una llave acotada para leer y enviar contenido a un sitio público (Delivery Access Token). En esta página verá qué es cada una de las dos llaves y cuándo se usa, y después las emitirá usted mismo desdel estudio de contenidos.

Las dos llaves tienen usos distintos

Antes que nada, esta es la diferencia entre ambas de un vistazo.

La idea clave es esta. El Personal Access Token se parece a una llave maestra que actúa en lugar de una persona, y el Delivery Access Token es una llave acotada que "solo puede ver el tablón de anuncios de la entrada". Como sus usos no se solapan, basta con elegir la que corresponda a lo que quiere hacer.

La llave ligada a una cuenta: Personal Access Token

El Personal Access Token es una llave que se liga a la propia cuenta que la emite. Con esta llave, puede hacer sin iniciar sesión todo lo que esa cuenta puede hacer en el estudio de contenidos. Llega incluso a tareas de gestión como registrar productos, modificarlos o publicarlos.

Por eso esta llave es potente. Por ejemplo, si crea un programa que sube automáticamente productos nuevos al estudio de contenidos cada noche, como ese programa no puede iniciar sesión como una persona, le entrega esta llave. Es la llave que se usa para ejecutar automáticamente tareas de gestión en lugares que no quedan a la vista directa de las personas, como servidores o scripts de automatización.

Por ser tan potente, hay que tener cuidado al manejarla. Esta llave no debe colocarse en el sitio web público que ven los clientes ni en el navegador. Si la pone en un lugar público, cualquiera puede sacarla y verla, y quien la consiga puede usar tal cual los permisos de la cuenta que la emitió. Cuando solo va a cargar y mostrar productos en un sitio público, en lugar de esta llave potente use el Delivery Access Token que se describe más abajo.

Para emitir un Personal Access Token solo hace falta ponerle un nombre. No se elige un alcance de permisos aparte. Esto se debe a que hereda tal cual los permisos que tiene la cuenta que la emite.

La llave ligada a un Space: Delivery Access Token

El Delivery Access Token es una llave de solo lectura que se liga a un único Space concreto. Con esta llave solo puede leer el contenido que está en estado Published (publicado) dentro de ese Space. El contenido en estado Draft, que no se ha publicado, no se puede leer con esta llave, y tampoco se puede modificar ni eliminar.

Esta es precisamente la llave que usa el sitio de la tienda online que ven los clientes para cargar y mostrar los productos. El sitio solo necesita mostrar los productos, no registrarlos ni borrarlos, así que basta con una llave acotada que solo permite leer. Aunque esta llave se filtre, lo único que ocurre es que se puede leer el contenido publicado, pero no se puede dañar el contenido.

Qué significa publicar contenido (Published) y por qué hay que publicarlo para que quede expuesto al exterior (entregado) se trata en Estados y publicación.

Acote el alcance de lectura ligando un rol reducido

Al emitir un Delivery Access Token, hasta dónde puede leer esta llave se define con un SpaceRole (rol) que se le liga. Un rol es un conjunto de permisos que establece "qué se puede hacer y con qué acciones". Cuando se liga un rol a una llave, esa llave solo puede leer hasta donde el rol ligado lo permite.

En el caso del sitio de la tienda online basta con leer los "productos", así que cree un rol reducido que solo permita Read sobre los productos (Content) y lígelo. De ese modo, aunque esta llave se filtre, lo único que se podrá leer es la información de los productos, sin que se filtre otro contenido ni la información de los miembros.

No ligue el rol Administrator, que puede hacer de todo. Administrator es el rol de máximo permiso, capaz de trabajar con todo dentro de ese Space. Si liga permisos tan amplios a una llave destinada a un sitio público que solo necesita leer, el riesgo aumenta cuando la llave se filtra. Lo seguro es crear aparte y ligar un rol acotado que solo lea lo necesario.

Cómo crear un rol y acotar sus permisos se trata en Roles y permisos. Consulte esa página para crear de antemano el rol que solo permite Read de productos, que ligará a la llave del sitio público.

Manejo del valor secreto emitido

Con ambas llaves, al terminar la emisión aparece en pantalla el valor secreto del token. Ese valor es la llave en sí. Es el valor que usa al colocarlo en un servidor o en un sitio. Cópielo y guárdelo en ese momento, justo después de emitirlo. También puede volver a consultarlo en la pantalla de detalle del token.

Sin embargo, las dos llaves se guardan en sitios distintos.

• Trate el Personal Access Token como una contraseña. Por ser una llave potente, guárdela solo dentro del servidor y no la coloque en el sitio público que ven los clientes, en el navegador ni en código que otros puedan ver.
• El Delivery Access Token, al contrario, está pensado precisamente para colocarse en el sitio público que ven los clientes. Eso supone que cualquiera que abra el sitio puede ver este valor, pero como le ha ligado un rol acotado, aunque alguien se lleve este valor no podrá hacer nada fuera del alcance de lectura que ese rol permite. Por eso colocarlo en el sitio no supone ningún problema en sí. Eso sí, no lo difunda a la ligera fuera del sitio donde lo va a usar.

Si pierde una llave o cree que se ha usado de forma distinta a la prevista, basta con eliminar esa llave, emitir una nueva y sustituirla.

Emitir un Personal Access Token

Va a emitir el Personal Access Token que entregará al programa que sube productos nuevos automáticamente cada noche.

1. En los ajustes de la cuenta, abra la pantalla de Personal Access Token.
2. Pulse el botón Crear de la parte superior derecha.
3. En el campo de nombre, escriba Subida nocturna de productos nuevos. Este nombre sirve para reconocer más tarde para qué uso se creó la llave.
4. Pulse el botón Guardar para emitirla.

Cuando termina la emisión, el valor secreto del token aparece en pantalla. Cópielo en ese momento y guárdelo en un lugar seguro. La pantalla tiene el mismo aspecto que el resultado de la emisión del Delivery Access Token que se muestra más abajo.

Emitir un Delivery Access Token

Esta vez va a emitir el Delivery Access Token que el sitio de la tienda online usará para cargar y mostrar los productos. Esta llave se liga al Space de la tienda de ropa, y se le liga también un rol reducido que permite leer los productos.

Primero, el rol que va a ligar a esta llave debe existir ya en el Space. Cree de antemano en Roles y permisos un rol que solo permita Read sobre los productos (Content). A continuación se supone que ha creado ese rol con el nombre Solo lectura de productos.

1. En los ajustes del Space de la tienda de ropa, abra la pantalla de Delivery Access Token.
2. Pulse el botón Crear de la parte superior derecha.
3. En el campo de nombre, escriba Entrega al sitio de la tienda online.
4. En el campo de descripción puede anotar para qué usa esta llave. (Es opcional.)
5. En Space Role elija Solo lectura de productos. No elija Administrator.
6. Pulse el botón Crear para emitirla.

Cuando termina la emisión, el valor secreto del token aparece en pantalla. Cópielo en ese momento y guárdelo en un lugar seguro.

Elimine las llaves que ya no use

Las llaves que ha dejado de usar es más seguro eliminarlas que dejarlas tal cual. Busque en la lista de tokens las llaves que ya no use y elimínelas. Cuando elimina una llave, deja de poder accederse con ella. Lo mismo cuando crea que una llave se ha filtrado. Basta con eliminar la llave sospechosa, emitir una nueva y sustituirla.

Qué hacer a continuación

• Roles y permisos: cree el rol con alcance de lectura acotado que ligará al Delivery Access Token.
• Estados y publicación: con el Delivery Access Token solo se lee el contenido en estado Published. Conozca qué es publicar.
• Referencia de la API: trata las especificaciones técnicas, como el formato de las solicitudes, que necesita para emitir tokens o cargar contenido directamente desde un programa.