Claves de acceso nativas para aplicaciones móviles

Aprenda a implementar flujos nativos de claves de acceso para aplicaciones móviles Android e iOS

Las passkeys son una alternativa resistente al phishing a las formas tradicionales de autenticación (como nombre de usuario y contraseña) que ofrecen una experiencia de usuario más sencilla y segura. Se basan en las especificaciones de FIDO® W3C Web Authentication (WebAuthn) y Client to Authenticator Protocol (CTAP).

Actualmente, Auth0 admite las passkeys como método de autenticación en conexiones de base de datos y ofrece dos métodos de implementación:

• Passkeys de Universal Login para aplicaciones web.
• Passkeys nativas para aplicaciones Android e iOS.
• Embedded Login para aplicaciones web y nativas

​

Cómo funciona

Las passkeys nativas usan una combinación de la API de autenticación de Auth0 y las API nativas de iOS o Android para integrar los flujos de desafío directamente en su aplicación móvil. Esto le permite crear una experiencia integrada de registro e inicio de sesión para su aplicación sin depender de redirigir a los usuarios a través del navegador para completar la autenticación.

El siguiente ejemplo muestra la experiencia que puede tener un usuario nuevo durante el flujo de registro con passkey:

1. Un usuario nuevo abre su aplicación móvil y accede a la pantalla de inicio de sesión. Como es un usuario nuevo, selecciona el botón Registrarse.
2. En la siguiente pantalla, el usuario introduce su correo electrónico y selecciona Crear cuenta.
3. A continuación, se le pregunta al usuario si desea crear una passkey para su aplicación. Para continuar, el usuario selecciona Continuar.
4. Para generar una passkey, el usuario debe autenticarse localmente en su dispositivo mediante biometría u otro método de autenticación, como introducir un PIN.
5. Una vez completada la autenticación local, se guarda una nueva passkey en el dispositivo del usuario y se sincroniza con su proveedor de passkeys, como iCloud o Google.
6. Después de guardar la passkey, el usuario continúa con el proceso de registro para finalizar su cuenta.

Una vez completado este proceso, el usuario podrá autenticarse con su passkey guardada la próxima vez que inicie sesión en su aplicación.

​

Antes de empezar

​

Configurar un dominio personalizado

Las passkeys nativas requieren el uso de un dominio personalizado. Antes de continuar, asegúrate de haber configurado un dominio personalizado para tu Tenant. Para obtener más información, consulta Dominios personalizados.

​

Configure la política de passkey

Antes de poder implementar passkey nativas para aplicaciones de Android o iOS, debe configurar una política de passkey en su Tenant de Auth0. Para preparar su Tenant, siga los pasos indicados en Configurar la política de passkey.

​

Prepare la aplicación

Para preparar la aplicación para passkeys nativas, debe configurar la configuración del dispositivo y agregar la concesión Passkey. Puede completar esta configuración desde su Auth0 Dashboard o mediante la Management API.

​

Dominios asociados

Para que los usuarios finales puedan autenticarse con una única passkey en distintos tipos de aplicaciones o en aplicaciones con subdominios diferentes, establezca el Relying Party ID en el dominio raíz o dominio principal. Para obtener más información, consulte Passkeys.

​

Configura Auth0 Dashboard

1. Ve a Applications > Applications y selecciona la aplicación que quieres actualizar.
2. En la parte inferior de la pestaña Settings, selecciona Advanced Settings. Luego, elige la pestaña Device Settings.
3. Completa las secciones iOS y Android según sea necesario para tu aplicación. Luego, haz clic en Save Changes.
4. En la sección Advanced Settings, selecciona la pestaña Grant Types.
5. Habilita la concesión Passkey y luego selecciona Save Changes.

​

Management API

Llame al endpoint Update a Client y:

• Actualice grant_types para incluir urn:okta:params:oauth:grant-type:webauthn.
• Use el objeto mobile para especificar la configuración de los dispositivos iOS y Android según sea necesario.

​

Implementar flujos con passkeys

Puede definir los siguientes flujos de passkeys para su aplicación:

• Flujo de registro: Permite que los usuarios nuevos generen y guarden una passkey durante el proceso de registro.
• Flujo de inicio de sesión: Permite que un usuario existente, que ya se haya inscrito en passkeys, se autentique con la passkey guardada durante el proceso de inicio de sesión.

​

Flujo de registro

Un usuario inicia el flujo de registro con passkey cuando intenta iniciar sesión en su aplicación por primera vez.

Si el usuario proporciona un identificador que ya existe, se recomienda pedirle que complete el flujo de inicio de sesión en su lugar. De lo contrario, la operación fallará.

​

Pasos del flujo

1. Un usuario visita su aplicación y elige registrar una cuenta nueva. El usuario proporciona un identificador solicitado por la aplicación, como su dirección de correo electrónico.
2. A continuación, la aplicación inicia el desafío de registro llamando al endpoint Solicitar desafío de registro de la API de autenticación de Auth0:

• Si no especifica un realm, se usa el directorio predeterminado de su Tenant.
• De forma predeterminada, el correo electrónico es el identificador obligatorio. Si ha habilitado Identificadores flexibles para su conexión de base de datos, puede usar en su lugar una combinación de email, phone_number o username. Estas opciones pueden ser obligatorias u opcionales y deben coincidir con la configuración de Identificadores flexibles.

   POST /passkey/register
   Content-Type: application/json

   {
     "client_id": "{YOUR_CLIENT_ID}",
     "realm": "{OPTIONAL_CONNECTION}",
     "user_profile": {
   	  "email": "{VALID_EMAIL_ADDRESS}",
   	  "name": "{OPTIONAL_USER_DISPLAY_NAME}",
     }
   }

3. Como respuesta, Auth0 devuelve PublicKeyCredentialCreationOptions junto con un ID de auth_session y rpId como rp.id:

   HTTP/1.1 200 OK
   Content-Type: application/json
   
   {
     "authn_params_public_key": {
       "challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}",
       "timeout": {MILLISECONDS},
       "rp": {
         "id": "{YOUR_CUSTOM_DOMAIN}",
         "name": "{YOUR_CUSTOM_DOMAIN}"
       },
       "pubKeyCredParams": [
         { type: 'public-key', alg: -8 },
         { type: 'public-key', alg: -7 },
         { type: 'public-key', alg: -257 }
       ],
       "authenticatorSelection": {
         "residentKey": "required",
         "userVerification": "preferred"
       },
       "user": {
         "id": "{GENERATED_ID}",
         "name": "{USER-ENTERED_IDENTIFIER}",
         "displayName": "{USER-ENTERED_DISPLAY_NAME_OR_IDENTIFIER_IF_MISSING}"
       }
     },
     "auth_session": "{SESSION_ID}"
    }
   
   El rpId devuelto en la respuesta coincide con el dominio usado en el flujo web para que las passkeys funcionen en dominios asociados.

4. A continuación, la aplicación completa el proceso de registro del usuario mediante las API nativas correspondientes:

   • Consulte la documentación de registro de Android.
   • Consulte la documentación de registro de iOS.

5. A continuación, la aplicación usa la información de credenciales obtenida durante el proceso de registro, incluidos los detalles de authn_response, para llamar al endpoint Token:

   POST /oauth/token
   Content-Type: application/json
   
   {
     "grant_type": "urn:okta:params:oauth:grant-type:webauthn",
     "client_id": "{YOUR_CLIENT_ID}",
     "realm": "{OPTIONAL_CONNECTION}",
     "scope": "{OPTIONAL_REQUESTED_SCOPE}",
     "audience": "{OPTIONAL_REQUESTED_AUDIENCE}"
     "auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}",
     "authn_response": {
       "id": "{BASE64URL_ID}",
       "rawId": "{BASE64URL_RAWID}",
       "type": "public-key",
       "authenticatorAttachment": "platform|cross-platform",
       "response": {
         "clientDataJSON": "{BASE64URL_CLIENT_DATA_JSON}",
         "attestationObject": "{BASE64URL_ATTESTATION_OBJECT}",
         {OTHER_PROPERTIES}
       },
     },
   }
   

6. Auth0 crea una nueva cuenta de usuario y devuelve los tokens solicitados para completar el flujo:

   HTTP/1.1 200 OK
   Content-Type: application/json
   
   {
     "access_token": "{BASE64_TOKEN}",
     "refresh_token": "{BASE64_TOKEN}",
     "id_token": "{BASE64_TOKEN}",
     "token_type": "Bearer",
     "expires_in": {SECONDS}
   }
   

​

Flujo de inicio de sesión

Un usuario existente inicia el flujo de inicio de sesión con passkeys cuando intenta iniciar sesión en tu aplicación. Este flujo solo se aplica a los usuarios existentes que hayan guardado passkeys en sus cuentas durante el registro inicial.

​

Pasos del flujo

1. Un usuario abre su aplicación y comienza el proceso de inicio de sesión. A continuación, su aplicación inicia el desafío de inicio de sesión llamando al endpoint Solicitar desafío de inicio de sesión de la API de autenticación:

   Si no especifica un realm, se usará el directorio predeterminado de su Tenant.

   POST /passkey/challenge
   Content-Type: application/json
   
   {
     "client_id": "{YOUR_CLIENT_ID}",
     "realm": "{OPTIONAL_CONNECTION}"
   }
   

2. Como respuesta, Auth0 devuelve PublicKeyCredentialRequestOptions junto con una auth_session para continuar el flujo en su aplicación:

   HTTP/1.1 200 OK
   Content-Type: application/json
   
   {
     "authn_params_public_key": {
       "challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}",
       "timeout": {AUTH_TIMEOUT_IN_MILLISECONDS},
       "rpId": "{CUSTOM_DOMAIN}",
       "userVerification": "preferred"
     },
     "auth_session": "{SESSION_ID}"
   }
   

3. A continuación, su aplicación completa el proceso de inicio de sesión mediante las API nativas correspondientes:

   • Consulte la documentación de inicio de sesión para Android
   • Consulte la documentación de inicio de sesión para iOS.

4. A continuación, su aplicación usa la información de credenciales obtenida durante el proceso de inicio de sesión, incluidos los detalles de authn_response, para llamar al endpoint Token:

   POST /oauth/token
   Content-Type: application/json
   
   {
     "grant_type": "urn:okta:params:oauth:grant-type:webauthn",
     "client_id": "{YOUR_CLIENT_ID}",
     "realm": "{OPTIONAL_CONNECTION}",
     "scope": "{OPTIONAL_REQUESTED_SCOPE}",
     "audience": "{OPTIONAL_REQUESTED_AUDIENCE}"
     "auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}",
     "authn_response": {
       "id": "{BASE64URL_ID}",
       "rawId": "{BASE64URL_RAWID}",
       "type": "public-key",
       "authenticatorAttachment": "platform|cross-platform",
       "response": {
         "authenticatorData": "{BASE64URL_AUTHENTICATORDATA}",
         "clientDataJSON": "{BASE64URL_CLIENTDATAJSON}",
         "signature": "{BASE64URL_SIGNATURE}",
         "userHandle": "{BASE64URL_USERHANDLE}"
       },
       "clientExtensionResults": {OPTIONAL_OBJECT}
      }
   }
   

5. Auth0 autentica las credenciales y devuelve los tokens solicitados para completar el flujo:

   HTTP/1.1 200 OK
   Content-Type: application/json
   
   {
     "access_token": "{BASE64_TOKEN}",
     "refresh_token": "{BASE64_TOKEN}",
     "id_token": "{BASE64_TOKEN}",
     "token_type": "Bearer",
     "expires_in": {SECONDS}
   }
   

​

Referencias

Puede consultar los siguientes recursos al implementar passkeys nativas para su aplicación móvil:

• API de autenticación de Auth0

  • Solicitar desafío de registro
  • Autenticar a un usuario nuevo
  • Solicitar desafío de inicio de sesión
  • Autenticar a un usuario existente

• Recursos de Android

  • Documentación de registro
  • Documentación de inicio de sesión

• Recursos de iOS

  • Documentación de registro
  • Documentación de inicio de sesión