API Clés d’identification natives

Spécifications d’Auth0 Authentication API pour les clés d’identification natives

Clés d’identification natives est actuellement proposé en accès anticipé limité. Pour en savoir plus sur les étapes de diffusion d’Auth0, consultez Étapes de la diffusion du produit.

Par rapport aux formes traditionnelles d’authentification (telles que le nom d’utilisateur et le mot de passe), les clés d’identification offrent une solution de rechange efficace contre l’hameçonnage et permettent aux utilisateurs de profiter d’une expérience plus facile et plus sûre. Pour obtenir des détails complets sur la mise en œuvre, consultez Clés d’identification natives pour les applications mobiles.

Les clés d’identification natives utilisent une combinaison d’API Auth0 et iOS ou Android natives pour intégrer les flux de défi-réponse directement dans votre application mobile. Les points de terminaison énumérés ci-dessous constituent un sous-ensemble de Authentication API et sont actuellement accessibles en accès anticipé limité. Pour en savoir plus sur l’utilisation de cette API, consultez la page Introduction à Authentication API.

Flux d’inscription

Demander un défi-réponse d’inscription

POST /passkey/register

Lance le flux d’inscription de la clé d’identification pour un nouvel utilisateur. En réponse, Auth0 renvoie PublicKeyCredentialCreationOptions et un ID de session.

Paramètres de la demande

Paramètres	Description
client_id	Obligatoire. client_id de votre application.
realm	Facultatif. Le nom de la connexion à associer avec cet utilisateur. Le répertoire par défaut de votre locataire est utilisé si aucune connexion n’est précisée.
user_profile	_Obligatoire. Un objet contenant des informations d’identification pour l’utilisateur. Par défaut, cela inclut un email valide et un name d’affichage facultatif. Si vous avez activé les identifiants flexibles pour votre connexion par base de données, vous pouvez utiliser une combinaison de email, phone_number, ou username comme identificateurs. Ces options peuvent être obligatoires ou facultatives et doivent correspondre à votre configuration d’identificateur flexible. Si l’identifiant transmis (tel que email) existe déjà dans le directory, l’utilisateur doit être invité à effectuer le flux de connexion.

Exemples de code

Demande

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

{
  "client_id": "<CLIENT_ID>",
  "realm": "<OPTIONAL_CONNECTION>",
  "user_profile": {
	  "email": "<VALID_EMAIL_ADDRESS>",
	  "name": "<OPTIONAL_USER_DISPLAY_NAME>",
  }
}

Réponse

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>"
}

Remarques

• Une fois la demande de défi-réponse terminée, votre application peut poursuivre le processus d’inscription des utilisateurs à l’aide des API natives Android ou iOS.
• Vous devez ensuite authentifier le nouvel utilisateur à l’aide des informations récupérées par les API natives pour terminer le flux.

Authentifier un nouvel utilisateur

L’enregistrement de clé d’identification native n’est actuellement pas pris en charge lorsque la vérification SMS/OTP par courriel est requise sur la même connexion lors d’une inscription.

POST /oauth/token

Utilise le point de terminaison du jeton pour authentifier l’utilisateur avec les informations d’identification fournies afin de créer son compte et de renvoyer les jetons demandés.

Le paramètre authn_response est basé sur la Spécification de Web Authentication API. Dans le flux de clés d’identification natives, les informations transmises à ce point de terminaison sont récupérables par l’intermédiaire des API natives de votre application mobile :

• Documentation d’inscription Android
• Documentation d’inscription iOS

Paramètres de la demande

Paramètres	Description
grant_type	Obligatoire. Inclure la valeur : urn:okta:params:oauth:grant-type:webauthn
scope	Facultatif. Utiliser openid pour obtenir un jeton d’ID ou openid profile email pour inclure des informations de profil utilisateur dans le jeton d’ID.
audience	Facultatif. Identifiant API de l’API pour laquelle vous souhaitez obtenir un jeton d’accès.
auth_session	Obligatoire. Identifiant de session retourné lors de la demande initiale de défi de clé d’identification.
authn_response	Obligatoire. Un objet contenant les éléments suivants : id rawId type authenticatorAttachment response
authn_response.id	Obligatoire. ID d’identification Base64URL.
authn_response.rawId	Obligatoire. ID d’identification Base64URL.
authn_response.type	Obligatoire. Inclure la valeur : public-key
authn_response.authenticatorAttachment	Obligatoire. Inclure les valeurs : platform cross-platform
authn_response.response	Obligatoire. Un objet contenant les éléments suivants : clientDataJSON: Contient la sérialisation compatible JSON des données client; héritée de AuthenticatorResponse. attestationObject: Contient des données d’authentification et une déclaration d’attestation; héritée de AuthenticatorResponse.

Exemples de code

Demande

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",
  "client_id": "<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>
    }  
}

Réponse

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>
}

Flux de connexion

Demander le défi-réponse de connexion

POST /passkey/challenge

Lance le processus de connexion à la clé d’identification pour un utilisateur existant qui a enregistré une clé d’identification sur son compte lors de son inscription initiale.

En réponse, Auth0 renvoie PublicKeyCredentialRequestOptions et un identificateur de session.

Paramètres de la demande

Paramètres	Description
client_id	Obligatoire. client_id de votre application.
realm	Facultatif. Le nom de la connexion à associer avec l’utilisateur. Le répertoire par défaut de votre locataire est utilisé si aucune connexion n’est précisée.

Exemples de code

Demande

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

{
  "client_id": "<CLIENT_ID>",
  "realm": "<OPTIONAL_CONNECTION>"
}

Réponse

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>"
}

Remarques

• Une fois la demande de défi-réponse terminée, votre application peut poursuivre le processus de connexion à l’aide des API natives Android ou iOS.
• Vous devrez ensuite authentifier l’utilisateur existant à l’aide des informations récupérées via les API natives pour terminer le flux.

Authentifier l’utilisateur existant

POST /oauth/token

Utilise le point de terminaison du jeton pour authentifier l’utilisateur avec les identifiants fournis et renvoyer les jetons demandés.

Le paramètre authn_response est basé sur la Spécification de Web Authentication API. Dans le flux de clés d’identification natives, les informations transmises à ce point de terminaison sont récupérables par l’intermédiaire des API natives de votre application mobile :

• Documentation de connexion Android
• Documentation de connexion iOS

Paramètres de la demande

Paramètres	Description
grant_type	Obligatoire. Inclure la valeur : urn:okta:params:oauth:grant-type:webauthn
scope	Facultatif. Utiliser openid pour obtenir un jeton d’ID ou openid profile email pour inclure des informations de profil utilisateur dans le jeton d’ID.
audience	Facultatif. Identifiant API de l’API pour laquelle vous souhaitez obtenir un jeton d’accès.
auth_session	Obligatoire. Identifiant de session retourné lors de la demande initiale de défi de clé d’identification.
authn_response	Obligatoire. Un objet contenant les éléments suivants : id rawId type authenticatorAttachment response clientExtensionResults
authn_response.id	Obligatoire. ID d’identification Base64URL.
authn_response.rawId	Obligatoire. ID d’identification Base64URL.
authn_response.type	Obligatoire. Inclure la valeur : public-key
authn_response.authenticatorAttachment	Obligatoire. Inclure les valeurs : platform cross-platform
authn_response.response	Obligatoire. Un objet contenant les éléments suivants : authenticatorData: Contient les données d’authentification renvoyées par l’authentificateur. clientDataJSON: Contient la sérialisation compatible JSON des données client; héritée de AuthenticatorResponse. signature: Signature Base64URL renvoyée par l’authentificateur. userHandle: Identifiant Base64URL du compte utilisateur.
authn_response.clientExtensionResults	Facultatif. Contient les résultats du traitement des extensions client demandées par la partie utilisatrice.

Exemples de code

Demande

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",
  "client_id": "<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>
}

Réponse

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>
}