En el pasado, las cookies de terceros se usaban para almacenar y transmitir información sobre el estado de un usuario, como su estado de acceso, información sobre el dispositivo que usa o si es conocido y de confianza. Por ejemplo, si el usuario accedió con el SSO, si tiene un tipo de dispositivo compatible o si es conocido y de confianza. Con la baja de la compatibilidad con cookies de terceros, muchos de estos casos de uso deberán admitirse por otros medios.
Los tokens de estado privados ofrecen una forma de compartir información en la Web, pero de una manera que preserva la privacidad a través de controles sobre la cantidad de datos que se pueden compartir.
Los tokens de estado privado (antes conocidos como tokens de confianza) permiten que se transmita la confianza en la autenticidad de un usuario de un contexto a otro y, al mismo tiempo, ayudan a los sitios a combatir el fraude y distinguir a los bots de las personas reales, sin seguimiento pasivo.
En este documento, se describen los detalles técnicos para implementar tokens de estado privado (PST). Para obtener un esquema más general, consulta la descripción general de PST.
¿Cómo funcionan los tokens de estado privado?
La relación clave que se debe comprender en el PST es la que existe entre los emisores y los canjeadores. Los emisores y los canjeadores pueden pertenecer a la misma empresa.
- Entidades emisoras: Estas entidades tienen algún indicador sobre un usuario (por ejemplo, si es un bot o no) y lo incorporan en un token que se almacena en el dispositivo del usuario (obtén más detalles en las siguientes secciones).
- Redeemers: Es posible que estas entidades no tengan indicadores sobre un usuario, pero necesiten saber algo sobre él (por ejemplo, si es un bot o no) y solicitar que se canjee un token del emisor para comprender la confiabilidad de ese usuario.
Cada interacción con PST requiere que los emisores y los canjeadores trabajen juntos para compartir indicadores en la Web. Esos indicadores son valores generales que no son lo suficientemente detallados para identificar a las personas.
¿Los tokens de estado privado son adecuados para mí?
Las empresas que toman decisiones de confianza y desean que esa información esté disponible en todos los contextos pueden beneficiarse de los PST. Para obtener más información sobre los posibles casos de uso de los PST, consulta nuestra documentación sobre los casos de uso de PST.
Emite y canjea tokens
La implementación de PST se realiza en tres fases:
- Emisión de tokens
- Cómo canjear tokens
- Reenvío de registros de canje
En la primera fase, los tokens se emiten a un navegador (por lo general, después de algún tipo de validación). En la segunda fase, otra entidad enviará una solicitud para canjear el token que se emitió para leer el valor en ese token. En la fase final, la parte que canjea recibe un registro de canje (RR) con el valor que se contenía en el token. Luego, esa parte puede usar ese registro como una certificación de ese usuario para varios fines.
Define tu estrategia de tokens
Para definir tu estrategia de tokens, debes comprender los conceptos clave de la PST (tokens y registros de canje), las variables, los comportamientos y las limitaciones para poder pensar en su posible uso en tu caso de uso.
Tokens y registros de canje: ¿cuál es la relación entre ellos?
Cada dispositivo puede almacenar hasta 500 tokens por sitio web y emisor de nivel superior. Además, cada token tiene metadatos que informan qué clave usó el emisor para emitirlo. Esa información se puede usar para decidir si canjear o no un token durante el proceso de canje. El navegador almacena los datos de PST de forma interna en el dispositivo del usuario, y solo la API de PST puede acceder a ellos.
Cuando se canjea un token, el registro de canje (RR) se almacena en el dispositivo. Este almacenamiento actúa como una caché para canjes futuros. Hay un límite de dos canjes de tokens cada 48 horas por dispositivo, página y emisor. Las nuevas llamadas de canje usarán RR almacenados en caché siempre que sea posible, en lugar de generar una solicitud al emisor.
- Se emiten tokens nuevos (máximo 500 por emisor, sitio y dispositivo).
- Todos los tokens se almacenan en el almacén de tokens del dispositivo (similar al almacén de cookies).
- Si no se encuentra ningún RR activo, se pueden generar RR nuevos después de la emisión (máximo 2 cada 48 horas).
- Los RR se consideran activos hasta el vencimiento y se usarán como una caché local.
- Las nuevas llamadas de canje llegarán a la caché local (no se generarán RR nuevos).
Después de definir tu caso de uso, debes definir cuidadosamente la vida útil de tu RR, ya que esto determinará cuántas veces podrás usarlo en tu caso.
Asegúrate de comprender los siguientes comportamientos y variables fundamentales antes de definir tu estrategia:
| Variable o comportamiento | Descripción | Uso potencial |
|---|---|---|
| Metadatos de la clave del token | Cada token se puede emitir con una sola clave criptográfica y, en PST, hay una limitación de seis claves por emisor. | Una posible forma de usar esta variable es definir un rango de confianza para tus tokens en función de tus claves criptográficas (por ejemplo, clave 1 = confianza alta, mientras que clave 6 = sin confianza). |
| Fecha de vencimiento del token | La fecha de vencimiento del token es la misma que la de la clave. | Las claves se pueden rotar al menos cada 60 días, y todos los tokens emitidos con claves no válidas también se consideran no válidos. |
| Límite de frecuencia de canje de tokens | Hay un límite de dos canjes de tokens por dispositivo y emisor cada 48 horas. | Depende de la cantidad estimada de canjes que requiera tu caso de uso cada 48 horas. |
| Cantidad máxima de emisores por origen de nivel superior | Actualmente, la cantidad máxima de emisores por origen de nivel superior es de dos. | Define cuidadosamente los emisores de cada página. |
| Tokens por emisor en un dispositivo | Actualmente, la cantidad máxima de tokens por emisor en un dispositivo específico es de 500. | Asegúrate de que la cantidad de tokens sea inferior a 500 por emisor. Asegúrate de controlar los errores en tu página web cuando intentes emitir tokens. |
| Rotación de compromisos de claves | Cada emisor de PST debe exponer un extremo con compromisos clave que se puedan cambiar cada 60 días, y se ignorará cualquier rotación más rápida. | Si tus claves vencerán en menos de 60 días, es obligatorio actualizar tus compromisos de claves antes de esa fecha para evitar interrupciones (consulta los detalles). |
| Vida útil del registro de canje | Se puede definir la vida útil de RR para determinar una fecha de vencimiento. Dado que los RR se almacenan en caché para evitar llamadas de canje nuevas innecesarias a la entidad emisora, esto es importante para asegurarse de tener indicadores de canje lo suficientemente actualizados. | Dado que existe un límite de frecuencia de canje de dos tokens cada 48 horas, es importante definir el ciclo de vida de tu RR para poder ejecutar llamadas de canje con éxito durante, al menos, este período (el ciclo de vida de la RR debe establecerse según corresponda). Se recomienda establecer este tiempo de vida en semanas. |
Situaciones de ejemplo
Situación 1: La vida útil de la RR es inferior a 24 horas (t=t) y la canje se realiza varias veces durante el período de 48 horas.
Situación 2: La vida útil de la RR es de 24 horas y la canje se realiza varias veces durante el período de 48 horas.
Situación 3: La vida útil de la RR es de 48 horas y la canje se realiza varias veces durante ese período.
Ejecuta la demostración
Antes de adoptar PST, te recomendamos que primero configures la demostración. Para probar la demo de PST , deberás ejecutar Chrome con marcas para habilitar los compromisos de claves del emisor de la demo (sigue las instrucciones disponibles en la página de demo).
Cuando ejecutas esta demostración, tu navegador usa los servidores de emisor y canjeador de la demo para proporcionar y consumir tokens.
Consideraciones técnicas
La demostración se ejecutará mejor si implementas los siguientes pasos:
- Asegúrate de detener todas las instancias de Chrome antes de ejecutarlo con marcas.
- Si ejecutas Chrome en una máquina con Windows, consulta esta guía para pasar parámetros al objeto binario ejecutable de Chrome.
- Abre las Herramientas para desarrolladores de Chrome en Aplicaciones > Almacenamiento > Tokens de estado privado mientras usas la aplicación de demostración para ver los tokens que emitió o canjeó el emisor de la demostración.
Configuración para la adopción
Conviértete en emisor
Los emisores desempeñan un papel clave en la PST. Asignan valores a los tokens para determinar si un usuario es un bot o no. Si quieres comenzar a usar PST como emisor, debes registrarte completando el proceso de registro de emisores.
Para solicitar convertirse en emisor, el operador del sitio web del emisor debe abrir un nuevo problema en el repositorio de GitHub con la plantilla "New PST Issuer". Sigue las instrucciones del repositorio para completar el problema. Una vez que se haya verificado un extremo, se combinará en este repositorio y la infraestructura del servidor de Chrome comenzará a recuperar esas claves.
Servidores del emisor
Los emisores y los canjeadores son los actores clave de la PST; los servidores y los tokens son las herramientas clave de la PST. Si bien ya proporcionamos algunos detalles sobre los tokens y en la documentación de GitHub, queríamos ofrecer más detalles sobre los servidores PST. Para configurarte como emisor de PST, primero debes configurar un servidor de emisión.
Implementa tu entorno: Servidores de emisores
Para implementar el servidor del emisor de tokens, deberás compilar tu propia aplicación del servidor exponiendo extremos HTTP.
El componente del emisor se compone de dos módulos principales: (1) el servidor del emisor y (2) el emisor de tokens.
Al igual que con todas las aplicaciones orientadas a la Web, te recomendamos que agregues una capa adicional de protección a tu servidor de emisor.
Servidor del emisor: En nuestra implementación de ejemplo, nuestro servidor de emisión es un servidor Node.js que usa el framework Express para alojar los extremos HTTP del emisor. Puedes consultar el código de muestra en GitHub.
Emisor de tokens: El componente criptográfico del emisor no requiere ningún lenguaje específico, pero debido a los requisitos de rendimiento de este componente, proporcionamos una implementación en C como ejemplo, que usa la biblioteca Boring SSL para administrar tokens. Puedes encontrar el ejemplo de código del emisor y más información sobre la instalación en GitHub.
Claves: El componente del emisor de tokens usa claves EC personalizadas para encriptar los tokens. Estas claves deben protegerse y almacenarse en un almacenamiento seguro.
Requisitos técnicos para los servidores de emisores
Según el protocolo, deberás implementar al menos dos extremos HTTP en tu servidor de emisor:
- Compromiso de clave (por ejemplo,
/.well-known/private-state-token/key-commitment): En este extremo, los detalles de la clave pública de encriptación estarán disponibles para los navegadores para confirmar que tu servidor es legítimo. - Emisión de tokens (por ejemplo,
/.well-known/private-state-token/issuance): Es el extremo de emisión de tokens en el que se controlarán todas las solicitudes de tokens. Este extremo será el punto de integración para el componente del emisor de tokens.
Como se mencionó anteriormente, debido al alto tráfico esperado que este servidor podría manejar, te recomendamos que lo implementes con una infraestructura escalable (por ejemplo, en un entorno de nube) para poder ajustar tu backend en función de una demanda variable.
Envía una llamada al servidor del emisor.
Implementa una llamada de recuperación de sitios web a tu pila de emisores para emitir tokens nuevos.
// issuer request
await fetch("/.well-known/private-state-token/issuance", {
method: "POST",
privateToken: {
version: 1,
operation: "token-request"
}
});
Consulta un ejemplo de código.
Servidores de canje
Para implementar el servicio de canje de tokens, deberás compilar tu propia aplicación del servidor. Esto te permitirá leer los tokens que envía un emisor. En los siguientes pasos, se describe cómo canjear tokens y cómo leer los registros de canje asociados con esos tokens.
Puedes ejecutar el emisor y el canjeador en el mismo servidor (o grupo de servidores).
Requisitos técnicos para los servidores de canje
Según el protocolo, deberás implementar al menos dos extremos HTTP para tu servidor de canje:
/.well-known/private-state-token/redemption: Es el extremo en el que se controlará todo el canje de tokens. Este extremo es donde se integrará el componente de canje de tokens.
Envía una llamada al servidor del canjeador
Para canjear tokens, deberás implementar una llamada de recuperación de sitios web en tu pila de canjeadores para canjear los tokens emitidos anteriormente.
// redemption request
await fetch("/.well-known/private-state-token/redemption", {
method: "POST",
privateToken: {
version: 1,
operation: "token-redemption",
refreshPolicy: "none"
}
});
Consulta la muestra de código.
Después de canjear un token, puedes enviar el registro de canje (RR) realizando otra llamada de recuperación:
// attach redemption records from the issuers to the request
await fetch("<DESTINATION_RESOURCE>", {
method: "POST",
privateToken: {
version: 1,
operation: "send-redemption-record",
issuers: [<ISSUER_DOMAIN>]
}
});
Consulta la muestra de código.
Implementa tu implementación
Para probar tu implementación, primero navega a la página web en la que se realiza la llamada de emisión y confirma que los tokens se creen según tu lógica. Verifica en tu backend que las llamadas se hayan realizado según la especificación. Luego, navega a la página web en la que se realiza la llamada de canje y confirma que se hayan creado los RR según tu lógica.
Implementación en el mundo real
Te recomendamos que elijas sitios web de segmentación que formen parte de tu caso de uso específico:
- Poca cantidad de visitas mensuales (<1 millón de visitas al mes): Debes comenzar por implementar la API para un público pequeño.
- Es tuyo y lo controlas: Si es necesario, puedes inhabilitar rápidamente la implementación sin aprobaciones complejas.
- No más de un emisor: Para limitar la cantidad de tokens y simplificar las pruebas.
- No más de dos canjeadores: Debes simplificar el proceso de solución de problemas en caso de que haya alguno.
Política de permisos
Para funcionar correctamente, la API de PST debe estar disponible para la página de nivel superior y para cualquier subrecurso que use la API.
La operación de solicitud de token está controlada por la directiva private-state-token-issuance. Las operaciones token-redemption y send-redemption-record están controladas por la directiva private-state-token-redemption. En Chrome 132 y versiones posteriores, la lista de entidades permitidas para estas directivas se establece en * (todos los orígenes) de forma predeterminada. Esto significa que la función está disponible para la página de nivel superior, los iframes del mismo origen y los iframes de origen cruzado sin delegación explícita.
Para inhabilitar la emisión o canje de tokens de PST para páginas específicas de tu sitio, incluye private-state-token-issuance=() y private-state-token-redemption=() en el encabezado Permissions-Policy de cada página.
También puedes usar el encabezado Permissions-Policy para controlar el acceso de terceros a PST. Como parámetros de la lista de orígenes del encabezado, usa self y cualquier origen al que quieras permitir el acceso a la API. Por ejemplo, para inhabilitar por completo el uso de PST en todos los contextos de navegación, excepto en tu propio origen y https://example.com, establece los siguientes encabezados de respuesta HTTP:
Permissions-Policy:private-state-token-issuance=(self "https://example.com"),private-state-token-redemption=(self "https://example.com")
Para habilitar la API para todos los recursos de origen cruzado, establece la lista de orígenes en *.
Obtén información para controlar las funciones de Privacy Sandbox con la Política de Permisos o profundiza en la comprensión de la Política de Permisos.
Solución de problemas
Puedes inspeccionar los PST desde las pestañas Red y Aplicación de las Herramientas para desarrolladores de Chrome.
En la pestaña Red, haz lo siguiente:
En la pestaña Application, haz lo siguiente:
Obtén más información sobre esta integración de DevTools.
Prácticas recomendadas para clientes
Si las funciones esenciales de tu sitio web dependen de ciertos emisores de tokens, prioriza los emisores. Llama a hasPrivateToken(issuer) para estos emisores preferidos antes de cargar cualquier otra secuencia de comandos. Esto es fundamental para evitar posibles fallas de canje.
La cantidad de emisores por nivel superior está limitada a dos, y las secuencias de comandos de terceros también pueden intentar llamar a hasPrivateToken(issuer) para priorizar sus propios emisores preferidos. Por lo tanto, protege tus emisores esenciales de antemano para asegurarte de que tu sitio funcione según lo previsto.
// Prioritize your critical token issuer.
document.hasPrivateToken('https://critical-issuer.example')
.then(hasToken => {
if (hasToken) {
// Use the token or perform actions based on its availability.
} else {
// Handle the case where the token is not available.
}
});
// Load third-party scripts or secure another token issuer (up to two in total).
Prácticas recomendadas y solución de problemas del servidor
Para que tu servidor emisor y canjeador funcione de manera eficaz, te recomendamos que implementes las siguientes prácticas recomendadas para asegurarte de no tener problemas de acceso, seguridad, registro o tráfico en PST.
- Tus extremos deben aplicar una criptografía sólida con TLS 1.3 o 1.2.
- Tu infraestructura debe estar preparada para manejar volúmenes de tráfico variables (incluidos los aumentos repentinos).
- Asegúrate de que tus claves estén protegidas y sean seguras, y de que estén alineadas con tu política de control de acceso, tu estrategia de administración de claves y tus planes de continuidad del negocio.
- Agrega métricas de observabilidad a tu pila para asegurarte de tener visibilidad para comprender el uso, los cuellos de botella y los problemas de rendimiento después de pasar a producción.
Más información
- Revisa la documentación para desarrolladores:
- Comienza por leer la descripción general para familiarizarte con PST y sus capacidades.
- Mira el video de presentación de PST.
- Prueba la demo de PST.
- También lee la explicación de la API para obtener más detalles al respecto.
- Obtén más información sobre las especificaciones actuales de la API.
- Contribuye a la conversación a través de los problemas de GitHub o las llamadas del W3C.
- Para comprender mejor la terminología, consulta el glosario de Privacy Sandbox.
- Para obtener más información sobre los conceptos de Chrome, como "prueba de origen" o "marcas de Chrome", revisa los videos y artículos breves disponibles en goo.gle/cc.