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.
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:
- Use a criação automática de chaves de acesso (
isConditional = truenoCreatePublicKeyCredentialRequest) para criar uma chave de acesso silenciosamente após um login com senha. - Use a API Signal para manter as credenciais e os nomes de usuário consistentes com os provedores de credenciais.
- Implemente o Restaurador de Credenciais para que os usuários façam login automaticamente no seu app ao configurar um novo dispositivo.
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.
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,
stateenonce. - 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
- Sobre chaves de acesso
- Criar uma chave de acesso
- Fazer login com uma chave de acesso
- Autenticação de usuários com chaves de acesso
- Autenticar usuários com o WebView
- Guia da guia Auth
- Documentação do Chrome Identity