No passado, cookies de terceiros eram usados para armazenar e transmitir informações sobre o estado de um usuário, como o status de login, informações sobre o dispositivo que ele está usando ou se ele é conhecido e confiável. Por exemplo, se o usuário fez login com o SSO, se o usuário tem determinado tipo de dispositivo compatível ou se o usuário é conhecido e confiável. Com o uso suspenso do suporte a cookies de terceiros, muitos desses casos de uso precisarão ser aceitos por outros meios.
Os tokens de estado particular oferecem uma maneira de compartilhar informações na Web, mas de maneira preservando a privacidade, com controles sobre a quantidade de dados que podem realmente ser compartilhados.
Os tokens de estado particular (anteriormente 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 a implementação de tokens de estado particular (PST, na sigla em inglês). Para um resumo mais detalhado, consulte a visão geral da PST.
Como funcionam os tokens de estado particular?
A principal relação a ser compreendida na PST é entre emissores e resgates. Emissores e resgates podem estar dentro da mesma empresa.
- Emissores: essas entidades têm algum indicador sobre um usuário (por exemplo, se esse usuário é um bot ou não) e as incorpora a um token armazenado no dispositivo do usuário (mais detalhes nas próximas seções).
- Resgates: essas entidades podem não ter um sinal sobre um usuário, mas precisam saber algo sobre ele (por exemplo, se esse usuário é um bot ou não) e pedir para resgatar um token do emissor para entender a confiabilidade desse usuário.
Todas as interações da PST exigem que os emissores e os resgates trabalhem juntos para compartilhar indicadores na Web. Esses sinais 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?
As empresas que estão tomando decisões de confiança e querem que as 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 PST.
Emitir e resgatar tokens
A implementação do PST ocorre em três fases:
- Emissão de tokens
- Como resgatar tokens
- Encaminhamento do registro 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 fará uma solicitação para resgatar o token que foi emitido para ler o valor desse token. Na fase final, a parte que faz o resgate recebe um registro de resgate (RR, na sigla em inglês) com o valor que estava contido no token. Essa parte resgate poderá usar esse registro como um atestado desse usuário para várias finalidades.
Defina sua estratégia de token
Para definir sua estratégia de token, você precisa entender os principais conceitos da PST (tokens e registros de resgate), variáveis, comportamentos e limitações para pensar sobre o possível uso 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 que informam qual chave o emissor usou para emiti-lo. Essas informações podem ser usadas para decidir entre resgatar ou não um token durante o processo de resgate. Os dados 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, na sigla em inglês) é armazenado no dispositivo. Esse armazenamento funciona como um cache para resgates futuros. Há um limite de resgate de dois tokens a cada 48 horas por dispositivo, página e emissor. Novas chamadas de resgate vão usar RRs armazenados em cache sempre que possível, em vez de causar uma solicitação ao emissor.
- Novos tokens são emitidos (máximo de 500 por emissor, site e dispositivo).
- Todos os tokens são armazenados no armazenamento de tokens no dispositivo (semelhante ao armazenamento de cookies).
- Se nenhuma RR ativa for encontrada, novas RRs poderão ser geradas após a emissão (máximo de 2 a cada 48 horas).
- Os RRs são considerados ativos até a expiração e serão usados como um cache local.
- Novas chamadas de resgate vão atingir o cache local (nenhum RR novo é gerado).
Depois de definir seu caso de uso, defina a vida útil da RR com cuidado, porque isso vai definir quantas vezes você poderá usá-la no seu caso.
Entenda os comportamentos e as variáveis essenciais a seguir antes de definir sua estratégia:
| Variável / comportamento | Descrição | Uso potencial |
|---|---|---|
| Metadados da chave de token | Cada token pode ser emitido usando apenas uma chave criptográfica. No PST, há uma limitação de seis chaves por emissor. | Uma possível maneira de usar essa variável é definir um intervalo de confiança em seus tokens com base em suas chaves criptográficas (por exemplo, chave 1 = alta confiança e chave 6 = nenhuma confiança). |
| Data de validade do token | A data de validade do token é igual à data de validade da chave. | As chaves podem ser alternadas pelo menos a cada 60 dias, e todos os tokens emitidos com chaves inválidas também são considerados inválidos. |
| Limite da taxa de resgate de tokens | Há um limite de dois resgates de token por dispositivo e emissor a cada 48 horas. | Depende do número estimado de resgates exigidos pelo seu caso de uso a cada 48 horas. |
| Número máximo de emissores por origem de nível superior | Atualmente, o número máximo de emissores por origem de nível superior é dois. | Defina com cuidado os emissores de cada página. |
| Tokens por emissor em um dispositivo | Atualmente, o número máximo de tokens por emissor em um dispositivo específico é 500. | Mantenha o número de tokens abaixo de 500 por emissor. Resolva os erros na sua página da Web ao tentar emitir tokens. |
| Rotação de compromissos de chaves | Cada emissor PST precisa expor um endpoint com compromissos de chave que podem ser alterados a cada 60 dias. Qualquer rotação mais rápida que isso será ignorada. | Se as chaves vão expirar em menos de 60 dias, é obrigatório atualizar os compromissos de chaves antes dessa data para evitar interrupções. Veja os detalhes. |
| Vida útil do registro de resgate | A vida útil da RR pode ser definida para determinar uma data de validade. Como os RRs são armazenados em cache para evitar novas chamadas de resgate desnecessárias para o emissor, isso é importante para garantir que você tenha sinais de resgate atualizados o suficiente. | Como há um limite de taxa de resgate de dois tokens a cada 48 horas, é importante definir a vida útil da RR para poder executar chamadas de resgate com sucesso ao longo de pelo menos esse período. A vida útil de RR precisa ser definida de acordo com isso. Recomendamos definir esse tempo de vida na ordem de semanas. |
Exemplos de cenários
Cenário 1: a vida útil de RR é menor que 24 horas (t=t) e o resgate é realizado várias vezes durante a janela de 48 horas.
Cenário 2: a vida útil de RR é de 24 horas e o resgate é realizado várias vezes durante o período de 48 horas.
Cenário 3: a vida útil de RR é de 48 horas e o resgate é realizado várias vezes durante o período de 48 horas.
Executar a demonstração
Antes de adotar a PST, recomendamos que você configure a demonstração. Para testar a demonstração da PST , execute o Chrome com sinalizações para ativar os compromissos de chave do emissor de demonstração. Siga as instruções disponíveis na página de demonstração.
Ao executar esta demonstração, seu navegador usará o emissor da demonstração e os servidores do resgate para fornecer e consumir tokens.
Considerações técnicas
A demonstração funciona melhor se você seguir estas etapas:
- Interrompa todas as instâncias do Chrome antes de executá-lo com sinalizações.
- Se você estiver executando em uma máquina com Windows, consulte este guia sobre como transmitir parâmetros para o binário executável do Chrome.
- Abra o Chrome DevTools em Aplicativos > Armazenamento > Tokens de estado particular enquanto usa o aplicativo de demonstração para ver os tokens emitidos/resgatados pelo emissor de demonstração.
Configurar para adoção
Torne-se um emissor
Os emissores têm um papel fundamental na PST. Eles atribuem valores aos tokens para determinar se um usuário é ou não um bot. Se você quiser começar a usar o PST como emissor, conclua o processo de registro do emissor.
Para se inscrever e se tornar um emissor, o operador do site do emissor precisa abrir um novo problema no repositório do GitHub usando o modelo "Novo emissor PST". Siga as orientações no repositório para preencher o problema. Depois que um endpoint for verificado, ele será mesclado a esse repositório, e a infraestrutura do lado do servidor do Chrome começará a buscar essas chaves.
Servidores do emissor
Emissores e resgates são os principais atores da PST. Os servidores e os tokens são as ferramentas mais importantes da PST. Já fornecemos alguns detalhes sobre tokens e na documentação do GitHub, mas queríamos oferecer mais detalhes sobre os servidores PST. Para ser configurado como um emissor do PST, primeiro é preciso configurar um servidor emissor.
Implante o ambiente: servidores do emissor
Para implementar o servidor do emissor de token, você precisa criar seu próprio aplicativo do lado do servidor expondo endpoints HTTP.
O componente do emissor é composto por dois módulos principais: (1) o servidor do emissor e (2) o emissor do token.
Assim como em todos os aplicativos voltados para a Web, recomendamos uma camada extra de proteção para o servidor do emissor.
Servidor emissor: no nosso exemplo de implementação, o servidor emissor é um Node.js que usa o framework Express para hospedar os endpoints HTTP do emissor. Confira o exemplo de código no GitHub (link em inglês).
Emissor de token: o componente criptográfico do emissor não requer nenhuma linguagem específica, mas, devido aos requisitos de desempenho desse componente, estamos fornecendo uma implementação C como exemplo, que usa a biblioteca Boring SSL para gerenciar tokens. Confira o exemplo de código do emissor e mais informações sobre a instalação no GitHub (link em inglês).
Chaves: o componente emissor do token usa chaves EC personalizadas para criptografar tokens. Essas chaves precisam ser protegidas e armazenadas em um armazenamento seguro.
Requisitos técnicos para servidores do emissor
De acordo com o protocolo, você precisará implementar pelo menos dois endpoints HTTP no servidor do emissor:
- Compromisso de chave (por exemplo,
/.well-known/private-state-token/key-commitment): é onde os detalhes da chave pública de criptografia ficam disponíveis aos navegadores para confirmar que o servidor é legítimo. - Emissão de token (por exemplo,
/.well-known/private-state-token/issuance): o endpoint emissor de token em que todas as solicitações serão processadas. Esse endpoint será o ponto de integração do componente do emissor do token.
Como mencionado anteriormente, devido ao alto tráfego esperado que esse servidor provavelmente 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 do site para a pilha do emissor a fim de emitir novos tokens.
// issuer request
await fetch("/.well-known/private-state-token/issuance", {
method: "POST",
privateToken: {
version: 1,
operation: "token-request"
}
});
Servidores do resgate
Você precisará implementar o serviço de resgate de token criando seu próprio aplicativo do lado do servidor. Isso permite que você leia os tokens enviados pelo emissor. Nas etapas a seguir, descrevemos como resgatar tokens e ler os registros de resgate associados a eles.
É possível executar o emissor e o resgate no mesmo servidor (ou grupo de servidores).
Requisitos técnicos para servidores de resgate
De acordo com o protocolo, você precisará implementar pelo menos dois endpoints HTTP para o servidor do resgate:
/.well-known/private-state-token/redemption: endpoint em que todo o resgate de tokens será processado. Esse endpoint será onde o componente resgate de token será integrado.
Enviar uma chamada para o servidor do resgate
Para resgatar tokens, você precisa implementar uma chamada de busca no site para a pilha do resgate.
// 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 (link em inglês).
Depois de resgatar um token, envie o registro de resgate (RR, na sigla em inglês) 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 (link em inglês).
Implantar sua implementação
Para testar a implementação, primeiro navegue até a página da Web em que a chamada emissora é feita e confirme se os tokens foram criados seguindo sua lógica. Verifique no 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:
- Pequeno número de visitas mensais (aproximadamente < 1 milhão de visitas/mês): você deve começar implantando a API para um público pequeno primeiro
- Você controla e controla: 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 a fim de simplificar o teste.
- No máximo dois resgates: é necessário simplificar a solução de problemas em caso de problemas.
Solução de problemas
É possível inspecionar os 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 e solução de problemas de servidor
Para que o emissor e o servidor do resgate operem de maneira eficaz, recomendamos a implementação das seguintes práticas recomendadas para garantir que você não encontre nenhum desafio de acesso, segurança, geração de registros ou tráfego para 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 à sua política de controle de acesso, à estratégia de gerenciamento de chaves e aos planos de continuidade de negócios.
- Adicione métricas de observabilidade à pilha para garantir que você tenha visibilidade para entender o uso, os gargalos e os problemas de desempenho depois da produção.
Mais informações
- Consulte a documentação para desenvolvedores:
- Comece lendo a visão geral para conhecer a PST e os recursos dele.
- Assista o vídeo de introdução à PST.
- Teste a demonstração da PST.
- Leia também a explicação da API para entender mais detalhes sobre ela.
- Leia mais sobre a especificação atual da API.
- Contribua com a conversa por meio de problemas do GitHub ou chamadas do W3C.
- Para entender melhor qualquer terminologia, consulte o glossário do Sandbox de privacidade.
- Para saber mais sobre os conceitos do Chrome, como "teste de origem" ou "sinalizações do Chrome", veja os vídeos curtos e artigos disponíveis em goo.gle/cc.