Passer au contenu principal
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ètreDescription
client_idObligatoire. Le client_id de votre application.
realmFacultatif. 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_profileObligatoire. 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 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 :

​
Paramètres de la requête

ParamètreDescription
grant_typeObligatoire. Incluez la valeur : urn:okta:params:oauth:grant-type:webauthn
client_idObligatoire. Le client_id de votre application
realmFacultatif. 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é.
scopeFacultatif. 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é.
audienceFacultatif. Identifiant de l’API pour laquelle vous souhaitez obtenir un jeton d’accès.
auth_sessionObligatoire. Identifiant de session renvoyé lors de la requête initiale de défi de clé d’accès.
authn_responseObligatoire. Un objet contenant les éléments suivants :
  • id
  • rawId
  • type
  • authenticatorAttachment
  • response
authn_response.idObligatoire. ID des informations d’identification en Base64URL.
authn_response.rawIdObligatoire. ID des informations d’identification en Base64URL.
authn_response.typeObligatoire. Incluez la valeur : public-key
authn_response.authenticatorAttachmentObligatoire. Incluez les valeurs suivantes :
  • platform
  • cross-platform
authn_response.responseObligatoire. 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 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ètreDescription
typeObligatoire. Incluez la valeur : public-key.
connectionFacultatif. Le nom de la connexion dans laquelle créer la clé d’accès.
identityFacultatif. 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.

​
Paramètres de la requête

ParamètresDescription
auth_sessionObligatoire. L’identifiant de session reçu dans la réponse à la première requête POST envoyée à /me/v1/authentication-methods.
authn_responseObligatoire. 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.idObligatoire. Identifiant d’authentification Base64URL.
authn_response.rawIdObligatoire. Identifiant d’authentification Base64URL.
authn_response.typeObligatoire. Incluez la valeur : public-key.
authn_response.authenticatorAttachmentObligatoire. Incluez les valeurs : platform, cross-platform.
authn_response.responseObligatoire. 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ètreDescription
client_idObligatoire. Le client_id de votre application.
realmFacultatif. 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 :

​
Paramètres de la requête

ParamètreDescription
grant_typeObligatoire. Incluez la valeur : urn:okta:params:oauth:grant-type:webauthn
client_idObligatoire. Le client_id de votre application
realmFacultatif. 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é.
scopeFacultatif. Utilisez openid pour obtenir un jeton d’identité, ou openid profile email pour inclure les renseignements du profil utilisateur dans le jeton d’identité.
audienceFacultatif. Identifiant de l’API pour laquelle vous voulez obtenir un jeton d’accès.
auth_sessionObligatoire. ID de session renvoyé lors de la requête initiale de défi de clé d’accès.
authn_responseObligatoire. Un objet contenant les éléments suivants :
  • id
  • rawId
  • type
  • authenticatorAttachment
  • response
  • clientExtensionResults
authn_response.idObligatoire. Identifiant d’information d’identification au format Base64URL.
authn_response.rawIdObligatoire. Identifiant d’information d’identification au format Base64URL.
authn_response.typeObligatoire. Incluez la valeur : public-key
authn_response.authenticatorAttachmentFacultatif. Incluez les valeurs suivantes :
  • platform
  • cross-platform
authn_response.responseObligatoire. 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.clientExtensionResultsFacultatif. 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}
}