Permitir a reutilização da chave de acesso nos seus sites com solicitações de origem relacionadas

Maud Nalpas

O problema que as solicitações de origem relacionadas resolvem

As chaves de acesso estão vinculadas a um site específico e só podem ser usadas para fazer login no site para o qual foram criadas.

Isso é especificado no ID da parte confiável (ID da RP), que, para chaves de acesso criadas para o domínio example.com, pode ser www.example.com ou example.com.

Embora os IDs de RP impeçam que as chaves de acesso sejam usadas como uma única credencial para autenticação em todos os lugares, elas geram problemas para:

• Sites com vários domínios: os usuários não podem usar a mesma chave de acesso para fazer login em diferentes domínios específicos de país (por exemplo, example.com e example.co.uk) gerenciados pela mesma empresa.
• Domínios de marca: os usuários não podem usar a mesma credencial em diferentes domínios usados por uma única marca (por exemplo, acme.com e acmerewards.com).
• Apps para dispositivos móveis: geralmente, os apps para dispositivos móveis não têm domínio próprio, o que dificulta o gerenciamento de credenciais.

Existem soluções alternativas com base na federação de identidade e outras baseadas em iframes, mas elas são inconvenientes em alguns casos. As solicitações de origem relacionadas oferecem uma solução.

Observação: os IDs de RP separam as credenciais entre diferentes sites, mas a proteção contra phishing vem da verificação da origem do site no campo CollectedClientData.

Solução

Com as solicitações de origem relacionadas, um site pode especificar as origens que podem usar o ID da RP.

Isso permite que os usuários reutilizem a mesma chave de acesso em vários sites que você opera.

Para usar solicitações de origem relacionadas, você precisa disponibilizar um arquivo JSON especial em um URL https://{RP ID}/.well-known/webauthn específico. Se o example.com quiser permitir que as origens adicionais o usem como um ID de RP, ele precisará enviar o seguinte arquivo em https://example.com/.well-known/webauthn:.

{
    "origins": [
        "https://example.co.uk",
        "https://example.de",
        "https://example-rewards.com"
    ]
}

Na próxima vez que um desses sites fizer uma chamada para a criação de chave de acesso (navigator.credentials.create) ou autenticação (navigator.credentials.get) que use example.com como um ID de RP, o navegador vai notar um ID de RP que não corresponde à origem solicitante. Se o navegador oferecer suporte a solicitações de origem relacionada, ele vai procurar primeiro um arquivo webauthn em https://{RP ID}/.well-known/webauthn. Se o arquivo existir, o navegador vai verificar se a origem que fez a solicitação está na lista de permissões desse arquivo. Se sim, ele segue para as etapas de criação ou autenticação da chave de acesso. Se o navegador não oferecer suporte a solicitações de origem relacionadas, ele vai gerar uma SecurityError.

Suporte ao navegador

• Chrome: compatível a partir do Chrome 128.
• Safari: compatível com o macOS 15 Beta 3 e com o iOS 18 Beta 3 para dispositivos móveis.
• Firefox: Aguardando posição.

Aviso: a partir de agosto de 2024, as solicitações de origem relacionadas não são mais compatíveis com o Firefox, e getClientCapabilities ainda não está disponível para você detectar o recurso ausente e implementar uma alternativa. Se você implementar solicitações de origem relacionadas, os usuários do Firefox não poderão criar uma chave de acesso (ou fazer login com ela) nos domínios que pretendem usar outro site como um ID da RP, e uma SecurityError será gerada.

Como configurar solicitações de origem relacionadas

A demonstração a seguir usa o exemplo de dois sites, https://ror-1.glitch.me e https://ror-2.glitch.me.
Para permitir que os usuários façam login com a mesma chave de acesso nesses dois sites, ele usa solicitações de origem relacionadas para permitir que ror-2.glitch.me use ror-1.glitch.me como ID de RP.

Demonstração

Observação: abra a demonstração em um dos navegadores compatíveis.

https://ror-2.glitch.me (link em inglês) implementa solicitações de origem relacionadas para usar ror-1.glitch.me como um ID da RP, então ror-1 e ror-2 usam ror-1.glitch.me como um ID da RP ao criar uma chave de acesso ou autenticar com ela.
Também implementamos um banco de dados de chaves compartilhadas nesses sites.

Observe a seguinte experiência do usuário:

• É possível criar uma chave de acesso e se autenticar com ela em ror-2, mesmo que o ID do RP seja ror-1 (e não ror-2).
• Depois de criar uma chave de acesso em ror-1 ou ror-2, você poderá fazer a autenticação com ela em ror-1 e ror-2. Como ror-2 especifica ror-1 como um RP ID, fazer uma solicitação de criação ou autenticação de chave de acesso em qualquer um desses sites é o mesmo que fazer a solicitação em ror-1. O ID do RP é a única coisa que vincula uma solicitação a uma origem.
• Depois que você cria uma chave de acesso em ror-1 ou ror-2, ela pode ser preenchida automaticamente pelo Chrome em ror-1 e ror-2.
• Uma credencial criada em qualquer um desses sites terá um ID de RP de ror-1.

Graças às solicitações de origem relacionadas, os usuários podem usar a mesma chave de acesso em ror-1 e ror-2. O Chrome também vai preencher automaticamente as credenciais.

Confira o código:

• Consulte o arquivo ./well-known/webauthn configurado na base de código ror-1 (link em inglês).
• Confira RP_ID_ROR ocorrências na base de código ror-2 (link em inglês).

Observação: nesta demonstração, para simplificar, nenhuma verificação de senha é feita. A demonstração se concentra nas chaves de acesso.

Etapa 1: implementar um banco de dados de contas compartilhadas

Se você quiser que os usuários possam fazer login com a mesma chave de acesso em site-1 e site-2, implemente um banco de dados de conta compartilhado entre esses dois sites.

Etapa 2: configurar o arquivo JSON .well-known/webauthn no site-1

Primeiro, configure site-1.com para que ele permita que site-2.com o use como um ID de RP. Para isso, crie seu arquivo JSON de webauthn:

{
    "origins": [
        "https://site-2.com"
    ]
}

O objeto JSON precisa conter origens com nome de chave cujo valor é uma matriz de uma ou mais strings que contêm origens da Web.

Limitação importante: máximo de 5 marcadores

Cada elemento dessa lista será processado para extrair o rótulo do eTLD+1. Por exemplo, os rótulos eTLD + 1 de example.co.uk e example.de são example. No entanto, o rótulo eTLD + 1 de example-rewards.com é example-rewards. No Chrome, o número máximo de marcadores é 5.

Aviso: se a lista incluir muitos identificadores (mais de cinco), os elementos em excesso serão ignorados.

Etapa 3: servir o JSON .well-known/webauthn no site-1

Em seguida, forneça o arquivo JSON em site-1.com/.well-known/webauthn.

Cuidado: o arquivo precisa ser enviado com um tipo de conteúdo application/json e conter um único objeto JSON que lista as origens permitidas. O formato correto do arquivo é /.well-known/webauthn (não inclua a extensão .json).

Por exemplo, em Express:

app.get("/.well-known/webauthn", (req, res) => {
  const origins = {
    origins: ["https://site-2.com"],
  };
  return res.json(origins);
});

Aqui, estamos usando o res.json expresso, que já define o content-type correto ('application/json').

Etapa 4: especificar o ID do RP desejado no site 2

Na base de código site-2, defina site-1.com como o ID da RP em todos os lugares necessários:

• Na criação da credencial:
  • Defina site-1.com como o ID da RP na options de criação de credenciais que são transmitidos para a chamada de front-end navigator.credentials.create e normalmente gerados no lado do servidor.
  • Defina site-1.com como o ID do RP esperado, conforme você executa as verificações de credenciais antes de salvar no banco de dados.
• Após a autenticação:
  • Defina site-1.com como o ID do RP nas options de autenticação que são transmitidas para a chamada de front-end navigator.credentials.get e normalmente geradas no lado do servidor.
  • Defina site-1.com como o ID de RP esperado para ser verificado no servidor, conforme você executa verificações de credencial antes de autenticar o usuário.

Observação: e o origin? E o name do RP? Na base de código do site 2, o origin esperado precisa permanecer inalterado (https://site-2.com), porque ele designa de onde a solicitação precisa vir. De acordo com o nome do RP (rp.name), ele não é usado na prática. Você pode deixar esse campo em branco.

Solução de problemas

Mensagem de erro no Chrome durante a criação de credenciais. Esse erro é gerado se o arquivo ".well-known/webauthn" não for encontrado em "https://{RP ID}/.well-known/webauthn".

Mensagem de erro no Chrome após a criação da credencial. Esse erro será gerado se o arquivo ".well-known/webauthn" puder ser encontrado, mas não listar a origem da qual você está tentando criar uma credencial.

Outras considerações

Compartilhar chaves de acesso entre sites e apps para dispositivos móveis

As solicitações de origem relacionadas permitem que os usuários reutilizem uma chave de acesso em vários sites. Para permitir que os usuários reutilizem uma chave de acesso em um site e em um app para dispositivos móveis, use as seguintes técnicas:

• No Chrome: Digital Asset Links. Saiba mais em Adicionar suporte a Digital Asset Links.
• No Safari: Domínios associados.

Compartilhar senhas entre sites

As solicitações de origem relacionadas permitem que os usuários reutilizem uma chave de acesso em vários sites. As soluções para compartilhar senhas entre sites variam de acordo com o gerenciador de senhas. Para o Gerenciador de senhas do Google, use o Digital Asset Links. O Safari tem um sistema diferente.

Função dos gerenciadores de credenciais e dos agentes do usuário

Isso vai além do seu escopo como desenvolvedor de sites, mas, a longo prazo, o ID do RP não deve ser um conceito visível para o usuário no agente do usuário ou no gerenciador de credenciais que ele está usando. Em vez disso, os agentes do usuário e os gerenciadores de credenciais precisam mostrar aos usuários onde as credenciais foram usadas. Essa mudança vai levar algum tempo para ser implementada. Uma solução temporária seria mostrar o site atual e o site de registro original.