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, 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 de 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 domínios específicos de países diferentes (por exemplo,
example.comeexample.co.uk) gerenciados pela mesma empresa. - Domínios de marca: os usuários não podem usar a mesma credencial em
domínios diferentes usados por uma única marca (por exemplo,
acme.comeacmerewards.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 relacionada oferecem uma solução.
Solução
Com as Solicitações de Origem Relacionadas, um site pode especificar as origens que podem usar o ID de RP dele.
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 relacionada, é necessário disponibilizar 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 de 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 de RP, o navegador vai notar um ID de RP que
não corresponde à origem da solicitação. Se o navegador for compatível com 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 faz a solicitação está no allowlist.
Em caso afirmativo, ele prossegue para as etapas de criação ou autenticação da chave de acesso.
Se o navegador não for compatível com as solicitações de origem relacionada, ele vai gerar um SecurityError.
Suporte ao navegador
As solicitações de origem relacionada são compatíveis com o Chrome e o Safari. Até janeiro de 2026, o Firefox ainda está considerando o recurso. Acompanhe o status no problema de posição dos padrões da 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 nos dois sites, ele usa as solicitações de origem relacionada para permitir que ror-2.glitch.me use ror-1.glitch.me como o ID da parte confiável.
Demonstração
https://ror-2.glitch.me implementa solicitações de origem relacionada para usar ror-1.glitch.me como um ID de RP. Assim, ror-1 e ror-2 usam ror-1.glitch.me como um ID de RP ao criar uma chave de acesso ou autenticar com ela.
Também implementamos um banco de dados de chaves de acesso compartilhado entre esses 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 da parte confiável sejaror-1(e nãoror-2). - Depois de criar uma chave de acesso no
ror-1ou noror-2, você pode usá-la para autenticação em ambosror-1osror-2sistemas. Comoror-2especificaror-1como um ID de 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 em 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-1ou noror-2, ela pode ser preenchida automaticamente pelo Chrome em ambosror-1os sistemas operacionaisror-2. - Uma credencial criada em qualquer um desses sites terá um ID de RP de
ror-1.
Confira o código:
- Confira o arquivo
/.well-known/webauthnconfigurado na base de código ror-1. - Confira as ocorrências de
RP_ID_RORna base de código 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 que ele permita que site-2.com o use como um
ID de RP. Para fazer isso, crie o arquivo JSON webauthn:
{
"origins": [
"https://site-2.com"
]
}
O objeto JSON precisa conter uma chave chamada origins, cujo valor é uma matriz de uma ou mais strings que contêm origens da web.
Limitação importante: máximo de 5 rótulos
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. 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, disponibilize 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);
});
Neste caso, estamos usando o express res.json, que já define o
content-type correto ('application/json');
Etapa 4: especificar o ID da parte confiável no site-2
Na base de código site-2, defina site-1.com como o ID da parte confiável em todos os lugares necessários:
- Na criação da credencial:
- Defina
site-1.comcomo o ID da parte confiável na criação de credenciaisoptionsque são transmitidas para a chamada de front-endnavigator.credentials.createe normalmente geradas do lado do servidor. - Defina
site-1.comcomo o ID de RP esperado, já que você executa verificações de credenciais antes de salvá-las no banco de dados.
- Defina
- Após a autenticação:
- Defina
site-1.comcomo o ID da parte confiável na autenticaçãooptions, que é transmitida para a chamada de front-endnavigator.credentials.gete gerada do lado do servidor. - Defina
site-1.comcomo o ID de RP esperado a ser verificado no servidor, já que você executa verificações de credenciais antes de autenticar o usuário.
- Defina
Solução de problemas
Outras considerações
Compartilhar chaves de acesso entre sites e apps para dispositivos móveis
As solicitações de origem relacionada 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 para Digital Asset Links.
- No Safari: Domínios associados.
Compartilhar senhas entre sites
As solicitações de origem relacionada 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.
Papel dos Credential Managers e 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 para o usuário no user agent ou no Credential Manager que seus usuários estão usando. Em vez disso, os user agents e os gerenciadores de credenciais precisam mostrar aos usuários onde as credenciais deles foram usadas. Essa mudança vai levar tempo para ser implementada. Uma solução temporária seria exibir o site atual e o site de registro original.