Guía para desarrolladores de Private State Tokens

En el pasado, las cookies de terceros se utilizaron para almacenar y transmitir información sobre el estado de un usuario, como su estado de acceso, información sobre el dispositivo que utiliza o si se lo conoce y confía en él. Por ejemplo, si el usuario accedió con SSO, si tiene un cierto tipo de dispositivo compatible o si es un usuario conocido y de confianza. Dado que se dejará de admitir las cookies de terceros, muchos de estos casos de uso deberán admitirse por otros medios.

Los tokens de estado privado 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 realmente se pueden compartir.

Los Private State Tokens (anteriormente conocidos como Trust Tokens) permiten que se transmita la confianza en la autenticidad de un usuario de un contexto a otro, a la vez que ayudan a los sitios a combatir el fraude y distinguir a los bots de los seres humanos, sin el seguimiento pasivo.

En este documento, se describen los detalles técnicos para implementar los tokens de estado privado (PST). Para obtener un esquema más general, consulta la descripción general de PST.

¿Cómo funcionan los Private State Tokens?

La relación clave que se debe comprender en PST es la que existe entre los emisores y los usuarios que canjean los puntos. 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 ese usuario es un bot o no) y lo incorporan en un token que se almacena en el dispositivo del usuario (se proporcionan más detalles en las siguientes secciones).
• Canjeadores: Es posible que estas entidades no tengan un indicador sobre un usuario, pero necesitan saber algo sobre él (por ejemplo, si es un bot o no) y solicitan canjear un token del emisor para comprender la confiabilidad de ese usuario.

Cada interacción de PST requiere que los emisores y los usuarios que canjean trabajen juntos para compartir indicadores en la Web. Esos indicadores son valores aproximados que no son lo suficientemente detallados como 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 los PST.

Emite y canjea tokens

La implementación del PST se realiza en tres fases:

1. Emisión de tokens
2. Canje de tokens
3. Reenvío de registros de canje

En la primera fase, se emiten tokens para un navegador (por lo general, después de algún tipo de validación). En la segunda fase, otra entidad realizará 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 contenía el token. Luego, esa parte que canjea puede usar ese registro como una certificación de ese usuario para diversos 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.

Registros de tokens y 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ó la entidad emisora para emitirlo. Esa información se puede usar para decidir si se canjea 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 se puede acceder a ellos a través de la API de PST.

Cuando se canjea un token, el registro de canje (RR) se almacena en el dispositivo. Este almacenamiento actúa como caché para futuros canjes. 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.

1. Se emiten tokens nuevos (máximo 500 por emisor, sitio y dispositivo).
2. Todos los tokens se almacenan en el almacén de tokens del dispositivo (similar al almacén de cookies).
3. Si no se encuentra ningún RR activo, se pueden generar RR nuevos después de la emisión (máximo de 2 cada 48 horas).
4. Los RR se consideran activos hasta su vencimiento y se usarán como caché local.
5. Las nuevas llamadas de canje alcanzarán la caché local (no se generarán nuevos RR).

Después de definir tu caso de uso, debes definir cuidadosamente la vida útil de tus RR, ya que esto determinará cuántas veces podrás usarlos en tu caso.

Antes de definir tu estrategia, asegúrate de comprender los siguientes comportamientos y variables críticos:

Situaciones de ejemplo

Situación 1: La vida útil del RR es inferior a 24 horas (t=t) y el canje se realiza varias veces durante el período de 48 horas.

Situación 2: La vida útil del RR es de 24 horas y el canje se realiza varias veces durante el período de 48 horas.

Situación 3: La vida útil del RR es de 48 horas y el canje se realiza varias veces durante el período de 48 horas.

Ejecuta la demostración

Antes de adoptar PST, te recomendamos que configures la demostración.

Cuando ejecutas esta demostración, tu navegador usa los servidores de la entidad emisora y del canje de la demostración 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 el programa en una máquina con Windows, consulta esta guía para saber cómo pasar parámetros al objeto binario ejecutable de Chrome.
• Abre las Herramientas para desarrolladores de Chrome en Applications > Storage > Private State Tokens mientras usas la aplicación de demostración para ver los tokens emitidos o canjeados por el emisor de demostración.

Configuración para la adopción

En esta sección, se explican los requisitos para convertirse en emisor o canjeador de PST.

Conviértete en entidad emisora

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, deberás registrarte completando el proceso de registro de emisor.

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 verifique un extremo, se combinará en este repositorio y la infraestructura del servidor de Chrome comenzará a recuperar esas claves.

Servidores de la entidad emisora

Las entidades emisoras y los usuarios que canjean son los actores clave del PST, mientras que los servidores y los tokens son las herramientas clave del 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 de PST. Para configurar tu cuenta como emisor de PST, primero debes configurar un servidor de emisión.

Implementa tu entorno: servidores de la entidad emisora

Para implementar el servidor de emisión de tokens, deberás compilar tu propia aplicación del servidor que exponga extremos HTTP.

El componente de la entidad emisora se compone de dos módulos principales: (1) el servidor de la entidad emisora y (2) la entidad emisora de tokens.

Al igual que con todas las aplicaciones orientadas a la Web, te recomendamos que agregues una capa de protección adicional a tu servidor de la entidad emisora.

1. Servidor de la entidad emisora: En nuestra implementación de ejemplo, el servidor de emisión es un servidor Node.js que usa el framework de Express para alojar los extremos HTTP de la entidad emisora. Puedes consultar muestras de código en GitHub.

2. 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 BoringSSL para administrar tokens. Puedes encontrar el ejemplo de código del emisor y más información sobre la instalación en GitHub.

3. Claves: El componente de la entidad emisora del token usa claves EC personalizadas para encriptar tokens. Estas claves deben protegerse y almacenarse en un almacenamiento seguro.

Requisitos técnicos para los servidores de la entidad emisora

Según el protocolo, deberás implementar al menos dos extremos HTTP en tu servidor de la entidad emisora:

• Confirmación de clave (por ejemplo, /.well-known/private-state-token/key-commitment): En este extremo, los detalles de tu clave pública de encriptación estarán disponibles para los navegadores para confirmar que tu servidor es legítimo.
  • Muestra de código en GitHub
  • Ver la demostración
• 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 del componente del emisor de tokens.
  • Muestra de código en GitHub
  • Ver la demostración

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 de la entidad emisora

Implementa una llamada de recuperación del sitio web en tu pila de la entidad emisora 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

Deberás implementar el servicio de canje de tokens creando 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 optar por 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á el canje de todos los tokens. Este extremo será donde se integrará el componente de canje de tokens.
  • Código de ejemplo en GitHub
  • Demostración

Envía una llamada al servidor del canjeador

Para canjear tokens, deberás implementar una llamada de recuperación del sitio web en tu pila de canje 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 integració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 crearon los RR según tu lógica.

Implementación en el mundo real

Te recomendamos que elijas sitios web objetivo que formen parte de tu caso de uso específico:

• Pocas visitas mensuales (menos de 1 millón de visitas por mes): Primero, debes implementar la API para un público pequeño.
• Eres propietario y tienes el control: 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 personas que canjean el código: Debes simplificar la solución de problemas en caso de que surjan inconvenientes.

Política de permisos

Para que funcione correctamente, la API de PST debe estar disponible para la página de nivel superior y cualquier subrecurso que use la API.

La operación de solicitud de token se controla con la directiva private-state-token-issuance. Las operaciones token-redemption y send-redemption-record se controlan con 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.

Puedes inhabilitar la emisión o el canje de tokens de PST para páginas específicas de tu sitio si incluyes 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 al PST. Como parámetros para la lista de orígenes del encabezado, usa self y cualquier origen al que desees 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, configura 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, configura la lista de orígenes como *.

Obtén más información para controlar las funciones de Privacy Sandbox con la Política de permisos o profundiza en 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 Aplicación, haz lo siguiente:

Obtén más información sobre esta integración de Herramientas para desarrolladores.

Prácticas recomendadas para clientes

Si las funciones críticas de tu sitio web dependen de ciertos emisores de tokens, priorízalos. Llama a hasPrivateToken(issuer) para estos emisores preferidos antes de cargar cualquier otro script. Esto es fundamental para evitar posibles errores de canje.

La cantidad de emisores por nivel superior está limitada a dos, y los secuencias de comandos de terceros también pueden intentar llamar a hasPrivateToken(issuer) para priorizar sus propios emisores preferidos. Por lo tanto, protege tus entidades emisoras esenciales por adelantado 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 del servidor y solución de problemas

Para que el servidor del emisor y el del canjeador funcionen de manera eficaz, te recomendamos que implementes las siguientes prácticas recomendadas para asegurarte de que no surjan problemas de acceso, seguridad, registro o tráfico para PST.

• Tus endpoints deben aplicar una criptografía sólida con TLS 1.3 o 1.2.
• Tu infraestructura debe estar lista para manejar volúmenes de tráfico variables (incluidos los picos).
• Asegúrate de que tus claves estén protegidas y seguras, y que se alineen con tu política de control de acceso, estrategia de administración de claves y planes de continuidad empresarial.
• Agrega métricas de observabilidad a tu pila para asegurarte de tener visibilidad y comprender el uso, los cuellos de botella y los problemas de rendimiento después de pasar a producción.

Más información

1. Revisa la documentación para desarrolladores:
   1. Comienza por leer la descripción general para conocer PST y sus capacidades.
   2. Mira el video de introducción a PST.
   3. Prueba la demostración de PST.
   4. También puedes leer la explicación de la API para comprender más detalles sobre ella.
   5. Obtén más información sobre la especificación actual de la API.
2. Participa en la conversación a través de problemas de GitHub o llamadas de W3C.
3. Para comprender mejor la terminología, consulta el glosario de Privacy Sandbox.
4. Para obtener más información sobre los conceptos de Chrome, como "prueba de origen" o "Chrome flags", revisa los videos y artículos cortos disponibles en goo.gle/cc.