API des clés d’accès natives

Spécifications de l’API d’authentification Auth0 pour les clés d’accès natives

Les clés d’accès constituent une solution de rechange aux méthodes d’authentification traditionnelles (comme le nom d’utilisateur et le mot de passe) qui résiste à l’hameçonnage et offre une expérience utilisateur plus simple et plus sécuritaire. Pour obtenir tous les détails de mise en œuvre, consultez Native Passkeys for Mobile Applications.

Les clés d’accès natives utilisent une combinaison d’Auth0 et d’API natives iOS ou Android pour intégrer directement les flux de vérification à votre application mobile. Les points de terminaison ci-dessous constituent un sous-ensemble de l’API d’authentification d’Auth0. Pour en savoir plus sur l’utilisation de cette API, consultez l’Introduction à l’API d’authentification.

Les clés d’accès comportent trois flux connexes :

• Inscription : Crée un nouveau compte utilisateur avec une clé d’accès comme méthode d’authentification principale.
• Inscription : Ajoute une clé d’accès comme méthode d’authentification au compte d’un utilisateur existant.
• Connexion : Demande à un utilisateur existant de s’authentifier à l’aide d’une clé d’accès associée à son compte.

​

Flux d’inscription

​

Demander le défi d’inscription

POST /passkey/register

Lance le flux d’inscription par clé d’accès pour un nouvel utilisateur.

En réponse, Auth0 renvoie PublicKeyCredentialCreationOptions et un identifiant de session. Consultez timeout dans authn_params_public_key de la réponse pour connaître le délai d’expiration de la session.

Le flux d’inscription par clé d’accès prend en charge les organisations au moyen du paramètre organization, conformément au comportement décrit dans Flux de connexion pour les organisations. Si votre application est configurée pour les utilisateurs d’entreprise, vous devez fournir le paramètre organization ainsi qu’un nom d’Organisation ou un identifiant d’Organisation valide. Après que l’utilisateur a enregistré une clé d’accès, Auth0 l’inscrit dans l’Organisation fournie.

​

Paramètres de requête

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

​

Exemples de code

Requête

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

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 requête de défi terminée, votre application peut poursuivre le processus d’inscription de l’utilisateur à 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 finaliser le flux.

​

Authentifier un nouvel utilisateur

L’inscription avec une clé d’accès native n’est actuellement pas prise en charge lorsqu’une vérification OTP par SMS/courriel est requise sur la même connexion au moment de l’inscription.

POST /oauth/token

Utilise le point de terminaison de jeton pour authentifier l’utilisateur à l’aide des informations d’identification fournies, créer son compte et renvoyer les jetons demandés.

Le paramètre authn_response est basé sur la spécification de l’API WebAuthn. Dans le flux de clé d’accès native, les informations transmises à ce point de terminaison peuvent être récupérées à l’aide des API natives de votre application mobile :

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

​

Paramètres de la requête

Paramètre	Description
grant_type	Obligatoire. Incluez la valeur : urn:okta:params:oauth:grant-type:webauthn
client_id	Obligatoire. Le client_id de votre application
realm	Facultatif. Le nom de la connexion à associer à l’utilisateur. Si aucune connexion n’est précisée, le répertoire par défaut de votre locataire est utilisé.
scope	Facultatif. Utilisez openid pour obtenir un jeton d’identité, ou openid profile email pour inclure les informations de profil de l’utilisateur dans le jeton d’identité.
audience	Facultatif. Identifiant de l’API pour laquelle vous souhaitez obtenir un jeton d’accès.
auth_session	Obligatoire. Identifiant de session renvoyé lors de la requête initiale de défi de clé d’accès.
authn_response	Obligatoire. Un objet contenant les éléments suivants : id rawId type authenticatorAttachment response
authn_response.id	Obligatoire. ID des informations d’identification en Base64URL.
authn_response.rawId	Obligatoire. ID des informations d’identification en Base64URL.
authn_response.type	Obligatoire. Incluez la valeur : public-key
authn_response.authenticatorAttachment	Obligatoire. Incluez les valeurs suivantes : platform cross-platform
authn_response.response	Obligatoire. Un objet contenant les éléments suivants : clientDataJSON : Contient une représentation sérialisée compatible JSON des données client; hérité de AuthenticatorResponse. attestationObject : Contient les données de l’authentificateur et une déclaration d’attestation; hérité de AuthenticatorResponse.

​

Exemples de code

Requête

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

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

​

Processus d’inscription

L’inscription d’une nouvelle clé d’accès pour un utilisateur se fait en deux étapes au moyen de l’API My Account. Ce processus garantit que l’inscription de la clé d’accès est lancée de manière sécurisée, puis vérifiée.

Avant de lancer le processus d’inscription, assurez-vous d’avoir un jeton d’accès avec le scope create:me:authentication_methods pour le point de terminaison /me.

​

Initier l’inscription d’une clé d’accès

POST /me/v1/authentication-methods

La première étape consiste à initier le processus d’inscription. Pour ce faire, envoyez une requête POST au point de terminaison /me/v1/authentication-methods.

​

Paramètres de la requête

Paramètre	Description
type	Obligatoire. Incluez la valeur : public-key.
connection	Facultatif. Le nom de la connexion dans laquelle créer la clé d’accès.
identity	Facultatif. L’identité de l’utilisateur. Utilisée avec les comptes liés.

​

Exemples de code

Requête

{
  "type": "passkey",
  "connection": "CONNECTION_NAME",
  "identity": "IDENTITY_USER_ID"
}

Réponse

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

​

Remarques

• La propriété auth_session dans le corps de la réponse est l’identifiant de la session d’authentification en cours. Elle doit être transmise au point de terminaison /verify.
• Une fois la requête de défi terminée, votre application peut continuer le processus d’inscription de l’utilisateur à l’aide des API natives Android ou iOS. L’utilisateur sera alors invité à créer une clé d’accès avec son authentificateur (par exemple, un lecteur d’empreintes digitales, une clé de sécurité ou un téléphone).

​

Vérifier l’inscription de la clé d’accès

POST /me/v1/authentication-methods/passkey|new/verify

L’ID dans le chemin est toujours passkey|new pour les nouvelles inscriptions.

Une fois que l’utilisateur a créé la clé d’accès avec succès à l’aide de son authentificateur, l’application recevra un AuthenticatorAttestationResponse de l’API WebAuthn. Cette réponse doit être renvoyée au service Auth0 pour finaliser et vérifier l’inscription.

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

​

Paramètres de la requête

Paramètres	Description
auth_session	Obligatoire. L’identifiant de session reçu dans la réponse à la première requête POST envoyée à /me/v1/authentication-methods.
authn_response	Obligatoire. Le paramètre authn_response repose sur la spécification de l’API WebAuthn. Dans le flux natif de clé d’accès, les renseignements transmis à ce point de terminaison peuvent être récupérés au moyen des API natives de votre application mobile.
authn_response.id	Obligatoire. Identifiant d’authentification Base64URL.
authn_response.rawId	Obligatoire. Identifiant d’authentification Base64URL.
authn_response.type	Obligatoire. Incluez la valeur : public-key.
authn_response.authenticatorAttachment	Obligatoire. Incluez les valeurs : platform, cross-platform.
authn_response.response	Obligatoire. Objet contenant les éléments suivants : clientDataJson : contient une sérialisation compatible JSON des données client; hérité de AuthenticatorResponse. attestationObject : contient les données de l’authentificateur et une déclaration d’attestation; hérité de AuthenticatorResponse.

​

Exemples de code

Requête

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

​

Remarques

Une fois cette étape terminée avec succès, la clé d’accès est inscrite pour l’utilisateur et peut servir aux authentifications futures.

​

Processus de connexion

​

Demander un défi de connexion

POST /passkey/challenge

Lance le flux de connexion par clé d’accès pour un utilisateur existant qui a enregistré une clé d’accès dans son compte lors de son inscription initiale.

En réponse, Auth0 renvoie PublicKeyCredentialRequestOptions, un ID de session et un identifiant de partie de confiance rpId. Vérifiez la valeur de timeout sous authn_params_public_key dans la réponse pour connaître le délai d’expiration de la session. Le rpId renvoyé dans la réponse est l’identifiant que l’appareil natif (iOS/Android) utilise pour retrouver les identifiants enregistrés associés à un domaine. Pour qu’une clé d’accès créée dans une application web (par exemple, example.com) soit disponible dans le flux natif, le rpId renvoyé doit correspondre à celui de l’application web. Pour savoir comment personnaliser l’identifiant RP de votre locataire, consultez Configurer la stratégie de clé d’accès.

Le flux de connexion par clé d’accès prend en charge les organisations au moyen du paramètre organization, conformément au comportement décrit dans Flux de connexion pour les organisations. Si votre application est configurée pour les utilisateurs d’entreprise, vous devez fournir le paramètre organization ainsi qu’une valeur valide de nom ou d’identifiant d’Organisation.

Tous les jetons émis sont dans le contexte de l’Organisation fournie. Si vous avez activé l’adhésion automatique pour votre Organisation, l’utilisateur est automatiquement inscrit dans l’Organisation après une authentification réussie.

​

Paramètres de la requête

Paramètre	Description
client_id	Obligatoire. Le client_id de votre application.
realm	Facultatif. Le nom de la connexion à associer à l’utilisateur. Si aucune connexion n’est spécifiée, l’annuaire par défaut de votre locataire est utilisé.

​

Exemples de code

Requête

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

{
  "client_id": "{YOUR_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 d’authentification terminée, votre application peut poursuivre le processus de connexion à l’aide des API natives Android ou iOS.
• Vous devez ensuite authentifier l’utilisateur existant à l’aide des informations récupérées par les API natives pour finaliser le flux.

​

Authentifier un utilisateur existant

POST /oauth/token

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

Le paramètre authn_response est basé sur la spécification de l’API WebAuthn. Dans le flux natif avec clé d’accès, les informations transmises à ce point de terminaison peuvent être récupérées au moyen des API natives de votre application mobile :

• documentation de connexion sur Android
• documentation de connexion sur iOS

​

Paramètres de la requête

Paramètre	Description
grant_type	Obligatoire. Incluez la valeur : urn:okta:params:oauth:grant-type:webauthn
client_id	Obligatoire. Le client_id de votre application
realm	Facultatif. Le nom de la connexion à associer à l’utilisateur. Si aucune connexion n’est indiquée, le répertoire par défaut de votre locataire est utilisé.
scope	Facultatif. Utilisez openid pour obtenir un jeton d’identité, ou openid profile email pour inclure les renseignements du profil utilisateur dans le jeton d’identité.
audience	Facultatif. Identifiant de l’API pour laquelle vous voulez obtenir un jeton d’accès.
auth_session	Obligatoire. ID de session renvoyé lors de la requête initiale de défi de clé d’accès.
authn_response	Obligatoire. Un objet contenant les éléments suivants : id rawId type authenticatorAttachment response clientExtensionResults
authn_response.id	Obligatoire. Identifiant d’information d’identification au format Base64URL.
authn_response.rawId	Obligatoire. Identifiant d’information d’identification au format Base64URL.
authn_response.type	Obligatoire. Incluez la valeur : public-key
authn_response.authenticatorAttachment	Facultatif. Incluez les valeurs suivantes : platform cross-platform
authn_response.response	Obligatoire. Un objet contenant les éléments suivants : authenticatorData : Contient les données de l’authentificateur renvoyées par l’authentificateur. clientDataJSON : Contient une sérialisation des données client compatible avec JSON; héritée de AuthenticatorResponse. signature : Signature Base64URL renvoyée par l’authentificateur. userHandle : Identifiant Base64URL du compte utilisateur, renvoyé sous la forme user.id à l’étape d’inscription.
authn_response.clientExtensionResults	Facultatif. Contient les résultats du traitement des extensions client demandées par la partie de confiance.

​

Exemples de code

Requête

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

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