Claves de acceso en aplicaciones nativas: Implementación nativa vs. WebView

Nota: System WebView y Embedded WebView a menudo se combinan; System WebView gestiona el inicio de sesión (con el uso compartido automático de credenciales) y, luego, Embedded WebView renderiza la gestión de claves de acceso en la configuración.

Factores clave de decisión:

• ¿Inicio de sesión basado en OAuth? → System WebView (ASWebAuthenticationSession, Chrome Custom Tabs)
• ¿Desea reutilizar la autenticación web en el entorno nativo? → Embedded WebView (WKWebView, Android WebView con WebKit 1.12.1+)
• ¿Construyendo una aplicación nativa primero? → Implementación nativa (Apple AuthenticationServices, Google Credential Manager)

Las plataformas móviles modernas proporcionan tres enfoques distintos para integrar claves de acceso en su aplicación nativa, cada uno con diferentes compromisos en cuanto a experiencia de usuario, complejidad técnica y compatibilidad con OAuth:

1. Implementación nativa: Construya flujos de claves de acceso directamente en su aplicación utilizando las API de la plataforma (AuthenticationServices en iOS, Credential Manager en Android). Proporciona la mejor experiencia de usuario con autenticación biométrica perfecta, pero requiere un esfuerzo de implementación técnica medio a alto.

2. System WebView: Utilice el componente de navegador de la plataforma (ASWebAuthenticationSession / SFSafariViewController en iOS, Chrome Custom Tabs en Android) para gestionar la autenticación. Excelente para flujos de inicio de sesión basados en OAuth y comparte credenciales con el navegador del sistema.

3. Embedded WebView: Integre una vista web personalizable (WKWebView en iOS, WebView en Android) dentro de su aplicación para reutilizar la autenticación web con un esqueleto de aplicación nativa. Proporciona una apariencia similar a la nativa sin barras de URL y un control total sobre la interfaz de usuario de la vista web. Requiere configuración adicional, incluidos permisos y derechos (entitlements) (iOS), y la configuración de WebView con AndroidX WebKit 1.12.1+ (Android) para habilitar la funcionalidad de claves de acceso.

La elección correcta depende de la arquitectura de autenticación de su aplicación, si utiliza proveedores OAuth, cuánto control necesita sobre la interfaz de usuario y si está construyendo primero de forma nativa o reutilizando componentes web.

Whitepaper empresarial de Passkeys. Guías prácticas, patrones de despliegue y KPIs para programas de passkeys.

Obtener whitepaper

Una implementación nativa de claves de acceso proporciona la experiencia de usuario óptima, con flujos de autenticación construidos directamente en la interfaz de usuario de su aplicación utilizando las API específicas de la plataforma. Los usuarios se benefician de los cuadros de diálogo nativos de la plataforma, la verificación biométrica fluida y los tiempos de inicio de sesión más rápidos posibles.

Cuándo elegir la implementación nativa:

• Construyendo una nueva aplicación nativa o refactorizando la autenticación hacia pantallas nativas
• Desea la mejor experiencia de usuario posible con autenticación instantánea y silenciosa
• Avisos automáticos de claves de acceso al inicio de la aplicación: Las implementaciones nativas pueden usar preferImmediatelyAvailableCredentials para mostrar automáticamente una superposición de claves de acceso cuando las claves de acceso están disponibles, proporcionando la experiencia de inicio de sesión más rápida sin requerir la entrada del identificador
• Necesita un control total sobre la interfaz de usuario y el flujo de autenticación
• Está dispuesto a invertir en una implementación específica de la plataforma (Swift en iOS, Kotlin en Android)

Ventaja clave: preferImmediatelyAvailableCredentials()

Las implementaciones nativas pueden aprovechar preferImmediatelyAvailableCredentials() para crear una superposición automática de claves de acceso que aparece inmediatamente al iniciar la aplicación cuando las claves de acceso están disponibles. Este flujo sin nombre de usuario proporciona la experiencia de inicio de sesión más rápida posible: los usuarios ven sus claves de acceso al instante sin ingresar primero un identificador. Esta capacidad es exclusiva de las implementaciones nativas y no está disponible en las variantes de WebView.

El siguiente diagrama ilustra cómo la autenticación nativa ofrece un proceso más rápido en comparación con el enfoque de UI condicional de WebView:

La superposición automática nativa proporciona una experiencia de usuario superior con tasas de uso de claves de acceso más altas, ya que la autenticación comienza inmediatamente al iniciar la aplicación, mientras que las implementaciones de WebView requieren que los usuarios interactúen primero con los campos de entrada.

Descripción general de los requisitos técnicos:

La integración nativa de claves de acceso requiere confianza criptográfica entre su aplicación y su dominio web. Sin ella, el sistema operativo rechazará todas las operaciones de WebAuthn. Requisitos clave:

1. Archivos de asociación de dominios de aplicaciones alojados en /.well-known/
2. ID de parte usuaria (Relying Party ID) correcto que coincida con su dominio web
3. Capacidades específicas de la plataforma (detalladas en la Sección 4)

El principal beneficio: las claves de acceso creadas en su sitio web funcionan a la perfección en su aplicación y viceversa.

La implementación nativa de claves de acceso en iOS implica el marco AuthenticationServices de Apple, que proporciona una API para las operaciones de WebAuthn:

Componentes clave:

• ASAuthorizationController: Gestiona el flujo de autenticación
• ASAuthorizationPlatformPublicKeyCredentialProvider: Crea solicitudes de clave de acceso
• Tres modos de interfaz de usuario distintos para gestionar el inicio de sesión con claves de acceso:
  • Inicio de sesión en campo de texto (Textfield): Campo tradicional de nombre de usuario con el inicio de sesión con clave de acceso que comienza al enviar el botón
  • Superposición modal de claves de acceso: Cuadro de diálogo del SO que enumera las claves de acceso disponibles
  • UI condicional: Sugerencias de claves de acceso en la barra QuickType por encima del teclado

Consejos de desarrollo

• Almacenamiento en caché de AASA: Apple almacena en caché el archivo AASA de forma muy agresiva (hasta 24 horas), lo que puede frustrar las pruebas. Solución: Habilite el Modo de Desarrollador en su dispositivo de prueba y agregue ?mode=developer a su URL AASA para forzar la obtención de una versión actualizada.
• Pruebas de rendimiento: Realice pruebas con cuentas de iCloud que contengan cientos de credenciales para observar la latencia en el mundo real. La superposición del sistema podría mostrar un ligero retraso con muchas claves de acceso almacenadas.

La implementación nativa de claves de acceso en Android utiliza la API de Credential Manager (o la API FIDO2 anterior por cuestiones de retrocompatibilidad):

Componentes clave:

• CredentialManager: API central para todas las operaciones de credenciales
• CreatePublicKeyCredentialRequest: Para el registro de claves de acceso
• GetCredentialRequest: Para la autenticación con claves de acceso
• Dos modos principales de interfaz de usuario:
  • Inicio de sesión en campo de texto (Textfield): Campo tradicional de nombre de usuario con el inicio de sesión con clave de acceso que comienza al enviar el botón
  • Superposición modal de claves de acceso: Cuadro de diálogo del SO que enumera las claves de acceso disponibles

Nota: Actualmente, Android carece de las sugerencias de teclado de UI condicional de iOS en aplicaciones nativas (aunque la UI condicional funciona en aplicaciones web).

La implementación nativa de claves de acceso tiene retos importantes y lecciones aprendidas: Integrarlas a nivel del SO puede revelar problemas en diferentes dispositivos y versiones del SO.

1. Por ejemplo, nuestro equipo encontró problemas como el almacenamiento en caché agresivo por parte de Apple del archivo apple-app-site-association (utilizado para vincular credenciales de aplicaciones/web) y diferencias sutiles de interfaz de usuario en ciertas indicaciones biométricas de fabricantes de equipos originales (OEM) de Android.
2. Además, considere que en algunos escenarios empresariales, los dispositivos gestionados pueden tener desactivada la sincronización de claves de acceso por política de empresa. En entornos corporativos donde la sincronización de iCloud Keychain o Google Password Manager está desactivada, las claves de acceso quedan vinculadas al dispositivo y no se pueden transferir, un escenario importante a tener en cuenta (por ejemplo, asegurándose de que los usuarios aún puedan iniciar sesión si obtienen un teléfono nuevo).
3. Asimismo, las aplicaciones de gestores de credenciales de terceros pueden influir en el flujo. Por ejemplo, si un usuario tiene un gestor de contraseñas como 1Password establecido como un proveedor de credenciales activo, a menudo interceptará la creación y el almacenamiento de claves de acceso, teniendo prioridad sobre el gestor de credenciales nativo de la plataforma.

Si bien puede implementar claves de acceso utilizando las API directas de la plataforma, los SDK creados específicamente aceleran significativamente el desarrollo al gestionar la complejidad de WebAuthn, los casos extremos y proporcionar telemetría integrada. Los SDK también ofrecen interfaces que se pueden simular para pruebas unitarias (crucial ya que no se pueden probar datos biométricos en simuladores).

Recomendación: Para implementaciones nativas, recomendamos utilizar los SDK de Corbado (iOS Swift Passkey SDK, Android Kotlin Passkey SDK), que gestionan los numerosos casos extremos descubiertos a través de implementaciones en producción, proporcionan telemetría adicional y facilitan las pruebas.

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

Los System WebViews utilizan el componente de navegador nativo de la plataforma para gestionar la autenticación dentro de su aplicación. A diferencia de las implementaciones totalmente nativas, los System WebViews muestran el contenido web utilizando el navegador real del sistema (Safari en iOS, Chrome en Android), manteniendo las cookies compartidas, las credenciales guardadas y los indicadores de seguridad del navegador conocidos.

Cuándo elegir System WebView:

• Su aplicación utiliza un inicio de sesión basado en OAuth: System WebView es el enfoque recomendado para flujos OAuth2/OIDC, proporcionando una autenticación segura.
• Autenticación basada en web existente que desea reutilizar en aplicaciones móviles.
• Necesita admitir múltiples métodos de autenticación (contraseñas, inicio de sesión social, claves de acceso) sin tener que reconstruirlos de forma nativa.
• Desea mantener una base de código de autenticación única en plataformas web y móviles.

Ventajas clave:

• Compatibilidad con OAuth: Diseñado específicamente para flujos de autenticación OAuth/OIDC.
• Indicadores de seguridad: Los usuarios ven la URL real y los certificados SSL, lo que genera confianza.
• Bajo esfuerzo de implementación: Se requiere un código nativo mínimo.
• Experiencia de usuario (UX) coherente: Interfaz de navegador familiar en la que los usuarios ya confían.

Componentes de la plataforma:

• iOS: ASWebAuthenticationSession (recomendado para flujos de autenticación) o SFSafariViewController (navegación general)
• Android: Chrome Custom Tabs (CCT)

Grandes empresas como Google y GitHub adoptaron este enfoque para añadir el inicio de sesión con claves de acceso a sus aplicaciones móviles a través de superposiciones de WebView en las páginas de autenticación web existentes. Esto funciona bien cuando las reconstrucciones de autenticación totalmente nativas no son factibles de inmediato.

iOS proporciona dos componentes principales de System WebView para la autenticación:

ASWebAuthenticationSession (Recomendado para la autenticación):

• Creado específicamente para OAuth/OIDC y flujos de inicio de sesión seguros.
• Solicita automáticamente al usuario que la aplicación desea autenticarse.
• Comparte cookies y credenciales con Safari.
• Soporta claves de acceso a través de iCloud Keychain.

SFSafariViewController (Navegación general):

• Experiencia Safari completa dentro de la aplicación.
• Muestra la barra de URL y los indicadores de seguridad.
• No comparte las cookies de Safari en iOS 11+; utilice ASWebAuthenticationSession cuando se requiera compartir la sesión de Safari.
• Menos personalizable pero más confiable para los usuarios.

Si su aplicación utiliza un inicio de sesión basado en OAuth, ASWebAuthenticationSession es la opción recomendada, ya que está diseñada específicamente para escenarios de autenticación y proporciona el mejor equilibrio entre seguridad y experiencia del usuario.

Chrome Custom Tabs (CCT) proporciona una experiencia de autenticación impulsada por Chrome dentro de su aplicación:

Características clave:

• Comparte cookies y credenciales con el navegador Chrome.
• Muestra URL e indicadores de seguridad.
• Puede personalizar el color de la barra de herramientas y la marca.
• Precalentamiento para tiempos de carga más rápidos.

Integración OAuth: Chrome Custom Tabs son el equivalente de Android de ASWebAuthenticationSession de iOS, proporcionando un excelente soporte OAuth al tiempo que mantiene el acceso a las claves de acceso almacenadas.

Prueba passkeys en una demo en vivo.

Probar passkeys

Embedded WebViews proporciona un control total sobre el contenido web que se renderiza dentro de su aplicación, permitiendo la manipulación directa de cookies, sesiones y la navegación sin barra de URL. Sin embargo, este control viene con requisitos técnicos adicionales para habilitar la funcionalidad de claves de acceso.

Cuándo elegir Embedded WebView:

• Experiencia similar a la nativa: Su aplicación ya integra la autenticación dentro de una vista web personalizada para mantener un aspecto y una sensación nativos, y desea mantener esta experiencia de usuario consistente.
• Necesita control de sesión/cookies: Su aplicación requiere manipulación directa de tokens de autenticación y estado de la sesión después de que se completa la autenticación OAuth.
• Flujo de autenticación existente donde la autenticación de System WebView devuelve un código de autenticación pero no una sesión en contextos incrustados.
• Debe mantener el estado de autenticación en múltiples pantallas web incrustadas.
• Solo autenticación de origen (first-party): Su aplicación gestiona la autenticación directamente; para implementaciones de claves de acceso de terceros, consulte aquí.
• AndroidX WebKit 1.12.1+ con detección de características en tiempo de ejecución.
• Acepte la limitación de la interfaz de usuario condicional para el inicio de sesión (no admitida en Embedded WebView), no es relevante para la configuración de gestión.

Contexto importante:

Muchas aplicaciones utilizan un enfoque híbrido: System WebView gestiona la autenticación OAuth inicial (donde las claves de acceso funcionan a la perfección) y, a continuación, cambian a Embedded WebView para después de la autenticación a fin de gestionar las claves de acceso en la configuración. Los desafíos surgen al intentar utilizar claves de acceso directamente dentro de los Embedded WebViews.

Requisitos técnicos:

Los Embedded WebViews requieren una configuración adicional en comparación con los System WebViews:

1. iOS: Derechos de Associated Domains (dominios asociados), configuración del archivo AASA.
2. Android: AndroidX WebKit 1.12.1+ con configuración WebAuthn de WebView (requiere detección de características).
3. Ambos: Archivos de asociación well-known correctamente configurados y Digital Asset Links.

Componentes de la plataforma:

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

Compromisos:

• Complejidad media: Requiere configuración de WebView (Android WebKit 1.12.1+) y configuración de derechos (entitlements en iOS).
• Menor adopción de claves de acceso: Los usuarios pueden encontrar más fricción en comparación con la solución nativa.
• No admite UI condicional: El autocompletado de claves de acceso en campos de entrada no funciona en Android Embedded WebView.
• Soporte limitado en la plataforma: Algunas características pueden no funcionar de forma consistente (por ejemplo, la creación automática de claves de acceso).

Al implementar claves de acceso a través de WebViews, es crucial comprender la distinción entre System WebViews y Embedded WebViews. Los tres enfoques descritos anteriormente (Implementación nativa, System WebView y Embedded WebView) sirven a diferentes casos de uso.

En iOS, tiene múltiples opciones para mostrar contenido web dentro de la aplicación:

• WKWebView es un WebView personalizable que forma parte del marco WebKit (introducido en iOS 8). Le da mucho control sobre la apariencia y el comportamiento del contenido web.
• SFSafariViewController es un controlador de vistas proporcionado por Apple que actúa como un navegador Safari ligero dentro de su aplicación. Utiliza el motor de Safari. En iOS 11+, tiene un almacén de cookies separado y no comparte las cookies de Safari. Utilice ASWebAuthenticationSession cuando se requiera compartir la sesión de Safari.
• SFAuthenticationSession / ASWebAuthenticationSession son sesiones de autenticación web especializadas (disponibles desde iOS 11/12) destinadas específicamente para flujos de inicio de sesión OAuth/OpenID u otros flujos de inicio de sesión seguros. Estas también aprovechan Safari a nivel interno, pero se centran en los flujos de autenticación y manejan automáticamente aspectos como las cookies compartidas y el inicio de sesión único (SSO).

En Android, las opciones principales son:

• Android WebView es el widget WebView estándar (android.webkit.WebView), que es esencialmente un mininavegador que puede ser incrustado en sus actividades. Es altamente personalizable pero se ejecuta en el proceso de su aplicación.
• Chrome Custom Tabs (CCT) es una función que abre una pestaña de Chrome dentro del contexto de su aplicación. Las pestañas personalizadas (Custom Tabs) aparecen como parte de su aplicación, pero están impulsadas por el navegador Chrome (si está instalado) con funciones como precarga, cookies compartidas y la barra de URL habitual para dar confianza al usuario.

En las siguientes secciones, profundizaremos un poco más en estos tipos de WebView para iOS y Android, y discutiremos cuáles podrían ser los más adecuados para los flujos de autenticación de claves de acceso.

Suscríbete a nuestro Substack de passkeys para recibir las últimas noticias.

Suscribirse

La plataforma de Apple proporciona las tres opciones de WebView enumeradas anteriormente. Su elección afectará la fluidez con la que se pueden usar las claves de acceso dentro de la aplicación:

Para probar el comportamiento de los diferentes WebViews en iOS, recomendamos la aplicación WebView - WKWebView and UIWebView rendering.

WKWebView es un componente WebView versátil para iOS. Los desarrolladores pueden integrar un WKWebView para renderizar contenido web con un alto grado de control sobre la interfaz de usuario y el comportamiento. WKWebView utiliza el mismo motor de renderizado que Safari, por lo que es muy eficiente y admite las funciones web modernas. En teoría, WKWebView puede gestionar WebAuthn (y, por lo tanto, las claves de acceso) si se configura correctamente, pero tenga en cuenta que algunas características avanzadas del navegador podrían estar restringidas por seguridad. Una cosa a tener en cuenta es que WKWebView por defecto no comparte cookies o datos de llavero (keychain) con Safari Móvil. Los usuarios podrían tener que volver a iniciar sesión porque su sesión de WebView está aislada de la sesión de Safari. Además, dado que el contenido de WKWebView puede ser totalmente personalizado por la aplicación, el usuario no ve una barra de direcciones o la interfaz de usuario de Safari, lo que es excelente para la marca, pero significa que el usuario tiene menos indicios para verificar la legitimidad de la página (una preocupación por el phishing). Algunas aplicaciones han llegado a abusar de WKWebView para inyectar scripts o alterar el contenido (por ejemplo, se observó que TikTok inyectaba JS de seguimiento a través de su navegador en la aplicación), por lo que se debe tener cuidado de usar WKWebView de una manera segura y confiable para el usuario.

SFSafariViewController proporciona una experiencia de Safari en la aplicación. Cuando se abre una URL con SFSafariViewController, es casi como abrirla en el navegador Safari real, excepto que el usuario permanece dentro de la interfaz de usuario de su aplicación. La ventaja para las claves de acceso es significativa: debido a que es esencialmente Safari, el llavero de iCloud (iCloud Keychain) del usuario y las claves de acceso guardadas son accesibles. Tenga en cuenta que las cookies no se comparten en iOS 11+. Esto significa que si el usuario ya tiene una clave de acceso para su sitio, Safari puede encontrarla e incluso mostrar el autocompletado de la UI Condicional para facilitar el inicio de sesión. SFSafariViewController es menos personalizable (no puede cambiar mucho su barra de herramientas), pero gestiona automáticamente muchas características de seguridad y privacidad. Se muestra la barra de URL, completa con el icono de candado para HTTPS, lo que da a los usuarios la confianza de que están en el dominio correcto. En general, SFSafariViewController se considera más seguro que un WKWebView estándar y es más fácil de implementar (Apple lo proporciona de forma sencilla). La principal contrapartida es que se sacrifica parte del control sobre el aspecto y el diseño. Para un flujo de autenticación, eso es habitualmente aceptable. La prioridad aquí es la seguridad y la facilidad de inicio de sesión, en las que SFSafariViewController sobresale al utilizar el contexto de Safari.

SFAuthenticationSession / ASWebAuthenticationSession – Estas clases (siendo esta última el nombre más reciente, compatible con Swift) se crean específicamente para flujos de inicio de sesión como OAuth u OpenID Connect. Cuando necesita autenticar a un usuario a través de una página web (tal vez ante un IdP externo), estas sesiones son la opción recomendada en iOS. Son muy similares a SFSafariViewController, ya que utilizan el navegador Safari por debajo y comparten cookies/almacenamiento con Safari. La diferencia clave es que SFAuthenticationSession siempre indicará al usuario que la aplicación desea autenticarse mediante una página web (para que el usuario sea consciente) y utilizará automáticamente la sesión de Safari existente del usuario si está disponible.

El beneficio es una experiencia de SSO fluida: si el usuario ya ha iniciado sesión en el proveedor en Safari, esta sesión puede utilizar esa cookie para evitar otro inicio de sesión. Para las claves de acceso, esto es importante porque significa que cualquier credencial de clave de acceso almacenada en Safari/iCloud Keychain se puede usar aquí también. La orientación oficial de Apple es utilizar ASWebAuthenticationSession para cualquier cosa que parezca un flujo de inicio de sesión. Las ventajas son la mejora de la privacidad (su aplicación nunca ve las credenciales o las cookies, Safari lo gestiona) y la compatibilidad con SSO integrada. La desventaja es que se limita a los flujos de autenticación (no se usaría simplemente para renderizar contenido web arbitrario en su aplicación). En resumen, si elige un enfoque WebView en iOS, ASWebAuthenticationSession es habitualmente la mejor opción para implementar claves de acceso porque es seguro, comparte el estado con Safari y está diseñado específicamente para la autenticación.

Consulta cuántas personas usan passkeys realmente.

Ver datos de adopción

En Android, la decisión sobre el WebView es entre el WebView clásico y Chrome Custom Tabs:

Para probar el comportamiento de los diferentes WebView en Android, recomendamos la aplicación WebView vs Chrome Custom Tabs.

Android WebView (android.webkit.WebView) es un componente que le permite incrustar páginas web en el diseño de su actividad (activity layout). Es similar a WKWebView en el sentido de que le otorga control total: puede interceptar la navegación, inyectar JavaScript, personalizar la interfaz de usuario, etc. También se ejecuta dentro del proceso de su aplicación. El uso de WebView para las claves de acceso significa que su aplicación carga su página de inicio de sesión web, y esa página puede iniciar una ceremonia de clave de acceso WebAuthn. El Android WebView moderno sí admite WebAuthn (siempre que la implementación de WebView del dispositivo esté actualizada a través de Android System WebView o el componente de Chrome). Una consideración importante: por defecto, un Android WebView no comparte cookies ni credenciales guardadas con el navegador Chrome del usuario. Por lo tanto, cualquier clave de acceso creada o utilizada en el WebView podría no ser conocida por Chrome, y viceversa. Este aislamiento puede ser bueno para la seguridad (su aplicación no puede leer las cookies del navegador), pero podría obligar a los usuarios a iniciar sesión de nuevo si ya se han autenticado en Chrome. Otro problema es la confianza. Un WebView simple no muestra la URL ni el icono de candado SSL, por lo que los usuarios tienen que confiar completamente en su aplicación para no ser víctimas de phishing. Google ha llegado a prohibir el uso de WebView para inicios de sesión con Google OAuth debido a los posibles riesgos de phishing. En cuanto al rendimiento, los WebViews están bien, pero pueden ser más lentos o requerir más memoria que el uso del navegador predeterminado del usuario, especialmente si se cargan páginas pesadas.

Las Chrome Custom Tabs (CCT) son un enfoque híbrido. Permiten que su aplicación abra una página renderizada por Chrome que parece formar parte de su aplicación. Puede personalizar el color de la barra de herramientas, añadir un logotipo de la aplicación, etc., pero el contenido es renderizado por Chrome en un proceso independiente. Para las claves de acceso, las CCT tienen varias ventajas: comparten las cookies del usuario y las credenciales con Chrome, lo que significa que si el usuario tiene una clave de acceso guardada a través de Chrome (Google Password Manager), la Pestaña Personalizada puede acceder a ella. El usuario también verá la URL real y los indicadores de seguridad, lo que genera confianza. El rendimiento es a menudo mejor: Chrome se puede "precalentar" en segundo plano para una carga más rápida. Y lo que es más importante, la seguridad es sólida: como se trata esencialmente de la aplicación de Chrome, aspectos como la Navegación Segura (Safe Browsing) de Google protegen la sesión, y su aplicación no puede inyectar scripts arbitrarios en la página (evitando ciertos ataques).

La desventaja es que requiere que el usuario tenga Chrome (o un navegador compatible) instalado y actualizado. La mayoría de los usuarios de Android lo tienen, pero en algunos dispositivos de ciertas regiones, esto podría ser un problema. En general, si opta por un enfoque web incrustado en Android, se recomiendan las Chrome Custom Tabs para los flujos de claves de acceso, ya que proporcionan un buen equilibrio de integración y seguridad. De hecho, son análogas a SFSafariViewController/ASWebAuthSession en iOS en muchos sentidos: aprovechan el navegador predeterminado para la autenticación.

(Como nota al margen: El enfrentamiento WKWebView de Apple frente a SFSafariViewController y WebView de Android frente a CCT tienen muchos paralelismos. Tanto Safari VC como Chrome Tabs comparten el estado del navegador y brindan mejor seguridad, mientras que WKWebView/Android WebView dan más control pero aíslan el contenido web. Para las claves de acceso, compartir el estado (cookies, almacenes de credenciales) es generalmente lo deseable para que se pueda acceder a la clave de acceso y crearla sin problemas.)

Independientemente del enfoque de implementación que elija, se deben cumplir ciertos requisitos técnicos para habilitar la funcionalidad de claves de acceso. Esta sección proporciona una guía exhaustiva sobre cómo configurar archivos de asociación well-known (conocidos), derechos de iOS (entitlements) y configuración de WebView en Android.

Nota sobre los dispositivos gestionados: El comportamiento de las claves de acceso cambia significativamente en los dispositivos gestionados donde las políticas de Gestión de Dispositivos Móviles (MDM) controlan el almacenamiento de credenciales. Para probar claves de acceso en dispositivos gestionados, consulte Claves de acceso en dispositivos gestionados con iOS y Android.

Los flujos nativos y de Embedded WebView requieren archivos de asociación para establecer la confianza criptográfica entre su aplicación y su dominio web. System WebView (ASWebAuthenticationSession) y Chrome Custom Tabs no requieren asociación de aplicación a sitio.

El archivo AASA establece la conexión entre su aplicación iOS y su dominio web, permitiendo que las claves de acceso funcionen en ambas plataformas.

Ubicación del archivo: https://sudominio.com/.well-known/apple-app-site-association

Requisitos de configuración:

• Alojar en /.well-known/apple-app-site-association de su dominio
• Servir sobre HTTPS con un certificado SSL válido
• Tipo de contenido (Content-Type): application/json
• Sin redirecciones en la ruta .well-known
• Incluir el ID de equipo (Team ID) y el ID de paquete (Bundle ID) de su aplicación

Ejemplo de archivo AASA:

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

Almacenamiento en caché de AASA y pruebas:

Apple almacena en caché de forma muy agresiva los archivos AASA (hasta 24-48 horas) utilizando una CDN, lo que puede frustrar el desarrollo y las pruebas. Para evitar el almacenamiento en caché durante el desarrollo:

1. Habilite el Modo de Desarrollador en su dispositivo de prueba.
2. Añada ?mode=developer a su dominio asociado en Xcode.
3. Esto fuerza a iOS a obtener el último archivo AASA directamente de su servidor.

⚠️ Importante: NO use ?mode=developer en los lanzamientos de producción. Este parámetro es solo para el desarrollo; si se utiliza en producción, impedirá que iOS detecte correctamente su archivo AASA, lo que romperá la funcionalidad de claves de acceso.

Validación: Use el validador AASA de Apple para verificar su configuración.

Android utiliza Digital Asset Links para verificar la relación entre su aplicación y el sitio web.

Ubicación del archivo: https://sudominio.com/.well-known/assetlinks.json

Requisitos de configuración:

• Alojar en /.well-known/assetlinks.json de su dominio
• Servir sobre HTTPS con certificado válido
• Tipo de contenido (Content-Type): application/json
• Incluir la huella digital SHA256 de su aplicación (del certificado de firma)

Ejemplo de archivo assetlinks.json:

[
    {
        "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"
            ]
        }
    }
]

Validación: Use el generador de Digital Asset Links de Google para crear y verificar su configuración.

Las aplicaciones de iOS requieren derechos adecuados para acceder a la funcionalidad de claves de acceso. Los requisitos difieren ligeramente en función de su enfoque de implementación.

El archivo de derechos (frecuentemente llamado Runner.entitlements en aplicaciones Flutter o YourApp.entitlements en proyectos nativos de iOS) define permisos y capacidades especiales concedidos por el sistema de Apple. Para las claves de acceso, este archivo configura los Dominios Asociados (Associated Domains).

Ubicación del archivo: Normalmente en su proyecto Xcode en ios/Runner/Runner.entitlements

La implementación nativa y Embedded WebView requieren la capacidad Associated Domains para vincular su aplicación con su dominio web. System WebView (ASWebAuthenticationSession) no lo requiere ya que se ejecuta en el contexto de Safari.

Configuración en Xcode:

1. Abra su proyecto en Xcode
2. Seleccione el target de su aplicación
3. Vaya a la pestaña "Signing & Capabilities"
4. Haga clic en "+ Capability" y añada "Associated Domains"
5. Añada su dominio con el prefijo webcredentials:

Ejemplo de configuración:

<?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:sudominio.com</string>
        <string>webcredentials:subdominio.sudominio.com</string>
    </array>
</dict>
</plist>

Varios dominios: Si su aplicación necesita funcionar con varios dominios, es posible que necesite Solicitudes de orígenes relacionados (Related Origin Requests, ROR).

Android Embedded WebViews admite claves de acceso a través de dos enfoques distintos: el enfoque más nuevo basado en WebKit (Sección 5.3.1) y el enfoque más antiguo de puente JavaScript (Sección 5.3.2). System WebView (Chrome Custom Tabs) no requiere ninguna configuración: las credenciales funcionan de manera automática.

Android proporciona ejemplos oficiales de claves de acceso en WebView que demuestran ambos enfoques de implementación.

Integración moderna de WebKit con la gestión nativa de claves de acceso. Este enfoque proporciona soporte nativo de WebAuthn sin requerir un código de puente personalizado.

Ejemplo oficial: Webkit WebView MainActivity

Requisitos:

• AndroidX WebKit 1.12.1 o posterior (se recomienda 1.14.0+)
• Configuración de Digital Asset Links
• APK de WebView con soporte WebAuthn (comprobar mediante detección de funciones)
• Nota: La biblioteca AndroidX Credentials NO es necesaria para WebView WebAuthn, solo para implementaciones totalmente nativas

Implementación:

import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature
 
// Check if Web Authentication is supported
if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION)) {
    // Enable Web Authentication
    WebSettingsCompat.setWebAuthenticationSupport(
        webView.settings,
        WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP
    )
 
    // Enable JavaScript
    webView.settings.javaScriptEnabled = true
}

Puntos clave:

• No se necesita un puente JavaScript: WebAuthn funciona de forma nativa en WebView
• Requiere detección de características: Compruebe siempre WebViewFeature.WEB_AUTHENTICATION en tiempo de ejecución
• No se admite la UI condicional: mediation:"conditional" (autocompletado de la clave de acceso en los campos de entrada) no funciona en Embedded WebView
• Estrategia alternativa (fallback): Si la característica no está disponible, utilice Chrome Custom Tabs en su lugar

Notas sobre versiones:

• Utilice WebKit 1.12.1 o superior (la 1.12.0 tenía un problema de disponibilidad en tiempo de ejecución)
• El soporte a esta característica depende de la versión del APK de WebView del usuario: los APK más antiguos del dispositivo no la expondrán

Antes de AndroidX WebKit 1.12.0, no existía el soporte nativo para WebAuthn en Embedded WebView. Este enfoque anterior utiliza un puente de Web a Nativo para gestionar las claves de acceso en dispositivos que carecen del soporte nativo para WebAuthn en WebView.

Ejemplos oficiales:

• PasskeyWebListener (Manejador de puentes)
• Utilidades de codificación en JavaScript

Cuándo utilizarlo: Al brindar soporte a versiones anteriores de Android o dispositivos con implementaciones heredadas de WebView.

Los equipos tenían que, o bien:

1. Utilizar Chrome Custom Tabs o Auth Tab (recomendado)
2. Construir un puente de JavaScript personalizado

Para ver la implementación detallada, consulte la Guía de integración de Credential Manager con WebView de Android. Sin embargo, recomendamos encarecidamente utilizar el enfoque nativo de WebKit 1.12.1+ para las aplicaciones modernas.

Recomendación: Utilice el soporte nativo de WebAuthn con AndroidX WebKit 1.12.1+. Si no está disponible en tiempo de ejecución, recurra a Chrome Custom Tabs, que proporciona un excelente soporte para las claves de acceso con credenciales compartidas.

Al implementar claves de acceso en aplicaciones nativas, debe establecer la confianza entre su aplicación y los dominios web. Esta sección describe cómo manejar un solo dominio, varios dominios relacionados (ROR) y cómo verificar que sus archivos de asociación well-known estén configurados correctamente.

Para aplicaciones que usan un solo dominio (por ejemplo, kayak.com), necesita:

• Un archivo AASA para iOS en https://kayak.com/.well-known/apple-app-site-association
• Un archivo assetlinks.json para Android en https://kayak.com/.well-known/assetlinks.json
• El derecho de Associated Domains (dominios asociados) configurado con webcredentials:kayak.com

Los Orígenes Relacionados (Related Origins, ROR) es una característica de WebAuthn que permite que un único conjunto de claves de acceso funcione en múltiples dominios relacionados (por ejemplo, kayak.com, kayak.de, kayak.co.uk). ROR utiliza el punto final (endpoint) /.well-known/webauthn en cada sitio para definir los orígenes relacionados, NO los archivos AASA ni assetlinks.

Puntos clave:

• Configuración de ROR: Cada dominio aloja /.well-known/webauthn con la lista de orígenes relacionados.
• Archivos de asociación de aplicaciones (AASA/assetlinks): Se utilizan solo para correlacionar aplicaciones con sus sitios web correspondientes.
• Embedded WebView de iOS 18+: Admite ROR cuando se configura correctamente.
• Derechos de Associated Domains: Incluya todos los dominios con los que su aplicación necesite autenticarse.

Ejemplo de configuración:

Si su aplicación funciona con kayak.com y kayak.de, ambos dominios deben:

• Alojar sus respectivos archivos AASA con el mismo ID de equipo (Team ID) y el ID del paquete (Bundle ID)
• Estar enumerados en los derechos de Associated Domains de su aplicación
• Tener los archivos well-known configurados correctamente y accesibles

Antes de poner su solución en marcha, verifique que sus archivos well-known estén configurados correctamente y sean accesibles. Apple y Google proporcionan direcciones URL de prueba basadas en sus CDN para comprobar la disponibilidad de los archivos:

Uso de estas URL de prueba:

• Haga clic en los enlaces para comprobar si Apple/Google pueden recuperar sus archivos well-known
• El parámetro ?nocache=1 de Apple fuerza una obtención reciente, pasando por alto la memoria caché del CDN
• Si los archivos no son accesibles a través de estas URL, la funcionalidad de las claves de acceso no funcionará en su aplicación
• Sustituya kayak.com o kayak.de por su(s) propio(s) dominio(s) en los patrones de URL anteriores.

Cuidado al probar: Asegúrese de que todos los dominios tengan los archivos well-known configurados correctamente. Un archivo faltante o mal configurado en cualquier dominio puede estropear la funcionalidad de la clave de acceso en ese dominio.

Más información: El ID de parte usuaria (Relying Party ID) de WebAuthn en aplicaciones nativas

La elección del enfoque de implementación correcto depende de la arquitectura de autenticación de su aplicación, los requisitos de OAuth y la necesidad de tener control sobre la sesión. Utilice este árbol de decisión para determinar el mejor camino a seguir.

El siguiente diagrama de flujo lo guía para que seleccione el enfoque de implementación correcto en función de los requisitos de su aplicación:

Referencia rápida para cada ruta:

• ¿Inicio de sesión basado en OAuth? → System WebView (ASWebAuthenticationSession / Chrome Custom Tabs)
• ¿Reutilizar la autenticación web en el entorno nativo? → Embedded WebView con configuración (WKWebView / Android WebView + WebKit 1.12.1+)
• ¿Construyendo una aplicación nativa primero? → Implementación nativa (AuthenticationServices / Credential Manager)
• ¿Autenticación web existente para reutilizar? → System WebView para una implementación rápida; de lo contrario Nativo para la experiencia de usuario óptima

A continuación se muestra el rendimiento de cada enfoque en las dimensiones clave:

Explicación de las dimensiones:

• Creación de claves de acceso: Facilidad de los usuarios para crear claves de acceso a través de este método.
• Uso de claves de acceso: La experiencia de autenticación cuando se usan claves de acceso existentes.
• Gestión de claves de acceso: Cómo los usuarios ven, editan o eliminan claves de acceso.
• Complejidad técnica: Esfuerzo de desarrollo y el mantenimiento en el tiempo.
• Soporte de OAuth: Capacidad de manejo del enfoque para los flujos de autenticación OAuth2/OIDC.
• Tiempo de configuración: Plazos típicos de implementación.

Recomendado: System WebView

Si su aplicación se autentica mediante OAuth2, OIDC o proveedores de inicio de sesión social (Google, GitHub, Microsoft, etc.), System WebView es la opción óptima:

• iOS: ASWebAuthenticationSession está diseñado específicamente para los flujos de OAuth.
• Android: Chrome Custom Tabs proporcionan una integración fluida con OAuth.
• Beneficios: Código nativo mínimo, uso compartido automático de credenciales.
• Implementación: Añada WebAuthn a su página de autenticación web y luego cárguela a través de System WebView.

Ejemplo: Aplicaciones de Viajes como kayak.com y kayak.de utilizan OAuth para la autenticación. System WebView les permite mantener su infraestructura actual de OAuth añadiendo al mismo tiempo el soporte a las claves de acceso mediante sus páginas de autenticación web.

Recomendado: Enfoque híbrido

Use System WebView para la autenticación OAuth inicial, y luego Embedded WebView para las sesiones posteriores a la autenticación:

1. Autenticación inicial: System WebView gestiona el inicio de sesión mediante OAuth + claves de acceso
2. Gestión de sesión: Cambie a Embedded WebView para contenido web autenticado donde se requiere un control directo de la cookie o la sesión.
3. Configuración técnica: Configure los requisitos tanto de System como de Embedded WebView; en el caso de Android, asegúrese de incluir AndroidX WebKit 1.12.1+ (ver Sección 5).

Cuándo usarlo: En aplicaciones que se autentican a través de OAuth y que luego necesitan mostrar contenido web autenticado en donde se requiere una manipulación directa de la sesión.

Recomendado: Implementación nativa

¿Lo está construyendo desde cero o tiene pantallas nativas? Adopte la solución totalmente nativa:

• iOS: Use el marco AuthenticationServices
• Android: Use la API Credential Manager
• Beneficios: La mejor UX, autenticación instantánea, control completo
• Ventaja exclusiva: Utilice preferImmediatelyAvailableCredentials para mostrar la superposición automática de claves de acceso en el inicio de la app - algo exclusivo de las implementaciones nativas que proporciona las tasas de conversión más altas.
• Recomendación de SDK: Use los SDK de Corbado (iOS, Android) para agilizar el desarrollo con un manejo de los casos extremos probado en producción.

Para aplicaciones nuevas: Recomendamos encarecidamente crear el inicio de sesión nativo desde el primer día. Lo prepara para obtener una UX óptima y evita migraciones futuras de WebView al entorno nativo.

Recomendado: Migración por fases

El siguiente diagrama muestra el camino de la migración gradual:

Cada fase se basa en la anterior, permitiendo mejoras graduales sin interrumpir a los usuarios que ya la usan.

Consulte la Sección 5 para conocer las instrucciones de configuración al detalle.

La prueba de claves de acceso en aplicaciones nativas requiere un enfoque estructurado y en varias capas. Siga la pirámide de pruebas: pruebas unitarias (lógica aislada), pruebas de integración (ceremonia de WebAuthn en simuladores o emuladores) y pruebas del sistema (de principio a fin en dispositivos físicos).

Categorías de pruebas imprescindibles:

• Trayectorias principales: Registro, autenticación, flujos a través de dispositivos cruzados, borrado de la clave de acceso.
• Cobertura en las plataformas: iOS (nativo), Android (nativo), navegadores web en las diferentes versiones del sistema operativo.
• Asociación de dominio: Comprobar que los archivos AASA (iOS) y los de Digital Asset Links (Android) resultan accesibles.
• Flujos de cancelación: Probar la cancelación por parte del usuario en las pantallas de aviso del sistema operativo y en las de datos biométricos.
• Manejo de errores: Caídas del sistema principal (backend), tiempos de espera por cuestiones de red, credenciales no coincidentes.
• Casos atípicos: Pantalla de bloqueo desconectada, llavero de iCloud o Google Password Manager desconectados.
• Flujos de OAuth: Integración completa de principio a fin de OAuth y de las claves de acceso.
• Dispositivos gestionados: Entornos regulados a través de MDM (consulte las pruebas de dispositivos gestionados).
• Gestores de terceros: Compatibilidad con 1Password, Bitwarden o Dashlane.
• Autenticación en dispositivos cruzados: Flujos de código QR y comprobación de transporte híbrido.
• Cuestiones específicas de Embedded WebView: Si se usa Embedded WebView, compruebe la configuración WebKit 1.12.1+ en Android.
• Supervisión de la producción: Tablero de mando para el control de tasas de éxito, los fallos y la latencia.

Si desea contar con una guía de comprobación de lo más completa, incluidas estrategias de automatización, los trucos por plataforma y la lista de control total de elementos previos, no dude en consultar la guía específica que le ofrecemos: Prueba de flujos de claves de acceso en las aplicaciones nativas de iOS y Android.

Tenga en cuenta la posibilidad de sugerir a sus usuarios que se hagan con una clave de acceso después del inicio de sesión habitual y correcto (contraseña o OAuth). Este planteamiento de conversión lenta:

• No entorpece los flujos de autenticación ya presentes
• Tolera una degradación cortés si el usuario la desestima
• Multiplica poco a poco la acogida de las claves de acceso sin necesidad de que se impongan las reformas.
• Empasta muy bien con cualquiera de los tres planteamientos de ejecución

Ejemplo: Después del inicio de sesión de tipo OAuth por medio de un System WebView, aparezca una instrucción nativa del tipo: "¿Dar paso al inicio rápido de sesión a través de Face ID?". En caso de que se afirme, se genera la clave de acceso a través de la página web que se haya activado en el System WebView.

El dirimir de qué forma se aplican las claves de acceso (mediante Implementación nativa, System WebView o Embedded WebView) constituye una determinación estructural determinante para la seguridad, el grado de confort del usuario y el nivel de sofisticación del desarrollo. No existe algo así como un patrón perfecto de uso general.

Para las aplicaciones que dependan de OAuth: System WebView (ASWebAuthenticationSession o Chrome Custom Tabs) sería el punto de inicio que se aconseja. Proporciona una ayuda de inmejorable categoría frente a OAuth, una demanda de aplicación de mínimos y se comparte, por sí mismo, de forma automática las credenciales.

Para aquellas que anteponen en todo momento el funcionamiento nativo: Actúe de la forma más nativa que le resulte posible, a la máxima celeridad. El entrar como una aplicación nativa permite un acceso dotado del máximo confort, del que no existen comparativas posibles, a partir de funciones propias a las que no tendría acceso otra modalidad que no fuera la nativa. Sería el caso del elemento preferImmediatelyAvailableCredentials, que despliega la pantalla de claves de acceso de forma automática en los compases de inicio de la app, algo que las ejecuciones de tipo WebView ni tan siquiera pueden imaginar. Al proporcionar en la actualidad y por parte del sistema iOS, al igual que del Android, de un abrigo de lo más notable para las claves de acceso, estas implementaciones están sumando triunfos tangibles en entornos reales que no hacen sino probar su altísima acogida entre los usuarios. Todas y cada una de las herramientas de aplicación (y de paso los SDK propios del entorno del código libre o bien las librerías propias del entorno informático) han ido perfeccionándose hasta un punto en que la agregación del entorno nativo sea ya algo completamente abordable dentro de unos márgenes de tiempo nada irrazonables. Bien es cierto que no podemos olvidar los preceptos rectores sobre la gobernanza y gestión de los dispositivos, el acomodo en varios terminales o a qué tipo de suministradores exteriores estamos acudiendo; ahora bien, todos los envites pueden mitigarse a nada que medie una ingeniería rigurosa y a base de un régimen pormenorizado de exámenes. Una vez efectuado esto obtendremos como premio un acceso a las aplicaciones tan ágil y liviano que provocará la admiración en todo su espectro y por añadidura, un robustecimiento innegable de la vertiente relacionada con la seguridad.

En caso de exigencia sobre tramas Embedded WebView: El caso del Embedded WebView hace presencia regular bajo un par de escenarios tangibles del mundo real. A modo de primera pauta de actuación, las aplicaciones subordinadas a la exigencia del OAuth, tiran en buena medida de un System WebView como paso inicial a todo el proceso del acceso, desplazándose acto seguido hacia el escalón correspondiente del Embedded WebView para que allí, en los recovecos de todo el apartado relativo a las configuraciones, donde deba quedar atada toda orden vinculada con las sesiones se ejecuten y tomen cuerpo todas las opciones tendentes a gobernar las citadas claves, a expensas de que ciertas aplicaciones allanan de forma importante tales vericuetos para así perpetuar durante todas las vicisitudes un único System WebView. El segundo escenario nos pone frente al hecho de las aplicaciones que habían encajado en su día al inicio del proceso unas tramas WebView, antes incluso de su asimilación de las claves y se empeñan ahora en no renunciar al antedicho dibujo de comportamiento para que prime ante cualquier circunstancia la congruencia. Una orden Embedded WebView a la que acompañe un abrigo del WebAuthn de formato nativo (AndroidX WebKit 1.12.1+) acarrearía sus propias configuraciones (al amparo de permisiones, derechos o un control desde el WebView) mas no demandaría bajo un mismo contexto de un particular y adusto código anclado en JavaScript. Haga memoria frente a todo esto de la total invalidez a efectos técnicos del modelo de UI Condicional, dentro de este Embedded WebView. Sírvase usted mismo de la citada elección en cuantas oportunidades precise de prolongar hacia el futuro un enramado previo o bien en toda situación de exigencia y requerimiento forzoso del gobierno y mando respecto de la cookie/sesión durante el periplo de pantallas tras la autenticación.

Puestas así las cosas, queda constatado que las citadas claves, de cara a esas mismas aplicaciones que se precien de la marca de nativas, evidencian un formidable salto en términos cualitativos referenciados al bienestar del interviniente, tanto como de la ineludible seguridad de la totalidad del formato. Póngase como se ponga uno y con independencia del sendero escogido, ya fuere desde una solución netamente Nativa o a partir de un recurso a un System WebView o aun incluso por la traza del Embedded WebView, no existe género de dudas en que neutralizan a base de bien todos los peligros originados por aquellas malas artes del tipo phishing y destierran a idéntica o mayor celeridad el incordio derivado de gobernar a mano y a modo artesano de incontables palabras reservadas que asedian, como quien dice, a todo hijo de vecino en la inmensidad de esta intrincada y basta Red. Un muestreo en directo del modo y manera de proceder relativo a estos casos (véase el de la asociación nativa dentro de esa otra aplicación regida por la firma VicRoads) dejan sobrada constancia del hecho palpable que aquellos que confían a ciegas y abrazan este proceder nativista recogen luego el tributo a sus afanes, acaparando el fervor absoluto en lo referido a su uso y no digamos si esto se remata, de igual forma que en este caso concreto, con florituras del empaque del uso automatizado y recurrente de una cortina al encender. Haciendo uso del camino pautado y de su abecedario en esta disciplina del trato al prójimo que hace honor a eso de no amargarle a nadie la jornada en todo paso donde la autenticidad sea clave, a lo que habría de unírsele una adopción resuelta para una acometida de los trabajos y del acopio que mejor calcen los designios y contornos del arquitecto: priorizar un planteamiento nativo desde el primer rayo de luz al despuntar una creación, la senda del System WebView tratándose del universo OAuth o del tan cacareado Embedded WebView para pergeñar los enmarañamientos por venir de este formato propio y característico; podrá alzar la voz para prometer un universo ausente del vocablo contraseña, de un acceso regido por las leyes ineludibles de lo corpóreo para que a fin de cuentas asome por todo su derecho la grandilocuencia real y auténtica de lo que habría de ser la promesa primigenia de estas llaves: dar con una puerta simple, segura de pleno derecho y deleite pleno que deba ser el certificar todo el trasiego del individuo en cualquier momento y rincón por igual.

Si las claves de acceso no funcionan en su aplicación nativa, compruebe estos problemas habituales por enfoque de implementación:

• Los archivos se sirven a través de HTTPS con un certificado válido
• Tipo MIME correcto: application/json
• No hay redirecciones en la ruta .well-known
• iOS: El ID de equipo y el ID de paquete coinciden exactamente en el archivo AASA
• Android: La huella digital SHA256 coincide con su certificado de firma en assetlinks.json
• El ID de la parte usuaria (Relying Party ID) coincide con su dominio (sin protocolo, sin puerto)
• Sin barras inclinadas (/) al final del RP ID
• Origen de WebAuthn: https://su-dominio.com (no app://)

• iOS: Capacidad de Dominios Asociados (Associated Domains) habilitada en Xcode con webcredentials:sudominio.com
• Android: Digital Asset Links declarados en AndroidManifest.xml
• El usuario tiene habilitado el bloqueo de pantalla (biométrico o PIN)
• Pruebas con el Validador AASA de Apple y la herramienta Digital Asset Links de Google
• Verificar que el archivo Runner.entitlements contiene los dominios asociados correctos

• iOS: Utilizando ASWebAuthenticationSession (recomendado) o SFSafariViewController
• Android: Utilizando Chrome Custom Tabs (no un WebView simple)
• iOS: Verifique que los Dominios Asociados están configurados si es necesario
• Pruebe que las cookies/credenciales se comparten con el navegador del sistema
• Verifique que la página de autenticación web tiene una implementación adecuada de WebAuthn

• iOS: Configurado con los derechos (entitlements) apropiados
• iOS: Los Dominios Asociados incluyen todos los dominios relevantes
• iOS: El archivo AASA es accesible y tiene el formato adecuado
• iOS: Pruebas con ?mode=developer durante el desarrollo (quitar en producción)
• Android: AndroidX WebKit 1.12.1+ (o más reciente) incluido en el proyecto
• Android: Comprobación de características en tiempo de ejecución para WebViewFeature.WEB_AUTHENTICATION
• Android: Se llama a setWebAuthenticationSupport() con WEB_AUTHENTICATION_SUPPORT_FOR_APP
• Android: JavaScript habilitado en la configuración de WebView
• Android: La versión APK de WebView del usuario soporta la característica WebAuthn (utilice la detección de características, no la versión del sistema operativo)
• No se utiliza la UI Condicional (no soportada en Embedded WebView)
• Alternativa (fallback) a Chrome Custom Tabs si la característica WebAuthn no está disponible

• Compruebe si el usuario tiene activo un proveedor de credenciales no predeterminado (1Password, Bitwarden, etc.)
• Verifique que el proveedor soporta claves de acceso (no todos los gestores de contraseñas lo hacen)
• Haga pruebas con el gestor de credenciales nativo de la plataforma (iCloud Keychain, Google Password Manager)

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

• Normalmente significa: Derechos (entitlements) ausentes (iOS) o característica de WebView no disponible/habilitada (Android Embedded WebView)
• Comprobar: Configuración de Dominios Asociados, accesibilidad del archivo AASA, versión de WebKit, detección de características, llamada a setWebAuthenticationSupport()

No aparece el indicador de clave de acceso

• Podría significar: AASA/assetlinks.json no se carga, tipo de WebView incorrecto, archivo AASA en caché
• Intentar: Validar archivos de asociación, utilizar ?mode=developer en iOS para pruebas, verificar el tipo de WebView

Para una depuración detallada, consulte nuestro artículo sobre IDs de parte usuaria (Relying Party IDs) en aplicaciones nativas.

Un error común: los entornos de preparación (staging) con acceso restringido (listas blancas de IP, solo VPN) fallarán porque las CDN de Apple y Google deben poder recuperar sus archivos de asociación.

• Los archivos AASA/assetlinks son accesibles públicamente (sin lista blanca de IP, sin requisito de VPN)
• Verifique que la CDN de Apple puede acceder a su archivo: https://app-site-association.cdn-apple.com/a/v1/su-dominio-staging.com?nocache=1
• Verifique que Google puede acceder a su archivo: https://digitalassetlinks.googleapis.com/v1/statements:list/?source.web.site=https://su-dominio-staging.com&relation=delegate_permission/common.handle_all_urls

Subdominio de staging con el rpID de producción:

Si su entorno de preparación (p. ej., stg.login.ejemplo.com) utiliza el dominio de producción como rpID (p. ej., ejemplo.com), la búsqueda de AASA se realiza en el dominio del rpID, no en su subdominio de preparación. Esto significa:

• Añada los ID de paquete (bundle IDs) de la aplicación de preparación a su archivo AASA de producción
• Tenga en cuenta que las claves de acceso creadas en preparación aparecerán en los flujos de inicio de sesión de producción (posible confusión)

Ejemplo (varios entornos compartiendo un solo AASA):

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

Recomendación: Utilice un rpID de preparación separado que coincida con su dominio de preparación para evitar la superposición de credenciales entre entornos. Esto requiere archivos AASA públicamente accesibles en el dominio de preparación.

Aclaración sobre ?mode=developer:

El parámetro ?mode=developer en Dominios Asociados evita la caché de la CDN de Apple pero no evita el requisito de accesibilidad. Su archivo AASA aún debe ser accesible desde el dispositivo (no a través de la CDN de Apple, sino de forma directa). Esto ayuda durante el desarrollo cuando se itera sobre los cambios de AASA, pero no ayudará si su servidor de preparación tiene una lista blanca de IPs.

SDK nativos de Corbado:

• SDK de iOS (Swift)
• SDK de Android (Kotlin)
• Paquete de Flutter

Documentación de la plataforma:

• Apple: Soporte de claves de acceso (Supporting Passkeys)
• Google: Credential Manager

Herramientas de validación:

• Validador AASA de Apple
• Generador Digital Asset Links de Google

Acerca de Corbado

Corbado es la Passkey Intelligence Platform para equipos de CIAM que gestionan autenticación de consumidores a gran escala. Te ayudamos a ver lo que los logs de tu IDP y las herramientas de analytics genéricas no muestran: qué dispositivos, versiones de SO, navegadores y gestores de credenciales soportan passkeys, por qué los registros no se convierten en inicios de sesión, dónde falla el flujo de WebAuthn y cuándo una actualización de SO o navegador rompe el login en silencio — todo sin reemplazar Okta, Auth0, Ping, Cognito o tu IDP propio. Dos productos: Corbado Observe aporta observabilidad para passkeys y cualquier otro método de login. Corbado Connect añade passkeys gestionados con analytics integrado (junto a tu IDP). VicRoads ejecuta passkeys para más de 5M de usuarios con Corbado (+80 % de activación de passkey). Habla con un experto en Passkeys →

La elección depende de su arquitectura de autenticación. Si su aplicación utiliza OAuth2 u OIDC, System WebView (ASWebAuthenticationSession en iOS o Chrome Custom Tabs en Android) requiere el menor esfuerzo de implementación y ninguna configuración de archivos de asociación. Para aplicaciones nuevas que priorizan lo nativo, la implementación nativa proporciona una experiencia de usuario (UX) superior, mientras que Embedded WebView es adecuada para aplicaciones que ya integran la autenticación en un marco de WebView y necesitan control de sesión o cookies después del inicio de sesión.

SFSafariViewController aprovecha el motor de Safari, muestra la barra de URL con indicadores SSL y proporciona protección contra el phishing, lo que lo hace más confiable para los flujos de autenticación. WKWebView ofrece más personalización de la interfaz de usuario pero tiene un almacén de cookies aislado separado de Safari, requiere los derechos de Associated Domains y un archivo AASA para habilitar las claves de acceso, y no muestra la barra de URL, lo que reduce las señales de confianza para el usuario.

Las Chrome Custom Tabs comparten las cookies y las credenciales almacenadas con el navegador Chrome del usuario, lo que significa que las claves de acceso guardadas en el Gestor de Contraseñas de Google son accesibles durante la autenticación. El Android WebView estándar tiene un almacén de cookies aislado, no muestra la URL o los indicadores SSL, y Google lo ha prohibido explícitamente para el inicio de sesión en cuentas de Google debido a los riesgos de phishing.

Si un usuario tiene un gestor de credenciales de terceros como 1Password establecido como su proveedor activo, a menudo interceptará la creación y el almacenamiento de claves de acceso, teniendo prioridad sobre el gestor de credenciales nativo de la plataforma (iCloud Keychain o Gestor de Contraseñas de Google). Esto significa que las claves de acceso pueden almacenarse en la aplicación de terceros en lugar de en el llavero de la plataforma, lo que afecta al comportamiento de la sincronización entre dispositivos y a la gestión de las claves de acceso.

Cuando las políticas MDM inhabilitan la sincronización de credenciales, las claves de acceso se quedan vinculadas al dispositivo y no se pueden transferir a un dispositivo de sustitución, a diferencia de los escenarios típicos de los consumidores. Las aplicaciones dirigidas a entornos corporativos deben planificar mecanismos de autenticación alternativos como el inicio de sesión con contraseña o enlace mágico para gestionar los casos en los que un usuario reciba un nuevo dispositivo gestionado.