Saltar al contenido principal
Las claves de acceso son una alternativa resistente al phishing frente a las formas tradicionales de autenticación (como username y contraseña) y ofrecen una experiencia de usuario más sencilla y segura. Para conocer todos los detalles de implementación, consulte Native Passkeys for Mobile Applications. Las claves de acceso nativas usan una combinació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. Los endpoints que se enumeran a continuación son un subconjunto de la API de autenticación de Auth0. Para obtener más información sobre cómo usar esta API, consulte la Introducción a la API de autenticación. Las claves de acceso tienen tres flujos relacionados:
  • Registro: Crea una cuenta de usuario nueva con una clave de acceso como método principal de autenticación.
  • Inscripción: Agrega una clave de acceso como método de autenticación a la cuenta de un usuario existente.
  • Inicio de sesión: Solicita a un usuario existente que se autentique con una clave de acceso asociada a su cuenta.

​
Flujo de registro

​
Solicitar desafío para el registro

POST /passkey/register Inicia el flujo de registro de clave de acceso para un nuevo usuario. Como respuesta, Auth0 devuelve PublicKeyCredentialCreationOptions y un id de sesión. Consulta timeout en authn_params_public_key de la respuesta para ver el tiempo de espera de la sesión. El flujo de registro de clave de acceso admite Organizaciones mediante el parámetro organization, según el comportamiento descrito en Flujos de inicio de sesión para Organizaciones. Si tu aplicación está configurada para Usuarios empresariales, debes proporcionar el parámetro organization y un valor válido de nombre o identificador de Organización. Después de que el usuario registre una clave de acceso, Auth0 lo inscribe en la Organización proporcionada.

​
Parámetros de la solicitud

ParámetroDescripción
client_idObligatorio. El client_id de su aplicación.
realmOpcional. El nombre de la conexión que se asociará con este usuario.

Si no se especifica una conexión, se usa el directorio predeterminado de su inquilino.
user_profileObligatorio. Un objeto que contiene información de identificación del usuario. De forma predeterminada, esto incluye un email válido y un name de visualización opcional.

Si ha habilitado Identificadores flexibles para su conexión de base de datos, puede usar una combinación de email, phone_number o username como identificadores. Estas opciones pueden ser obligatorias u opcionales y deben coincidir con la configuración de sus Identificadores flexibles.

Si el identificador proporcionado (como email) ya existe en el directorio, debe pedirse al usuario que, en su lugar, complete el flujo de inicio de sesión.

​
Ejemplos de código

Solicitud
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}",
  }
}
Respuesta
HTTP/1.1 200 OK
Content-Type: application/json

{
  "authn_params_public_key": {
    "challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}",
    "timeout": {MILLISECONDS},
    "rp": {
      "id": "{THE_CUSTOM_DOMAIN}",
      "name": "{THE_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}"
}

​
Observaciones

  • Una vez completada la solicitud de desafío, la aplicación puede continuar el proceso de registro del usuario mediante las API nativas de Android o iOS.
  • A continuación, debe autenticar al nuevo usuario con la información obtenida a través de las API nativas para completar el flujo.

​
Autenticar a un usuario nuevo

Actualmente no se admite el registro nativo con claves de acceso si en la misma conexión se requiere la verificación mediante OTP por SMS/correo electrónico durante el registro.
POST /oauth/token Usa el para autenticar al usuario con las credenciales proporcionadas, crear su cuenta y devolver los tokens solicitados. El parámetro authn_response se basa en la especificación de la API de autenticación web (WebAuthn). En el flujo nativo de claves de acceso, la información que se envía a este endpoint puede recuperarse mediante las API nativas de su aplicación móvil:

​
Parámetros de la solicitud

ParámetroDescripción
grant_typeObligatorio. Incluya el valor: urn:okta:params:oauth:grant-type:webauthn
client_idObligatorio. El client_id de su aplicación
realmOpcional. El nombre de la conexión que se asociará al usuario. Si no se especifica una conexión, se usa el directorio predeterminado de su inquilino.
scopeOpcional. Use openid para obtener un token de ID o openid profile email para incluir información del perfil del usuario en el token de ID.
audienceOpcional. Identificador de la API para la que desea obtener un token de acceso.
auth_sessionObligatorio. ID de sesión devuelto durante la solicitud inicial del desafío de passkey.
authn_responseObligatorio. Un objeto que contiene los siguientes elementos:
  • id
  • rawId
  • type
  • authenticatorAttachment
  • response
authn_response.idObligatorio. ID de credencial Base64URL.
authn_response.rawIdObligatorio. ID de credencial Base64URL.
authn_response.typeObligatorio. Incluya el valor: public-key
authn_response.authenticatorAttachmentObligatorio. Incluya los valores:
  • platform
  • cross-platform
authn_response.responseObligatorio. Un objeto que contiene los siguientes elementos:
  • clientDataJSON: Contiene una serialización compatible con JSON de los datos del cliente; heredada de AuthenticatorResponse.
  • attestationObject: Contiene datos del autenticador y una declaración de atestación; heredada de AuthenticatorResponse.

​
Ejemplos de código

Solicitud
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}
    },
  }
}
Respuesta
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 inscripción

Registrar una nueva clave de acceso para un usuario implica un proceso de dos pasos mediante la My Account API. Este flujo garantiza que la inscripción de la clave de acceso se inicie de forma segura y luego se verifique. Antes de iniciar el flujo de inscripción, asegúrate de tener un con el scope create:me:authentication_methods para el endpoint /me.

​
Iniciar la inscripción de clave de acceso

POST /me/v1/authentication-methods El primer paso es iniciar el proceso de inscripción. Para ello, haga una solicitud POST al endpoint /me/v1/authentication-methods.

​
Parámetros de la solicitud

ParámetroDescripción
typeObligatorio. Incluya el valor public-key.
connectionOpcional. El nombre de la conexión en la que se creará la clave de acceso.
identityOpcional. La identidad del usuario. Se usa con cuentas vinculadas.

​
Ejemplos de código

Solicitud
{
  "type": "passkey",
  "connection": "CONNECTION_NAME",
  "identity": "IDENTITY_USER_ID"
}
Respuesta
{
  "authn_params_public_key": {
    "challenge": "GENERATED_CHALLENGE_FOR_THIS_SESSION",
    "timeout": MILLISECONDS,
    "rp": {
      "id": "CUSTOM_DOMAIN",
      "name": "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"
}

​
Observaciones

  • La propiedad auth_session del cuerpo de la respuesta es el identificador de la sesión de autenticación actual. Debe pasarse al endpoint /verify.
  • Una vez completada la solicitud de desafío, su aplicación puede continuar con el proceso de inscripción del usuario mediante las API nativas de Android o iOS. Se le pedirá al usuario que cree una clave de acceso con su autenticador (como un escáner de huellas digitales, una llave de seguridad o un teléfono).

​
Verificar la inscripción de la clave de acceso

POST /me/v1/authentication-methods/passkey|new/verify
El ID de la ruta siempre es passkey|new para las nuevas inscripciones.
Una vez que el usuario haya creado correctamente la clave de acceso con su autenticador, la aplicación cliente recibirá una AuthenticatorAttestationResponse de la API de WebAuthn. Esta respuesta debe enviarse al servicio de Auth0 para completar y verificar la inscripción.

​
Parámetros de la solicitud

ParámetrosDescripción
auth_sessionObligatorio. El identificador de sesión recibido en la respuesta de la primera solicitud POST a /me/v1/authentication-methods.
authn_responseObligatorio. El parámetro authn_response se basa en la especificación de la API de autenticación web (WebAuthn). En el flujo nativo de clave de acceso, la información que se envía a este endpoint puede recuperarse mediante las API nativas de tu aplicación móvil.
authn_response.idObligatorio. id de la credencial en Base64URL.
authn_response.rawIdObligatorio. id de la credencial en Base64URL.
authn_response.typeObligatorio. Incluye el valor: public-key.
authn_response.authenticatorAttachmentObligatorio. Incluye los valores: platform, cross-platform.
authn_response.responseObligatorio. Un objeto que contiene los siguientes elementos:
  • clientDataJson: Contiene una serialización compatible con JSON de los datos del cliente; heredada de AuthenticatorResponse.
  • attestationObject: Contiene datos del autenticador y una declaración de atestación; heredada de AuthenticatorResponse.

​
Ejemplos de código

Solicitud
{
  "auth_session": "SESSION_ID",
  "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"
    }
  }
}

​
Observaciones

Una vez completado correctamente este paso, la clave de acceso quedará inscrita para el usuario y podrá utilizarse en autenticaciones posteriores.

​
Flujo de autenticación

​
Solicitar desafío de inicio de sesión

POST /passkey/challenge Inicia el flujo de inicio de sesión con clave de acceso para un usuario existente que guardó una clave de acceso en su cuenta durante el registro inicial. Como respuesta, Auth0 devuelve PublicKeyCredentialRequestOptions, un ID de sesión y un identificador de parte de confianza rpId. Consulta timeout en authn_params_public_key de la respuesta para conocer el tiempo de espera de la sesión. El rpId devuelto en la respuesta es el identificador que el dispositivo nativo (iOS/Android) usa para buscar credenciales guardadas vinculadas a un dominio. Para que una clave de acceso creada en una aplicación web (por ejemplo, example.com) esté disponible en el flujo nativo, el rpId devuelto debe coincidir con el rpId de la web. Para obtener más información sobre cómo personalizar el RP ID de tu inquilino, consulta Configurar la política de claves de acceso. El flujo de inicio de sesión con clave de acceso admite Organizaciones mediante el parámetro organization, según el comportamiento descrito en Flujos de inicio de sesión para Organizaciones. Si tu aplicación está configurada para Usuarios empresariales, debes proporcionar el parámetro organization y un nombre o identificador de Organización válidos. Todos los tokens emitidos se generan en el contexto de la Organización proporcionada. Si habilitaste Membresía automática para tu Organización, el usuario se inscribe automáticamente en la Organización después de autenticarse correctamente.

​
Parámetros de la solicitud

ParámetroDescripción
client_idObligatorio. El client_id de tu aplicación.
realmOpcional. El nombre de la conexión que se asociará con el usuario.

Si no se especifica una conexión, se usará el directorio predeterminado de tu inquilino.

​
Ejemplos de código

Solicitud
POST /passkey/challenge
Content-Type: application/json

{
  "client_id": "{YOUR_CLIENT_ID}",
  "realm": "{OPTIONAL_CONNECTION}"
}
Respuesta
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}"
}

​
Observaciones

  • Una vez completada la solicitud de desafío, tu aplicación puede continuar con el proceso de inicio de sesión mediante las API nativas de Android o iOS.
  • Luego, debes autenticar al usuario existente con la información obtenida a través de las API nativas para completar el flujo.

​
Autenticar a un usuario existente

POST /oauth/token Usa el endpoint de token para autenticar al usuario con las credenciales proporcionadas y devolver los tokens solicitados. El parámetro authn_response se basa en la especificación de la API de autenticación web (WebAuthn). En el flujo nativo de claves de acceso, la información enviada a este endpoint puede recuperarse a través de las API nativas de tu aplicación móvil:

​
Parámetros de la solicitud

ParámetroDescripción
grant_typeObligatorio. Incluya el valor: urn:okta:params:oauth:grant-type:webauthn
client_idObligatorio. El client_id de su aplicación
realmOpcional. El nombre de la conexión que se asociará al usuario. Si no se especifica una conexión, se usa el directorio predeterminado de su inquilino.
scopeOpcional. Use openid para obtener un token de ID o openid profile email para incluir información del perfil del usuario en el token de ID.
audienceOpcional. Identificador de la API para la que desea obtener un token de acceso.
auth_sessionObligatorio. ID de sesión devuelto durante la solicitud inicial del desafío de clave de acceso.
authn_responseObligatorio. Un objeto que contiene los siguientes elementos:
  • id
  • rawId
  • type
  • authenticatorAttachment
  • response
  • clientExtensionResults
authn_response.idObligatorio. ID de credencial en Base64URL.
authn_response.rawIdObligatorio. ID de credencial en Base64URL.
authn_response.typeObligatorio. Incluya el valor: public-key
authn_response.authenticatorAttachmentOpcional. Incluya los valores:
  • platform
  • cross-platform
authn_response.responseObligatorio. Un objeto que contiene los siguientes elementos:
  • authenticatorData: Contiene los datos del autenticador devueltos por el autenticador.
  • clientDataJSON: Contiene una serialización compatible con JSON de los datos del cliente; heredada de AuthenticatorResponse.
  • signature: Firma en Base64URL devuelta por el autenticador.
  • userHandle: Identificador en Base64URL de la cuenta de usuario, devuelto como user.id en el paso de registro.
authn_response.clientExtensionResultsOpcional. Contiene los resultados del procesamiento de las extensiones del cliente solicitadas por la parte de confianza.

​
Ejemplos de código

Solicitud
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}
  },
}
Respuesta
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}
}