Las llaves de acceso se convirtieron en el estándar para la autenticación segura y fácil de usar, y una cantidad cada vez mayor de servicios las están adoptando tanto en sitios web como en apps para Android. Sin embargo, cuando comienzas a agregar llaves de acceso a una app para Android, a menudo te enfrentas a una pregunta clave sobre la arquitectura: ¿llamas directamente a las APIs nativas, abres tu página de acceso web existente en una pestaña del navegador o ejecutas llaves de acceso dentro de un WebView en la app?
Descripción general
Puedes admitir llaves de acceso en apps para Android a través de tres enfoques principales: Credential Manager, pestaña Auth y WebView. La documentación oficial abarca los detalles de implementación paso a paso para cada opción. Elegir una arquitectura que minimice la fricción del usuario y, al mismo tiempo, mantenga los costos de desarrollo y mantenimiento manejables se reduce a comprender las características y restricciones de cada opción a un nivel alto. En esta guía, se explica cómo elegir el enfoque adecuado según el diseño de tu app y la infraestructura de autenticación existente. En la siguiente tabla, se comparan estos enfoques:
| Función | Credential Manager | Pestaña Auth | WebView |
|---|---|---|---|
| Caso práctico recomendado | Apps con IU de acceso nativa | Reutilizar una página de acceso web existente o un proveedor de identidad (IdP) de OAuth o de OpenID Connect (OIDC) | Apps híbridas existentes con WebView (solo dominio propio) |
| IU y experiencia del usuario | Integración de la hoja inferior del SO nativo y el autocompletado del teclado | Pestaña del navegador dedicada y minimalista para la autenticación | Página web incorporada con hoja inferior del SO nativo |
| Autocompletar y la IU condicional | Compatible (autocompletado de Credential Manager) | Compatible (IU condicional de WebAuthn) | No compatible |
| Uso compartido de sesiones y credenciales | Comparte llaves de acceso en la Web y la app con assetlinks.json y rpId compartido (no se comparten las cookies de Chrome) |
Comparte cookies y el estado de las credenciales con Chrome (se puede inhabilitar con la navegación efímera) | Comparte llaves de acceso con assetlinks.json, pero aísla las cookies y las sesiones de Chrome. |
Vínculos de recursos digitales (assetlinks.json) |
Obligatorio en el dominio web de la parte de confianza | Es obligatorio en el dominio de tu URI de redireccionamiento para los redireccionamientos HTTPS (se recomienda por sobre los esquemas personalizados, que no lo requieren) | Es obligatorio en el dominio web de la parte de confianza (no se puede usar con IdP externos o de terceros) |
Credential Manager
Si tu app para Android tiene pantallas de acceso o registro nativas, la biblioteca de Jetpack de Credential Manager es el enfoque principal recomendado.
La principal ventaja de Credential Manager es que unifica las llaves de acceso, las contraseñas y Acceder con Google en una sola hoja inferior del sistema optimizada. Cuando un usuario
accede, completa la autenticación biométrica con un solo toque sin salir de
tu app, lo que reduce la fricción de acceso. Incluso si un usuario descarta la hoja inferior inicial y presiona un campo de entrada de nombre de usuario o contraseña, puedes usar PendingGetCredentialRequest para mostrar llaves de acceso, contraseñas y Acceder con Google directamente en el teclado o en las sugerencias de autocompletado desplegables. Este resguardo proporciona una integración de autocompletado nativa equivalente a la IU condicional de WebAuthn.
El Administrador de credenciales también proporciona paridad de funciones completa con las capacidades modernas del ciclo de vida de las llaves de acceso web. Con el Administrador de credenciales, puedes hacer lo siguiente:
- Usa la creación automática de llaves de acceso (
isConditional = trueenCreatePublicKeyCredentialRequest) para crear una llave de acceso de forma silenciosa después de un acceso correcto con contraseña. - Usa la API de Signal para mantener la coherencia entre tus credenciales y nombres de usuario con los proveedores de credenciales.
- Implementa Restore Credentials para que los usuarios vuelvan a acceder automáticamente a tu app cuando configuren un dispositivo nuevo.
Las llaves de acceso son compatibles con dispositivos que ejecutan Android 9 (nivel de API 28) y versiones posteriores,
mientras que otras credenciales, como las contraseñas, siguen siendo compatibles con versiones anteriores de Android
a través de los Servicios de Google Play. En Android 14 (nivel de API 34) y versiones posteriores, el Administrador de credenciales también funciona con cualquier proveedor de credenciales de terceros que seleccione el usuario. Las funciones adicionales, como la integración de autocompletado basada en View (PendingGetCredentialRequest) y la API de Signal, requieren Android 15 (nivel de API 35) y versiones posteriores.
Comparte credenciales en la Web y la app
Para comenzar, sigue los Requisitos previos para alojar un archivo de Vínculos de recursos digitales (assetlinks.json) en tu dominio web para asociar tu sitio web y tu app para Android. Asociar tu sitio web y tu app a través de assetlinks.json significa que comparten el mismo ID de la parte que confía (rpId), por lo que las llaves de acceso creadas en tu sitio web en Chrome funcionan en tu app nativa para Android a través de Credential Manager, y las llaves de acceso creadas en tu app funcionan en tu sitio web. El Administrador de credenciales comparte
las credenciales en tu sitio web y app. Solo necesitas la pestaña de autenticación cuando quieras
reutilizar la IU de acceso web o la página del IdP.
Como se describe en Crea una llave de acceso, también debes configurar tu servidor para verificar los orígenes de la app para Android (android:apk-key-hash:ENCODED_SHA256_HASH, con el formato del hash SHA-256 codificado en Base64URL sin padding de tu certificado de firma de APK). Si
tu app tiene una IU nativa y quieres una experiencia integrada en el SO para
acceder con llaves de acceso, elige Credential Manager.
Pestaña Auth
Muchos servicios operan un microservicio de proveedor de identidad (IdP) basado en OAuth o en OpenID Connect (OIDC), o bien quieren reutilizar una página de acceso web existente habilitada para llaves de acceso en todas las apps para dispositivos móviles. Históricamente, las apps usaban pestañas personalizadas para estos flujos. A partir de Chrome 137 y AndroidX Browser 1.9.0, la pestaña Auth proporciona una pestaña del navegador dedicada y adaptada específicamente para los flujos de autenticación.
Las pestañas personalizadas estándar están diseñadas como navegadores integrados en la app de uso general, que muestran elementos de la IU no relacionados con el acceso, como el menú para compartir, los favoritos y Abrir en Chrome, que pueden distraer a los usuarios. También requieren que declares filtros de intents en tu archivo de manifiesto para recibir redireccionamientos posteriores a la autenticación, agregar código estándar y necesitar protecciones contra la interceptación de intents por parte de apps maliciosas.
La pestaña de autenticación resuelve estos desafíos específicos de la autenticación. Quita la IU innecesaria del navegador, como el botón para minimizar y el menú para compartir, y presenta una interfaz enfocada solo con las funciones de acceso esenciales, como el autocompletado de llaves de acceso y contraseñas. En lugar de enrutar a través de intents del SO, la pestaña de autenticación entrega los redireccionamientos de autenticación directamente a una devolución de llamada en la app con un esquema personalizado o una URL HTTPS verificada con Vínculos de recursos digitales, lo que fortalece la seguridad y reduce el código estándar de implementación.
Uso compartido de sesiones y resguardo de pestañas personalizadas
De forma predeterminada, la pestaña de autenticación también comparte las cookies y el estado de las credenciales directamente con el
navegador Chrome del sistema. Este uso compartido permite que tu app aproveche las sesiones activas de acceso en Chrome y ejecute tu implementación existente de WebAuthn tal como está, incluidos la IU condicional y el modo de IU inmediato (el equivalente web de preferImmediatelyAvailableCredentials de Credential Manager). Por el contrario, si tu caso de uso requiere una sesión de autenticación aislada que no comparta cookies ni historial de navegación con el navegador, puedes habilitar la navegación efímera llamando a AuthTabIntent.Builder.setEphemeralBrowsingEnabled(true).
Si bien empaquetas androidx.browser:browser (versión 1.9.0 o posterior) con tu app, el hecho de que la pestaña de Auth se ejecute en el entorno de ejecución depende del navegador predeterminado del usuario. Si
el navegador predeterminado es una versión de Chrome anterior a la 137 o un navegador
de terceros que no admite la pestaña de autenticación, esta recurre automáticamente
al inicio de una pestaña personalizada estándar. Cuando se produce este resguardo, el redireccionamiento posterior a la autenticación se devuelve a través de un filtro de intents en AndroidManifest.xml, como en las pestañas personalizadas estándar, en lugar de a través de la devolución de llamada de la pestaña de autenticación (ActivityResultCallback). En producción, Google recomienda verificar la compatibilidad del navegador predeterminado de antemano con CustomTabsClient.isAuthTabSupported(context, provider) para ramificar tu flujo o retener el filtro de intents del manifiesto para que tu app pueda controlar los resultados de cualquiera de las rutas de acceso. Para ver ejemplos concretos de implementación de resguardo, consulta Android Browser Helper.
Requisitos de seguridad de OAuth y OIDC
La pestaña de autenticación protege y simplifica solo el canal de redireccionamiento del cliente desde el
navegador de vuelta a tu app; no protege automáticamente el protocolo OAuth o OIDC
en sí. En especial, dado el comportamiento de resguardo de las pestañas personalizadas, debes seguir las instrucciones de OAuth 2.0 para aplicaciones nativas (RFC 8252). Específicamente,
combina PKCE (clave de prueba para el intercambio de código, RFC 7636) con los
parámetros code_challenge y code_verifier para evitar la intercepción del código de autorización,
la validación del parámetro state para evitar la falsificación de solicitudes entre sitios
(CSRF) y los ataques de fijación de sesión, y la generación y validación del parámetro nonce
en OpenID Connect para evitar ataques de repetición de tokens de ID. Con estas
protecciones implementadas, Google recomienda migrar las arquitecturas de acceso basadas en la Web
de las pestañas personalizadas estándar a la pestaña de autenticación.
WebView
Algunas apps se compilan en torno a una arquitectura de WebView híbrida en la que no es práctico separar solo la pantalla de acceso en la IU nativa (Administrador de credenciales) o en una pestaña del navegador (pestaña de autenticación). En esos casos, puedes habilitar la compatibilidad con WebAuthn directamente en WebView.
Para usar llaves de acceso en WebView, agrega la biblioteca de WebKit de AndroidX
(androidx.webkit:webkit versión 1.12.0 o posterior) y las dependencias de Credential Manager (androidx.credentials:credentials y
androidx.credentials:credentials-play-services-auth) a tu archivo
build.gradle. Luego, verifica la compatibilidad con las funciones usando
WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION) y
habilita explícitamente la compatibilidad con WebAuthn llamando a
WebSettingsCompat.setWebAuthenticationSupport(webView.settings,
WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP).
Esta configuración une automáticamente las solicitudes de creación y autenticación de llaves de acceso de las páginas web en WebView con Credential Manager.
Restricciones de dominio y UX
Al igual que con las integraciones nativas del Administrador de credenciales, debes seguir los Requisitos previos para alojar un archivo de Vínculos de recursos digitales (assetlinks.json) en el dominio web de tu parte de confianza para asociar tu app. Tu servidor recibe android:apk-key-hash:ENCODED_SHA256_HASH (el hash del certificado SHA-256 codificado en Base64URL) como origen. Como este enfoque requiere alojar assetlinks.json en el dominio de la parte de confianza para confiar en el certificado de firma de tu app para Android, solo funciona cuando controlas el dominio web de la parte de confianza (acceso web propio). Si tu flujo de autenticación
redirecciona a un IdP externo o de terceros en el que no puedes alojar
assetlinks.json para tu paquete de app, debes usar la pestaña de autenticación (o el acceso nativo
con Google a través de Credential Manager) en lugar de WebView.
Ten en cuenta dos restricciones funcionales y de UX: WebView no admite la IU condicional (integración de autocompletado de mediation: "conditional" cuando un usuario se enfoca en un campo de entrada) y no comparte cookies ni sesiones de acceso con el navegador Chrome del sistema. Debido a estas restricciones, Google recomienda usar el Administrador de credenciales o la pestaña de autenticación cuando se diseñan flujos de autenticación nuevos. Sin embargo,
si quieres agregar compatibilidad con llaves de acceso a una app híbrida propia existente sin
cambios importantes en la arquitectura, puedes integrar las llaves de acceso con WebView.
Resumen
Comenzar con la infraestructura de autenticación y la IU actuales de tu app te ayuda a elegir el enfoque de llave de acceso adecuado:
- Si tu app tiene una IU de acceso nativa y quieres una experiencia integrada en el SO sin cambiar a una pantalla del navegador, elige Administrador de credenciales para acceder con una llave de acceso.
- Si operas un microservicio de IdP de OAuth o de OIDC, redireccionas a un IdP externo o quieres volver a usar tu página de acceso web existente habilitada para llaves de acceso (incluida la IU condicional) y compartir sesiones activas del navegador con Chrome, adopta la pestaña de autenticación y, luego, implementa los requisitos de seguridad en OAuth 2.0 para aplicaciones nativas (RFC 8252), específicamente PKCE,
stateynonce. - Si tu app se compila en una arquitectura de WebView híbrida en la que el acceso debe permanecer dentro de pantallas web propias incorporadas, usa WebView y ten en cuenta la falta de compatibilidad con la IU condicional y las cookies aisladas.
Próximos pasos
- Acerca de las llaves de acceso
- Cómo crear una llave de acceso
- Cómo ingresar con una llave de acceso
- Autenticación de usuarios con llaves de acceso
- Cómo autenticar usuarios con WebView
- Guía de la pestaña Auth
- Documentación de Chrome Identity