No passado, cookies de terceiros têm sido usados para armazenar e transmitir informações sobre o estado do usuário, como status de login, informações sobre o dispositivo usados ou se eles são conhecidos e confiáveis. Por exemplo, se o fez login com SSO, mesmo que ele tenha um determinado tipo de dispositivo, ou se o usuário é conhecido e confiável. Com o suporte a cookies de terceiros será descontinuado; muitos desses casos de uso precisarão de suporte de outros meios.
Os tokens de estado particular oferecem uma maneira de compartilhar informações na Web, mas forma de preservar a privacidade com controles sobre a quantidade de dados que podem realmente serão compartilhados.
Os tokens de estado particular (anteriormente conhecidos como tokens de confiança) permitem confiar a autenticidade seja transmitida de um contexto a outro e, ao mesmo tempo, ajude sites combater fraudes e distinguir bots de pessoas reais, sem rastreamento passivo.
Neste documento, descrevemos os detalhes técnicos para implementar as campanhas Tokens (PST). Para um resumo mais detalhado, consulte o Visão geral da PST.
Como funcionam os tokens de estado particular?
A principal relação a ser entendida no PST é entre emissores e resgatadores. Emissores e resgatadores podem ser da mesma empresa.
- Emissores: essas entidades têm algum sinal sobre um usuário (por (por exemplo, se o usuário é um bot ou não) e incorpora essa sinalização a uma 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 eles (por exemplo, se esse usuário é um bot ou não) e peça para resgatar um token do emissor para entender o da confiabilidade do usuário.
Cada interação da PST exige que emissores e resgatadores 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 ideais para mim?
As empresas que estão tomando decisões sobre confiança e querem que essas informações sejam disponíveis em vários contextos podem se beneficiar dos PSTs. Para saber mais sobre possíveis casos de uso de PSTs, consulte nossa documentação sobre casos de uso da PST.
Emitir e resgatar tokens
A implementação da PST ocorre em três fases:
- Como emitir tokens
- Como resgatar tokens
- Encaminhamento de registro de resgate
Na primeira fase, os tokens são emitidos para um navegador (normalmente 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 final a parte que faz o resgate recebe um registro de resgate (RR) com o valor estava contido no token. O resgate poderá, então, ser usado como atestado desse usuário para várias finalidades.
Definir sua estratégia de token
Para definir sua estratégia de token, você precisa entender os principais conceitos da PST (tokens). e resgate, variáveis, comportamentos e limitações para poder pense no possível uso delas para 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. Isso informações podem ser usadas para decidir resgatar ou não um token durante o resgate de desenvolvimento de software. 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 dois de tokens a cada 48 horas, por dispositivo, página e emissor. Novo resgate chamadas usarão RRs armazenados em cache quando 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 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é o vencimento e são usados como um cache.
- Novas chamadas de resgate vão atingir o cache local (nenhum novo RR é gerado).
Depois de definir seu caso de uso, é preciso definir cuidadosamente a vida útil do RR, como isso vai definir quantas vezes você poderá usá-las em seu caso.
Entenda os seguintes comportamentos e variáveis essenciais antes de definir sua estratégia:
| Variável / comportamento | Descrição | Potencial de uso |
|---|---|---|
| Metadados da chave de token | Cada token pode ser emitido usando apenas uma chave criptográfica e em 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 aos seus tokens com base em suas chaves criptográficas (por exemplo, chave 1 = alta confiança, enquanto a chave 6 = sem confiança). |
| Data de validade do token | A data de validade do token é a mesma da chave. | As chaves podem ser trocadas pelo menos a cada 60 dias e todos os tokens emitidos com chaves inválidas também são consideradas inválidas. |
| 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 exigidos por seu 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 | No momento, o número máximo de tokens por emissor em um dispositivo específico é 500, | Mantenha o número de tokens menor que 500 por emissor. Não se esqueça de resolver os erros na sua página da Web ao tentar resolver o problema tokens. |
| Rotação de compromissos de chaves | Cada emissor PST precisa expor um endpoint com chave compromissos que podem ser alterados a cada 60 dias e qualquer rotação mais rápido do que esse será ignorado. | Caso suas chaves estejam para expirar em menos de 60 dias, é obrigatório para atualizar os compromissos principais antes dessa data e evitar interrupções Veja mais detalhes. |
| Vida útil do registro de resgate | A vida útil da RR pode ser definida para determinar uma expiração data. Como os RRs são armazenados em cache para evitar novas chamadas de resgate desnecessárias para o emissor, isso é importante para garantir de resgate. | Como há um limite de taxa de resgate de dois tokens a cada 48 horas, é importante definir a vida útil do RR para poder executá-lo chamadas de resgate com sucesso pelo menos durante esse período (RR vida útil deve ser definida adequadamente). Recomendamos definir vida útil em semanas. |
Exemplos de cenários
Cenário 1: a vida útil da RR é menor que 24 horas (t=t), e o resgate é realizada várias vezes durante a janela de 48 horas.
Cenário 2: a vida útil da RR é de 24 horas e o resgate é realizado várias vezes durante a janela de 48 horas.
Cenário 3: a vida útil da RR é de 48 horas e o resgate é realizado várias vezes durante a janela de 48 horas.
Executar a demonstração
Antes de adotar a PST, recomendamos configurar com a demonstração. Para testar a demonstração da PST , será necessário executar o Google Chrome com sinalizações para ativar o emissor da demonstração compromissos principais (siga as instruções disponíveis na página de demonstração ).
Ao executar esta demonstração, seu navegador está usando o emissor e o resgate da demonstração para fornecer e consumir tokens.
Considerações técnicas
A demonstração funcionará melhor se você implementar as seguintes etapas:
- Interrompa todas as instâncias do Chrome antes de executá-lo com flags.
- Se você estiver usando uma máquina Windows, confira neste guia sobre como transmitir parâmetros para o binário executável do Chrome.
- Abra o Chrome DevTools em Aplicativos > Armazenamento > Estado particular Tokens ao usar o aplicativo de demonstração para ver os tokens emitidos/resgatados pelo emissor da demonstração.
Configurar para adoção
Tornar-se um emissor
Os emissores desempenham um papel fundamental na PST. Eles atribuem valores aos tokens para determinar se o usuário é um bot ou não. Se quiser começar a usar a PST como emissor, precisarão se registrar preenchendo Processo de registro do emissor.
Para se inscrever e se tornar um emissor, a operadora do site do emissor precisa abrir uma nova problema no GitHub de projeto usando o arquivo "New PST". Emissor" modelo. Siga as orientações do repositório para preencher o problema. Depois que um endpoint for verificado, ele será mesclado neste repositório e A infraestrutura do lado do servidor do Chrome começará a buscar essas chaves.
Servidores do emissor
Emissores e resgatadores são os principais atores da PST. os servidores e os tokens são a chave ferramentas para PST. Embora já tenhamos fornecido alguns detalhes sobre tokens e no documentação do GitHub, queríamos oferecem mais detalhes sobre os servidores PST. Para configurar-se como um emissor de PST, você precisa configurem um servidor emissor primeiro.
Implantar seu ambiente: servidores do emissor
Para implementar o servidor do emissor de token, será necessário criar seu próprio servidor um aplicativo que expõe endpoints HTTP.
O componente emissor é composto de dois módulos principais: (1) o servidor do emissor e (2) o emissor do token.
Assim como acontece com todos os aplicativos voltados para a Web, recomendamos uma camada adicional de proteção ao servidor do emissor.
Servidor emissor: em nosso exemplo de implementação, o servidor emissor é uma Node.js que usa o framework Express para hospedar o Endpoints HTTP do emissor. Confira um exemplo de código no GitHub (link em inglês).
Emissor do token: o componente criptográfico do emissor não exige nenhuma linguagem específica, mas devido aos requisitos de desempenho do componente, estamos fornecendo uma implementação C como exemplo, que usa a classe Boring SSL (em inglês) para gerenciar tokens. Veja o exemplo do código do emissor e mais informações sobre a instalação no GitHub
Chaves: o componente do emissor de token usa chaves EC personalizadas para criptografar tokens. Essas chaves precisam ser protegidas e armazenadas em um armazenamento seguro.
Requisitos técnicos para servidores de 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): Esse endpoint é onde os detalhes da chave pública de criptografia vão ficar disponíveis para que os navegadores confirmem que seu servidor é legítimo. - Emissão de token (por exemplo,
/.well-known/private-state-token/issuance): O endpoint emissor de token onde todas as solicitações de token serão tratadas. Isso será o ponto de integração do componente emissor do token.
Conforme mencionado anteriormente, devido ao alto tráfego esperado, este servidor será com capacidade de processamento, recomendamos implantá-lo usando um do Google (por exemplo, em um ambiente de nuvem) para ajustar seus back-end com base em uma demanda variável.
Enviar uma chamada para o servidor do emissor
Implemente uma chamada de busca de site à pilha do emissor para emitir novas 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 permitirá que você leia os tokens que um emissor envia. As etapas a seguir descrevem como resgatar tokens e ler registros de resgate associados a esses tokens.
É possível executar o emissor e o resgate no mesmo servidor (ou grupo de servidores).
Requisitos técnicos para servidores do resgate
De acordo com o protocolo, você precisará implementar pelo menos dois pontos de extremidade HTTP para do servidor do resgate:
/.well-known/private-state-token/redemption: endpoint em que todos do resgate de tokens serão processados. Esse endpoint será onde o token do resgate será integrado
Enviar uma chamada para o servidor do resgate
Para resgatar tokens, você precisará implementar uma chamada de busca de site para da 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"
}
});
Consulte o exemplo de código.
Depois de resgatar um token, você pode 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>]
}
});
Consulte o exemplo de código.
Implantar a implementação
Para testar sua implementação, primeiro acesse a página da Web na qual é 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, acesse a página da Web em que a chamada de resgate é feita e confirme se os RRs são criados, seguindo sua lógica.
Implantação no mundo real
Recomendamos que você escolha os sites de destino que fazem parte do seu uso específico caso:
- Pequeno número de visitas mensais (~ <1 milhão de visitas/mês): Você comece implantando a API para um público pequeno primeiro
- Você tem a propriedade e a controla. Se necessário, você pode desativar rapidamente a implementação sem aprovações complexas
- No máximo um emissor: para limitar a quantidade de tokens a fim de simplificar os testes.
- No máximo dois resgates: é preciso simplificar a solução de problemas no 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 a usam.
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. Por padrão, a lista de permissões para essas diretivas é definida como própria. Isso significa que o recurso está disponível apenas para a página de nível superior (e iframes de mesma origem) e não está disponível para os iframes de origem cruzada sem delegação explícita pela página.
É possível desativar a emissão ou o resgate do token PST para 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 às quais você quer permitir acesso à API. Por exemplo, para desativar completamente o uso de 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 para todos os recursos de origem cruzada, defina a lista de origens como *.
Saiba como controlar os recursos do Sandbox de privacidade com a Política de permissões ou entenda melhor a Política de permissões.
Solução de problemas
Você pode inspecionar os PSTs nas guias "Network" e "Application" do Chrome DevTools.
Na guia Rede:
Na guia "Aplicativo":
Leia mais sobre o assunto Integração do DevTools.
Práticas recomendadas do cliente
Se as funções essenciais do seu site dependerem de determinados emissores de token, priorize-os. Chame hasPrivateToken(issuer) para esses emissores preferenciais antes de carregar qualquer outro script. 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 seus próprios 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 de servidores
Para que o emissor e o servidor do resgatador operem de maneira eficaz, recomendamos implementando as seguintes práticas recomendadas para garantir que você não se depare com 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 variáveis de tráfego incluindo picos.
- Confira se as chaves estão protegidas e alinhadas ao seu sistema de acesso Política de controle, 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 problemas de uso, gargalos e desempenho após para produção.
Mais informações
- Revise a documentação para desenvolvedores:
- Comece lendo visão geral para se atualizar sobre a PST e seus recursos.
- Assista ao vídeo de apresentação da PST (em inglês).
- Confira a demonstração da PST.
- Ler também a API explainer para entender melhor mais detalhes sobre ele.
- Leia mais sobre o atual spec da API.
- Contribua com a conversa pelo GitHub problemas ou W3C chamadas.
- Para entender melhor os termos, consulte a Glossário do Sandbox de privacidade.
- Para saber mais sobre conceitos do Chrome, como "teste de origem" ou "Sinalizações do Chrome", veja os vídeos e artigos curtos disponíveis em goo.gle/cc.