Passer au contenu principal
Les clés d’identification sont une solution de rechange résistante à l’hameçonnage aux formes traditionnelles d’authentification (comme le nom d’utilisateur et le mot de passe) qui offre une expérience utilisateur plus simple et plus sécurisée. Elles sont conçues d’après les spécifications FIDO® W3C Web Authentication (WebAuthn) et Client to Authenticator Protocol (CTAP). Auth0 prend actuellement en charge les clés d’identification comme méthode d’authentification pour les connexions de base de données, avec deux méthodes d’implémentation :

Avant de commencer

Configurer un domaine personnaliséLes clés d’identification natives nécessitent l’utilisation d’un . Avant de continuer, assurez-vous d’avoir configuré un domaine personnalisé pour votre locataire. Pour en savoir plus, consultez Domaines personnalisés.Configurer votre politique de clés d’identificationAvant de pouvoir implémenter des clés d’identification natives pour les applications Android ou iOS, vous devez configurer une politique de clés d’identification dans votre locataire Auth0. Pour préparer votre locataire, suivez les étapes de la section Configurer la politique de clés d’identification.Préparer votre applicationToutes les applications utilisant les API de clés d’identification doivent ajouter le type d’autorisation Passkey et configurer le Relying Party ID (RP ID). Selon votre plateforme, vous devrez peut-être aussi configurer des paramètres supplémentaires au moyen de votre ou de la .

​
Comment ça fonctionne

Les API de clés d’identification utilisent une combinaison de l’Authentication API d’Auth0 et d’API d’identifiants propres à la plateforme pour intégrer les flux de défi directement dans votre application. Pour les applications mobiles natives, cela signifie utiliser les API de plateforme iOS ou Android. Pour les applications Web, cela signifie utiliser l’API de navigateur WebAuthn. Cela vous permet de créer une expérience intégrée d’inscription et de connexion qui ne repose pas sur la redirection des utilisateurs vers leur navigateur pour effectuer l’authentification. L’exemple suivant illustre ce qu’un nouvel utilisateur peut vivre pendant le flux d’inscription par clé d’identification :
  1. Un nouvel utilisateur lance votre application mobile et accède à l’écran de connexion. Comme il s’agit d’un nouvel utilisateur, il sélectionne S’inscrire.
  2. À l’écran suivant, l’utilisateur saisit son adresse courriel et sélectionne Créer un compte.
  3. Ensuite, on demande à l’utilisateur s’il souhaite créer une clé d’identification pour votre application. Pour continuer, l’utilisateur sélectionne Continuer.
  4. Pour générer une clé d’identification, l’utilisateur doit s’authentifier localement sur son appareil au moyen de données biométriques ou d’une autre méthode d’authentification, comme la saisie d’un NIP.
  5. Une fois l’authentification locale terminée, une nouvelle clé d’identification est enregistrée sur l’appareil de l’utilisateur et synchronisée avec son fournisseur de clés d’identification, comme le Trousseau iCloud ou le Gestionnaire de mots de passe Google.
  6. Une fois la clé d’identification enregistrée, l’utilisateur poursuit votre processus d’enregistrement de nouvel utilisateur pour finaliser son compte.
Une fois ce processus terminé, l’utilisateur peut s’authentifier avec sa clé d’identification enregistrée la prochaine fois qu’il se connecte à votre application.

​
Configurer les paramètres de l’appareil

Configurer les paramètres de l’appareil dans Auth0 Dashboard :
  1. Accédez à Applications > Applications et sélectionnez votre application.
  2. Au bas de l’onglet Paramètres, sélectionnez Paramètres avancés.
  3. Choisissez l’onglet Paramètres de l’appareil.
  4. Dans la section iOS, saisissez vos ID provenant d’Apple :
    • Team ID
    • App ID
  5. Sélectionnez Enregistrer les modifications.
  • Auth0 héberge automatiquement le fichier apple-app-site-association sur le domaine personnalisé de votre locataire à l’adresse https://YOUR_CUSTOM_DOMAIN/.well-known/apple-app-site-association, en fonction du Team ID et de l’App ID que vous configurez. Vous n’avez pas besoin d’héberger ce fichier vous-même.
  • Dans Xcode, activez le droit Associated Domains et ajoutez une entrée pour votre domaine personnalisé dans un format semblable : webcredentials:YOUR_CUSTOM_DOMAIN.

​
Activer le type d’autorisation Passkey

Pour activer le type d’autorisation Passkey sur toutes les plateformes :
  1. Accédez à Applications > Applications et sélectionnez votre application.
  2. Dans la section Paramètres avancés, sélectionnez l’onglet Types d’autorisation.
  3. Activez le type d’autorisation Clé d’identification, puis sélectionnez Enregistrer les modifications.
Vous pouvez également utiliser la Management API : Appelez le terminal Update a Client et :
  • Mettez à jour grant_types pour inclure urn:okta:params:oauth:grant-type:webauthn.
  • Pour les applications natives, utilisez l’objet mobile pour spécifier les paramètres d’appareil iOS et Android au besoin.

​
Relying party ID (rpId)

Pour que les utilisateurs finaux puissent s’authentifier avec une seule clé d’identification dans différents types d’applications ou dans des types d’applications ayant différents sous-domaines, définissez le relying party ID sur le domaine racine ou parent dans Auth0 Dashboard > Paramètres du locataire.

​
Implémenter les flux de clés d’identification

Vous pouvez définir les flux de clés d’identification suivants pour votre application :
  • Flux d’inscription : permet aux nouveaux utilisateurs de générer et d’enregistrer une clé d’identification pendant le processus d’enregistrement de l’utilisateur.
  • Flux de connexion : permet à un utilisateur existant qui s’est déjà enrôlé aux clés d’identification de s’authentifier avec sa clé d’identification enregistrée pendant le processus de connexion.
  • Flux d’enrôlement : permet aux utilisateurs existants d’ajouter une clé d’identification à leur compte après l’authentification.

​
Flux d’inscription

Un utilisateur amorce le flux d’inscription par clé d’identification lors de sa première tentative de connexion à votre application. Si l’utilisateur fournit un identifiant qui existe déjà, nous recommandons de l’inviter plutôt à effectuer le flux de connexion. Sinon, l’action échouera.
L’enregistrement de clés d’identification natives n’est pas pris en charge pendant l’inscription lorsque la vérification par OTP SMS/courriel est requise sur la même connexion.
  1. Votre application amorce le défi d’inscription en appelant le terminal POST /passkey/register :
POST /passkey/register
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "realm": "OPTIONAL_CONNECTION",
  "user_profile": {
    "email": "user@example.com",
    "name": "John Doe"
  }
},
  • Si vous ne spécifiez pas de realm, le répertoire par défaut de votre locataire est utilisé.
  • Par défaut, email est l’identifiant requis. Si vous avez activé Flexible Identifiers pour votre connexion de base de données, vous pouvez utiliser une combinaison de email, phone_number ou username à la place.
  1. Auth0 renvoie PublicKeyCredentialCreationOptions nécessaire à la création de clés d’identification, ainsi qu’un ID auth_session :
{
  "authn_params_public_key": {
    "challenge": "GENERATED_CHALLENGE_FOR_THIS_SESSION",
    "timeout": 60000,
    "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_EMAIL",
      "displayName": "USER_EMAIL_OR_NAME"
    }
  },
  "auth_session": "SESSION_ID"
}
  1. Votre application crée une clé d’identification sur l’appareil de l’utilisateur à l’aide du PublicKeyCredentialCreationOptions renvoyé. La méthode dépend de votre plateforme :
Utilisez ASAuthorizationPlatformPublicKeyCredentialProvider pour créer l’identifiant avec Face ID, Touch ID ou le NIP de l’appareil. Pour en savoir plus, consultez la documentation d’enregistrement iOS.
  1. Votre application utilise les informations d’identifiant issues du processus d’enregistrement pour appeler le terminal POST /oauth/token afin d’échanger les identifiants contre des jetons :
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": "openid profile email",
  "audience": "YOUR_API_IDENTIFIER",
  "auth_session": "SESSION_ID_FROM_STEP_1",
  "authn_response": {
    "id": "BASE64URL_ID",
    "rawId": "BASE64URL_RAWID",
    "type": "public-key",
    "authenticatorAttachment": "platform",
    "response": {
      "clientDataJSON": "BASE64URL_CLIENT_DATA_JSON",
      "attestationObject": "BASE64URL_ATTESTATION_OBJECT"
    }
  }
}
  1. Auth0 crée un nouveau compte d’utilisateur et renvoie les jetons demandés, comme le montre l’exemple de réponse ci-dessous :
{
  "access_token": "eyJz93a...TJVA95w",
  "refresh_token": "GEz...NaYM",
  "id_token": "eyJ0exA...f1jrv3",
  "token_type": "Bearer",
  "expires_in": 86400
}
Pour en savoir plus sur les appels et les paramètres du flux d’inscription, consultez l’explorateur de l’Authentication API.

​
Flux de connexion

Un utilisateur existant amorce le flux de connexion par clé d’identification lorsqu’il tente de se connecter à votre application. Ce flux s’applique uniquement aux utilisateurs existants qui ont enregistré des clés d’identification dans leur compte lors de l’inscription initiale.
  1. Votre application appelle le terminal POST /passkey/challenge pour amorcer le défi de connexion :
POST /passkey/challenge
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "realm": "OPTIONAL_CONNECTION"
}
Si vous ne spécifiez pas de realm, le répertoire par défaut de votre locataire est utilisé.
  1. Auth0 renvoie PublicKeyCredentialRequestOptions ainsi qu’un auth_session :
{
  "authn_params_public_key": {
    "challenge": "GENERATED_CHALLENGE_FOR_THIS_SESSION",
    "timeout": 60000,
    "rpId": "YOUR_CUSTOM_DOMAIN",
    "userVerification": "preferred"
  },
  "auth_session": "SESSION_ID"
}
  1. Votre application utilise le PublicKeyCredentialRequestOptions renvoyé pour récupérer une clé d’identification à partir de l’appareil de l’utilisateur. La méthode dépend de votre plateforme :
Utilisez ASAuthorizationPlatformPublicKeyCredentialProvider pour récupérer l’identifiant avec Face ID, Touch ID ou le NIP de l’appareil. Pour en savoir plus, consultez la documentation de connexion iOS.
  1. Votre application utilise les informations d’identifiant issues du processus de connexion pour appeler le terminal POST /oauth/token afin d’échanger les identifiants contre des jetons :
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": "openid profile email",
  "audience": "YOUR_API_IDENTIFIER",
  "auth_session": "SESSION_ID_FROM_STEP_1",
  "authn_response": {
    "id": "BASE64URL_ID",
    "rawId": "BASE64URL_RAWID",
    "type": "public-key",
    "authenticatorAttachment": "platform",
    "response": {
      "authenticatorData": "BASE64URL_AUTHENTICATORDATA",
      "clientDataJSON": "BASE64URL_CLIENTDATAJSON",
      "signature": "BASE64URL_SIGNATURE",
      "userHandle": "BASE64URL_USERHANDLE"
    },
    "clientExtensionResults": {}
  }
}
  1. Auth0 authentifie les identifiants et renvoie les jetons demandés :
{
  "access_token": "eyJz93a...TJVA95w",
  "refresh_token": "GEz...NaYM",
  "id_token": "eyJ0exA...f1jrv3",
  "token_type": "Bearer",
  "expires_in": 86400
}
Pour en savoir plus sur les appels et les paramètres du flux de connexion, consultez l’explorateur de l’Authentication API.

​
Flux d’enrôlement

Le flux d’enrôlement permet aux utilisateurs d’ajouter une clé d’identification à leur compte après s’être déjà authentifiés au moyen d’une autre méthode, comme un nom d’utilisateur et un mot de passe. Lorsqu’un utilisateur existant et authentifié souhaite enrôler une nouvelle clé d’identification, utilisez la My Account API.

Avant de commencer

Avant d’amorcer le flux d’enrôlement, assurez-vous de ce qui suit :
  1. Activez la My Account API pour votre locataire.
  2. Récupérez un jeton d’accès ayant la permission create:me:authentication_methods pour le terminal /me.
Pour obtenir les instructions de configuration complètes, lisez My Account API.
  1. Votre application authentifiée appelle le terminal POST /me/v1/authentication-methods avec le jeton d’accès :
POST /me/v1/authentication-methods
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "type": "passkey",
  "connection": "CONNECTION_NAME"
}
  1. Auth0 renvoie un défi et un ID de session :
{
  "authn_params_public_key": {
    "challenge": "GENERATED_CHALLENGE",
    "timeout": 60000,
    "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_IDENTIFIER",
      "displayName": "USER_DISPLAY_NAME"
    }
  },
  "auth_session": "SESSION_ID"
}
  1. Votre application utilise le PublicKeyCredentialCreationOptions renvoyé pour créer une clé d’identification sur l’appareil de l’utilisateur, en suivant les mêmes étapes propres à la plateforme que le flux d’inscription :
Utilisez ASAuthorizationPlatformPublicKeyCredentialProvider pour créer l’identifiant avec Face ID, Touch ID ou le NIP de l’appareil. Pour en savoir plus, consultez la documentation d’enregistrement iOS.
  1. Une fois que l’utilisateur a créé la clé d’identification avec son authentifiant, appelez le terminal POST /me/v1/authentication-methods/passkey|new/verify pour terminer l’enrôlement :
POST /me/v1/authentication-methods/passkey|new/verify
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "auth_session": "SESSION_ID_FROM_STEP_1",
  "authn_response": {
    "id": "BASE64URL_ID",
    "rawId": "BASE64URL_RAWID",
    "type": "public-key",
    "authenticatorAttachment": "platform",
    "response": {
      "clientDataJSON": "BASE64URL_CLIENT_DATA_JSON",
      "attestationObject": "BASE64URL_ATTESTATION_OBJECT"
    }
  }
}
Une fois cette étape terminée avec succès, la clé d’identification est enrôlée pour l’utilisateur et peut être utilisée pour les authentifications futures. Pour en savoir plus sur les appels et les paramètres du flux d’enrôlement, consultez l’explorateur de la My Account API.

​
Relying party ID

Une clé d’identification créée dans l’une de vos applications peut servir à se connecter à vos autres applications, qu’il s’agisse d’applications natives ou Web, lorsque ces applications partagent le même relying party ID (rpId). Cela fonctionne parce que les fournisseurs de clés d’identification (Trousseau iCloud, Gestionnaire de mots de passe Google, 1Password, Dashlane et autres) synchronisent les identifiants entre les appareils de l’utilisateur au sein du même fournisseur.

​
Déplacer les utilisateurs entre les plateformes

Dans la plupart des cas, les utilisateurs n’ont pas besoin de balayer un code QR ni d’utiliser un deuxième appareil. Le flux dépend du fait que la clé d’identification soit déjà disponible ou non sur l’appareil qu’ils utilisent :
  • Même fournisseur, appareil différent (le plus courant) : un utilisateur enrôle une clé d’identification dans votre application iOS; son Trousseau iCloud la synchronise vers son Mac, où il peut se connecter immédiatement à votre application Web. Il en va de même pour les clés d’identification Android synchronisées au moyen du Gestionnaire de mots de passe Google vers Chrome sur un Chromebook ou un PC Windows connecté au même compte Google.
  • Entre écosystèmes ou appareil partagé (moins courant) : si la clé d’identification n’est pas disponible sur l’appareil utilisé (par exemple, une clé d’identification d’iPhone utilisée sur un PC Windows ou un ordinateur public), le navigateur propose un code QR pour s’authentifier au moyen du téléphone de l’utilisateur à l’aide du transport hybride (CTAP 2.2). L’utilisateur conserve sa clé d’identification sur son téléphone; le code QR ne fait que relier les deux appareils pour cette connexion unique.

​
Choisir votre relying party ID

Le rpId détermine quelles origines peuvent utiliser une clé d’identification. Auth0 définit le rpId sur votre domaine personnalisé par défaut. Choisissez le rpId qui correspond le mieux à la portée sur laquelle vous souhaitez que les clés d’identification fonctionnent — et pas plus large. Recommandé : utilisez un domaine parent dont la portée couvre vos surfaces d’authentification et de produit, comme auth.example.com ou accounts.example.com. Une clé d’identification créée avec “rpId=auth.example.com fonctionne sur auth.example.com et sur tout sous-domaine de celui-ci (par exemple, app.auth.example.com, m.auth.example.com). Évitez d’utiliser votre eTLD+1 (apex enregistrable) comme rpId — par exemple, example.com. Définir le rpId à ce niveau permet à chaque sous-domaine de example.com de demander et d’utiliser ces clés d’identification, y compris les sites de marketing, les services hébergés par des tiers ou les domaines exploités par d’autres équipes. Cela étend le périmètre de confiance bien au-delà de votre surface d’authentification. Pour en savoir plus sur le relying party ID, lisez Analyse approfondie du RP ID.

​
Scénarios multidomaines et de marque

Si vous desservez plusieurs domaines de marque (p. ex., login.brand1.com et login.brand2.com), les clés d’identification ne fonctionnent pas automatiquement de l’un à l’autre — chaque domaine possède son propre rpId. Lisez Clés d’identification avec plusieurs domaines personnalisés pour obtenir des conseils sur les modèles d’enrôlement, de communication et de migration propres à chaque domaine.

​
Liste de vérification de la configuration

Une fois que vous avez choisi un rpId, assurez-vous que toutes vos applications le partagent :
  1. Utilisez un seul domaine personnalisé comme rpId pour chaque application native et Web qui doit partager des clés d’identification.
  2. Pour les applications natives, configurez les Paramètres de l’appareil dans Auth0 Dashboard avec vos Team ID/App ID iOS et votre nom de package/empreinte SHA-256 Android. Auth0 héberge automatiquement les fichiers apple-app-site-association et assetlinks.json sur votre domaine personnalisé.
  3. Pour les applications Web, servez votre origine Web à partir du rpId ou d’un de ses sous-domaines, et ajoutez-la aux Origines Web autorisées pour le CORS.

​
En savoir plus

Vous pouvez consulter les ressources suivantes lors de l’implémentation de l’authentification par clé d’identification pour votre application :