API de clés d’accès pour les applications intégrées

Utilisez les API de clés d’accès Auth0 pour créer des flux intégrés d’inscription, de connexion et d’enrôlement par clé d’accès pour les applications iOS, Android et Web.

Les clés d’accès constituent une solution de rechange résistante à l’hameçonnage aux méthodes d’authentification traditionnelles (comme le nom d’utilisateur et le mot de passe) et offrent une expérience utilisateur plus simple et plus sécuritaire. Elles s’appuient sur les spécifications FIDO® W3C Web Authentication (WebAuthn) et Client to Authenticator Protocol (CTAP).

Auth0 prend actuellement en charge les clés d’accès comme méthode d’authentification pour les connexions de base de données, selon deux méthodes de mise en œuvre :

• Clés d’accès Universal Login pour les applications Web.
• API de clés d’accès pour les applications mobiles natives (iOS, Android) et les applications Web.
• Connexion intégrée pour les applications Web et natives

Avant de commencer

Configurez un domaine personnalisé

Les clés d’accès natives exigent l’utilisation d’un domaine personnalisé. Avant de continuer, assurez-vous d’avoir configuré un domaine personnalisé pour votre tenant. Pour en savoir plus, consultez Custom Domains.

Configurez votre politique de clés d’accès

Avant de pouvoir mettre en œuvre les clés d’accès natives pour les applications Android ou iOS, vous devez configurer une politique de clés d’accès dans votre tenant Auth0. Pour préparer votre tenant, suivez les étapes de Configure Passkey Policy.

Préparez votre application

Toutes les applications qui utilisent les API de clés d’accès doivent ajouter l’autorisation Passkey et configurer le Relying Party ID (RP ID). Selon votre plateforme, vous devrez peut-être également configurer des paramètres supplémentaires dans votre Auth0 Dashboard ou au moyen de la Management API.

​

Fonctionnement

Les API de clés d’accès combinent l’API d’authentification Auth0 et des API d’identifiants propres à chaque plateforme pour intégrer directement les flux de challenge à votre application. Pour les applications mobiles Native, cela implique d’utiliser les API iOS ou Android. Pour les Web Applications, cela implique d’utiliser l’API WebAuthn du navigateur. Vous pouvez ainsi créer une expérience intégrée d’inscription et de connexion qui ne nécessite pas de rediriger les utilisateurs vers leur navigateur pour effectuer l’authentification.

L’exemple suivant illustre l’expérience d’un nouvel utilisateur durant le flux d’inscription par clé d’accès :

1. Un nouvel utilisateur lance votre application mobile et accède à l’écran de connexion. Comme il est 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. L’utilisateur doit ensuite indiquer s’il souhaite créer une clé d’accès pour votre application. Pour continuer, il sélectionne Continuer.
4. Pour générer une clé d’accès, l’utilisateur doit s’authentifier localement sur son appareil à l’aide 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’accès est enregistrée sur l’appareil de l’utilisateur et synchronisée avec son fournisseur de clés d’accès, comme iCloud Keychain ou Google Password Manager.
6. Une fois la clé d’accès enregistrée, l’utilisateur poursuit le processus d’enregistrement d’un nouvel utilisateur afin de finaliser son compte.

Une fois ce processus terminé, l’utilisateur peut s’authentifier avec sa clé d’accès enregistrée lors de sa prochaine connexion à votre application.

​

Configurer les paramètres de l’appareil

iOS

Configurer les paramètres de l’appareil dans le tableau de bord Auth0 :

1. Accédez à Applications > Applications et sélectionnez votre application.
2. Au bas de l’onglet Settings, sélectionnez Advanced Settings.
3. Sélectionnez l’onglet Device Settings.
4. Dans la section iOS, saisissez vos identifiants Apple :
   • Team ID
   • App ID
5. Sélectionnez Save Changes.

• Auth0 héberge automatiquement le fichier apple-app-site-association sur le domaine personnalisé de votre tenant, à l’adresse https://YOUR_CUSTOM_DOMAIN/.well-known/apple-app-site-association, selon le Team ID et l’App ID que vous configurez. Vous n’avez pas besoin d’héberger ce fichier vous-même.

• Dans Xcode, activez l’autorisation Associated Domains et ajoutez une entrée pour votre domaine personnalisé dans un format semblable : webcredentials:YOUR_CUSTOM_DOMAIN.

Android

Configurer les paramètres de l’appareil dans le tableau de bord Auth0 :

1. Accédez à Applications > Applications et sélectionnez votre application.
2. Au bas de l’onglet Settings, sélectionnez Advanced Settings, puis l’onglet Device Settings.
3. Dans la section Android, saisissez :
   • App Package Name
   • Key Hashes. Saisissez le certificat de signature SHA-256 de votre application.
4. Sélectionnez Save Changes.

Auth0 héberge automatiquement le fichier assetlinks.json sur le domaine personnalisé de votre tenant, à l’adresse https://YOUR_CUSTOM_DOMAIN/.well-known/assetlinks.json, selon le nom du package et l’empreinte SHA-256 que vous configurez. Vous n’avez pas besoin d’héberger ce fichier vous-même.

Web

Configurer les origines Web autorisées :

1. Accédez à Applications > Applications et sélectionnez votre application.
2. Dans l’onglet Settings, repérez Application URIs.
3. Dans Allowed Web Origins, ajoutez l’origine de votre application Web (p. ex., https://YOUR_CUSTOM_DOMAIN).
4. Sélectionnez Save Changes.

• Les applications Web utilisent l’API WebAuthn du navigateur, qui gère automatiquement la validation de l’origine. Vous n’avez pas besoin de fichiers d’association d’applications pour les Web Applications.
• Assurez-vous que l’ID de la Relying Party, rpId, correspond à l’origine de votre application Web afin que le flux WebAuthn fonctionne correctement.

​

Activez 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 Advanced Settings, sélectionnez l’onglet Grant Types.
3. Activez le type d’autorisation Passkey, puis sélectionnez Save Changes.

Vous pouvez également utiliser la Management API : Appelez le endpoint Update a Client, puis :

• Mettez à jour grant_types pour inclure urn:okta:params:oauth:grant-type:webauthn.
• Pour les applications Native, utilisez l’objet mobile afin de spécifier les paramètres des appareils iOS et Android, au besoin.

​

ID de la partie utilisatrice (rpId)

Pour permettre aux utilisateurs finaux de s’authentifier avec une même clé d’accès dans différents types d’applications ou dans des applications ayant des sous-domaines différents, définissez l’ID de la partie utilisatrice sur le domaine racine ou parent dans Auth0 Dashboard > Tenant Settings.

​

Implémenter des flux de clés d’accès

Vous pouvez définir les flux de clés d’accès suivants pour votre application :

• Flux d’inscription : permet aux nouveaux utilisateurs de générer et d’enregistrer une clé d’accès lors de leur inscription.
• Flux de connexion : permet aux utilisateurs existants déjà enrôlés pour les clés d’accès de s’authentifier à l’aide de leur clé d’accès enregistrée lors de la connexion.
• Flux d’enrôlement : permet aux utilisateurs existants d’ajouter une clé d’accès à leur compte après l’authentification.

​

Flux d’inscription

Lors de sa première tentative de connexion à votre application, l’utilisateur lance le flux d’inscription par passkey. Si l’utilisateur fournit un identifiant qui existe déjà, nous recommandons plutôt de l’inviter à suivre le flux de connexion. Sinon, l’action échouera.

L’enregistrement de passkeys natives n’est pas pris en charge lors de l’inscription si une vérification par SMS ou OTP par courriel est requise pour la même connection.

1. Votre application lance le défi d’inscription en envoyant une requête à l’endpoint POST /passkey/register :

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

{
  "client_id": "YOUR_CLIENT_ID",
  "realm": "OPTIONAL_CONNECTION",
  "user_profile": {
    "email": "[e-mail]",
    "name": "John Doe"
  }
},

• Si vous ne précisez pas de realm, l’annuaire de votre tenant est utilisé.
• Par défaut, email est l’identifiant requis. Si vous avez activé Flexible Identifiers pour votre connexion à la base de données, vous pouvez plutôt utiliser une combinaison de email, phone_number et username.

2. Auth0 renvoie les PublicKeyCredentialCreationOptions nécessaires à la création de passkeys, 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"
}

3. Votre application crée une passkey sur l’appareil de l’utilisateur à l’aide des PublicKeyCredentialCreationOptions renvoyées. La méthode dépend de votre plateforme :

iOS

Utilisez ASAuthorizationPlatformPublicKeyCredentialProvider pour créer les informations d’identification avec Face ID, Touch ID ou le NIP de l’appareil. Pour en savoir plus, consultez la documentation sur l’enregistrement dans iOS.

Android

Utilisez CredentialManager pour créer les informations d’identification à l’aide de l’authentification biométrique ou du NIP de l’appareil. Pour en savoir plus, consultez la documentation sur l’enregistrement dans Android.

Web

Utilisez navigator.credentials.create() avec les PublicKeyCredentialCreationOptions renvoyées par Auth0. Pour en savoir plus, consultez l’API Web Authentication de MDN.

4. Votre application utilise les informations d’identification issues du processus d’enregistrement pour appeler le point de terminaison POST /oauth/token afin d’échanger les informations d’identification 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"
    }
  }
}

5. Auth0 crée un compte d’utilisateur et renvoie les jetons demandés, comme dans l’exemple de réponse suivant :

{
  "access_token": "eyJz93a...TJVA95w",
  "refresh_token": "GEz...NaYM",
  "id_token": "eyJ0exA...f1jrv3",
  "token_type": "Bearer",
  "expires_in": 86400
}

Pour en savoir plus sur les requêtes et les paramètres du flux d’inscription, consultez l’explorateur de l’API d’authentification.

​

Flux de connexion

Un utilisateur existant lance le flux de connexion par passkey lorsqu’il tente de se connecter à votre application. Ce flux s’applique uniquement aux utilisateurs existants qui ont enregistré des passkeys dans leur compte lors de leur inscription initiale.

1. Votre application envoie une requête au endpoint POST /passkey/challenge pour lancer le défi de connexion :

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

{
  "client_id": "YOUR_CLIENT_ID",
  "realm": "OPTIONAL_CONNECTION"
}

Si vous ne précisez pas de realm, l’annuaire par défaut de votre tenant est utilisé.

2. Auth0 renvoie PublicKeyCredentialRequestOptions avec une auth_session :

{
  "authn_params_public_key": {
    "challenge": "GENERATED_CHALLENGE_FOR_THIS_SESSION",
    "timeout": 60000,
    "rpId": "YOUR_CUSTOM_DOMAIN",
    "userVerification": "preferred"
  },
  "auth_session": "SESSION_ID"
}

3. Votre application utilise les PublicKeyCredentialRequestOptions renvoyées pour récupérer une passkey sur l’appareil de l’utilisateur’. La méthode varie selon votre plateforme :

iOS

Utilisez ASAuthorizationPlatformPublicKeyCredentialProvider pour récupérer les informations d’identification à l’aide de Face ID, de Touch ID ou du NIP de l’appareil. Pour en savoir plus, consultez la documentation sur la connexion iOS.

Android

Utilisez CredentialManager pour récupérer les informations d’identification à l’aide de l’authentification biométrique ou du NIP de l’appareil. Pour en savoir plus, consultez la documentation sur la connexion Android.

Web

Utilisez navigator.credentials.get() avec les PublicKeyCredentialRequestOptions renvoyées par Auth0. Pour en savoir plus, consultez l’API Web Authentication de MDN.

4. Votre application utilise les informations d’identification du processus de connexion pour appeler le endpoint POST /oauth/token et échanger les informations d’identification 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": {}
  }
}

5. 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 requêtes et les paramètres du flux de connexion, consultez l’explorateur de l’API d’authentification.

​

Enrôlement

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

Avant de commencer

Avant de commencer l’enrôlement, assurez-vous de suivre ces étapes :

1. Activez la My Account API pour votre tenant.
2. Obtenez un jeton d’accès doté de la portée create:me:authentication_methods pour le point de terminaison /me.

Pour obtenir les instructions de configuration complètes, consultez My Account API.

1. Votre application authentifiée envoie une requête au point de terminaison 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"
}

2. Auth0 renvoie un challenge 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"
}

3. Votre application utilise les PublicKeyCredentialCreationOptions renvoyées pour créer une clé d’accès sur l’appareil de l’utilisateur en suivant les mêmes étapes propres à la plateforme que dans le flux d’inscription :

iOS

Utilisez ASAuthorizationPlatformPublicKeyCredentialProvider pour créer les identifiants avec Face ID, Touch ID ou le NIP de l’appareil. Pour en savoir plus, consultez la documentation sur l’enregistrement pour iOS.

Android

Utilisez CredentialManager pour créer les identifiants à l’aide de l’authentification biométrique ou du NIP de l’appareil. Pour en savoir plus, consultez la documentation sur l’enregistrement pour Android.

Web

Utilisez navigator.credentials.create() avec les PublicKeyCredentialCreationOptions renvoyées par Auth0. Pour en savoir plus, consultez l’API Web Authentication de MDN.

4. Une fois que l’utilisateur a créé la clé d’accès à l’aide de son authentificateur, appelez le point de terminaison POST /me/v1/authentication-methods/passkey|new/verify pour terminer l’enregistrement :

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 passkey est enregistrée pour l’utilisateur et peut être utilisée lors de futures authentifications.

Pour en savoir plus sur les requêtes et les paramètres liés à l’enrôlement, consultez l’API Explorer My Account.

​

ID de partie utilisatrice

Une clé d’accès créée dans l’une de vos applications peut être utilisée pour ouvrir une session dans vos autres applications, natives ou Web, lorsque ces applications partagent le même ID de partie utilisatrice (rpId). Cela est possible parce que les fournisseurs de clés d’accès (iCloud Keychain, Google Password Manager, 1Password, Dashlane et d’autres) synchronisent les identifiants entre les appareils de l’utilisateur au sein d’un même fournisseur.

​

Faire passer les utilisateurs d’une plateforme à l’autre

Dans la plupart des cas, les utilisateurs n’ont pas besoin de numériser un code QR ni d’utiliser un deuxième appareil. Le flow dépend du fait que la passkey soit déjà disponible ou non sur l’appareil qu’ils utilisent :

• Même fournisseur, appareil différent (le cas le plus courant) : un utilisateur enregistre une passkey dans votre application iOS ; son Keychain iCloud la synchronise avec son Mac, où il peut se connecter immédiatement à votre application Web. Il en va de même pour les passkeys Android synchronisées via Google Password Manager avec Chrome sur un Chromebook ou un PC Windows connecté au même compte Google.
• Écosystèmes différents ou appareil partagé (moins courant) : si la passkey n’est pas disponible sur l’appareil utilisé par l’utilisateur (par exemple, une passkey d’iPhone utilisée sur un PC Windows ou un ordinateur public), le navigateur propose un code QR pour s’authentifier à l’aide du téléphone de l’utilisateur au moyen du transport hybride (CTAP 2.2). L’utilisateur conserve sa passkey sur son téléphone ; le code QR ne fait le lien entre les deux appareils que pour cette connexion.

​

Choisissez votre ID de partie de confiance

Le rpId détermine quelles origines peuvent utiliser une clé d’accès. Par défaut, Auth0 définit le rpId sur votre domaine personnalisé. Choisissez le rpId qui correspond le mieux à la portée dans laquelle vous voulez que les clés d’accès fonctionnent — sans aller au-delà.

Recommandation : Utilisez un domaine parent qui englobe vos interfaces d’authentification et de produit, comme auth.example.com ou accounts.example.com. Une clé d’accès créée avec “rpId=auth.example.com fonctionne sur auth.example.com et sur tous ses sous-domaines (par exemple, app.auth.example.com, m.auth.example.com).

Évitez d’utiliser votre eTLD+1 (domaine racine 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’accès, y compris les sites de marketing, les services hébergés par des tiers ou les domaines exploités par d’autres équipes. Cela élargit la limite de confiance bien au-delà de votre interface d’authentification.

Pour en savoir plus sur l’ID de partie de confiance, consultez RP ID Deep Dive.

​

Scénarios à plusieurs domaines et images de marque

Si vous utilisez plusieurs domaines associés à différentes images de marque (p. ex., login.brand1.com et login.brand2.com), les clés d’accès ne fonctionnent pas automatiquement d’un domaine à l’autre : chaque domaine possède son propre rpId. Consultez Clés d’accès avec plusieurs domaines personnalisés pour obtenir des conseils sur l’inscription, la communication et les stratégies de migration propres à chaque domaine.

​

Liste de contrôle de la configuration

Une fois que vous avez choisi un rpId, assurez-vous que toutes vos applications l’utilisent :

1. Utilisez un même domaine personnalisé comme rpId pour toutes les applications natives et web qui doivent partager des clés d’accès.
2. Pour les applications natives, configurez les paramètres de l’appareil dans le Auth0 Dashboard avec votre Team ID/App ID iOS et le nom du package/l’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 de l’un de ses sous-domaines, et ajoutez-la aux Allowed Web Origins pour CORS.

​

En savoir plus

Vous pouvez consulter les ressources suivantes pour mettre en œuvre l’authentification par passkey dans votre application :

• API Auth0

  • Authentication API : Consultez les endpoints d’authentification par passkey.
  • My Account API : Consultez les endpoints d’inscription de passkey.
  • Documentation de My Account API : Découvrez l’activation, les scopes et CORS.

• Documentation des plateformes

  • Apple Developer : Prise en charge des passkeys
  • Android Developers : Créer des passkeys
  • Android Developers : Se connecter avec des passkeys
  • API Web Authentication de MDN
  • Spécification WebAuthn

• Ressources supplémentaires

  • passkeys.dev : Un guide complet de mise en œuvre des passkeys.