No passado, os 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 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 de suporte por outros meios.
Os tokens de estado particular oferecem uma maneira de compartilhar informações na Web, mas de uma forma que preserva a privacidade, com controles sobre a quantidade de dados que podem 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 entre humanos reais e bots, sem rastreamento passivo.
Este documento descreve os detalhes técnicos para implementar tokens de estado particular (PST, na sigla em inglês). Para um resumo mais geral, consulte a Visão geral do PST.
Como os tokens de estado particular funcionam?
A principal relação a ser compreendida no PST é entre emissores e resgatadores. Os emissores e os resgatadores podem estar na mesma empresa.
- Emissores: essas entidades têm algum 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 esse usuário é um bot ou não) e pedir para resgatar um token do emissor para entender a confiabilidade desse usuário.
Cada interação de PST exige que emissores e resgatadores trabalhem juntos para compartilhar sinais na Web. Esses indicadores são valores grosseiros 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 essas informações estejam disponíveis em todos os contextos podem se beneficiar dos 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 do PST ocorre em três fases:
- Emissão de tokens
- Resgatar tokens
- Encaminhamento de 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 faz uma solicitação para resgatar o token emitido para ler o valor dele. Na fase final, a parte que resgata recebe um registro de resgate (RR, na sigla em inglês) com o valor que estava contido no token. Essa parte pode usar esse registro como uma atestação do usuário para vários fins.
Definir sua estratégia de tokens
Para definir sua estratégia de token, você precisa entender os principais conceitos do PST (tokens e registros de resgate), variáveis, comportamentos e limitações para poder 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 emiti-lo. Essas informações podem ser usadas para decidir se um token será resgatado ou não durante o processo de resgate. Os dados do 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. As novas chamadas de resgate vão usar RRs em cache sempre que possível, em vez de gerar uma solicitação para o emissor.
- Novos tokens são emitidos (máximo de 500 por emissor, site e dispositivo).
- Todos os tokens são armazenados no dispositivo (semelhante ao armazenamento de cookies).
- Se nenhum RR ativo for encontrado, novos RRs poderão ser gerados 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.
- As novas chamadas de resgate vão atingir o cache local (nenhuma RR nova será gerada).
Depois de definir seu caso de uso, defina a duração do RR com cuidado, pois isso vai definir quantas vezes você poderá usá-lo no caso.
Entenda os seguintes comportamentos e variáveis importantes antes de definir sua estratégia:
| Variável / comportamento | Descrição | Uso em potencial |
|---|---|---|
| Metadados da chave do token | Cada token pode ser emitido usando uma e apenas uma chave criptográfica, e no PST há uma limitação de seis chaves por emissor. | Uma maneira possível de usar essa variável é definir um intervalo de confiança para seus tokens com base nas chaves criptográficas. Por exemplo, chave 1 = confiança alta, enquanto chave 6 = sem confiança. |
| Data de validade do token | A data de validade do token é a mesma 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 de 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 necessários para o caso de uso a cada 48 horas. |
| Número máximo de emissores por origem de nível superior | No momento, o número máximo de emissores por origem de nível superior é de dois. | Defina cuidadosamente os emissores de cada página. |
| Tokens por emissor em um dispositivo | O número máximo de tokens por emissor em um dispositivo específico é de 500. | Mantenha o número de tokens abaixo de 500 por emissor. Processe os erros na sua página da Web ao tentar emitir tokens. |
| Rotação de chaves | Todos os emissores de PST precisam expor um endpoint com chaves de confirmação que podem ser alteradas a cada 60 dias. Qualquer rotação mais rápida será ignorada. | Se as chaves expirarem em menos de 60 dias, será obrigatório atualizar os compromissos de chaves antes dessa data para evitar interrupções (consulte os detalhes). |
| Duração do registro de resgate | A duração 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 haja indicadores de resgate frescos o suficiente. | Como há um limite de taxa de resgate de dois tokens a cada 48 horas, é importante definir a vida útil do RR para que seja possível executar chamadas de resgate com sucesso por pelo menos esse período (a vida útil do RR precisa ser definida de acordo com isso). É recomendável definir esse período na ordem de semanas. |
Exemplos de cenários
Cenário 1: a vida útil do RR é menor que 24 horas (t=t) e a resgate é realizada várias vezes durante a janela de 48 horas.
Cenário 2: a duração da RR é de 24 horas e a resgate é realizada várias vezes durante a janela de 48 horas.
Cenário 3: a duração do RR é de 48 horas e a troca é realizada várias vezes durante esse período.
Executar a demonstração
Antes de adotar o PST, recomendamos que você faça a demonstração. Para testar a demonstração do PST , você precisa executar o Chrome com flags para ativar os principais compromissos do emissor de demonstração. Siga as instruções disponíveis na página de demonstração.
Ao executar essa demonstração, o navegador usa os servidores de emissor e de resgate de demonstração para fornecer e consumir tokens.
Considerações técnicas
Para que a demonstração funcione melhor, siga estas etapas:
- Pare todas as instâncias do Chrome antes de executar o Chrome com flags.
- Se você estiver executando em uma máquina Windows, consulte este guia sobre como transmitir parâmetros para o binário executável do Chrome.
- Abra o Chrome DevTools em Applications > Storage > Private State Tokens enquanto usa o aplicativo de demonstração para conferir os tokens emitidos/resgatados pelo emissor de demonstração.
Configurar para adoção
Tornar-se 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 o PST como emissor, faça o processo de registro de emissor.
Para se inscrever para 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 de 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 vai começar a buscar essas chaves.
Servidores do emissor
Emissores e resgatadores são os principais atores do PST. Servidores e tokens são as principais ferramentas do PST. Já fornecemos alguns detalhes sobre tokens e na documentação do GitHub, mas queremos oferecer mais detalhes sobre os servidores PST. Para configurar o emissor do PST, primeiro é necessário configurar um servidor emissor.
Implantar seu ambiente: servidores do emissor
Para implementar o servidor emissor de tokens, você precisa criar seu próprio aplicativo do lado do servidor que expõe endpoints HTTP.
O componente do emissor é composto por dois módulos principais: (1) o servidor do emissor e (2) o emissor do token.
Como em todos os aplicativos voltados para a Web, recomendamos uma camada extra de proteção ao servidor do emissor.
Servidor emissor: no exemplo de implementação, o servidor emissor é um servidor Node.js que usa a estrutura Express para hospedar os endpoints HTTP do emissor. Confira o exemplo de código no GitHub.
Emissor de token: o componente criptográfico do emissor não exige nenhuma linguagem específica, mas devido aos requisitos de desempenho desse componente, fornecemos uma implementação em 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.
Chaves: o componente do emissor de tokens usa chaves EC personalizadas para criptografar tokens. Essas chaves precisam ser protegidas e armazenadas em um local seguro.
Requisitos técnicos para servidores emissores
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): neste endpoint, os detalhes da chave pública de criptografia ficam disponíveis para os navegadores para confirmar que o servidor é legítimo. - 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.
Como mencionado anteriormente, devido ao tráfego alto esperado que esse servidor vai processar, recomendamos que você o implante usando uma infraestrutura escalonável (por exemplo, em um ambiente de nuvem) para poder ajustar seu back-end com base em uma demanda variável.
Enviar uma chamada para o servidor do emissor
Implemente uma chamada de busca de site no seu stack de emissor para emitir novos tokens.
// issuer request
await fetch("/.well-known/private-state-token/issuance", {
method: "POST",
privateToken: {
version: 1,
operation: "token-request"
}
});
Servidores do redentor
Você vai precisar implementar o serviço de resgate de tokens criando seu próprio aplicativo do lado do servidor. Isso permite que você leia os tokens que um emissor envia. As etapas a seguir descrevem como resgatar tokens e como ler os registros de resgate associados a eles.
É possível 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, você precisará implementar pelo menos dois endpoints HTTP para seu servidor de resgate:
/.well-known/private-state-token/redemption: endpoint em que todo o resgate de tokens será processado. Esse endpoint será onde o componente de resgate de token será integrado.
Enviar uma chamada para o servidor do resgatador
Para resgatar tokens, você precisa implementar uma chamada de busca de site na sua pilha de redimidores para resgatar os tokens emitidos anteriormente.
// redemption request
await fetch("/.well-known/private-state-token/redemption", {
method: "POST",
privateToken: {
version: 1,
operation: "token-redemption",
refreshPolicy: "none"
}
});
Consulte o exemplo de código.
Depois de resgatar um token, você pode enviar 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>]
}
});
Consulte o exemplo de código.
Implantar a implementação
Para testar a 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 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 (~ <1 milhão de visitas/mês): comece implantando a API para um público-alvo pequeno.
- Você é o proprietário e controla: se necessário, é possível desativar rapidamente a implementação sem aprovações complexas.
- Não mais de um emissor: para limitar a quantidade de tokens e simplificar os testes.
- Não mais de dois resgatadores: você precisa simplificar 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 subrecursos 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 dessas 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.
Para desativar a emissão ou resgate de tokens PST em páginas específicas do seu site, inclua 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 ao PST. Como parâmetros para a lista de origem 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 na sua 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 para todos os recursos de várias origens, defina a lista de origem como *.
Saiba como controlar os recursos da Sandbox de privacidade 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 "Aplicação":
Leia mais sobre essa integração do DevTools.
Práticas recomendadas para clientes
Se as funções essenciais do seu site dependem de determinados emissores de token, priorize-os. Chame hasPrivateToken(issuer) para esses emissores preferidos 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 os scripts de terceiros também podem tentar chamar hasPrivateToken(issuer) para priorizar os próprios emissores preferidos. Portanto, garanta os emissores essenciais com antecedência 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 práticas recomendadas a seguir para garantir que você não encontre problemas de acesso, segurança, registro ou tráfego para o PST.
- Os endpoints precisam aplicar criptografia forte usando o TLS 1.3 ou 1.2.
- Sua infraestrutura precisa estar pronta para lidar com volumes de tráfego variáveis, incluindo picos.
- Confira se as chaves estão protegidas e seguras, alinhadas à 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 produção.
Mais informações
- Consulte a documentação para desenvolvedores:
- Comece lendo a visão geral para se familiarizar com a PST e os recursos dela.
- Assista ao vídeo de introdução da PST.
- Teste a demonstração do PST.
- Leia também o explicativo da API para entender mais detalhes sobre ela.
- Leia mais sobre a especificação atual da API.
- Contribua com a conversa nas issues do GitHub ou nas chamadas do W3C.
- Para entender melhor a terminologia, consulte o glossário do Sandbox de privacidade.
- Para saber mais sobre os conceitos do Chrome, como "teste de origem" ou "flags do Chrome", assista os vídeos curtos e os artigos disponíveis em goo.gle/cc.