Gerenciar chaves de acesso em vários domínios e apps com o ID do RP

Eiji Kitamura

No WebAuthn e nas chaves de acesso, o ID da parte confiável (RP ID) especifica o escopo de uma credencial pelo nome de domínio. Quando você cria uma chave de acesso, o navegador a vincula a um ID de RP específico. Em seguida, o navegador impede o uso dessa chave de acesso em um domínio que não corresponda ou esteja dentro do escopo desse ID. Definir o ID do RP corretamente garante uma experiência de chave de acesso perfeita em subdomínios, origens entre sites e apps móveis próprios.

Princípios básicos do ID da parte restrita

O ID da parte confiável (RP ID) é uma string exclusiva que identifica seu serviço ou site. Um ID da RP precisa ser uma string de domínio. Pode ser o nome do host atual exato ou um domínio pai mais amplo, desde que seja um eTLD+1 ou superior. Não é possível usar endereços IP e sufixos públicos (eTLDs) como um ID de RP.

Por exemplo, se você hospedar seu servidor em https://www.example.com, poderá usar example.com ou www.example.com como ID do RP, dependendo das necessidades específicas. A tabela a seguir mostra exemplos de IDs de RP permitidos, dependendo do host de origem:

Host de origem ID da parte restrita permitida (eTLD+1)
https://login.example.com example.com ou login.example.com
https://example.com:8080 example.com (os números de porta são excluídos)
https://mobile.example.co.jp example.co.jp ou mobile.example.co.jp
https://sub.project.org.uk project.org.uk ou sub.project.org.uk
https://user.github.io user.github.io (github.io é um eTLD)
https://myapp.pages.dev myapp.pages.dev (pages.dev é um eTLD)
http://localhost localhost (uma exceção ao requisito HTTPS)

O navegador vincula criptograficamente as chaves de acesso ao ID do RP quando você as cria. Para usar uma credencial, a origem da solicitação de autenticação precisa corresponder ao RP ID.

Quando você usa um eTLD+1 como ID da RP, a chave de acesso funciona em subdomínios relacionados. Por exemplo, um ID de RP example.com funciona para https://login.example.com e https://shop.example.com. Um RPID mais específico, como login.example.com, funciona na origem exata, mas não em https://shop.example.com.

ID da parte restrita em contextos entre sites

Se o serviço abranger vários eTLD+1s (por exemplo, example.com e example.co.jp), será uma configuração entre sites. Os IDs padrão da parte com restrições não são compatíveis com configurações entre sites.

Para compartilhar chaves de acesso entre sites distintos, use Solicitações de origem relacionadas (ROR, na sigla em inglês). Com o ROR, é possível compartilhar chaves de acesso entre sites distintos porque o cliente (navegador) reconhece origens diferentes como parte do mesmo serviço lógico.

Requisitos para o ROR:

  • Escolha um ID de RP:você precisa escolher um ID de RP e usá-lo em todos os sites.
  • Hospede um arquivo de configuração:o domínio do ID da RP principal precisa hospedar um arquivo de configuração em /.well-known/webauthn que liste as origens autorizadas.
  • Mantenha a consistência:mesmo que o usuário esteja em https://www.example.co.jp, o rpId na chamada WebAuthn precisa ser o principal (por exemplo, example.com) na criação e autenticação.

Exemplo de ROR para ID da parte restrita example.com: https://example.com/.well-known/webauthn

{
  "origins": [
    "https://www.example.co.jp",
    "https://shop.example"
  ]
}

Para mais informações sobre os detalhes da implementação de solicitações de origem relacionadas, consulte Permitir a reutilização de chaves de acesso em seus sites com solicitações de origem relacionadas

ID da parte restrita em apps para dispositivos móveis

Os aplicativos para dispositivos móveis podem usar chaves de acesso associando-se a um domínio da Web. Você precisa hospedar um arquivo de verificação no seu servidor para estabelecer essa relação.

O Gerenciador de credenciais do Android exige um arquivo Digital Asset Link (DAL) no domínio do ID da RP para associar ao app.

  • Hospedagem:hospede o arquivo em https://<RP ID>/.well-known/assetlinks.json.
  • Verificação:verifique o origin em clientDataJSON. No Android, isso é uma string como android:apk-key-hash:<hash>.

Exemplo de DAL para o ID da RP example.com (hospedado em https://example.com/.well-known/assetlinks.json)

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls",
      "delegate_permission/common.get_login_creds"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.google.credentialmanager.sample",
      "sha256_cert_fingerprints": [
        "4F:20:47:1F:D9:9A:BA:96:47:8D:59:27:C2:C8:A6:EA:8E:D2:8D:14:C0:B6:A2:39:99:9F:A3:4D:47:3D:FA:11"
      ]
    }
  }
]

Para mais informações, consulte Configurar Digital Asset Links entre seu app e site.

iOS: domínios associados

As plataformas da Apple exigem um arquivo apple-app-site-association (AASA) no domínio do ID do RP para associação com o app.

  • Arquivo AASA:host https://<RP_ID>/.well-known/apple-app-site-association.
  • Direitos:adicione webcredentials:<app info> aos direitos do app.

Exemplo de AASA para o ID da parte restrita example.com: https://example.com/.well-known/apple-app-site-association:

{
  "webcredentials":
    {
      "apps": ["EXAMPLE123.com.example.passkey"]
    }
}

Para mais informações, consulte Como se conectar a um serviço com chaves de acesso na documentação para desenvolvedores da Apple.

Resumo

O ID do RP determina onde os usuários acessam as chaves de acesso. Tenha estes pontos em mente ao implementar:

  • Hierarquia e subdomínios: o ID da RP precisa ser uma string de domínio (eTLD+1 ou superior). Usar um domínio mais amplo, como example.com, permite que as chaves de acesso funcionem em todos os subdomínios (por exemplo, login.example.com e shop.example.com).
  • Soluções entre sites: use solicitações de origem relacionadas (ROR, na sigla em inglês) para serviços que abrangem vários eTLDs+1. Isso exige um ID de RP e um arquivo de configuração em /.well-known/webauthn.
  • Integração com dispositivos móveis: estabeleça uma relação verificada entre seu site e apps para dispositivos móveis usando um arquivo Digital Asset Links (DAL) em /.well-known/assetlinks.json para Android e um arquivo apple-app-site-association (AASA) em /.well-known/apple-app-site-association para iOS.

Saiba mais