Chaves de acesso em aplicações nativas: implementação nativa vs. WebView

Nota: System e Embedded WebView são frequentemente combinados, onde o System WebView gere o início de sessão (com partilha automática de credenciais), e o Embedded WebView apresenta a gestão de chaves de acesso nas definições.

Fatores de decisão essenciais:

• Início de sessão baseado em OAuth? → System WebView (ASWebAuthenticationSession, Chrome Custom Tabs)
• Quer reutilizar a autenticação web na shell nativa? → Embedded WebView (WKWebView, Android WebView com WebKit 1.12.1+)
• A criar uma aplicação nativa (native-first)? → Implementação nativa (Apple AuthenticationServices, Google Credential Manager)

As plataformas móveis modernas fornecem três abordagens distintas para integrar chaves de acesso na sua aplicação nativa, cada uma com diferentes compromissos para a experiência do utilizador, complexidade técnica e compatibilidade OAuth:

1. Implementação nativa: crie fluxos de chaves de acesso diretamente na sua aplicação usando APIs da plataforma (iOS AuthenticationServices, Android Credential Manager). Fornece a melhor experiência de utilizador com autenticação biométrica perfeita, mas requer um esforço de implementação técnica médio a alto.

2. System WebView: use o componente de navegador da plataforma (iOS ASWebAuthenticationSession / SFSafariViewController, Android Chrome Custom Tabs) para gerir a autenticação. Excelente para fluxos de início de sessão baseados em OAuth e partilha credenciais com o navegador do sistema.

3. Embedded WebView: incorpore uma visualização web personalizável (iOS WKWebView, Android WebView) na sua aplicação para reutilizar a autenticação web com uma estrutura de aplicação nativa. Fornece uma aparência nativa sem barras de URL e controlo total sobre a IU da visualização web. Requer configuração adicional, incluindo permissões e direitos (iOS), e configuração de WebView com AndroidX WebKit 1.12.1+ (Android) para ativar a funcionalidade de chave de acesso.

A escolha certa depende da arquitetura de autenticação da sua aplicação, se utiliza fornecedores OAuth, de quanto controlo necessita sobre a IU e se está a criar uma aplicação native-first ou a reutilizar componentes web.

Whitepaper empresarial de Passkeys. Guias práticos, padrões de implementação e KPIs para programas de passkeys.

Obter whitepaper

Uma implementação nativa de chaves de acesso proporciona a melhor experiência de utilizador, com fluxos de autenticação integrados diretamente na IU da sua aplicação utilizando APIs específicas da plataforma. Os utilizadores beneficiam de diálogos nativos da plataforma, verificação biométrica perfeita e os tempos de início de sessão mais rápidos possíveis.

Quando escolher a Implementação nativa:

• A construir uma nova aplicação nativa ou a refatorar a autenticação para ecrãs nativos
• Pretende a melhor experiência de utilizador possível com autenticação instantânea e silenciosa
• Avisos automáticos de chaves de acesso no arranque da aplicação: as implementações nativas podem usar preferImmediatelyAvailableCredentials para exibir automaticamente a sobreposição de chaves de acesso quando estas estiverem disponíveis, proporcionando a experiência de início de sessão mais rápida sem exigir a introdução de um identificador
• Necessita de controlo total sobre a IU e o fluxo de autenticação
• Disposto a investir numa implementação específica da plataforma (iOS Swift, Android Kotlin)

Vantagem principal: preferImmediatelyAvailableCredentials()

As implementações nativas podem tirar partido de preferImmediatelyAvailableCredentials() para criar uma sobreposição automática de chave de acesso que aparece imediatamente no arranque da aplicação quando existem chaves de acesso disponíveis. Este fluxo sem nome de utilizador fornece a experiência de início de sessão mais rápida possível - os utilizadores veem as suas chaves de acesso instantaneamente sem terem de introduzir primeiro um identificador. Esta capacidade é exclusiva das implementações nativas e não está disponível nas variantes WebView.

O diagrama abaixo ilustra como a autenticação nativa proporciona um percurso do utilizador mais rápido em comparação com a abordagem Conditional UI da WebView:

A sobreposição automática nativa proporciona uma UX superior com taxas de utilização de chaves de acesso mais elevadas, uma vez que a autenticação começa imediatamente no arranque da aplicação, enquanto as implementações WebView exigem que os utilizadores interajam primeiro com os campos de entrada.

Visão geral dos requisitos técnicos:

A integração de chaves de acesso nativas requer confiança criptográfica entre a sua aplicação e o domínio web. Sem isso, o SO rejeitará todas as operações WebAuthn. Requisitos principais:

1. Ficheiros de associação App-Domínio alojados em /.well-known/
2. ID de Relying Party correto correspondente ao seu domínio web
3. Capacidades específicas da plataforma (detalhadas na Secção 4)

A principal vantagem: as chaves de acesso criadas no seu website funcionam perfeitamente na sua aplicação e vice-versa.

A implementação de chaves de acesso nativamente no iOS envolve o framework AuthenticationServices da Apple, que fornece uma API para operações WebAuthn:

Componentes principais:

• ASAuthorizationController: gere o fluxo de autenticação
• ASAuthorizationPlatformPublicKeyCredentialProvider: cria pedidos de chaves de acesso
• Três modos de IU distintos para gerir o início de sessão com chaves de acesso:
  • Início de sessão com campo de texto: campo tradicional de nome de utilizador com o início de sessão por chave de acesso a começar no botão de submissão
  • Sobreposição modal de chave de acesso: diálogo do SO que lista as chaves de acesso disponíveis
  • Conditional UI: sugestões de chaves de acesso na barra QuickType acima do teclado

Dicas de desenvolvimento

• Cache do AASA: a Apple guarda o ficheiro AASA em cache de forma agressiva (até 24 horas), o que pode frustrar os testes. Solução: ative o Modo de Programador no seu dispositivo de teste e acrescente ?mode=developer ao seu URL AASA para forçar obtenções recentes
• Testes de desempenho: teste com contas do iCloud que contêm centenas de credenciais para observar a latência do mundo real. A sobreposição do sistema pode apresentar um ligeiro atraso com muitas chaves de acesso guardadas

A implementação de chaves de acesso nativas no Android usa a Credential Manager API (ou a API FIDO2 mais antiga para retrocompatibilidade):

Componentes principais:

• CredentialManager: API central para todas as operações com credenciais
• CreatePublicKeyCredentialRequest: para registo de chave de acesso
• GetCredentialRequest: para autenticação com chave de acesso
• Dois modos primários de IU:
  • Início de sessão com campo de texto: campo tradicional de nome de utilizador com o início de sessão por chave de acesso a começar no botão de submissão
  • Sobreposição modal de chave de acesso: diálogo do SO que lista as chaves de acesso disponíveis

Nota: atualmente, o Android não possui as sugestões de teclado da Conditional UI do iOS em aplicações nativas (embora a Conditional UI funcione em aplicações web).

A implementação nativa de chaves de acesso apresenta desafios e lições aprendidas importantes: a integração ao nível do SO pode trazer à superfície problemas em diferentes dispositivos e versões do SO.

1. Por exemplo, a nossa equipa deparou-se com problemas como o cache agressivo da Apple do ficheiro apple-app-site-association (usado para ligar as credenciais da aplicação/web) e subtis diferenças de IU em certos prompts biométricos de OEM do Android.
2. Além disso, considere que em alguns cenários empresariais, dispositivos geridos podem ter a sincronização de chaves de acesso desativada por política. Em ambientes corporativos onde a sincronização do iCloud Keychain ou do Google Password Manager está desativada, as chaves de acesso ficam vinculadas ao dispositivo e não fazem roaming - um cenário importante a prever (por exemplo, garantir que os utilizadores ainda conseguem iniciar sessão se tiverem um telemóvel novo).
3. Adicionalmente, aplicações de gestão de credenciais de terceiros podem influenciar o fluxo. Por exemplo, se um utilizador tiver um gestor de palavras-passe como o 1Password definido como fornecedor ativo de credenciais, este irá frequentemente intercetar a criação e o armazenamento das chaves de acesso, assumindo prioridade sobre o gestor de credenciais nativo da plataforma.

Embora seja possível implementar chaves de acesso utilizando APIs de plataforma puras, SDKs específicos aceleram significativamente o desenvolvimento ao lidarem com a complexidade do WebAuthn, casos extremos e por fornecerem telemetria integrada. Os SDKs também oferecem interfaces mockáveis para testes unitários (cruciais visto que não se pode testar biometria em simuladores).

Recomendação: para implementações nativas, recomendamos o uso dos SDKs da Corbado (iOS Swift Passkey SDK, Android Kotlin Passkey SDK), que lidam com os inúmeros casos extremos descobertos através de implementações em produção e fornecem telemetria e testes adicionais.

Igor Gjorgjioski

Head of Digital Channels & Platform Enablement, VicRoads

We hit 80% mobile passkey activation across 5M+ users without replacing our IDP.

See how VicRoads scaled passkeys to 5M+ users — alongside their existing IDP.

Read the case study

As System WebViews usam o componente nativo de navegador da plataforma para lidar com a autenticação dentro da sua aplicação. Ao contrário das implementações puramente nativas, as System WebViews apresentam conteúdo web usando o navegador real do sistema (Safari no iOS, Chrome no Android), mantendo cookies partilhados, credenciais guardadas e os indicadores de segurança familiares do navegador.

Quando escolher a System WebView:

• A sua aplicação usa início de sessão baseado em OAuth: o System WebView é a abordagem recomendada para fluxos OAuth2/OIDC, proporcionando uma autenticação segura
• Autenticação baseada na web existente que deseja reutilizar em aplicações móveis
• Necessita suportar vários métodos de autenticação (palavras-passe, início de sessão social, chaves de acesso) sem ter de reconstruir nativamente
• Deseja manter uma base de código de autenticação única na web e em mobile

Principais vantagens:

• Compatibilidade OAuth: concebida para fluxos de autenticação OAuth/OIDC
• Indicadores de segurança: os utilizadores veem o URL e os certificados SSL reais, criando confiança
• Baixo esforço de implementação: mínimo código nativo necessário
• UX consistente: interface de navegador familiar em que os utilizadores já confiam

Componentes da plataforma:

• iOS: ASWebAuthenticationSession (recomendado para fluxos de autenticação) ou SFSafariViewController (navegação geral)
• Android: Chrome Custom Tabs (CCT)

Grandes empresas como o Google e o GitHub adotaram esta abordagem para adicionar o início de sessão por chave de acesso às suas aplicações móveis através de sobreposições de WebView em páginas de autenticação web já existentes. Isto funciona bem quando não é imediatamente viável reconstruir totalmente a autenticação nativa.

O iOS fornece dois componentes principais de System WebView para autenticação:

ASWebAuthenticationSession (Recomendado para Autenticação):

• Construído para OAuth/OIDC e fluxos de início de sessão seguros
• Avisa automaticamente o utilizador que a aplicação pretende autenticar
• Partilha cookies e credenciais com o Safari
• Suporta chaves de acesso via iCloud Keychain

SFSafariViewController (Navegação Geral):

• Experiência completa do Safari dentro da aplicação
• Mostra a barra de URL e os indicadores de segurança
• Não partilha os cookies do Safari no iOS 11+; utilize o ASWebAuthenticationSession quando for necessária a partilha de sessões do Safari
• Menos personalizável, mas transmite mais confiança aos utilizadores

Se a sua aplicação utiliza o início de sessão baseado em OAuth, a ASWebAuthenticationSession é a escolha recomendada, pois foi desenhada especificamente para cenários de autenticação e fornece o melhor equilíbrio entre segurança e experiência do utilizador.

O Chrome Custom Tabs (CCT) fornece uma experiência de autenticação alimentada pelo Chrome dentro da sua aplicação:

Principais características:

• Partilha cookies e credenciais com o navegador Chrome
• Mostra URL e indicadores de segurança
• Permite personalizar a cor da barra de ferramentas e o branding
• Pré-aquecimento (pre-warming) para tempos de carregamento mais rápidos

Integração OAuth: o Chrome Custom Tabs é o equivalente Android do iOS ASWebAuthenticationSession, fornecendo excelente suporte a OAuth enquanto mantém o acesso às chaves de acesso armazenadas.

Teste passkeys em uma demo ao vivo.

Testar passkeys

As Embedded WebViews fornecem controlo total sobre a renderização do conteúdo web na sua aplicação, permitindo a manipulação direta de cookies, sessões e navegação sem a barra de URL. No entanto, este controlo implica requisitos técnicos adicionais para ativar a funcionalidade de chave de acesso.

Quando escolher Embedded WebView:

• Experiência nativa: a sua aplicação já incorpora a autenticação num web view personalizado para manter um aspeto e comportamento nativos e deseja manter esta experiência de utilizador consistente
• Necessita controlo sobre a sessão/cookies: a sua aplicação requer a manipulação direta de tokens de autenticação e do estado da sessão após o término da autenticação OAuth
• Fluxo de autenticação existente onde a autenticação System WebView retorna um código de autenticação, mas não uma sessão em contextos embebidos
• Tem de manter o estado autenticado através de vários ecrãs web incorporados
• Autenticação originais apenas: a sua aplicação gere a autenticação diretamente; para implementações de chaves de acesso de terceiros, veja aqui
• AndroidX WebKit 1.12.1+ com deteção de funcionalidades em tempo de execução
• Aceita a limitação de Conditional UI para Login (não suportado na Embedded WebView), o que não é relevante para configurações de gestão

Contexto importante:

Muitas aplicações utilizam uma abordagem híbrida: a System WebView lida com a autenticação OAuth inicial (onde as chaves de acesso funcionam perfeitamente), e depois muda para a Embedded WebView no pós-autenticação para gerir as chaves de acesso nas definições. O desafio surge quando se tenta usar chaves de acesso diretamente dentro de Embedded WebViews.

Requisitos técnicos:

As Embedded WebViews requerem configurações adicionais em comparação com as System WebViews:

1. iOS: Direitos de Associated Domains, configuração de ficheiro AASA
2. Android: AndroidX WebKit 1.12.1+ com configuração de WebAuthn do WebView (necessita deteção de funcionalidade)
3. Ambos: Ficheiros de associação well-known devidamente configurados e Digital Asset Links

Componentes de plataforma:

• iOS: WKWebView
• Android: android.webkit.WebView

Compromissos:

• Complexidade média: Requer configuração da WebView (Android WebKit 1.12.1+) e a configuração de direitos (iOS)
• Menor adoção de chaves de acesso: Os utilizadores poderão encontrar mais atrito comparativamente a uma solução nativa
• Conditional UI não suportada: O preenchimento automático de chaves de acesso em campos de introdução não funciona no Android Embedded WebView
• Suporte limitado de plataforma: Algumas funcionalidades poderão não funcionar de modo consistente (ex. criação automática de chave de acesso)

Ao implementar chaves de acesso através de WebViews, é crucial compreender a distinção entre System WebViews e Embedded WebViews. As três abordagens descritas acima (Implementação Nativa, System WebView e Embedded WebView) servem, cada uma, casos de uso diferentes.

No iOS, tem várias opções para apresentar conteúdo web na aplicação:

• WKWebView é um WebView personalizável que faz parte do framework WebKit (introduzido no iOS 8). Dá-lhe grande controlo sobre o aspeto e comportamento do conteúdo web.
• SFSafariViewController é um view controller disponibilizado pela Apple que atua como um browser Safari leve dentro da sua aplicação. Utiliza o motor do Safari. No iOS 11+, tem um armazém de cookies em separado e não partilha os cookies do Safari. Use ASWebAuthenticationSession quando for necessária a partilha da sessão do Safari.
• SFAuthenticationSession / ASWebAuthenticationSession são sessões de autenticação web especializadas (disponíveis desde o iOS 11/12) destinadas especificamente para fluxos de login como OAuth/OpenID ou outros fluxos seguros. Também tiram partido do Safari por trás, mas estão focadas nos fluxos de autenticação e gerem automaticamente processos como a partilha de cookies e o Single Sign-On (SSO).

No Android, as principais opções são:

• Android WebView é o widget padrão de WebView (android.webkit.WebView), que essencialmente é um mini browser que pode ser incorporado nas suas atividades. É altamente personalizável, mas corre no processo da sua aplicação.
• Chrome Custom Tabs (CCT) é uma funcionalidade que abre um separador potenciado pelo Chrome dentro do contexto da sua aplicação. As Custom Tabs surgem como parte da sua aplicação, mas são alimentadas pelo browser Chrome (se instalado) com funcionalidades como o pré-carregamento, partilha de cookies e a barra URL familiar para passar confiança ao utilizador.

Nas próximas secções, entraremos em maior detalhe sobre estes tipos de WebView no iOS e Android, e discutiremos qual se adapta melhor aos fluxos de autenticação com chave de acesso.

Assine nosso Substack de passkeys para receber as últimas novidades.

Assinar

A plataforma da Apple fornece as três opções de WebView listadas acima. A sua escolha afetará a fluidez da utilização das chaves de acesso na aplicação:

Para testar o comportamento das várias WebViews no iOS, recomendamos a aplicação WebView - WKWebView and UIWebView rendering.

A WKWebView é um componente WebView versátil para iOS. Os programadores podem incorporar uma WKWebView para exibir conteúdo web com um elevado grau de controlo sobre a UI e o comportamento. A WKWebView utiliza o mesmo motor de renderização do Safari, sendo, portanto, muito eficiente e suportando funcionalidades web modernas. Em teoria, a WKWebView consegue gerir o WebAuthn (e assim as chaves de acesso) se configurada corretamente, mas repare que algumas funcionalidades avançadas do browser poderão ser limitadas por motivos de segurança. Um aspeto a ter em atenção é que, por predefinição, a WKWebView não partilha cookies nem dados de keychain com o Mobile Safari. Os utilizadores poderão ter de iniciar a sessão novamente, pois a sua sessão de WebView é isolada da sessão do Safari. Além disso, uma vez que o conteúdo da WKWebView pode ser totalmente personalizado pela aplicação, o utilizador não visualiza uma barra de endereço ou a UI do Safari – o que é excelente para o branding, mas significa que o utilizador tem menos indicações para verificar a legitimidade da página (uma preocupação ao nível do anti-phishing). Algumas aplicações abusaram inclusivamente da WKWebView para injetar scripts ou alterar o conteúdo (por ex., notou-se que o TikTok injetava JS de rastreio através do seu browser in-app), portanto, é necessário utilizar a WKWebView de uma forma segura e que transmita confiança aos utilizadores.

O SFSafariViewController oferece uma experiência Safari in-app. Ao abrir um URL com o SFSafariViewController, é quase como se o abrisse no browser Safari real, com a diferença de que o utilizador permanece na UI da sua aplicação. A vantagem para as chaves de acesso é significativa: por ser essencialmente o Safari, o iCloud Keychain e as chaves de acesso guardadas do utilizador estão acessíveis. Note que os cookies não são partilhados no iOS 11+. Isto significa que, se o utilizador já tiver uma chave de acesso para o seu site, o Safari poderá encontrá-la e até apresentar o preenchimento automático (Conditional UI) para simplificar o login. O SFSafariViewController é menos personalizável (não é possível alterar muito a sua barra de ferramentas), mas lida automaticamente com muitas características de segurança e privacidade. A barra de URL é mostrada, juntamente com o ícone de cadeado para HTTPS, o que dá confiança aos utilizadores de que se encontram no domínio correto. Em geral, o SFSafariViewController é considerado mais seguro do que um WKWebView puro e é mais simples de implementar. O principal compromisso é sacrificar algum controlo sobre o aspeto e comportamento. Para um fluxo de autenticação, isso é habitualmente aceitável. A prioridade aqui é a segurança e facilidade de login, aspetos em que o SFSafariViewController tem excelência ao usar o contexto do Safari.

SFAuthenticationSession / ASWebAuthenticationSession – Estas classes (sendo a última o nome amigável ao Swift, por ser a mais atual) são desenhadas especialmente aos fluxos ligados ao OAuth ou para os OpenID Connect. Ao ter de atestar que uma pessoa num determinado portal web (ou IdP forasteira) autentica bem-sucedidamente, no que diz respeito ao iOS a opção deve assentar nas sessões desta vertente. São de uma aproximação evidente no fundo ao que acontece nos moldes do SFSafariViewController, que correm tendo o browser Safari em funcionamento pela parte mais discreta do sistema bem como vão na mesma linha que a forma utilizada em gerenciar os storages e partilhas com recurso a cookies. Destaque no que concerne esta vertente diz respeito à quebra da não comunicação do sistema; a SFAuthenticationSession pedirá constantemente via mensagem para a autorização ligada à utilização da página web, alertando à necessidade e fazendo uso dos sessões do Safari preexistentes.

O benefício resulta na continuidade SSO fluída – caso seja uma utilizadora ou utilizador com a sua conta ativa via Safari o meio servirá o cookie à pessoa dispensando mais registos. Para as passkeys tudo isso se converte vital de momento que o Safari detém o crédito salvaguardado no iCloud Keychain as possibilidades à aplicação são enormes. À luz destas orientações, da parte da Apple para estas situações relacionadas aos fluxos o conselho incide no emprego ASWebAuthenticationSession. Dentre as vantagens pontifica-se como não acede quer os cookies nem credenciais na sua posse à salvaguarda em especial destas garantias do navegador onde corre além das aptidões aos casos relacionados de SSO. A fraqueza encontra no seio deste tema ser focado unicamente na ótica do desenrolamento ou andamento face os procedimentos exigentes sem os render em todas circunstâncias do contexto web na vossa aplicação. Rematando e de modo síntese ao optar em seguir este processo focado em iOS, o ideal na ótica com inclusões no modelo passkeys aponta em utilizar de imediato ASWebAuthenticationSession quer em prol ou por motivos óbvios de segurança e salvaguardando na melhor maneira de gerir fluxos de SSO à parte destas.

Veja quantas pessoas realmente usam passkeys.

Ver dados de adoção

No Android, a decisão sobre o WebView é entre o WebView clássico e os Chrome Custom Tabs:

Para testar o comportamento das várias WebViews no Android, recomendamos a aplicação WebView vs Chrome Custom Tabs.

O Android WebView (android.webkit.WebView) é o componente base à apresentação das vias da internet perante o meio interno à app e nos espaços da vossa aplicação. Enquadra muito das similaridades quando contrapostas da solução na base via WKWebView porquanto atribui o acesso abrangente ao dono para com os destinos associados ao intercepto destas vias onde estão na ordem a apresentação além do funcionamento associado. Processa bem em virtude de laborar à medida associada, tal qual corre na sua app nativa num modelo interno ao processo destas. Implementando-se para o modo passkey a solução leva em sentido estrito ao ato à exibição inicial à parte do seu login do servidor principal para a iniciarem em fase destas formas cerimoniais do sistema destas chaves passkeys WebAuthn. Devem também levar à linha em consideração que na via primária ao se enquadrar como WebView Android o acesso fica bloqueado face ao uso partilhado das palavras passe e cookie ao browser predefinido (no caso aos Google Passwords/ Chrome em questão do utilizador comum) nas contas do serviço a uso num terminal do indivíduo. Isto quer em caso se trate para iniciar na modalidade do browser de origem para o contrário, onde de ambas partes será interdito quer numa modalidade Web ou de igual peso WebView Android os elementos passkeys criadas nas plataformas não se conhecem na íntegra perante ambas no cenário na ausência para outras pontes via JavaScript e webkit da mais inovadora em questão. E isto conduz ao aspeto fulcral a saber como ao ser assim a situação não favorece os usuários as recair num procedimento ao registo à mesma no terminal à via de novo se estes tivessem, entretanto a autenticação em ordem via Chrome no momento na sua página original. Em prol de confiança será menos robusto no visual à WebView convencional dado na lacuna associada não dar exibição SSL e/ou na secção URL no qual exigirá dos indivíduos o maior voto confiança perante à sua aplicação da vertente para não serem lesados a práticas nocivas ligadas no phishing à sua privacidade perante a situação. Com nota para além deste âmbito as proibições das partes Google têm surgidos para a adoção desta frente nas partes ligadas à suas submissões em início sessões face as contas suas com recurso com vista na vulnerabilidade latentes no processo em evidência. À performance aspeto é um processo com a viabilidade associada no que contorna à web no caso se os aspetos num ponto fraco recaia a ser no geral o mais exaustivo nos processamentos comparativos num navegador normal com perdas lentas, à priori quando na leitura em que no global a carga da visualização recaia numa página complexa.

Chrome Custom Tabs (CCT) resultam de um processo com uma componente à maneira via tipo abordagem de contornos híbridos à base do sistema para as resoluções num espaço do dispositivo. Devem-se a ter à modalidade do processamento num ambiente exterior de Chrome associada para o modelo na aba exterior num separador incorporado. Dá opções à escolha como pintar cor no painel, do ícone das aplicações na inserção no ecrã e à customização via componentes à apresentação, da renderização à tarefa que fica ao encargo unicamente ao Google Chrome. O resultado final num ambiente chaves passkeys nas frentes nestas plataformas têm uma enormidade benéficas à utilidade face aos aspetos relacionados em prol as parcerias no processo Chrome, no que resultaria no acessos imediatos das passwords Google e Chrome (via Google Password Manager), da passkeys em uso nas vertentes as CCT na aba. Esta característica de visuais com barra indicando as origens dos endereços garantem um maior laço dos laços a unirem no seu público. De realce à componente na sua base com o uso aos processamentos aquecimentos “warm ups" na secção Chrome permite tempos e resposta ao nível mais reduzido no desenrolar na funcionalidade das carregamentos de exibição da apresentação global nas Custom Tabs da aplicação à performance do seu geral com garantias sólidas e um processamento seguro: sendo de aspeto geral via Chrome da conta e à par do seu Google, este último atua no controlo de proteção aos sessões via Safe Browsings o de não autorização ao se introduzir uma injeção perante o que seja à via de certas ameaças perante os códigos destas no que bloqueia aos abusos face certos comportamentos nocivos perante a execução.

Fica só condicionado as pessoas estarem da sua adesão nestes terminais Android no browser oficial Chrome (da lista com base no sistema). Nalguma parte se no dispositivo faltasse esta ou estarem no seu sistema à desatualizadas poderá representar o seu entraves na execução no âmbito. Na conclusão global nas recomendações as via que se sugere aos moldes Android é nas frentes Chrome Custom Tabs face aos resultados positivos nos moldes de fluidez segurança passkeys em destaque nas integrações e nos ambientes a atuar que de um lado em Android se espelharia noutra realidade ao equivalente para SFSafariViewController/ ASWebAuthSession no iOS a aproveitar os browser primários do sistema nas tarefas à autenticação em causa num sistema à escolha ao sucesso passkey no momento de utilização no local na hora em segurança sem mais nem menos na partilha a essas sessões à qual a sua passkey usufrui neste ambiente seguro de facto.

(A título complementar: as dicotomias WKWebView da Apple vs SFSafariViewController com as suas congéneres via Android ao equivalente em CCT tem pontes paralelas das similitudes associadas nestes espetros nos contextos de partilhas via credenciais com o resultado destas vertentes Web num ganho positivo à experiência e de um melhor na segurança às contrárias na customização mas noutro num ambiente e estado das passkeys num isolado conteúdo das isolamentos de partilhas no âmbito Web à plataforma que seja nos sistemas Web.)

Independentemente da abordagem de implementação que escolher, certos requisitos técnicos têm de ser cumpridos para ativar a funcionalidade da chave de acesso. Esta secção fornece orientação abrangente sobre a configuração de ficheiros de associação well-known, direitos iOS e configuração da WebView Android.

Nota sobre dispositivos geridos: o comportamento das chaves de acesso muda significativamente em dispositivos geridos onde as políticas de Gestão de Dispositivos Móveis (MDM) controlam o armazenamento de credenciais. Para testar chaves de acesso em dispositivos geridos, consulte Passkeys on Managed iOS & Android Devices.

Fluxos da Implementação nativa e Embedded WebView requerem ficheiros de associação para estabelecer confiança criptográfica entre a sua aplicação e o domínio web. O System WebView (ASWebAuthenticationSession) e o Chrome Custom Tabs não necessitam de associação app-para-site.

O ficheiro AASA estabelece a ligação entre a sua aplicação iOS e o seu domínio web, permitindo que as chaves de acesso funcionem nas duas plataformas.

Localização do ficheiro: https://seudominio.com/.well-known/apple-app-site-association

Requisitos de configuração:

• Alojado em /.well-known/apple-app-site-association no seu domínio
• Servido em HTTPS com um certificado SSL válido
• Content-Type: application/json
• Sem redirecionamentos no caminho .well-known
• Incluir o Team ID e o Bundle ID da sua app

Exemplo do ficheiro AASA:

{
    "webcredentials": {
        "apps": ["TEAMID123.com.example.app"]
    }
}

Caching e testes com o AASA:

A Apple guarda agressivamente ficheiros AASA em cache (até 24-48 horas) utilizando uma CDN, o que pode atrasar os desenvolvimentos e testes. Para passar a cache na fase de desenvolvimento:

1. Ative o Modo Programador (Developer Mode) no dispositivo alvo dos seus testes
2. Insira à mesma a ?mode=developer para domínio das Associated Domains ao nível do projeto do Xcode das opções à escolha do domínio e vertente
3. Desta via garantem as formas recentes a obter os ficheiros nas atualizações via na rede no terminal servidor com forçar à obtenção atual ao mesmo no que iOS força à ação à plataforma da Apple no local.

⚠️ Atenção importante: DE FORMA ALGUMA, coloque o uso na vertente de um sistema com modo finalização da inserção do ?mode=developer à parte as exibições na via produção da sua plataforma e das apps, visto as vias à produção que não terão leituras nas vias na Apple de processos à vista do normal funcionarem sem a base do modo e no iOS. Tudo resulta não reconhecer as suas bases da vertente ao uso da app nativa via ao modo das chave do passkey num contexto app nas origens das mesmas.

Validações nos testes das opções no ambiente: Em utilização no site da Apple em ambiente Validador da plataforma AASA Validator do serviço, efetue os testes e comprove a validação associada ao funcionamento perante o seu setup em conformidade na plataforma online.

O Android usa Digital Asset Links com vista à validação ao estabelecer e das verificações ao seu domínio entre app nativa nestas vertentes e do domínio Web nestes cenários.

Sítio/Endereço para ficheiro no caso base: https://seudominio.com/.well-known/assetlinks.json

Lista ao formato a constar:

• Alojamento via .well-known/assetlinks.json da origem do domínio online no servidor local na base.
• Vias das seguranças da HTTPS face às emissões via do certificado com base e as suas credenciais ativas.
• Da declaração no Content-Type nas opções à: application/json
• Inserir da parte das apps o fingerprint/identificador do certificado via formato com o modelo da base do SHA256 nestas plataformas face à via.

O exemplo em modelo base à base na json no caso dos assetlinks:

[
    {
        "relation": [
            "delegate_permission/common.handle_all_urls",
            "delegate_permission/common.get_login_creds"
        ],
        "target": {
            "namespace": "android_app",
            "package_name": "com.example.app",
            "sha256_cert_fingerprints": [
                "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
            ]
        }
    }
]

As aprovações das suas conformidades base nos serviços das Google e ligações à ferramentas do Google: Recorra da via aos Digital Asset Links do lado gerador da via na plataforma das ferramentas da base Google nas ferramentas ligadas ao site no Google das bases da validação na internet nas opções em ferramentas base Digital da Google no site via Generator Digital nas conformidade no fim nos seus ficheiros.

Aplicações iOS dependem nas áreas associadas aos direitos do sistema (entitlements) na funcionalidade via nas inserção nas capacidades de chave acesso e no uso do funcionamento. Variam nas áreas dependendo das inserção das implementações via à app.

Os ficheiros ao que se designam no Xcode para entitlements (com os moldes nas apps via framework na base no Flutter do estilo do seu em Runner.entitlements da aplicação nestas ou de uma vertente a ser na YourApp.entitlements das plataformas iOS na sua originaria na criação original nas vias normais). Determinam nas plataformas Apple à sua componente via de privilégios de acesso aos sistemas e opções em acesso nestas da capacidade das funções nos cenários aos níveis da sistema base e privilégios que este detém na app à autorização do modelo. Configuram, em especial passkey nos modelos com vias nos Domínio aos níveis Associated Domains de ligações nestas opções nas plataformas e ao sistema em vias na plataforma de base.

No local do caminho aos processos via a localizar no caso ao uso via Xcode: Encontra a ser da área habitual do projeto do Xcode no ios/Runner/Runner.entitlements nas áreas do terminal via do seu percurso da vertente na aplicação.

Nas vertentes das Implementação nativa no contexto da mesma e Embedded WebView exige dos privilégios o de na Associated Domains de ligar o uso app a de web domínio em ambiente de chaves. System WebView da vertente ao uso de vias (ASWebAuthenticationSession) da área no panorama Safari é no caso livre neste pormenor em exigência.

Modo em configuração e setup à volta do Xcode no caso na área do domínio iOS e terminal na plataforma macOS com o acesso via ambiente de base:

1. Iniciar do modelo do projeto a abrir em processo na plataforma e a ferramenta base a abrir no base a do base do app à área da aplicação no modelo.
2. Da vertente Target no modelo, selecionar no programa na opção da app a área na vertente app target em foco do target do seu alvo ao Target app.
3. Transitar à vertente da "Signing & Capabilities" no contexto à parte no painel e área no panorama na aba.
4. Acionar a opção "+ Capability" e na opção de juntar "Associated Domains" no modelo de inserção no painel de opções à vista na app nas partes da opção.
5. Inserir nas vertentes domínios em uso perante as áreas de ligação com base da webcredentials: e no formato prévio a usar a inserção de opção do seu texto à via antes do nome ao seu domínio da vertente app no texto em foco.

Um exemplo ao contexto do formato via no contexto nas opções em configurações e texto via a base na app a código em base à sua inserção XML base de formatação via plist de base iOS do terminal e ao ficheiro em causa nestas opções da app iOS:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>webcredentials:yourdomain.com</string>
        <string>webcredentials:subdomain.yourdomain.com</string>
    </array>
</dict>
</plist>

Domínios ao Múltiplos a em foco em causa: Num plano à app e opções a app precise em vários do uso na base domínios as vias a usar ROR das originárias em pedidos ROR (Related Origin Requests) e de opções em origens ROR em causa nas partes de uso nas áreas.

Embedded WebView no cenário Android faculta o suporte do WebAuthn em formatos duas com as opções distintas num plano em abordagem de contextos: do formato das atualizadas Android e bases no processo ao formato WebKit no caso do Android (na 5.3.1) ou da JavaScript pontes e nos seus modelos nestes contextos dos pontes no passado com JavaScript em base nestas opções e da 5.3.2. A System WebView em Chrome Custom Tabs é num formato em livre das configurações ao sistema nas aplicações as credenciais nas áreas.

Android na sua opção de modelos da via em base de origens: amostras nas opções do webview no repositório de base oficial Android nos samples WebAuthn nas opções a via na exibição de código do contexto para demonstrar da mesma nas bases em foco para a Android das vertentes para webview nas amostras destas.

Da mais atual WebKit em modernidade na ligação em chaves na via passkeys num funcionamento da parte em processos com um apoio WebAuthn. Neste uso sem a via em precisar do custom e dos pontes no contexto nas via à base código bridge de origem do código à Javascript no contexto de uso nas áreas.

Da oficial na Amostras: Webkit de opções do WebView da app do MainActivity a base webkit da amostra do código MainActivity no código a base e código do site oficial

Requisitos da app nestes moldes e requisitos a respeitar na base da Android:

• Na WebKit à área base do AndroidX em base do AndroidX do WebKit nas 1.12.1 em diante e de novo ou nas 1.14.0+ e das em recomendação das mesmas à plataforma do sistema a usar as áreas nestes contextos nas web views do uso Android
• Da áreas configuradas na via Asset Links das Digitais via Digital na base Asset na plataforma online
• Com WebView com da app e pacotes APK em suporte a WebAuthn (no processo na via de áreas e deteção das vias nos suportes)
• Uma Nota para: AndroidX a componente Credentials das Bibliotecas a via a NÃO OBRIGATÓRIA ao WebView do WebAuthn base do funcionamento e das webAuthn. No de uso só na nativa com o formato as implementações base na via base Android na total nativa com a área.

Da Via de Contexto da Implementação em uso e Código em Android a inserir no código Kotlin da área da app:

import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature
 
// Validar nas áreas caso a Autenticação via WebAuthn à base Web de funcionalidade for num contexto a suportar
if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION)) {
    // Da Ativação a Autenticação nas vias e Web de suportes na WebAuthn e as chaves de acesso
    WebSettingsCompat.setWebAuthenticationSupport(
        webView.settings,
        WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP
    )
 
    // E de via a Ativar as áreas em JavaScript e Javascript nas vias
    webView.settings.javaScriptEnabled = true
}

Os Pontos do Contexto Principal das Opções base:

• JavaScript sem a uso de a bridge ponte na código da vertente a não precisar no contexto: WebAuthn a no modelo ao suporte e o seu formato e na nativa de processo num WebView contexto nativo da base do Android e código da WebView da plataforma
• Da Deteção as partes do feature aos recursos em requisito e deteção necessária em foco na Android base e na plataforma Android a via e do Feature WebAuthentication de deteção: Da via ao validar à runtime com na WebViewFeature o estado do contexto base WebViewFeature.WEB_AUTHENTICATION em via execução no contexto da app nativa.
• Na sua Conditional do seu UI em que na indisponível o seu UI via e opções no uso não são a parte e com preenchimento indisponível com as do uso em opções de "conditional" do uso com Conditional não está num base indisponível: A via nas passkey para preenchimento de inputs com mediation:"conditional" não da parte e Embedded do Android e não na WebView com o uso.
• Ao seu processo plano as partes com plano em B na falta a feature do WebViewFeature no sistema do uso com o B das Custom nas partes Tabs: CCT de uso a Tabs a via Custom das vias a falta com base no Chrome.

Notas sobre as versões do Android WebKit:

• Use WebKit 1.12.1 ou mais recente (1.12.0 tinha um problema de disponibilidade em runtime)
• O suporte a funcionalidades depende da versão do APK WebView do utilizador - APKs mais antigos no dispositivo não exporão a funcionalidade

Antes do AndroidX WebKit 1.12.0, o suporte nativo do WebAuthn não existia na Embedded WebView. Esta abordagem mais antiga usa uma ponte Web-para-Nativo para gerir chaves de acesso em dispositivos sem suporte WebAuthn nativo no WebView.

Amostras oficiais:

• PasskeyWebListener (Manipulador de Ponte)
• Utilitários de codificação JavaScript

Quando usar: Ao suportar versões mais antigas do Android ou dispositivos com implementações WebView legadas.

As equipas tinham de:

1. Usar Chrome Custom Tabs ou Auth Tab (recomendado)
2. Construir uma ponte JavaScript personalizada

Para uma implementação detalhada, consulte o guia de integração do Credential Manager WebView do Android. No entanto, recomendamos vivamente o uso da abordagem nativa do WebKit 1.12.1+ para aplicações modernas.

Recomendação: Use o suporte nativo WebAuthn com o AndroidX WebKit 1.12.1+. Se não estiver disponível em tempo de execução, recorra ao Chrome Custom Tabs, que oferece um excelente suporte de chaves de acesso com credenciais partilhadas.

Ao implementar chaves de acesso em aplicações nativas, necessita de estabelecer a confiança entre a sua app e o(s) domínio(s) web. Esta secção cobre como lidar com domínios únicos, múltiplos domínios relacionados (ROR) e como verificar se os seus ficheiros de associação well-known estão corretamente configurados.

Para aplicações que usam um único domínio (por ex. kayak.com), necessita de:

• Um ficheiro AASA para iOS em https://kayak.com/.well-known/apple-app-site-association
• Um assetlinks.json para Android em https://kayak.com/.well-known/assetlinks.json
• Direito de Associated Domains configurado com webcredentials:kayak.com

As Related Origins (ROR) são uma funcionalidade do WebAuthn que permite que um único conjunto de chaves de acesso funcione em vários domínios relacionados (por ex. kayak.com, kayak.de, kayak.co.uk). As ROR usam o endpoint /.well-known/webauthn em cada site para definir as origens relacionadas, NÃO os ficheiros AASA ou assetlinks.

Pontos principais:

• Configuração ROR: cada domínio aloja /.well-known/webauthn com a lista de origens relacionadas
• Ficheiros de associação de aplicação (AASA/assetlinks): usados apenas para mapear aplicações aos respetivos websites
• Embedded WebView do iOS 18+: suporta ROR quando devidamente configurado
• Direitos de Associated Domains: inclua todos os domínios com os quais a sua aplicação precisa de se autenticar

Exemplo de configuração:

Se a sua app funciona com kayak.com e kayak.de, ambos os domínios têm de:

• Alojar os seus respetivos ficheiros AASA com o mesmo Team ID e Bundle ID
• Estar listados nos direitos de Associated Domains da sua app
• Ter ficheiros well-known devidamente configurados e acessíveis

Antes de entrar em produção, verifique se os seus ficheiros well-known estão devidamente configurados e acessíveis. A Apple e o Google fornecem URLs de teste baseados em CDN para verificar a disponibilidade dos ficheiros:

Usando estes URLs de teste:

• Clique nos links para verificar se a Apple/Google consegue obter os seus ficheiros well-known
• O parâmetro ?nocache=1 da Apple força a obtenção de uma versão recente, contornando a cache da CDN
• Se os ficheiros não estiverem acessíveis através destes URLs, a funcionalidade da chave de acesso não funcionará na sua aplicação
• Substitua kayak.com ou kayak.de pelo(s) seu(s) próprio(s) domínio(s) nos padrões de URL acima

Problema com testes: Certifique-se de que todos os domínios têm ficheiros well-known devidamente configurados. Um ficheiro em falta ou mal configurado em qualquer domínio pode quebrar a funcionalidade das chaves de acesso para esse domínio.

Mais informação: Identificador de Relying Party WebAuthn em aplicações nativas

A escolha da abordagem de implementação certa depende da arquitetura de autenticação da sua aplicação, dos requisitos OAuth e da necessidade de controlo da sessão. Use esta árvore de decisão para determinar o melhor caminho a seguir.

O fluxograma seguinte orienta-o na seleção da abordagem de implementação certa com base nos requisitos da sua aplicação:

Referência rápida para cada caminho:

• Início de sessão baseado em OAuth? → System WebView (ASWebAuthenticationSession / Chrome Custom Tabs)
• Reutilizar a autenticação web na shell nativa? → Embedded WebView com configuração (WKWebView / Android WebView + WebKit 1.12.1+)
• Construção nativa (native-first)? → Implementação nativa (AuthenticationServices / Credential Manager)
• Autenticação web existente para reutilizar? → System WebView para uma implementação rápida; caso contrário, Nativo para UX ótima

Eis como cada abordagem se comporta ao longo de dimensões fundamentais:

Explicações das dimensões:

• Criar chaves de acesso: facilidade com que os utilizadores criam chaves de acesso
• Usar chaves de acesso: a experiência de autenticação ao usar as existentes
• Gerir chaves de acesso: como os utilizadores veem, editam ou eliminam chaves
• Complexidade técnica: esforço de desenvolvimento e manutenção contínua
• Suporte OAuth: adequação da abordagem para fluxos de autenticação OAuth2/OIDC
• Tempo de configuração: linha de tempo típica de implementação

Recomendado: System WebView

Se a sua app autentica via OAuth2, OIDC ou fornecedores de início de sessão social (Google, GitHub, Microsoft, etc.), o System WebView é a escolha ideal:

• iOS: ASWebAuthenticationSession é concebido para fluxos OAuth
• Android: Chrome Custom Tabs fornecem uma integração OAuth perfeita
• Vantagens: Mínimo código nativo, partilha automática de credenciais
• Implementação: Adicione WebAuthn à sua página de autenticação web e, em seguida, carregue-a via System WebView

Exemplo: as aplicações de viagens como o kayak.com e o kayak.de usam OAuth para autenticação. O System WebView permite-lhes manter a sua infraestrutura OAuth existente enquanto adicionam suporte para chaves de acesso através das suas páginas de autenticação web.

Recomendado: Abordagem Híbrida

Use o System WebView para a autenticação OAuth inicial, e depois o Embedded WebView para sessões pós-autenticação:

1. Autenticação Inicial: O System WebView gere o início de sessão OAuth + chave de acesso
2. Gestão de Sessão: Mude para o Embedded WebView para o conteúdo web autenticado onde precisa de controlo sobre cookies/sessões
3. Configuração Técnica: Configure os requisitos do System e do Embedded WebView; para Android, certifique-se de que o AndroidX WebKit 1.12.1+ está incluído (ver Secção 5)

Quando usar: Aplicações que se autenticam via OAuth, mas que depois precisam de exibir conteúdo web autenticado onde a manipulação direta da sessão é necessária.

Recomendado: Implementação Nativa

Está a começar do zero ou tem ecrãs nativos? Escolha a via totalmente nativa:

• iOS: Use o framework AuthenticationServices
• Android: Use a API Credential Manager
• Vantagens: Melhor UX, autenticação instantânea, controlo total
• Vantagem Única: Use preferImmediatelyAvailableCredentials para apresentar uma sobreposição automática de chaves de acesso no arranque da app - exclusivo das implementações nativas e proporcionando as mais elevadas taxas de conversão
• Recomendação de SDK: Use os SDKs Corbado (iOS, Android) para acelerar o desenvolvimento com o tratamento de casos extremos testados em produção

Para Novas Aplicações: Recomendamos fortemente a construção de um início de sessão nativo desde o primeiro dia. Prepara-o para uma UX ideal e evita futuras migrações de WebView para nativo.

Recomendado: Migração Faseda

O diagrama seguinte mostra o caminho de migração incremental:

Cada fase baseia-se na anterior, permitindo melhorias incrementais sem interromper os utilizadores existentes.

Veja a Secção 5 para instruções de configuração detalhadas.

O teste de chaves de acesso em aplicações nativas requer uma abordagem estruturada e em várias camadas. Siga a pirâmide de testes: testes unitários (lógica isolada), testes de integração (cerimónia WebAuthn em simuladores/emuladores) e testes de sistema (ponta a ponta em dispositivos físicos).

Categorias de Teste Essenciais:

• Jornadas Principais: Registo, autenticação, fluxos cruzados (cross-device), eliminação de chaves
• Cobertura de Plataforma: iOS (nativo), Android (nativo), navegadores web em diferentes versões de SO
• Associação de Domínios: Verifique se os ficheiros AASA (iOS) e Digital Asset Links (Android) estão acessíveis
• Fluxos de Cancelamento: Teste o cancelamento do utilizador nos avisos do SO e ecrãs biométricos
• Tratamento de Erros: Falhas de backend, timeouts de rede, credenciais incorretas
• Casos Extremos: Bloqueio de ecrã desativado, iCloud/Google Password Manager desativado
• Fluxos OAuth: Integração OAuth + chave de acesso ponta a ponta
• Dispositivos Geridos: Ambientes controlados por MDM
• Gestores de Terceiros: Compatibilidade com 1Password, Bitwarden, Dashlane
• Autenticação Multi-Dispositivo: Fluxos de código QR e testes de transporte híbrido
• Específicos do Embedded WebView: No Android, verifique a configuração do WebKit 1.12.1+
• Monitorização de Produção: Dashboard com taxas de sucesso, falhas e latência

Para uma orientação de teste abrangente, veja o nosso guia dedicado: Testar fluxos de chaves de acesso em aplicações nativas iOS e Android.

Considere pedir aos utilizadores que criem chaves de acesso após um início de sessão tradicional bem-sucedido (palavra-passe, OAuth). Esta abordagem de conversão gradual:

• Não interrompe os fluxos de autenticação existentes
• Permite uma degradação suave se o utilizador recusar
• Aumenta a adoção de chaves de acesso com o tempo sem forçar mudanças
• Funciona bem com as três abordagens de implementação

Exemplo: Após o início de sessão OAuth através do System WebView, mostre um prompt nativo: "Ativar um início de sessão mais rápido com o Face ID?" Se aceite, crie a chave de acesso através da página web carregada no System WebView.

A decisão sobre como implementar chaves de acesso - através de Implementação nativa, System WebView ou Embedded WebView é uma escolha de design crucial que afeta a segurança, a experiência do utilizador e a complexidade do desenvolvimento. Não há uma resposta única para todas as situações.

Para aplicações baseadas em OAuth: o System WebView (ASWebAuthenticationSession, Chrome Custom Tabs) é o ponto de partida recomendado. Fornece um excelente suporte OAuth, esforço mínimo de implementação e partilha automática de credenciais.

Para aplicações native-first: escolha a via nativa mais cedo do que tarde. O início de sessão nativo por chave de acesso oferece a UX mais perfeita com capacidades exclusivas como preferImmediatelyAvailableCredentials, que ativa a sobreposição automática de chaves de acesso no arranque da app - algo que as implementações WebView não podem fornecer. Com o iOS e o Android a oferecerem agora suporte de primeira classe para chaves de acesso, os sucessos no mundo real demonstram uma elevada adoção. As ferramentas (incluindo SDKs open-source e bibliotecas de plataforma) amadureceram para tornar a integração nativa alcançável em prazos razoáveis. Embora se deva ter em conta as políticas de gestão de dispositivos, a sincronização entre dispositivos e os fornecedores de terceiros, estes desafios podem ser geridos com uma engenharia e testes cuidadosos. O resultado é um início de sessão na aplicação que encanta os utilizadores pela sua facilidade e rapidez, melhorando significativamente a segurança.

Para requisitos de Embedded WebView: o Embedded WebView é comummente utilizado em dois cenários do mundo real. Em primeiro lugar, as aplicações baseadas em OAuth utilizam frequentemente o System WebView para o fluxo de início de sessão inicial, mudando depois para o Embedded WebView para renderizar opções de gestão de chaves de acesso em ecrãs de definições onde o controlo da sessão é necessário - embora algumas aplicações simplifiquem isto mantendo o System WebView para ambos os fluxos. Em segundo lugar, aplicações que já incorporavam o seu fluxo de autenticação em janelas WebView antes de adotarem as chaves de acesso mantêm este padrão por consistência. O Embedded WebView com suporte nativo WebAuthn (AndroidX WebKit 1.12.1+) requer configuração e preparação (permissões, direitos, definições de WebView), mas já não necessita de código de ponte JavaScript personalizado. Note que a Conditional UI não é suportada na Embedded WebView. Escolha esta abordagem quando mantiver padrões de autenticação embutidos existentes ou quando precisar de controlo de sessão/cookies para ecrãs pós-autenticação.

Em última análise, as chaves de acesso em aplicações nativas representam um enorme salto em frente, tanto na conveniência para o utilizador como na segurança. Quer sejam implementadas via Native, System WebView ou Embedded WebView, eliminam os riscos de phishing e os encargos da gestão de palavras-passe para os seus utilizadores. Implementações reais como a integração de chaves de acesso na aplicação nativa da VicRoads demonstram que as abordagens native-first oferecem a adoção e satisfação mais elevadas dos utilizadores quando devidamente executadas com funcionalidades como as sobreposições automáticas de chaves de acesso. Ao seguir as melhores práticas para uma autenticação fácil de utilizar e ao escolher a abordagem de implementação que corresponde à arquitetura da sua aplicação - native-first para novas aplicações, System WebView para fluxos OAuth, ou Embedded WebView para padrões embutidos existentes - pode oferecer inícios de sessão biométricos sem palavra-passe que realizam verdadeiramente a visão das chaves de acesso: uma autenticação simples, segura e encantadora para todos.

Se as chaves de acesso não estiverem a funcionar na sua aplicação nativa, verifique estes problemas comuns por abordagem de implementação:

• Ficheiros servidos por HTTPS com um certificado válido
• Tipo de MIME correto: application/json
• Sem redirecionamentos no caminho .well-known
• iOS: Team ID e Bundle ID correspondem exatamente no ficheiro AASA
• Android: fingerprint SHA256 corresponde ao seu certificado de assinatura em assetlinks.json
• O ID da Relying Party corresponde ao seu domínio (sem protocolo, sem porto)
• Sem barras finais (trailing slashes) no ID da RP
• Origem do WebAuthn: https://seu-dominio.com (e não app://)

• iOS: funcionalidade de Associated Domains ativada no Xcode com webcredentials:seudominio.com
• Android: Digital Asset Links declarados no AndroidManifest.xml
• O utilizador tem o bloqueio de ecrã ativado (biometria ou PIN)
• Teste com o AASA Validator da Apple e a ferramenta Digital Asset Links do Google
• Verifique se o ficheiro Runner.entitlements contém os domínios associados corretos

• iOS: a utilizar ASWebAuthenticationSession (recomendado) ou SFSafariViewController
• Android: a utilizar Chrome Custom Tabs (não o WebView simples)
• iOS: verifique se os Associated Domains estão configurados, se necessário
• Teste se os cookies/credenciais são partilhados com o navegador do sistema
• Verifique se a página de autenticação web tem uma implementação de WebAuthn adequada

• iOS: configurado com os direitos adequados
• iOS: os Associated Domains incluem todos os domínios relevantes
• iOS: ficheiro AASA acessível e devidamente formatado
• iOS: teste com ?mode=developer durante o desenvolvimento (remova na produção)
• Android: AndroidX WebKit 1.12.1+ (ou mais recente) incluído no projeto
• Android: verificação de funcionalidade em tempo de execução para WebViewFeature.WEB_AUTHENTICATION
• Android: setWebAuthenticationSupport() chamado com WEB_AUTHENTICATION_SUPPORT_FOR_APP
• Android: JavaScript ativado nas definições da WebView
• Android: a versão APK do WebView do utilizador suporta a funcionalidade WebAuthn (use a deteção de funcionalidade, não a versão do SO)
• Conditional UI não utilizada (não suportada na Embedded WebView)
• Fallback para Chrome Custom Tabs se a funcionalidade WebAuthn não estiver disponível

• Verifique se o utilizador tem um fornecedor de credenciais não padrão ativo (1Password, Bitwarden, etc.)
• Verifique se o fornecedor suporta chaves de acesso (nem todos os gestores de palavras-passe o fazem)
• Teste com o gestor de credenciais nativo da plataforma (iCloud Keychain, Google Password Manager)

"NotAllowedError: The request is not allowed by the user agent or the platform in the current context"

• Geralmente significa: Direitos em falta (iOS) ou funcionalidade WebView não disponível/ativada (Android Embedded WebView)
• Verifique: Configuração de Associated Domains, acessibilidade do ficheiro AASA, versão do WebKit, deteção de funcionalidade, chamada a setWebAuthenticationSupport()

Nenhum aviso de chave de acesso aparece

• Pode significar: AASA/assetlinks.json a não carregar, tipo de WebView incorreto, ficheiro AASA em cache
• Tente: Validar ficheiros de associação, usar ?mode=developer no iOS para testar, verificar o tipo de WebView

Para depuração detalhada, veja o nosso artigo sobre IDs da Relying Party em aplicações nativas.

Uma armadilha comum: os ambientes de staging com acesso restrito (IPs permitidos, apenas por VPN) falharão porque as CDNs da Apple e do Google têm de conseguir obter os seus ficheiros de associação.

• Ficheiros AASA/assetlinks estão publicamente acessíveis (sem restrição de IPs, sem requisitos de VPN)
• Verifique se a CDN da Apple acede ao seu ficheiro: https://app-site-association.cdn-apple.com/a/v1/o-seu-dominio-de-staging.com?nocache=1
• Verifique se o Google acede ao seu ficheiro: https://digitalassetlinks.googleapis.com/v1/statements:list/?source.web.site=https://o-seu-dominio-de-staging.com&relation=delegate_permission/common.handle_all_urls

Subdomínio de staging com rpID de produção:

Se o seu ambiente de staging (por ex., stg.login.example.com) usar o domínio de produção como rpID (por ex., example.com), a pesquisa do AASA acontece no domínio do rpID, não no seu subdomínio de staging. Isto significa:

• Adicione os IDs de pacote da aplicação de staging ao seu ficheiro AASA de produção
• Tenha em atenção que as chaves de acesso criadas no staging aparecerão nos fluxos de início de sessão em produção (potencial confusão)

Exemplo (vários ambientes a partilhar um AASA):

{
    "webcredentials": {
        "apps": [
            "TEAMID123.com.example.app",
            "TEAMID123.com.example.app.dev",
            "TEAMID123.com.example.app.stg",
            "TEAMID123.com.example.app.pre"
        ]
    }
}

Recomendação: Use um rpID de staging separado que corresponda ao seu domínio de staging para evitar a sobreposição de credenciais entre os ambientes. Isto requer ficheiros AASA publicamente acessíveis no domínio de staging.

Esclarecimento sobre ?mode=developer:

O parâmetro ?mode=developer nos Associated Domains evita a cache da CDN da Apple mas não contorna o requisito de acessibilidade. O seu ficheiro AASA continua a ter de estar acessível pelo dispositivo (não através da CDN da Apple, mas diretamente). Isto ajuda durante o desenvolvimento ao fazer iterações em alterações no AASA, mas não ajudará se o seu servidor de staging tiver restrição de IPs.

SDKs Nativos da Corbado:

• SDK iOS (Swift)
• SDK Android (Kotlin)
• Pacote Flutter

Documentação da plataforma:

• Apple: Suporte a chaves de acesso
• Google: Gestor de Credenciais

Ferramentas de Validação:

• AASA Validator da Apple
• Gerador de Digital Asset Links do Google

Sobre a Corbado

Corbado é a Passkey Intelligence Platform para times de CIAM que rodam autenticação consumer em escala. Mostramos o que logs de IDP e ferramentas genéricas de analytics não enxergam: quais dispositivos, versões de SO, navegadores e gerenciadores de credenciais suportam passkeys, por que os registros não viram logins, onde o fluxo WebAuthn falha e quando uma atualização de SO ou navegador quebra silenciosamente o login — tudo sem substituir Okta, Auth0, Ping, Cognito ou seu IDP interno. Dois produtos: Corbado Observe adiciona observabilidade para passkeys e qualquer outro método de login. Corbado Connect entrega passkeys gerenciados com analytics integrado (junto ao seu IDP). VicRoads roda passkeys para mais de 5M de usuários com Corbado (+80% de ativação de passkey). Fale com um especialista em Passkeys →

A escolha depende da sua arquitetura de autenticação. Se a sua aplicação usar OAuth2 ou OIDC, o System WebView (ASWebAuthenticationSession no iOS ou Chrome Custom Tabs no Android) requer o menor esforço de implementação e nenhuma configuração de ficheiro de associação. Para novas aplicações native-first, a Implementação Nativa oferece uma UX superior, enquanto o Embedded WebView é adequado para aplicações que já incorporam a autenticação num WebView e precisam de controlo de sessão ou de cookies após o início de sessão.

O SFSafariViewController tira partido do motor do Safari, apresenta a barra de URL com os indicadores SSL e fornece proteção contra phishing, tornando-o mais fiável para fluxos de autenticação. O WKWebView oferece uma maior personalização da IU mas possui um armazém de cookies isolado do Safari, requer direitos de Associated Domains e um ficheiro AASA para ativar as chaves de acesso e não apresenta a barra de URL, reduzindo os sinais de confiança do utilizador.

Os Chrome Custom Tabs partilham cookies e credenciais guardadas com o navegador Chrome do utilizador, o que significa que as chaves de acesso guardadas no Google Password Manager estão acessíveis durante a autenticação. O Android WebView padrão possui um armazém de cookies isolado, não mostra o URL nem os indicadores SSL e o Google proibiu-o explicitamente para inícios de sessão com contas Google devido a riscos de phishing.

Se um utilizador tiver um gestor de credenciais de terceiros, como o 1Password, definido como o seu fornecedor ativo, este intercetará frequentemente a criação e o armazenamento das chaves de acesso, assumindo prioridade sobre o gestor de credenciais nativo da plataforma (iCloud Keychain ou Google Password Manager). Isto significa que as chaves de acesso podem ser armazenadas na aplicação de terceiros em vez de no keychain da plataforma, afetando o comportamento da sincronização entre dispositivos e a gestão de chaves de acesso.

Quando as políticas MDM desativam a sincronização de credenciais, as chaves de acesso ficam associadas ao dispositivo e não podem ser transferidas para um dispositivo de substituição, ao contrário do que acontece em cenários de consumo típicos. As aplicações direcionadas a ambientes empresariais devem prever mecanismos de autenticação de recurso, tais como o início de sessão através de palavra-passe ou ligação mágica (magic link), para lidar com os casos em que um utilizador recebe um novo dispositivo gerido.