Guia para desenvolvedores de tokens de estado particular

No passado, os cookies de terceiros eram usados para armazenar e transmitir informações sobre o estado de um usuário, como status de login, informações sobre o dispositivo usado ou se ele era conhecido e confiável. Por exemplo, se o usuário fez login com SSO, se ele tem um determinado tipo de dispositivo compatível ou se ele é conhecido e confiável. Com a descontinuação do suporte a cookies de terceiros, muitos desses casos de uso precisarão ser compatíveis com outros meios.

Os tokens de estado particular oferecem uma maneira de compartilhar informações na Web, mas de uma forma que preserva a privacidade, usando controles sobre a quantidade de dados que podem ser compartilhados.

Os tokens de estado particular (antes conhecidos como tokens de confiança) permitem que a confiança na autenticidade de um usuário seja transmitida de um contexto para outro, ajudando os sites a combater fraudes e distinguir bots de pessoas reais, sem rastreamento passivo.

Este documento descreve os detalhes técnicos para implementar tokens de estado privado (PSTs, na sigla em inglês). Para um resumo mais geral, consulte a visão geral do PST.

Como os Private State Tokens funcionam?

A principal relação a ser entendida no PST é entre emissores e resgatadores. Os emissores e os resgatadores podem estar na mesma empresa.

• Emissores: essas entidades têm um indicador sobre um usuário (por exemplo, se ele é um bot ou não) e incorporam esse indicador a um token armazenado no dispositivo do usuário. Mais detalhes nas próximas seções.
• Resgatadores: essas entidades podem não ter um indicador sobre um usuário, mas precisam saber algo sobre ele (por exemplo, se ele é um bot ou não) e pedem para resgatar um token do emissor para entender a confiabilidade desse usuário.

Toda interação do PST exige que emissores e beneficiários trabalhem juntos para compartilhar sinais na Web. Esses indicadores são valores aproximados que não são detalhados o suficiente para identificar indivíduos.

Os tokens de estado particular são adequados para mim?

Empresas que tomam decisões de confiança e querem que essas informações estejam disponíveis em todos os contextos podem se beneficiar das PSTs. Para mais informações sobre possíveis casos de uso de PSTs, consulte nossa documentação sobre casos de uso de PSTs.

Emitir e resgatar tokens

A implementação da PST ocorre em três fases:

1. Emissão de tokens
2. Resgate de tokens
3. Encaminhamento de registros de resgate

Na primeira fase, os tokens são emitidos para um navegador (geralmente após algum tipo de validação). Na segunda fase, outra entidade vai fazer uma solicitação para resgatar o token emitido para ler o valor nele. Na fase final, o beneficiário recebe um registro de resgate (RR) com o valor contido no token. A parte resgatadora pode usar esse registro como uma atestação do usuário para várias finalidades.

Definir sua estratégia de token

Para definir sua estratégia de token, é necessário entender os principais conceitos do PST (tokens e registros de resgate), variáveis, comportamentos e limitações para pensar no uso potencial deles no seu caso de uso.

Tokens e registros de resgate: qual é a relação entre eles?

Cada dispositivo pode armazenar até 500 tokens por site de nível superior e emissor. Além disso, cada token tem metadados informando qual chave o emissor usou para emitir o token. Essas informações podem ser usadas para decidir se um token será resgatado ou não durante o processo de resgate. Os dados de PST são armazenados internamente pelo navegador no dispositivo do usuário e só podem ser acessados pela API PST.

Quando um token é resgatado, o registro de resgate (RR) é armazenado no dispositivo. Esse armazenamento funciona como um cache para resgates futuros. Há um limite de dois resgates de tokens a cada 48 horas, por dispositivo, página e emissor. Novas chamadas de resgate vão usar RRs em cache sempre que possível, em vez de fazer uma solicitação ao emissor.

1. Novos tokens são emitidos (máximo de 500 por emissor, site e dispositivo).
2. Todos os tokens são armazenados no repositório de tokens do dispositivo (semelhante a um repositório de cookies).
3. Se não houver um RR ativo, novos RRs poderão ser gerados após a emissão (máximo de dois a cada 48 horas).
4. As RRs são consideradas ativas até a expiração e serão usadas como um cache local.
5. Novas chamadas de resgate vão atingir o cache local (nenhum novo RR será gerado).

Depois de definir o caso de uso, defina cuidadosamente o ciclo de vida das respostas geradas automaticamente, já que isso vai definir quantas vezes você poderá usá-las no seu caso.

Entenda os seguintes comportamentos e variáveis críticos antes de definir sua estratégia:

Exemplos de cenários

Cenário 1: o ciclo de vida do RR é inferior a 24 horas (t=t) e o resgate é realizado várias vezes durante a janela de 48 horas.

Cenário 2: o ciclo de vida da RR é de 24 horas e o resgate é feito várias vezes durante o período de 48 horas.

Cenário 3: o ciclo de vida da RR é de 48 horas e o resgate é feito várias vezes durante a janela de 48 horas.

Executar a demonstração

Antes de adotar o PST, recomendamos que você configure a demonstração.

Ao executar esta demonstração, seu navegador usa os servidores de emissor e resgatador de demonstração para fornecer e consumir tokens.

Considerações técnicas

Para aproveitar ao máximo a demonstração, siga estas etapas:

• Pare todas as instâncias do Chrome antes de executar o navegador com flags.
• Se você estiver usando uma máquina Windows, consulte este guia sobre como transmitir parâmetros ao binário executável do Chrome.
• Abra o Chrome DevTools em Applications > Storage > Private State Tokens ao usar o aplicativo de demonstração para conferir os tokens emitidos ou resgatados pelo emissor de demonstração.

Configurar para adoção

Esta seção explica os requisitos para se tornar um emissor ou resgatador de PST.

Seja um emissor

Os emissores têm um papel fundamental no PST. Eles atribuem valores aos tokens para determinar se um usuário é um bot ou não. Se você quiser começar a usar os PSTs como um emissor, precisará se registrar concluindo o processo de registro de emissor.

Para se inscrever como emissor, o operador do site precisa abrir um novo problema no repositório do GitHub usando o modelo "Novo emissor de PST". Siga as orientações no repositório para preencher o problema. Depois que um endpoint é verificado, ele é mesclado a este repositório, e a infraestrutura do lado do servidor do Chrome começa a buscar essas chaves.

Servidores do emissor

Os emissores e resgatadores são os principais atores do PST, e os servidores e tokens são as principais ferramentas. Já fornecemos alguns detalhes sobre tokens e na documentação do GitHub, mas queríamos oferecer mais detalhes sobre os servidores PST. Para se configurar como um emissor de PST, primeiro é necessário configurar um servidor de emissão.

Implante seu ambiente: servidores emissores

Para implementar o servidor emissor de tokens, você precisa criar seu próprio aplicativo do lado do servidor que exponha endpoints HTTP.

O componente emissor é composto por dois módulos principais: (1) o servidor emissor e (2) o emissor de tokens.

Como em todos os aplicativos voltados para a Web, recomendamos uma camada extra de proteção para o servidor do emissor.

1. Servidor de emissão: na nossa implementação de exemplo, o servidor de emissão é um servidor Node.js que usa a framework Express para hospedar os endpoints HTTP do emissor. Confira exemplos de código no GitHub.

2. Emissor de token: o componente criptográfico do emissor não exige nenhuma linguagem específica, mas, devido aos requisitos de desempenho desse componente, estamos fornecendo uma implementação em C como exemplo, que usa a biblioteca Boring SSL para gerenciar tokens. Você encontra o exemplo de código do emissor e mais informações sobre a instalação no GitHub.

3. Chaves: o componente emissor de token usa chaves EC personalizadas para criptografar tokens. Elas precisam ser protegidas e armazenadas em um local seguro.

Requisitos técnicos para servidores emissores

De acordo com o protocolo, é necessário implementar pelo menos dois endpoints HTTP no servidor do emissor:

• Comprometimento de chave (por exemplo, /.well-known/private-state-token/key-commitment): esse endpoint é onde os detalhes da sua chave pública de criptografia ficam disponíveis para os navegadores confirmarem que seu servidor é legítimo.
  • Exemplo de código no GitHub
  • Confira a demonstração
• Emissão de token (por exemplo, /.well-known/private-state-token/issuance): o endpoint de emissão de token em que todas as solicitações de token serão processadas. Esse endpoint será o ponto de integração do componente emissor de token.
  • Exemplo de código no GitHub
  • Confira a demonstração

Como mencionado anteriormente, devido ao alto tráfego esperado que esse servidor vai processar, recomendamos que você o implante usando uma infraestrutura escalonável (por exemplo, em um ambiente de nuvem) para ajustar o back-end com base em uma demanda variável.

Enviar uma chamada para o servidor do emissor

Implemente uma chamada de busca de site na sua pilha de emissor para emitir novos tokens.

 // issuer request
    await fetch("/.well-known/private-state-token/issuance", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-request"
      }
    });

Veja um exemplo de código.

Servidores de resgate

Você precisa implementar o serviço de resgate de token criando seu próprio aplicativo do lado do servidor. Isso permite ler os tokens enviados por um emissor. As etapas a seguir descrevem como resgatar tokens e ler os registros de resgate associados a eles.

Você pode optar por executar o emissor e o resgatador no mesmo servidor (ou grupo de servidores).

Requisitos técnicos para servidores de resgate

De acordo com o protocolo, é necessário implementar pelo menos dois endpoints HTTP para o servidor de resgate:

• /.well-known/private-state-token/redemption: endpoint em que todas as trocas de token serão processadas. Esse endpoint será o local em que o componente de resgate de token será integrado
  • Exemplo de código no GitHub
  • Demonstração

Enviar uma chamada ao servidor de resgate

Para resgatar tokens, é necessário implementar uma chamada de busca do site na sua pilha de resgate para resgatar tokens emitidos anteriormente.

    // redemption request
    await fetch("/.well-known/private-state-token/redemption", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-redemption",
        refreshPolicy: "none"
      }
    });

Confira um exemplo de código.

Depois de resgatar um token, é possível enviar o registro de resgate (RR) fazendo outra chamada de busca:

    // 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>]
      }
    });

Confira um exemplo de código.

Implantar a implementação

Para testar sua implementação, primeiro navegue até a página da Web em que a chamada de emissão é feita e confirme se os tokens são criados de acordo com sua lógica. Verifique no seu back-end se as chamadas foram feitas de acordo com a especificação. Em seguida, navegue até a página da Web em que a chamada de resgate é feita e confirme se os RRs foram criados, seguindo sua lógica.

Implantação no mundo real

Recomendamos que você escolha sites de destino que façam parte do seu caso de uso específico:

• Número pequeno de visitas mensais (menos de 1 milhão de visitas/mês): comece implantando a API para um público pequeno.
• Você é o proprietário e tem o controle: se necessário, é possível desativar rapidamente a implementação sem aprovações complexas.
• No máximo um emissor: para limitar a quantidade de tokens e simplificar os testes.
• No máximo dois resgatadores: simplifique a solução de problemas em caso de problemas.

Política de permissões

Para funcionar corretamente, a API PST precisa estar disponível para a página de nível superior e todos os sub-recursos que usam a API.

A operação de solicitação de token é controlada pela diretiva private-state-token-issuance. As operações token-redemption e send-redemption-record são controladas pela diretiva private-state-token-redemption. No Chrome 132 e versões mais recentes, a lista de permissões para essas diretivas é definida como * (todas as origens) por padrão. Isso significa que o recurso está disponível para a página de nível superior, iframes de mesma origem e iframes de origem cruzada sem delegação explícita.

É possível desativar a emissão ou o resgate de tokens PST em páginas específicas do seu site incluindo private-state-token-issuance=() e private-state-token-redemption=() no cabeçalho Permissions-Policy de cada página.

Também é possível usar o cabeçalho Permissions-Policy para controlar o acesso de terceiros à PST. Como parâmetros para a lista de origens do cabeçalho, use self e todas as origens que você quer permitir o acesso à API. Por exemplo, para desativar completamente o uso do PST em todos os contextos de navegação, exceto sua própria origem e https://example.com, defina os seguintes cabeçalhos de resposta HTTP:

Permissions-Policy:private-state-token-issuance=(self "https://example.com"),private-state-token-redemption=(self "https://example.com")

Para ativar a API em todos os recursos de origem cruzada, defina a lista de origens como *.

Saiba como controlar os recursos da Privacy Sandbox com a Política de permissões ou entenda melhor a Política de permissões.

Solução de problemas

É possível inspecionar PSTs nas guias "Rede" e "Aplicativo" do Chrome DevTools.

Na guia "Rede":

Na guia "Aplicativo":

Leia mais sobre essa integração do DevTools.

Práticas recomendadas para clientes

Se as funções críticas do seu site dependerem de determinados emissores de tokens, priorize-os. Chame hasPrivateToken(issuer) para esses emissores preferenciais antes de carregar outros scripts. Isso é crucial para evitar possíveis falhas de resgate.

O número de emissores por nível superior é limitado a dois, e scripts de terceiros também podem tentar chamar hasPrivateToken(issuer) para priorizar os emissores preferidos. Portanto, proteja seus emissores essenciais antecipadamente para garantir que seu site funcione conforme o esperado.

  // 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áticas recomendadas e solução de problemas do servidor

Para que o servidor do emissor e do resgatador funcione de maneira eficaz, recomendamos implementar as seguintes práticas recomendadas para evitar problemas de acesso, segurança, registro ou tráfego para o PST.

• Seus endpoints precisam aplicar criptografia forte usando TLS 1.3 ou 1.2.
• Sua infraestrutura precisa estar pronta para lidar com volumes de tráfego variáveis (incluindo picos).
• Verifique se as chaves estão protegidas e seguras, alinhadas com sua política de controle de acesso, estratégia de gerenciamento de chaves e planos de continuidade de negócios.
• Adicione métricas de observabilidade à sua pilha para garantir que você tenha visibilidade para entender o uso, os gargalos e os problemas de desempenho após a entrada em produção.

Mais informações

1. Consulte a documentação para desenvolvedores:
   1. Comece lendo a visão geral para conhecer a PST e os recursos dela.
   2. Assista ao vídeo de introdução à PST.
   3. Teste a demonstração do PST.
   4. Leia também a explicação da API para entender mais detalhes sobre ela.
   5. Leia mais sobre a especificação atual da API.
2. Contribua para a conversa usando problemas do GitHub ou chamadas do W3C.
3. Para entender melhor a terminologia, consulte o glossário do Sandbox de privacidade.
4. Para saber mais sobre conceitos do Chrome, como "teste de origem" ou "flags do Chrome", assista aos vídeos curtos e leia os artigos disponíveis em goo.gle/cc.