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 tres tipos de llaves con usos distintos: una llave potente que actúa en lugar de toda la cuenta (Personal Access Token), una llave para leer y escribir contenido dentro de un único Space (Space Access Token) y una llave de solo lectura para leer y enviar contenido a un sitio público (Delivery Access Token). En esta página verá qué es cada una de las tres llaves y cuándo se usa, y después las emitirá usted mismo en el estudio de contenidos.

Las tres llaves tienen usos distintos

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

La idea clave es esta. El Personal Access Token se parece a una llave maestra que sustituye por completo a una persona con su cuenta; el Space Access Token es una llave que lee y escribe contenido solo dentro de un único Space; y el Delivery Access Token es una llave de solo lectura que únicamente lee el contenido publicado. Según lo que quiera hacer (si abarca toda la cuenta, si escribe dentro de un único Space o si solo lee en un sitio público), elija la llave que corresponda.

La llave que actúa en lugar de toda la cuenta: Personal Access Token

El Personal Access Token es una llave que usa tal cual los permisos de 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, modificar o publicar productos.

Por eso esta llave es potente. Si se la entrega a un programa que sube y modifica contenido automáticamente en lugar de una persona, ese programa puede trabajar como si fuera el dueño de la cuenta. La necesita para tareas de gestión que van de un Space a otro o que llegan a tocar la configuración del Space. Al contrario, cuando basta con leer y escribir contenido dentro de un único Space, es más seguro acotar los permisos con el Space Access Token que se describe más adelante, en vez de esta llave que actúa en lugar de toda la cuenta.

Por ser tan potente, hay que manejarla con cuidado. Esta llave no debe colocarse en un cliente público que llega a los clientes. 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 de más abajo.

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

La llave que lee y escribe en un Space: Space Access Token

El Space Access Token es una llave que se usa solo dentro de un único Space concreto. A diferencia del Delivery Access Token, que solo permite leer, con esta llave puede tanto leer como escribir el contenido de ese Space. Un programa puede registrar productos nuevos o modificarlos sin que una persona tenga que iniciar sesión.

Por ejemplo, imagine que quiere permitir que un cliente deje un mensaje de consulta en el sitio de la tienda de ropa sin haber iniciado sesión. El cliente que usa el visitante tiene que escribir ese mensaje nuevo en el Space de la tienda de ropa, pero con el Delivery Access Token, que es de solo lectura, no se puede escribir. Y si coloca en el cliente el Personal Access Token, que actúa en lugar de toda la cuenta, cuando esa llave se filtre queda en peligro no solo la tienda de ropa, sino todo lo que la cuenta alcanza. Para estos casos se usa el Space Access Token, que llega a escribir pero solo dentro de un único Space. Este caso de hacer que un cliente escriba contenido es el uso más representativo de esta llave, y también se usa cuando un servidor registra y modifica contenido automáticamente.

El Space Access Token solo es válido dentro de un único Space. Aunque puede leer y escribir el contenido del Space de la tienda de ropa, no puede asomarse a otro Space, ni cambiar la configuración del Space, ni tocar la organización y la cuenta. Por eso, aun tratándose de la misma tarea de escritura, es más seguro que el Personal Access Token.

Dónde colocar esta llave se decide según su uso. Puede ponerla en un servidor, o en el cliente que usa el visitante. La seguridad no se logra escondiendo la llave en algún sitio, sino acotando el rol que se le liga según ese uso. Por eso, a continuación, es importante cómo se liga el rol.

Ligue un rol para definir hasta dónde puede leer y escribir

Al emitir un Space Access Token también se define hasta dónde puede llegar esta llave con un SpaceRole (rol) que se le liga. A diferencia del rol del Delivery Access Token, que define "hasta dónde se puede leer", el rol del Space Access Token define "hasta dónde se puede leer y escribir".

El rol que se liga se acota según dónde se coloque esa llave. Si es una llave que registra y modifica productos automáticamente en un servidor, líguele un rol que solo permita Read, Create y Edit sobre los productos (Content) y que no incluya Delete ni Publish. En cambio, si es una llave que se coloca en el cliente del visitante y solo recibe mensajes de consulta, líguele un rol más acotado que solo permita crear (Create) "mensajes de consulta" nuevos. Así, aunque este valor se filtre, no se podrá hacer nada fuera de lo que cada uno permite.

No ligue el rol Administrator, que puede manejarlo todo. Cuanto más llega una llave a escribir, y sobre todo cuanto más se coloca en un lugar que el visitante puede ver, más segura es cuando se le liga un rol lo bastante acotado como para asumirlo aunque se filtre.

Cómo crear un rol que permite escribir se trata en Roles y permisos. El rol Registrador de productos que se crea en esa página es un ejemplo de rol de escritura que permite registrar y modificar productos.

La llave que solo lee en un Space: Delivery Access Token

El Delivery Access Token es una llave de solo lectura que solo tiene efecto dentro de 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.

Defina con Referrers permitidos en qué sitios se puede usar la llave

Si el rol ligado define qué puede leer esta llave, los Referrers permitidos definen dónde se puede usar. Están en la parte inferior de la pantalla de emisión y se pueden cambiar también después de haberla emitido.

El valor inicial es Sin restricción. En ese estado el contenido se entrega aunque se cargue desde cualquier sitio. Si elige Permitir solo los referrers indicados, aparece un campo para escribir la dirección y, a partir de ahí, solo pasan las solicitudes que vienen de las direcciones anotadas aquí. Si la dirección de la tienda online de ropa es https://shop.example.com, anote esa dirección. Así, aunque el valor de esta llave caiga en manos de otra persona, no tendrá efecto fuera del sitio de la tienda de ropa.

Puede anotar varias direcciones. Si pulsa el botón Añadir, aparece un campo más, y si pulsa el icono de eliminar que hay a la derecha del campo, esa línea desaparece.

Para permitir de una vez las direcciones que cuelgan de shop.example.com, ponga *. al principio y anótela como https://*.shop.example.com. Anotada así, quedan incluidas todas las direcciones que llevan algo delante, como event.shop.example.com. Eso sí, aun anotándola así, el propio https://shop.example.com no queda incluido. Si tiene que permitir las dos, añada también https://shop.example.com en una línea aparte.

Esta lista funciona pensando en el caso de que alguien abra el sitio en su navegador y desde ahí se cargue el contenido. Si esta llave la usa un programa que se ejecuta en un servidor y no un sitio, no se puede saber de qué sitio viene la solicitud, así que en esas llaves deje Sin restricción tal cual.

Manejo del valor secreto emitido

Con las tres llaves, al terminar la emisión pasa a la pantalla de detalle de esa llave. El campo Token de Información básica contiene el valor secreto del token y, si pulsa el botón Copiar de la izquierda del campo, se copia el valor completo. El valor es más largo que el campo, así que en pantalla se ve cortado por el final, pero lo que se copia es el valor completo. Este valor es la llave en sí, y es el que usa al colocarlo en un servidor o en un sitio. Aunque no lo haya copiado justo después de emitirlo, más adelante puede volver a entrar en esta pantalla de detalle y copiarlo. El ID que está en el apartado Token del panel derecho es el identificador que señala a esta llave, y no es el valor secreto.

Sin embargo, cada llave se guarda en un sitio distinto.

• 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 un cliente público que ven los clientes ni en código que otros puedan ver.
• Para el Space Access Token, ajuste dónde colocarlo mediante el rol que le liga. A la llave que pone en un servidor, líguele un rol de escritura con lo justo que necesita; a la llave que pone en un cliente que llega a los clientes, líguele un rol lo bastante acotado como para asumirlo aunque se filtre (por ejemplo, crear solo un tipo de mensaje nuevo). No ligue el rol Administrator ni un rol de escritura amplio a una llave que coloque en un lugar público.
• 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í. Si además anota aquí la dirección del sitio de la tienda online con Referrers permitidos, aunque el valor caiga en manos de otra persona no podrá usarse fuera de ese sitio. 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, pasa a la pantalla de detalle de esa llave. Copie en esta pantalla el valor secreto del token, tal como se explica en Manejo del valor secreto emitido, y guárdelo en un lugar seguro del servidor donde se ejecuta este programa.

Emitir un Space Access Token

Esta vez va a emitir el Space Access Token que usará el servidor que registra productos automáticamente en el Space de la tienda de ropa. Esta llave se usa en el Space de la tienda de ropa, y se le liga un rol que permite registrar y modificar 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 pueda hacer Read, Create y Edit sobre los productos (Content). A continuación se supone que ha creado ese rol con el nombre Registrador de productos.

La pantalla de emisión y gestión está dentro de los mismos ajustes del Space que el Delivery Access Token.

1. En los ajustes del Space de la tienda de ropa, abra la pantalla de Space Access Token.
2. Pulse el botón Crear de la parte superior derecha de la lista. Se abre la pantalla de creación del Space Access Token.
3. En el campo Nombre, escriba Servidor de registro automático de productos nuevos.
4. En SpaceRole elija Registrador de productos. No elija Administrator.
5. En Referrers permitidos deje Sin restricción tal cual. Esta llave se usa en un servidor y no en un sitio.
6. Pulse el botón Crear de la parte superior derecha de la pantalla para emitirla.

Cuando termina la emisión, pasa a la pantalla de detalle de esa llave. Copie en esta pantalla el valor secreto del token, tal como se explica en Manejo del valor secreto emitido, y guárdelo en un lugar seguro. Como aquí ha ligado un rol que permite registrar y modificar productos, esta llave se usa en el servidor que necesita ese rol. Si tiene que colocarla directamente en el cliente que usa el visitante, emita aparte y use una llave con un rol más acotado, lo bastante como para asumirlo aunque se filtre. En una llave que llega así a los clientes, anote además la dirección de ese sitio en Referrers permitidos.

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 de la lista. Se abre la pantalla de creación del Delivery Access Token.

3. En el campo Nombre, escriba Entrega al sitio de la tienda online.

4. En el campo Descripción puede anotar para qué usa esta llave. (Es opcional.)

5. En SpaceRole elija Solo lectura de productos. No elija Administrator.

   

6. En Referrers permitidos, en la parte inferior de la pantalla, elija Permitir solo los referrers indicados. Es el ajuste que liga esta llave para que solo se use en el sitio de la tienda online.

7. En el campo que aparece, escriba https://shop.example.com.

8. Pulse el botón Añadir.

9. En el campo que acaba de aparecer, escriba https://*.shop.example.com.

   

10. Pulse el botón Crear de la parte superior derecha de la pantalla para emitirla.

Cuando termina la emisión, pasa a la pantalla de detalle de esa llave. Copie en esta pantalla el valor secreto del token, tal como se explica en Manejo del valor secreto emitido, y colóquelo en el sitio de la tienda online para usarlo.

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 de solo lectura que ligará al Delivery Access Token y el rol de lectura y escritura que ligará al Space Access Token.
• Estados y publicación: con el Delivery Access Token solo se lee el contenido en estado Published. Conozca qué es publicar.
• Space Access Token: trata las especificaciones técnicas, como el formato de las solicitudes, que necesita para emitir un Space Access Token desde un programa o para leer y escribir contenido con esta llave.
• Delivery Access Token: trata las especificaciones técnicas, como las reglas exactas de notación para anotar direcciones en Referrers permitidos y el formato de las solicitudes que necesita al manejar esta llave desde un programa.
• Referencia de la API: trata las especificaciones técnicas, como el formato de las solicitudes, que necesita al emitir otros tokens o al manejar contenido directamente desde un programa.