Guia para desenvolvedores sobre tokens de estado particular

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.

Fluxo de aprendizado da PST.
Processo de aprendizagem da PST: é composto por várias etapas, começando pelo entendimento da API e definindo sua própria estratégia de token (mais atividades relacionadas ao produto ou aos negócios). Depois disso, a fase técnica é sobre a implementação da demonstração no ambiente local e a aplicação em um caso de uso real.

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?

Casos de uso de tokens de estado particular.

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:

  1. Como emitir tokens
  2. Como resgatar tokens
  3. 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.

Fluxo básico de tokens de estado particular.
Diagrama de sequência: o diagrama mostra o uso básico da PST em um cenário real em que dois sites querem trocar algum sinal sobre a instância específica do Chrome. Os dois sites realizam as operações de emissão e resgate em momentos diferentes, podendo trocar um sinal confiável entre eles.

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.

Relação entre PST e RR.
  1. Novos tokens são emitidos (máximo de 500 por emissor, site e dispositivo).
  2. Todos os tokens são armazenados no dispositivo (semelhante ao armazenamento de cookies).
  3. 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).
  4. Os RRs são considerados ativos até o vencimento e são usados como um cache.
  5. 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.

Exemplo de cenário 1 de PST: vida útil pequena.
Nesse cenário, há uma janela de 28 horas em que o usuário não pode resgatar novos tokens, e todos os RRs expirarão.

Cenário 2: a vida útil da RR é de 24 horas e o resgate é realizado várias vezes durante a janela de 48 horas.

Exemplo de cenário 2 de PST: vida útil de 24 horas.
Nesse cenário, como a vida útil da RR é de 24 horas, os resgates podem ser feitos durante esse período sem qualquer limitação.

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

Exemplo de cenário 3 da PST: 48 horas de vida útil.
Nesse cenário, como a vida útil da RR é de 48 horas, os resgates podem ser feitos durante esse período sem qualquer limitação.

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 ).

Tela de demonstração da PST.

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.
Tela do Chrome DevTools mostrando a PST.

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.

Componentes do servidor do emissor.

Assim como acontece com todos os aplicativos voltados para a Web, recomendamos uma camada adicional de proteção ao servidor do emissor.

  1. 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).

  2. 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

  3. 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"
      }
    });

Confira um exemplo de código.

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).

Componentes do servidor do Redentor.
Componentes de demonstração PST: são os principais componentes do servidor do resgate. Servidor do Redentor (Aplicativo Node.js) e Resgate de token (componente criptográfico responsável por verificar assinaturas e tokens no processo de resgate).

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:

Inspeção do DevTools para a guia &quot;Network&quot;.
Inspeção do DevTools para PST: acesse Rede > Tokens de estado particular para receber todas as informações relevantes sobre tokens e emissores de uma página específica.

Na guia "Aplicativo":

Inspeção do DevTools para a guia Application.
Inspeção do DevTools para PST: vá para Aplicativo > Tokens de estado particular para receber todas as informações relevantes sobre tokens e emissores de uma página específica.

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

  1. Revise a documentação para desenvolvedores:
    1. Comece lendo visão geral para se atualizar sobre a PST e seus recursos.
    2. Assista ao vídeo de apresentação da PST (em inglês).
    3. Confira a demonstração da PST.
    4. Ler também a API explainer para entender melhor mais detalhes sobre ele.
    5. Leia mais sobre o atual spec da API.
  2. Contribua com a conversa pelo GitHub problemas ou W3C chamadas.
  3. Para entender melhor os termos, consulte a Glossário do Sandbox de privacidade.
  4. 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.