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

Maud Nalpas

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

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

Embora os IDs da RP impeçam que as chaves de acesso sejam usadas como uma única credencial para autenticação em todos os lugares, eles criam 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íses (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: os apps para dispositivos móveis geralmente não têm um domínio próprio, o que dificulta o gerenciamento de credenciais.

Há soluções alternativas baseadas 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.

Solução

Com solicitações de origem relacionadas, um site pode especificar origens permitidas para 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 as solicitações de origem relacionadas, é necessário veicular um arquivo JSON especial em um URL específico https://{RP ID}/.well-known/webauthn. Se example.com quiser permitir que as origens adicionais o usem como um ID da RP, ele precisará disponibilizar 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 criação de chave de acesso (navigator.credentials.create) ou autenticação (navigator.credentials.get) que use example.com como um ID da RP, o navegador vai notar um ID da RP que não corresponde à origem solicitante. Se o navegador oferecer suporte a solicitações de origem relacionadas, ele primeiro vai procurar um arquivo webauthn em https://{RP ID}/.well-known/webauthn. Se o arquivo existir, o navegador vai verificar se a origem que está fazendo a solicitação está na allowlist. Se sim, ele vai prosseguir 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 um SecurityError.

Suporte ao navegador

As solicitações de origem relacionadas são compatíveis com o Chrome e o Safari. Em janeiro de 2026, o Firefox ainda estava considerando o recurso. Você pode acompanhar o status dele no problema de posição de padrões do Mozilla (link em inglês).

Configurar solicitações de origem relacionadas

A demonstração a seguir usa 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 em ambos os sites, ela usa solicitações de origem relacionadas para permitir que ror-2.glitch.me use ror-1.glitch.me como ID da RP.

Demonstração

https://ror-2.glitch.me implementa solicitações de origem relacionadas para usar ror-1.glitch.me como um ID da RP. Assim, 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 de acesso compartilhadas nesses sites.

Observe a experiência do usuário a seguir:

• Você pode criar uma chave de acesso e autenticar com ela no ror-2, mesmo que o ID da RP seja ror-1 (e não ror-2).
• Depois de criar uma chave de acesso no ror-1 ou no ror-2, você pode autenticar com ela no ror-1 e no ror-2. Como ror-2 especifica ror-1 como um ID da RP, 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 no ror-1. O ID da RP é a única coisa que vincula uma solicitação a uma origem.
• Depois de criar uma chave de acesso no ror-1 ou no ror-2, ela pode ser preenchida automaticamente pelo Chrome no ror-1 e no ror-2.
• Uma credencial criada em qualquer um desses sites terá um ID da RP de ror-1.

Consulte o código:

• Consulte o arquivo /.well-known/webauthn configurado na base de código do ror-1.
• Consulte as ocorrências de RP_ID_ROR na base de código do ror-2.

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 no site-1 e no site-2, implemente um banco de dados de contas compartilhado entre esses dois sites.

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

Primeiro, configure site-1.com para permitir que site-2.com o use como um ID da RP. Para fazer isso, crie o arquivo JSON webauthn:

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

O objeto JSON precisa conter a chave chamada origens, 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 eTLD + 1. Por exemplo, os rótulos eTLD + 1 de example.co.uk e example.de são ambos example. Mas o rótulo eTLD + 1 de example-rewards.com é example-rewards. No Chrome, o número máximo de rótulos é 5.

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

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

Por exemplo, no 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 do Express, que já define o correct content-type ('application/json');

Etapa 4: especificar o ID da RP no site-2

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

• Na criação de credenciais:
  • Defina site-1.com como o ID da RP na criação de credenciais options que são transmitidas para a chamada de front-end navigator.credentials.create e normalmente geradas do lado do servidor.
  • Defina site-1.com como o ID da RP esperado ao executar verificações de credenciais antes de salvá-las no banco de dados.
• Na autenticação:
  • Defina site-1.com como o ID da RP nas options de autenticação transmitidas para a chamada de front-end navigator.credentials.get e normalmente geradas do lado do servidor.
  • Defina site-1.com como o ID da RP esperado a ser verificado no servidor ao executar verificações de credenciais antes de autenticar o usuário.

Solução de problemas

Outras considerações

Compartilhar chaves de acesso em 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 um app para dispositivos móveis, use as técnicas a seguir:

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

Compartilhar senhas em sites

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

Função dos gerenciadores de credenciais e dos user agents

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