Escolher a implementação certa de chave de acesso para seu app Android

As chaves de acesso se tornaram o padrão para autenticação segura e fácil de usar, e um número cada vez maior de serviços as está adotando em sites e apps Android. No entanto, ao começar a adicionar chaves de acesso a um app Android, você geralmente se depara com uma questão arquitetônica importante: você chama as APIs nativas diretamente, abre sua página de login da Web em uma guia do navegador ou executa chaves de acesso em uma WebView no app?

Visão geral

É possível oferecer suporte a chaves de acesso em apps Android de três maneiras principais: Gerenciador de credenciais, guia de autenticação e WebView. A documentação oficial aborda os detalhes de implementação de cada opção. Para escolher uma arquitetura que minimize o atrito do usuário e mantenha os custos de desenvolvimento e manutenção gerenciáveis, é preciso entender as características e restrições de cada opção em um nível geral. Este guia explica como escolher a abordagem certa com base no design do app e na infraestrutura de autenticação existente. A tabela a seguir compara essas abordagens:

Recurso Credential Manager Guia Auth WebView
Caso de uso recomendado Apps com interface de login nativa Reutilizar uma página de login da Web ou um provedor de identidade (IdP) OAuth ou OpenID Connect (OIDC) Apps híbridos do WebView (somente domínio próprio)
Interface e experiência do usuário Integração nativa da página inferior do SO e do preenchimento automático do teclado Guia do navegador dedicada e minimalista para autenticação Página da Web incorporada com página inferior nativa do SO
Preenchimento automático e interface condicional Compatível (preenchimento automático do Credential Manager) Compatível (interface condicional do WebAuthn) Incompatível
Compartilhamento de sessões e credenciais Compartilha chaves de acesso na Web e no app usando assetlinks.json e rpId compartilhado (os cookies do Chrome não são compartilhados) Compartilha cookies e o estado das credenciais com o Chrome (pode ser desativado usando a navegação temporária) Compartilha chaves de acesso usando o assetlinks.json, mas isola cookies e sessões do Chrome
Digital Asset Links (assetlinks.json) Obrigatório no domínio da Web da parte confiável Obrigatório no domínio do URI de redirecionamento para redirecionamentos HTTPS (recomendado em vez de esquemas personalizados, que não exigem isso) Obrigatório no domínio da Web da parte confiável (não pode ser usado com IdPs externos ou de terceiros)

Credential Manager

Se o app Android tiver telas de login ou registro nativas, a biblioteca do Jetpack Credential Manager é a principal abordagem recomendada.

A principal vantagem do Credential Manager é que ele unifica chaves de acesso, senhas e o recurso Fazer login com o Google em uma única página inferior do sistema. Quando um usuário faz login, ele conclui a autenticação biométrica com um toque sem sair do app, reduzindo o atrito do login. Mesmo que um usuário dispense a página inferior inicial e toque em um campo de entrada de nome de usuário ou senha, você pode usar PendingGetCredentialRequest para mostrar chaves de acesso, senhas e o recurso Fazer login com o Google diretamente no teclado ou nas sugestões de preenchimento automático suspensas. Esse substituto oferece uma integração de preenchimento automático nativa equivalente à interface condicional da WebAuthn.

Página inferior do Gerenciador de credenciais mostrando as opções de chave de acesso, Fazer login com o Google e senha.
Figura 1. O Gerenciador de credenciais unifica as chaves de acesso, o recurso Fazer login com o Google e as senhas em uma página inferior do sistema.

O Credential Manager também oferece paridade total de recursos com as funcionalidades modernas de ciclo de vida de chaves de acesso da Web. Com o Gerenciador de credenciais, é possível:

As chaves de acesso são compatíveis com dispositivos que executam o Android 9 (nível 28 da API) e versões mais recentes, enquanto outras credenciais, como senhas, continuam sendo compatíveis com versões anteriores do Android pelo Google Play Services. No Android 14 (nível 34 da API) e versões mais recentes, o Gerenciador de credenciais também funciona com qualquer provedor de credenciais de terceiros selecionado pelo usuário. Outros recursos, como a integração de preenchimento automático baseada em View (PendingGetCredentialRequest) e a API Signal, exigem o Android 15 (nível 35 da API) ou versões mais recentes.

Compartilhar credenciais entre a Web e o app

Para começar, siga os Pré-requisitos para hospedar um arquivo Digital Asset Links (assetlinks.json) no seu domínio da Web para associar o site e o app Android. Associar o site e o app usando o assetlinks.json significa que eles compartilham o mesmo ID da parte confiável (rpId). Assim, as chaves de acesso criadas no seu site no Chrome funcionam no app Android nativo pelo Gerenciador de credenciais, e as chaves de acesso criadas no app funcionam no site. O Gerenciador de credenciais compartilha credenciais no site e no app. Você só precisa da guia de autenticação quando quiser reutilizar a interface de login da Web ou a página do IdP.

Conforme descrito em Criar uma chave de acesso, você também precisa configurar seu servidor para verificar as origens do app Android (android:apk-key-hash:ENCODED_SHA256_HASH, formatado usando o hash SHA-256 codificado em Base64URL sem preenchimento do certificado de assinatura do APK). Se o app tiver uma interface nativa e você quiser uma experiência integrada ao SO para fazer login com chaves de acesso, escolha o Gerenciador de credenciais.

Guia Auth

Muitos serviços operam um microsserviço de provedor de identidade (IdP) criado com base no OAuth ou no OpenID Connect (OIDC) ou querem reutilizar uma página de login da Web com chave de acesso em apps para dispositivos móveis. No passado, os apps usavam guias personalizadas para esses fluxos. A partir do Chrome 137 e do AndroidX Browser 1.9.0, a guia de autenticação oferece uma guia dedicada do navegador, personalizada especificamente para fluxos de autenticação.

Guia Auth exibindo uma interface de processo de login mínima do navegador sem itens de menu de uso geral.
Figura 2. A guia de autenticação apresenta uma interface de navegador focada e adaptada para fluxos de autenticação.

As guias personalizadas padrão são projetadas como navegadores no app de uso geral, mostrando elementos da interface não relacionados ao processo de login, como o menu de compartilhamento, favoritos e Abrir no Chrome, que podem distrair os usuários. Eles também exigem a declaração de filtros de intent no arquivo de manifesto para receber redirecionamentos pós-autenticação, adicionando código boilerplate e precisando de proteções contra interceptação de intent por apps maliciosos.

A guia Auth resolve esses desafios específicos de autenticação. Ele remove elementos desnecessários da interface do navegador, como o botão de minimizar e o menu de compartilhamento, e apresenta uma interface focada apenas com os recursos essenciais de login, incluindo o preenchimento automático de chaves de acesso e senhas. Em vez de rotear por intents do SO, a guia de autenticação envia redirecionamentos de autenticação diretamente para um callback no app usando um esquema personalizado ou um URL HTTPS verificado com o Digital Asset Links, o que aumenta a segurança e reduz o código de implementação.

Compartilhamento de sessão e substituto de guias personalizadas

Por padrão, a guia de autenticação também compartilha cookies e o estado de credenciais diretamente com o navegador Chrome do sistema. Esse compartilhamento permite que o app aproveite as sessões de login ativas no Chrome e execute a implementação atual do WebAuthn como está, incluindo a interface condicional e o modo de interface imediata (o equivalente da Web do preferImmediatelyAvailableCredentials do Credential Manager). Por outro lado, se o caso de uso exigir uma sessão de autenticação isolada que não compartilhe cookies ou histórico de navegação com o navegador, você poderá ativar a navegação temporária chamando AuthTabIntent.Builder.setEphemeralBrowsingEnabled(true).

Ao agrupar androidx.browser:browser (versão 1.9.0 ou mais recente) com seu app, a execução da guia de autenticação no momento da execução depende do navegador padrão do usuário. Se o navegador padrão for uma versão do Chrome anterior à 137 ou um navegador de terceiros que não oferece suporte à guia de autenticação, ela vai voltar automaticamente para uma guia personalizada padrão. Quando esse substituto ocorre, o redirecionamento pós-autenticação retorna por um filtro de intent em AndroidManifest.xml, como nas guias personalizadas padrão, em vez de pelo callback da guia de autenticação (ActivityResultCallback). Na produção, o Google recomenda verificar o suporte ao navegador padrão com antecedência usando CustomTabsClient.isAuthTabSupported(context, provider) para ramificar o fluxo ou manter o filtro de intent do manifesto para que o app possa processar os resultados de qualquer um dos caminhos. Para ver exemplos concretos de implementação de substituição, consulte o Android Browser Helper.

Requisitos de segurança do OAuth e do OIDC

A guia de autenticação protege e simplifica apenas o canal de redirecionamento do lado do cliente do navegador de volta para o app. Ela não protege automaticamente o protocolo OAuth ou OIDC em si. Especialmente devido ao comportamento de substituição das guias personalizadas, é necessário seguir o OAuth 2.0 para apps nativos (RFC 8252). Especificamente, combine a PKCE (Proof Key for Code Exchange, RFC 7636) usando os parâmetros code_challenge e code_verifier para evitar a interceptação do código de autorização, a validação do parâmetro state para evitar ataques de falsificação de solicitação entre sites (CSRF) e de fixação de sessão, além da geração e validação do parâmetro nonce no OpenID Connect para evitar ataques de repetição de token de ID. Com essas proteções, o Google recomenda migrar as arquiteturas de login baseadas na Web das guias personalizadas padrão para a guia de autenticação.

WebView

Alguns apps são criados com base em uma arquitetura híbrida de WebView, em que separar apenas a tela de login na interface nativa (Credential Manager) ou em uma guia do navegador (guia de autenticação) não é prático. Nesses casos, é possível ativar o suporte ao WebAuthn diretamente na WebView.

Para usar chaves de acesso na WebView, adicione a biblioteca AndroidX WebKit (androidx.webkit:webkit versão 1.12.0 ou mais recente) e as dependências do Gerenciador de credenciais (androidx.credentials:credentials e androidx.credentials:credentials-play-services-auth) ao arquivo build.gradle. Em seguida, verifique se há suporte para o recurso usando WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION) e ative explicitamente o suporte à WebAuthn chamando WebSettingsCompat.setWebAuthenticationSupport(webView.settings, WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP). Essa configuração conecta automaticamente as solicitações de criação e autenticação de chaves de acesso de páginas da Web na WebView ao Credential Manager.

Restrições de domínio e UX

Assim como nas integrações nativas do Credential Manager, você precisa seguir os pré-requisitos para hospedar um arquivo Digital Asset Links (assetlinks.json) no domínio da Web da parte confiável para associar seu app. Seu servidor recebe android:apk-key-hash:ENCODED_SHA256_HASH (o hash do certificado SHA-256 codificado em Base64URL) como origem. Como essa abordagem exige a hospedagem de assetlinks.json no domínio da parte confiável para confiar no certificado de assinatura do app Android, ela só funciona quando você controla o domínio da Web da parte confiável (login na Web próprio). Se o fluxo de autenticação redirecionar para um IdP externo ou de terceiros em que não é possível hospedar assetlinks.json para o pacote do app, use a guia de autenticação (ou o recurso nativo Fazer login com o Google pelo Gerenciador de credenciais) em vez do WebView.

Esteja ciente de duas restrições funcionais e de UX: a WebView não oferece suporte à interface condicional (integração de preenchimento automático do mediation: "conditional" quando um usuário foca em um campo de entrada) e não compartilha cookies ou sessões de login com o navegador Chrome do sistema. Devido a essas restrições, o Google recomenda o Credential Manager ou a guia Auth ao projetar novos fluxos de autenticação. No entanto, se você quiser adicionar suporte a chaves de acesso a um app híbrido próprio sem grandes mudanças na arquitetura, integre as chaves de acesso ao WebView.

Resumo

Começar com a interface e a infraestrutura de autenticação atuais do app ajuda você a escolher a abordagem certa para as chaves de acesso:

  • Se o app tiver uma interface de login nativa e você quiser uma experiência integrada ao SO sem mudar para uma tela do navegador, escolha o Credential Manager para fazer login com uma chave de acesso.
  • Se você opera um microsserviço de IdP OAuth ou OIDC, redireciona para um IdP externo ou quer reutilizar sua página de login na Web com chave de acesso (incluindo a interface condicional) e compartilhar sessões ativas do navegador com o Chrome, adote a guia de autenticação e implemente os requisitos de segurança em OAuth 2.0 para apps nativos (RFC 8252), especificamente PKCE, state e nonce.
  • Se o app for criado em uma arquitetura híbrida de WebView em que o login precisa permanecer em telas da Web próprias incorporadas, use o WebView, mas considere a falta de suporte à interface condicional e aos cookies isolados.

Próximas etapas