--- url: 'https://www.corbado.com/pt/blog/webauthn-relying-party-id-rpid-passkeys' title: 'WebAuthn Relying Party ID (rpID) e passkeys: domínios e apps nativos' description: 'Este artigo explica o Relying Party ID do WebAuthn para a autenticação com passkeys. Aborda a configuração, domínios e apps nativos.' lang: 'pt' author: 'Vincent Delitz' date: '2026-06-15T13:59:52.497Z' lastModified: '2026-06-16T06:03:57.000Z' keywords: 'relying party id, chaves de acesso, passkeys, webauthn, domínios, apps nativos, autenticação' category: 'WebAuthn Know-How' --- # WebAuthn Relying Party ID (rpID) e passkeys: domínios e apps nativos ## Key Facts - O **Relying Party ID** é um domínio embutido em cada chave de acesso (passkey). A autenticação falha se a origem do navegador não corresponder, tornando as chaves de acesso altamente resistentes a phishing. - O **RP ID** não deve estar na **Public Suffix List** e alterá-lo invalida todas as chaves de acesso existentes. Use o domínio raiz por padrão para preparar-se para o futuro. - Os apps do iOS requerem um arquivo **apple-app-site-association** em `/.well-known/` sob o RP ID. O Android requer o **assetlinks.json** no mesmo caminho. Novos arquivos podem levar até 24 horas para serem armazenados em cache. - Múltiplos domínios raiz precisam de **Related Origin Requests** via `.well-known/webauthn` para compartilhamento de chaves de acesso. Use um único servidor WebAuthn com um RP ID para todos os apps, web e nativos. ## 1. Introdução A [autenticação](https://www.corbado.com/pt/blog/passkeys-revolut) com [chaves de acesso](https://www.corbado.com/pt/glossary/cda) está se tornando rapidamente a norma, à medida que gigantes da tecnologia como [TikTok](https://www.corbado.com/blog/tiktok-passkeys), GitHub e [WhatsApp](https://www.corbado.com/blog/whatsapp-passkeys), X (Twitter), [LinkedIn](https://www.corbado.com/blog/linkedin-passkeys) e Amazon as lançam ou já o fizeram. É evidente que o mundo tecnológico está reconhecendo a importância de uma [autenticação](https://www.corbado.com/pt/blog/passkeys-revolut) simples e segura. Além da experiência de usuário perfeita de se autenticar com [Face ID](https://www.corbado.com/faq/is-face-id-passkey), Touch ID ou [Windows Hello](https://www.corbado.com/glossary/windows-hello), as [chaves de acesso](https://www.corbado.com/pt/glossary/cda) oferecem [segurança](https://www.corbado.com/pt/blog/senhas-complexas-quebradas-em-breve) incomparável em comparação com métodos de [autenticação](https://www.corbado.com/pt/blog/passkeys-revolut) tradicionais como senhas. Um dos recursos de destaque é sua forte resistência a [phishing](https://www.corbado.com/glossary/phishing). Um ataque de [phishing](https://www.corbado.com/glossary/phishing) é um ataque onde a vítima é enganada para fornecer credenciais a um site falso que imita o site original. Por exemplo, imagine receber um e-mail do que parece ser o seu banco, pedindo que você faça login. Você clica no link e o site parece legítimo, então você insere suas credenciais e o invasor pode usá-las para fazer login no site original. Este é um problema cada vez maior na era digital e até mesmo grandes empresas como [Okta](https://www.darkreading.com/application-security/okta-flaw-involved-mgm-resorts-breach-attackers-claim) (um provedor de autenticação!) ou [Retool](https://retool.com/blog/mfa-isnt-mfa/) foram vítimas de ataques de spear-[phishing](https://www.corbado.com/glossary/phishing) (uma forma especial de phishing onde vítimas individuais são particularmente visadas com truques de phishing muito pessoais), enfatizando a necessidade de medidas de [segurança](https://www.corbado.com/pt/blog/senhas-complexas-quebradas-em-breve) robustas. Pelo contrário, se você usar uma [chave de acesso](https://www.corbado.com/pt/blog/senhas-complexas-quebradas-em-breve) e o site for falso, sua autenticação falhará. Isso ocorre porque as [chaves de acesso](https://www.corbado.com/pt/glossary/cda) estão vinculadas aos domínios para os quais foram criadas através do **Relying Party ID**. > Você não pode fazer login com uma > [chave de acesso](https://www.corbado.com/pt/blog/senhas-complexas-quebradas-em-breve) em nenhum outro site, o > que torna as chaves de acesso fortemente resistentes a phishing (embora nenhum sistema > seja absolutamente imune a todos os vetores de ataque). Esse mecanismo está embutido no WebAuthn, o padrão da web subjacente à [chave de acesso](https://www.corbado.com/pt/blog/senhas-complexas-quebradas-em-breve) para [autenticação sem senha](https://www.corbado.com/pt/glossary/cda). O WebAuthn é construído sobre duas cerimônias principais: a cerimônia de registro e a de autenticação. Durante a cerimônia de registro (inscrição), uma nova chave de acesso é criada para um serviço online (a [Relying Party](https://www.corbado.com/glossary/relying-party)) através de um app web ou nativo. Nesse processo, o domínio (Relying Party ID) para o qual a chave de acesso é criada é armazenado na chave de acesso. Isso permite que a cerimônia de autenticação (login) verifique se o serviço online (a [Relying Party](https://www.corbado.com/glossary/relying-party)), ao qual o app web ou nativo pertence, corresponde ao [Relying Party](https://www.corbado.com/glossary/relying-party) ID armazenado na chave de acesso. A seguir, veremos em detalhes como esse processo de [correspondência de domínios](#what-relying-party-id) funciona e como, em particular, os apps nativos são protegidos. ## 2. O que é o Relying Party ID? O [**Relying Party ID**](https://www.w3.org/TR/webauthn-2/#relying-party-identifier) é essencialmente um domínio armazenado na chave de acesso, garantindo que a chave de acesso só funcione se a URL atual do navegador (a origem do usuário que é enviada automaticamente em cada solicitação) corresponder a ele (veja a abordagem de app nativo [abaixo](#integration-options-native-apps)). É um componente crucial da especificação WebAuthn, na qual você pode se aprofundar [aqui](https://www.w3.org/TR/webauthn-2/). O Relying Party ID pode ser o domínio raiz (por exemplo, `corbado.com`) ou um subdomínio (`auth.corbado.com`). Você não pode armazenar o domínio raiz como Relying Party ID se ele estiver na lista de sufixos públicos (encontre a lista e as bibliotecas para detecção de sufixos públicos [aqui](https://publicsuffix.org/learn/)). Alterar o Relying Party ID de um serviço online quebrará as chaves de acesso existentes (exceções: o novo Relying Party ID é um subdomínio do antigo Relying Party ID, ou Related Origin Requests estão configurados via `.well-known/webauthn` para permitir o reuso de chaves de acesso em domínios relacionados). Durante o processo de autenticação, o Relying Party ID é verificado em relação à URL do navegador (origem do usuário) para garantir que eles correspondam. Correspondência nesse sentido significa que: - A URL do navegador (origem do usuário) corresponde exatamente ao Relying Party ID OU - A URL do navegador (origem do usuário) é um subdomínio que corresponde ao Relying Party ID e o domínio pai é registrável (por exemplo, `com` ou qualquer domínio na Public Suffix List não funciona) Aqui está um esboço detalhado de qual _originalHost_ (segunda coluna) tem permissão para acessar seu domínio pai: ![tabela do relying party id](https://www.corbado.com/website-assets/relying_party_id_table_4c98cc04f4.jpg) A seguir, você vê as [**PublicKeyCredentialCreationOptions**](https://www.w3.org/TR/webauthn-2/#iface-pkcredential) analisadas: ```json { "publicKey": { "attestation": "direct", "authenticatorSelection": { "authenticatorAttachment": "platform", "requireResidentKey": false, "userVerification": "preferred" }, "challenge": "qNqrdXUrk5S7dCM1MAYH3qSVDXznb-6prQoGqiACR10=", "excludeCredentials": [], "pubKeyCredParams": [ { "alg": -7, "type": "public-key" } ], "rp": { "id": "corbado.com", "name": "Corbado" }, "timeout": 30000, "user": { "displayName": "Corbado user", "id": "bz9ZDfHzOBLycqISTAdWwWIZt8VO-6mT3hBNXS5jwmY=" } } } ``` `rp` significa Relying Party. Um dos principais benefícios do Relying Party ID é a prevenção de ataques de phishing. Imagine o seguinte cenário: 1. Um invasor desenvolve um clone do [PayPal](https://www.corbado.com/blog/paypal-passkeys), que é um site falso que tenta roubar suas credenciais do [PayPal](https://www.corbado.com/blog/paypal-passkeys) para fazer login em seu nome e enviar dinheiro para a conta do invasor. Este site falso do [PayPal](https://www.corbado.com/blog/paypal-passkeys) está hospedado no domínio paybal.com (por isso, muitas vezes não é visível que é um domínio diferente à primeira vista). 2. Você já criou uma chave de acesso no passado para o site legítimo do PayPal. Esta chave de acesso armazenou o Relying Party ID paypal.com. 3. Você visita o site falso do PayPal em paybal.com (ao visitar este site, a origem de sua solicitação é paybal.com\*) e o site envia ao seu dispositivo (o autenticador) um desafio para o Relying Party ID `paypal.com` (aqui ele tenta enganá-lo) e pede que você o assine com sua chave de acesso para o Relying Party ID paypal.com. 4. Seu dispositivo (o autenticador) verifica se a origem da solicitação (`paypal.com`) e o Relying Party ID que ele armazenou na chave de acesso (`paypal.com`) correspondem. 5. Como eles obviamente não correspondem, a autenticação falha e impede que você dê a algum invasor acesso à sua conta do PayPal. O diagrama a seguir ilustra esse mecanismo de prevenção de phishing. _No caso de um app nativo, o manuseio da origem difere por plataforma: No Android, a origem é formatada como `android:apk-key-hash:`. No iOS, a origem da web do WebAuthn é a origem da web do RP (por exemplo, `https://paypal.com`). Em ambos os casos, a confiança entre seu app nativo e o servidor é verificada através do arquivo de associação correspondente (veja [abaixo](#configuring-relying-party-native-apps)). Para informações detalhadas sobre como a validação de origem funciona para apps nativos, consulte nosso guia dedicado sobre validação de origem WebAuthn para apps nativos._ ## 3. As duas opções diferentes de integração para apps nativos Para implementar chaves de acesso em um app nativo, um desenvolvedor pode decidir entre adicioná-las via [WebView](https://www.corbado.com/blog/native-app-passkeys) ou nativamente. Vamos examinar os benefícios e as desvantagens de ambas as abordagens a seguir. ### 3.1 Integração de chaves de acesso via WebView ![Integração de chave de acesso via WebView (GitHub)](https://www.corbado.com/website-assets/650c601b1eb462e25702a870_android_webview_passkey_github_8bc81d9852.jpg) Usar um **WebView**\* para integrar chaves de acesso significa embutir um navegador web dentro do app nativo para lidar com o processo de autenticação. Essa abordagem exibe essencialmente uma página da web dentro do app, facilitando o reuso de fluxos de autenticação baseados na web sem ter que reescrevê-los para a plataforma nativa. No entanto, existem algumas desvantagens. Os WebViews podem não suportar todos os recursos das chaves de acesso e há um risco potencial de ataques "man-in-the-middle" se não forem implementados com [segurança](https://www.corbado.com/pt/blog/senhas-complexas-quebradas-em-breve). Além disso, a experiência do usuário pode não ser tão suave quanto as integrações nativas, e pode haver desafios na manutenção do comportamento consistente em diferentes dispositivos e versões do sistema operacional. _\*Existem vários tipos de WebViews: No iOS (WKWebView, SFSafariViewController ou SFAuthenticationSession / ASWebAuthenticationSession para fluxos de autenticação baseados em OAuth/OpenID Connect) e Android (WebView, CCT-Chrome Custom Tabs). Consulte este artigo do blog para obter detalhes. Recomendamos o uso do SFSafariViewController/ ASWebAuthenticationSession e Chrome Custom Tabs no contexto de chaves de acesso se você não quiser uma integração nativa._ ### 3.2 Integração nativa de chaves de acesso ![Integração nativa de chave de acesso (Kayak)](https://www.corbado.com/website-assets/650c625cac723f594137a029_android_native_passkey_kayak_0f689e761e.jpg) **Integração nativa** envolve a construção da funcionalidade da chave de acesso diretamente no app [iOS](https://www.corbado.com/blog/how-to-enable-passkeys-ios) ou [Android](https://www.corbado.com/blog/how-to-enable-passkeys-android) usando APIs e bibliotecas específicas da plataforma. Esse método oferece uma experiência de usuário mais perfeita, pois não há necessidade de fazer a transição entre o app nativo e um [WebView](https://www.corbado.com/blog/native-app-passkeys). Ele também permite um melhor desempenho e uma aparência mais consistente. Do ponto de vista da segurança, a integração nativa pode oferecer proteção aprimorada contra certos tipos de ataques, especialmente quando combinada com recursos de segurança específicos da plataforma. No entanto, o esforço de implementação pode ser maior, pois os desenvolvedores precisam escrever e manter código separado para cada plataforma (Android e [iOS](https://www.corbado.com/blog/how-to-enable-passkeys-ios)). Além disso, manter-se atualizado com as especificações mais recentes de chaves de acesso / WebAuthn pode exigir atualizações de app mais frequentes. A seguir, nos concentramos na integração nativa de chaves de acesso. ## 4. Configurando a Relying Party para apps nativos Os apps nativos (por exemplo, apps iOS ou [Android](https://www.corbado.com/blog/how-to-enable-passkeys-android)) apresentam um desafio em comparação aos apps web. Diferente dos apps web, não há URL do navegador para corresponder ao Relying Party ID. Mesmo assim, para garantir o mesmo nível de segurança, os domínios são conectados a apps nativos através de **arquivos de associação**, para que a confiança entre um domínio e um app nativo seja estabelecida. Isso é particularmente importante se uma chave de acesso foi criada em um app web e deve ser usada para o mesmo Relying Party ID em um app nativo (e vice-versa). ### 4.1 Arquivos de associação no iOS: apple-app-site-association O iOS usa o arquivo apple-app-site-association. Este arquivo contém vários direitos (entitlements), mas para o WebAuthn e as chaves de acesso, o direito webcredentials é importante. ```json { "webcredentials": { "apps": ["9RF9KY88B2.com.corbado.passkeys"] } } ``` Em webcredentials.apps, você precisa armazenar seu Application Identifier Prefix (por exemplo, `9RF9KY77B2`) e seu Bundle Identifier (por exemplo, `com.corbado.passkeys`). Para que os apps nativos do iOS funcionem, o arquivo apple-app-site-association deve ser armazenado no diretório `/.well-known` do Relying Party ID (`https:///.well-known/apple-app-site-association`). Veja um exemplo ao vivo [aqui](https://pro-6244024196016258271.frontendapi.cloud.corbado.io/.well-known/apple-app-site-association). ### 4.2 Arquivos de associação no Android: assetlinks.json O [Android](https://www.corbado.com/blog/how-to-enable-passkeys-android) usa o arquivo `assetlinks.json`, que, assim como seu equivalente no iOS, requer configurações particulares para WebAuthn e chaves de acesso. ```json [ { "relation": [ "delegate_permission/common.handle_all_urls", "delegate_permission/common.get_login_creds" ], "target": { "namespace": "android_app", "package_name": "com.corbado.passkeys.pub", "sha256_cert_fingerprints": [ "F8:90:4E:9A:99:01:71:75:25:38:D5:36:16:2D:B3:65:EB:41:51:D4:53:9A:72:BC:4B:56:C5:16:43:62:E2:C0" ] } } ] ``` Você precisa ter os valores de relation `delegate_permission/common.handle_all_urls` e `delegate_permission/common.get_login_creds` definidos. Além disso, você precisa adicionar o nome do seu pacote e a impressão digital SHA-256 do seu certificado de assinatura. Para permitir o compartilhamento de uma chave de acesso entre um app nativo e um app web, você precisa adicionar duas entradas. Uma para o namespace web e uma para o namespace android_app. Veja um exemplo ao vivo [aqui](https://pro-6244024196016258271.frontendapi.cloud.corbado.io/.well-known/assetlinks.json). Para que os apps do Android funcionem, o arquivo assetlinks.json deve ser armazenado no diretório `/.well-known` do Relying Party ID `https:///.well-known/assetlinks.json` - portanto, muito parecido com o iOS. Confira este artigo do blog para ver um exemplo de implementação que compartilha chaves de acesso entre um app nativo do Android/iOS e um app web. ## 5. Estabelecendo a confiança entre um app nativo e um app web ### 5.1 iOS O processo para estabelecer a confiança entre um app iOS e um app web é o seguinte: 1. O desenvolvedor do app iOS precisa especificar uma lista de domínios que ele deseja associar ao app nativo. Esses domínios são codificados (hardcoded) nos direitos do app iOS, por exemplo: - webcredentials:auth.Corbado.com - webcredentials:\*.Corbado.com 2. Toda vez que o app iOS for instalado ou atualizado, o iOS fará o download do arquivo apple-app-site-association para cada entrada da lista de direitos do app iOS. 3. Quando uma credencial (por exemplo, chave de acesso) é criada dentro de um app iOS, o app iOS valida se o domínio do servidor da relying party está associado ao app iOS verificando os dois aspectos a seguir: - Existe um arquivo `apple-app-site-association` para este domínio do servidor da relying party no dispositivo? - O app iOS está listado nesse arquivo `apple-app-site-association`? Se, e somente se, ambas as perguntas puderem ser respondidas com sim, uma chave de acesso pode ser criada dentro do app iOS. ### 5.2 Android O processo para estabelecer a confiança entre um app Android e um app web é o seguinte: 1. O desenvolvedor do app Android precisa especificar uma lista de domínios que ele deseja associar ao app Android. Esses domínios são armazenados como destinos com o namespace web no arquivo assetlinks.json. Para declarar que os apps Android e os apps web compartilham credenciais, `delegate_permission/common.get_login_creds` precisa ser especificado. Encontre detalhes [aqui](https://developer.android.com/training/sign-in/passkeys#add-support-dal). 2. Se uma chave de acesso for criada dentro do app Android, o app Android validará se o Relying Party ID está associado ao app Android verificando o `assetlinks.json`: - Existe um arquivo `assetlinks.json` para este Relying Party ID em `https://./well-known/assetlinks.json`? - O app Android está definido corretamente como um alvo? 3. Se, e somente se, ambas as perguntas puderem ser respondidas com sim, uma chave de acesso pode ser criada dentro do app Android. O diagrama abaixo compara esses processos de estabelecimento de confiança lado a lado. ## 6. Visão geral para configurações de Android, iOS e Flutter A seguir, fornecemos uma visão geral detalhada das diferentes configurações que são necessárias para configurar adequadamente a autenticação com chaves de acesso para apps nativos. | Recurso | iOS | Android | | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Orientação de implementação oficial para autenticação de chaves de acesso nativa | Apple Developer | Google Developer | | Permite o compartilhamento de chaves de acesso com apps web | Sim, via arquivo apple-app-site-association | Sim, via assetlinks.json | | Localização do arquivo de associação | [https://acme.com/.well-known/apple-app-site-association](https://acme.com/.well-known/apple-app-site-association) | [https://acme.com/.well-known/assetlinks.json](https://acme.com/.well-known/assetlinks.json) | | Arquivo armazenado em cache | Sim (desde o iOS 14), a sincronização inicial pode levar até 24h | Sim (pelo Play Services) | | Possível ignorar (bypass) | Sim, com a seção de modo alternativo | Não | | Testável com | apple-app-site-association test | assetlinks.json test | | Identificador do app com exemplo | `.`, por exemplo, `T84QZS65DQ.com.facebook.Messenger` | Impressão digital SHA256, por exemplo, `E3:F9:E1:E0:CF:99:D0:E5:6A:05:5B:A6: 5E:24:1B:33:99: 7F:CE:A5:24:32: 6B:0C:DD:6E:C1:32: 7E:D0:FD:C1` | | Onde encontrar o identificador do app | O Team Application Identifier Prefix pode ser encontrado na conta do desenvolvedor em developer.apple.com e o Bundle Identifier é o nome exato do projeto XCode | Quando já enviado: Google Play Console > Gerenciamento de versão > Assinatura de app. Local: `keytool -list -v -keystore -alias -storepass -keypass ` | | Nome da seção que vincula o app à web | applinks (não necessário para chaves de acesso) | `delegate_permission/common.handle_all_urls` (necessário para chaves de acesso) | | Nome da seção que permite compartilhamento de credenciais entre app / web | webcredentials | `delegate_permission/common.get_login_creds` | | Registro de todos os arquivos de associação | Habilite e adicione o domínio associado no ambiente de desenvolvimento XCode (configuração da propriedade para gerar o arquivo de direitos) | Ao usar a API Credential Manager, o registro do assetlinks.json no manifesto não é necessário para chaves de acesso (para senhas, é). Ao não usar a API Credential Manager, você precisa listar os nomes de host com entrada `` no AndroidManifest.xml na atividade específica (parte do código-fonte do Android-App). O `` precisa ser autoVerify=true. | Para o [Flutter](https://www.corbado.com/blog/flutter-passkeys-package), a regra respectiva do Android ou iOS se aplica. A única configuração específica do [Flutter](https://www.corbado.com/blog/flutter-passkeys-package) é o registro dos arquivos de associação, onde você deve adicionar: - Para Android: [flutter_deeplinking_enabled no AndroidManifest.xml](https://docs.flutter.dev/cookbook/navigation/set-up-app-links) - Para iOS: [FlutterDeepLinkingEnabled true no Info.plist](https://docs.flutter.dev/cookbook/navigation/set-up-universal-links) ## 7. Exemplos de Relying Party ID e arquivos de associação válidos e inválidos Como nós mesmos experimentamos, trabalhar com Relying Party IDs, diferentes níveis de (sub)domínios e CNAMEs pode ser uma tarefa bastante desafiadora, apresentamos quatro exemplos distintos e explicamos por que e como eles funcionam. Observe que a linha CNAME da tabela não é necessária para a autenticação com chave de acesso e é apenas o resultado de nossa pesquisa que queríamos adicionar. ### 7.1 Exemplo 1: a Relying Party é o domínio raiz | **Relying Party ID** | corbado.com | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **Entitlements (apenas iOS)** | webcredentials:corbado.com | | **Localização do arquivo apple-app-site-association** | [https://corbado.com/.well-known/apple-app-site-association](https://corbado.com/.well-known/apple-app-site-association) | | **Localização do arquivo assetlinks.json** | [https://corbado.com/.well-known/assetlinks.json](https://corbado.com/.well-known/assetlinks.json) | | **CNAME** | n/a | Neste exemplo, o arquivo `apple-app-site-association` / `assetlinks.json` para Corbado.com pode ser baixado sem nenhum problema quando o app nativo é instalado / atualizado, porque o arquivo está na mesma localização do Relying Party ID. **Uma chave de acesso para o Relying Party ID pode ser criada.** ### 7.2 Exemplo 2: a Relying Party é um subdomínio e o CNAME está configurado | Relying Party ID | auth.corbado.com | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Entitlements (apenas iOS)** | webcredentials:auth.corbado.com | | **Localização do arquivo apple-app-site-association** | [https://pro-123.passkeys.eu/.well-known/apple-app-site-association](https://pro-123.passkeys.eu/.well-known/apple-app-site-association) | | **Localização do arquivo assetlinks.json** | [https://pro-123.passkeys.eu/.well-known/assetlinks.json](https://pro-123.passkeys.eu/.well-known/assetlinks.json) | | **CNAME** | auth.corbado.com => pro-123.passkeys.eu | Neste exemplo, o arquivo `apple-app-site-association` / `assetlinks.json` para auth.corbado.com pode ser baixado sem nenhum problema quando o app nativo é instalado / atualizado, porque o arquivo está no local do Relying Party ID, já que o CNAME aponta do Relying Party ID para a localização armazenada. **Uma chave de acesso para o Relying Party ID pode ser criada.** ### 7.3 Exemplo 3: a Relying Party é o domínio raiz e o CNAME está configurado | Relying Party ID | corbado.com | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Entitlements (apenas iOS)** | webcredentials:corbado.com; webcredentials:auth.corbado.com | | **Localização do arquivo apple-app-site-association** | [https://pro-123.passkeys.eu/.well-known/apple-app-site-association](https://pro-123.passkeys.eu/.well-known/apple-app-site-association) | | **Localização do arquivo assetlinks.json** | [https://pro-123.passkeys.eu/.well-known/assetlinks.json](https://pro-123.passkeys.eu/.well-known/assetlinks.json) | | **CNAME** | auth.corbado.com => pro-123.passkeys.eu | Neste exemplo, o arquivo `apple-app-site-association` / `assetlinks.json` para auth.corbado.com pode ser baixado sem problemas quando o app nativo é instalado/atualizado, porque o arquivo está, devido ao CNAME, no local onde `auth.corbado.com` o espera. MAS: O `apple-site-association-file` / `assetlinks.json` para corbado.com não pode ser baixado quando o app nativo é instalado/atualizado, porque o arquivo não está em `https://corbado.com/.well-known/apple-app-site-association` / `https://corbado.com/.well-known/assetlinks.json`, onde é esperado, e nenhum CNAME está apontando para ele. **Uma chave de acesso para o Relying Party ID não pode ser criada.** ### 7.4 Exemplo 4: a Relying Party é um subdomínio e o Entitlement coringa (wildcard) está configurado | Relying Party ID | auth.corbado.com | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **Entitlements (apenas iOS)** | webcredentials:\*.corbado.com | | **Localização do arquivo apple-app-site-association** | [https://corbado.com/.well-known/apple-app-site-association](https://corbado.com/.well-known/apple-app-site-association) | | **Localização do arquivo assetlinks.json** | [https://corbado.com/.well-known/assetlinks.json](https://corbado.com/.well-known/assetlinks.json) | | **CNAME** | n/a | Neste exemplo, o arquivo `apple-app-site-association` para corbado.com pode ser baixado sem nenhum problema, quando o app nativo é instalado / atualizado, porque o arquivo está onde é esperado e o entitlement de webcredentials (`*.corbado.com`) corresponde ao Relying Party ID (`auth.corbado.com`). Observe que este exemplo não funciona para o Android, pois o Android não funciona com algo como entitlements curinga (wildcard). Em geral, essa maneira de definir Relying Party IDs não é recomendada. **Uma chave de acesso para o Relying Party ID pode ser criada.** ## 8. Erros comuns de Relying Party ID e como evitá-los ### 8.1 Alterando o Relying Party ID de subdomínio para domínio raiz **Erro:** Você começou a desenvolver e definiu um subdomínio (por exemplo, `login.acme.com`) como seu Relying Party ID. Os primeiros usuários criaram uma chave de acesso para este Relying Party ID. Então, você nota que também precisa dessas chaves de acesso para autenticação em outro subdomínio (por exemplo, `app.acme.com`). Como a origem de um usuário e o Relying Party ID para o novo subdomínio não correspondem, o usuário não pode fazer login com a chave de acesso. Mudar o Relying Party ID nas suas configurações de WebAuthn para `acme.com` invalidaria todas as chaves de acesso existentes, pois a nova origem e o Relying Party ID armazenado nas chaves de acesso existentes não correspondem. **Solução:** Verifique duplamente no início, ao definir seu Relying Party ID, pois isso é mais ou menos definitivo. Se você não tem certeza e quer estar pronto para o futuro, o que significa que outros subdomínios no futuro podem precisar da chave de acesso para autenticação, recomendamos que use o domínio raiz (por exemplo, acme.com) como Relying party ID, a menos que ele esteja na [Public Suffix List](https://publicsuffix.org/learn/). ### 8.2 Diferentes Relying Party IDs para apps nativos e web **Erro:** Você está desenvolvendo um app nativo e web simultaneamente. Para agilizar as coisas, você usa dois servidores WebAuthn diferentes (com diferentes Relying Party IDs para o app nativo e web). À medida que seus usuários criam as primeiras chaves de acesso, o respectivo Relying Party ID é armazenado na chave de acesso. Permitir login entre dispositivos / plataformas com a mesma chave de acesso, por exemplo, com uma chave de acesso criada em um app web e tentando entrar em um app nativo, não é mais possível. Mesclar os dois servidores WebAuthn abandonará as chaves de acesso que foram registradas com o servidor WebAuthn antigo (Relying Party ID antigo) e seus usuários não poderão fazer login com essas chaves de acesso. **Solução:** Se você tiver vários aplicativos (por exemplo, um app web e um app nativo), tenha sempre apenas um servidor WebAuthn e defina apenas um Relying Party ID para todos os seus apps. A vinculação entre esses aplicativos pode ser feita através das etapas descritas acima. ### 8.3 Arquivos de associação inválidos e inacessíveis **Erro:** Você começou a desenvolver seu aplicativo, configurou os arquivos de associação e os implantou no seu servidor. Por algum motivo, você ainda está recebendo mensagens de erro e não encontra a causa raiz. **Solução:** Uma causa potencial para a mensagem de erro pode ser um arquivo de associação malformado ou inacessível. Antes de implantar qualquer arquivo de associação em um servidor, recomendamos fortemente que verifique a validade e acessibilidade (muitas vezes esses arquivos podem estar por trás de [uma VPN robusta](https://cybernews.com/best-vpn/most-secure-vpns/) ou firewall que impede o acesso adequado dos crawlers da Apple e do Google) de um arquivo de associação através das ferramentas fornecidas para [iOS](https://www.corbado.com/blog/how-to-enable-passkeys-ios) e Android. ### 8.4 Arquivo apple-app-site-association não está em cache na CDN da Apple ainda **Erro:** Você implantou seu arquivo apple-app-site-association no seu servidor e deseja começar a criar imediatamente uma chave de acesso em seu dispositivo de teste. Por algum motivo, você não consegue criar a chave de acesso e recebe mensagens de erro. **Solução:** O motivo por trás dessas mensagens de erro é que os dispositivos iOS baixam o arquivo `apple-app-site-association` para validar a Relying Party. Para isso, os dispositivos iOS não enviam uma solicitação direta para o seu servidor, mas usam uma CDN. Tanto o dispositivo quanto a CDN armazenam em cache o arquivo `apple-app-site-association` depois que ele for recuperado com sucesso. Devido a essa funcionalidade de cache, as novas mudanças em seu arquivo `apple-app-site-association` não são refletidas diretamente em seu app. Pode levar até 24 horas até que a CDN armazene em cache o arquivo `apple-app-site-association`. Para contornar essa restrição durante o desenvolvimento, você pode adicionar `?mode=developer` ao Relying Party ID e desabilitar totalmente o cache (por exemplo, o Relying Party ID seria `acme.com?mode=developer`). ### 8.5 Incompatibilidade entre o Emulador Android e a versão da API **Erro:** Você começou a desenvolver um app Android e deseja testá-lo em um emulador Android. Por algum motivo, você está recebendo mensagens de erro, mesmo tendo configurado o emulador Android corretamente e outros apps parecem funcionar perfeitamente nele. **Solução:** As versões do Android, o suporte da Play Store e as versões da API desempenham um papel importante ao testar um aplicativo de chaves de acesso. Além disso, você precisa estar logado em uma conta do Google. Consulte nossa seção de solução de problemas para obter detalhes. ## 9. Recomendação ### 9.1 Recomendação geral Nossa recomendação geral é escolher o seu Relying Party ID com cuidado, com base na paisagem do seu aplicativo e requisitos. Abaixo, coletamos os casos de uso mais comuns, mas nossa recomendação geral é que você deve **buscar escolher o seu domínio raiz como o seu Relying Party ID** e configurar a sua autenticação dessa maneira. Com a Corbado, nós também já pré-configuramos isso para você dessa forma (como parte da nossa abordagem para oferecer uma autenticação de chaves de acesso contínua para todas as configurações técnicas. Nossos componentes de interface de usuário (UI) e SDKs estão preparados para serem usados com o seu domínio raiz como Relying Party ID). | Caso | Recomendação | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **A) Você tem um domínio raiz:**

Exemplo: acme.com

Todos os aplicativos e a autenticação rodam nesse domínio raiz ou subdomínios dele | ✔️ Escolha o domínio raiz como seu Relying Party ID, pois isso não causará problemas para apps nativos ou web. | | **B) Você tem vários domínios raiz:**

Exemplo: kayak.com, kayak.co.uk, kayak.de

Você atende os seus usuários de diferentes domínios de nível superior internacionais. Kayak.com para os EUA e kayak.co.uk para o Reino Unido ou você tem domínios raiz completamente diferentes que deveriam permitir que os mesmos usuários fizessem login com as mesmas chaves de acesso. | ⚠️ Nos seus apps web, compartilhar chaves de acesso requer configurar as Related Origin Requests via `.well-known/webauthn` para permitir que origens especificadas usem um RP ID em comum (o suporte do navegador varia; verifique a compatibilidade). Como alternativa, escolha um domínio raiz de autenticação comum.

✔️ Você pode conectar seus apps nativos a qualquer número de domínios raiz desde que você tenha controle sobre os arquivos de associação raiz.

❌ No caso de você querer migrar depois para outro domínio raiz para hospedar o seu site, você não conseguirá usar as suas chaves de acesso já criadas, porque você terá que reformular e mudar o domínio (Relying Party ID). | | **C) Você NÃO tem um domínio raiz ainda, você está rodando apenas no backend ou em um subdomínio público. Existem alguns casos em que isso pode acontecer:**

1. Você trabalha em um subdomínio livremente disponível, onde o domínio raiz não está sob o seu controle (o domínio raiz está listado em [https://publicsuffix.org/](https://publicsuffix.org/)) por exemplo URLs de CDN

2. Você trabalha em um app nativo. | ❌ Em subdomínios públicos, você não pode controlar os arquivos de associação a nível raiz do domínio raiz. Portanto, as chaves de acesso não funcionarão nativamente.

⚠️ A única maneira de consertar isso em alguns serviços é mudar para um plano pago, onde você pode definir um CNAME ou obter um domínio raiz customizado para você. | ### 9.2 Recomendação ao usar a Corbado A seguir, fornecemos uma árvore de decisão muito específica que deve ajudar a determinar o Relying Party ID correto e como você deve lidar / hospedar os arquivos de associação ao usar a Corbado como sua solução de chaves de acesso. A primeira decisão é se você está em um ambiente de desenvolvimento ou de produção. O próximo nível de decisão que você deve tomar é baseado na paisagem do seu aplicativo: você tem apenas um app nativo ou um app nativo e um app web. #### A) Desenvolvimento Para o ambiente de desenvolvimento, assumimos que você quer iniciar o desenvolvimento e testes rapidamente. O Relying Party ID pode ser alterado depois, se você quiser colocar em produção. ##### A1) Apenas nativo - Definir Relying Party ID = `pro-XXX.frontendapi.cloud.corbado.io` (valor padrão) - A Corbado hospeda o arquivo de associação para você - Nenhuma tarefa pendente de DNS para você ##### A2) App nativo e app web Não é fácil testar o app web e o app nativo ao mesmo tempo **Opção 1:** Ou você define Relying Party ID = `pro-XXX.frontendapi.cloud.corbado.io` (app nativo funciona) OU define Relying Party ID = `localhost` (app web funciona) **Opção 2:** A única solução para app nativo e web funcionarem ao mesmo tempo é usar um proxy reverso local (é uma solução meio improvisada): - Definir Relying Party ID = `acme-dev.com` - Definir CNAME de `acme-dev.com` => `pro-XXX.frontendapi.cloud.corbado.io` - Adicionar entrada `/etc/hosts` local `localhost acme-dev.com` - Adicionar proxy reverso (nginx) com regra para `acme-dev.com` => `localhost:3000` (como um exemplo) #### B) Produção No ambiente de produção, você precisa decidir se você está satisfeito com um subdomínio como o Relying Party ID (por exemplo, `auth.acme.com`) ou se você quer um domínio raiz como o Relying Party ID (por exemplo, `acme.com`) ##### B1) Subdomínio como Relying Party ID ###### B1.1) Apenas nativo - Definir Relying Party ID = `auth.acme.com` - A Corbado hospeda o arquivo de associação para você - Definir CNAME de `auth.acme.com` => `pro-XXX.frontendapi.cloud.corbado.io` ###### B1.2) App nativo e app web - Definir Relying Party ID = `auth.acme.com` - A Corbado hospeda o arquivo de associação para você - Definir CNAME de `auth.acme.com` => `pro-XXX.frontendapi.cloud.corbado.io` (também necessário para os cookies funcionarem se você usar o gerenciamento de sessões da Corbado) ##### B2) Domínio raiz como Relying Party ID ###### B2.1) Apenas nativo - Definir Relying Party ID = `acme.com` - Hospedar o arquivo de associação você mesmo no seu próprio servidor em `acme.com/.well-known/` - Nenhuma tarefa pendente de DNS para você ###### B2.2) App nativo e app web - Definir Relying Party ID = `acme.com` - Hospedar o arquivo de associação você mesmo no seu próprio servidor em `acme.com/.well-known/` - Se você usar o gerenciamento de sessões da Corbado, você precisa definir CNAME de `auth.acme.com` => `pro-XXX.frontendapi.cloud.corbado.io` para fazer os cookies funcionarem (este CNAME não é necessário para o Relying Party ID, apenas para o gerenciamento de sessão) A árvore de decisão a seguir resume todos os caminhos de configuração. ## 10. Conclusão O Relying Party ID é uma pedra [angular](https://www.corbado.com/blog/angular-passkeys) do WebAuthn e da autenticação baseada em chaves de acesso e fornece uma forte resistência a phishing. Configurá-lo adequadamente, entender as complexidades de correspondência de domínios e garantir a implantação correta para apps nativos é crucial. Esta postagem do blog mostrou como configurá-los corretamente e como lidar com diferentes erros. Depois que a sua configuração de rpID estiver sólida, concentre-se na otimização dos fluxos de [criação de chaves de acesso](https://www.corbado.com/pt/blog/melhores-praticas-criacao-passkeys) e fluxos de [login com chaves de acesso](https://www.corbado.com/pt/blog/aumentar-adocao-login-passkeys) para impulsionar a adoção real. Para mais ideias sobre como configurar chaves de acesso para app nativo, recomendamos ler sobre chaves de acesso no [Flutter](https://www.corbado.com/blog/flutter-passkeys-package). Se você tiver mais dúvidas ou precisar de assistência, não hesite em [entrar em contato](https://bit.ly/passkeys-community). ## Perguntas Frequentes ### Como o Relying Party ID previne o phishing na autenticação com chaves de acesso? O autenticador compara a origem real do navegador com o Relying Party ID armazenado na chave de acesso. Se um invasor hospedar um site falso em um domínio diferente, a incompatibilidade de origem fará com que a autenticação falhe automaticamente, mesmo que o desafio falsificado reivindique um RP ID legítimo. Essa vinculação significa que uma chave de acesso registrada em paypal.com não pode ser usada em um domínio parecido como paybal.com. ### O que acontece se eu alterar meu WebAuthn Relying Party ID depois que os usuários já registraram chaves de acesso? Alterar o RP ID invalida todas as chaves de acesso existentes porque o RP ID armazenado em cada credencial não corresponderá mais ao novo valor. As únicas exceções são quando o novo RP ID é um subdomínio do antigo ou quando Related Origin Requests são configurados via `.well-known/webauthn`. Escolha o domínio raiz como RP ID desde o início para evitar este problema irreversível. ### Por que minha chave de acesso do iOS não funciona imediatamente após eu implantar o arquivo apple-app-site-association? O iOS não busca o arquivo apple-app-site-association diretamente do seu servidor. Ele usa a CDN da Apple, que pode levar até 24 horas para armazenar em cache um arquivo recém-implantado ou atualizado. Durante o desenvolvimento, anexe `?mode=developer` ao Relying Party ID para contornar o cache inteiramente. ### Devo usar um subdomínio ou domínio raiz como meu Relying Party ID para chaves de acesso? O uso do domínio raiz (por exemplo, acme.com) é recomendado porque as chaves de acesso criadas em qualquer subdomínio podem se autenticar em todos os subdomínios desse raiz. Um RP ID de subdomínio restringe o uso da chave de acesso a esse subdomínio e seus filhos, o que pode quebrar fluxos entre subdomínios posteriormente. Se você tiver vários domínios raiz, como acme.com e acme.co.uk, configure Related Origin Requests via `.well-known/webauthn` para permitir a reutilização de chaves de acesso entre eles.