Inscrire et vérifier les authentificateurs SMS et d’appel vocal

Décrit comment créer vos propres flux MFA en utilisant les SMS ou l’appel vocal comme facteur d’authentification.

Auth0 offre un MFA intégré d’inscription et d’authentification à l’aide de Universal Login. Cependant, si vous souhaitez créer votre propre interface utilisateur, vous pouvez utiliser la MFA API pour le faire.

​

Prérequis

Avant de pouvoir utiliser les API MFA, vous devez activer le type d’autorisation MFA pour votre application. Accédez à Auth0 Dashboard > Applications > Advanced Settings > Grant Types et sélectionnez MFA.

• Configurer le téléphone comme facteur dans le Dashboard ou à l’aide de la Management API.

​

S’inscrire par SMS ou appel vocal

​

Obtenir un jeton MFA

Selon le moment où vous lancez l’inscription, vous pouvez obtenir un jeton d’accès pour utiliser la MFA API de différentes façons :

• Si vous effectuez l’inscription pendant l’authentification, consultez S’authentifier avec Resource Owner Password Grant et MFA.
• Si vous souhaitez permettre à l’utilisateur d’inscrire un facteur à tout moment, consultez Gérer les inscriptions aux facteurs MFA.

​

Inscrire un authentificateur

Faites une requête POST à l’endpoint MFA Associate pour inscrire l’authentificateur de l’utilisateur. Le bearer token exigé par cet endpoint est le MFA token obtenu à l’étape précédente.

Pour l’inscription par SMS ou appel vocal, l’utilisateur s’inscrit avec un numéro de téléphone qui peut être utilisé pour une demande de vérification par SMS ou par appel vocal. Indiquez les paramètres ci-dessous pour faire une requête à l’endpoint. Le paramètre oob_channels indique comment vous voulez envoyer le code à l’utilisateur (SMS ou appel vocal).

Paramètre	Valeur
authentication_types	[oob]
oob_channels	[sms] ou [voice]
phone_number	+11...9, le numéro de téléphone au format E.164

Si l’opération réussit, vous recevez une réponse comme celle-ci :

{
  "authenticator_type": "oob",
  "binding_method": "prompt",
  "recovery_codes": [ "N3BGPZZWJ85JLCNPZBDW6QXC" ],
  "oob_channel": "sms",
  "oob_code": "ata6daXAiOi..."
}
`

Si vous obtenez l’erreur User is already enrolled, c’est que l’utilisateur a déjà un facteur MFA configuré. Avant d’associer un autre facteur à l’utilisateur, vous devez d’abord le soumettre à une vérification à l’aide du facteur existant.

S’il s’agit de la première fois que l’utilisateur associe un authentificateur, vous remarquerez que la réponse comprend recovery_codes. Les codes de récupération servent à accéder au compte de l’utilisateur s’il perd l’accès au compte ou à l’appareil utilisé pour son deuxième facteur d’authentification. Ces codes sont à usage unique, et de nouveaux codes sont générés au besoin.

​

Confirmer l’inscription par SMS ou appel vocal

Les utilisateurs devraient recevoir un message contenant un code à 6 chiffres qu’ils devront fournir à l’application.

Pour terminer l’inscription, envoyez une requête POST au OAuth point de terminaison de jeton. Vous devez inclure le oob_code renvoyé dans la réponse précédente, ainsi que le binding_code avec la valeur reçue dans le message.

Si la requête a réussi, vous recevrez une réponse au format suivant, contenant le jeton d’accès :

{
  "id_token": "eyJ...i",
  "access_token": "eyJ...i",
  "expires_in": 600,
  "scope": "openid profile",
  "token_type": "Bearer"
}

​

Vérification par SMS ou appel vocal

​

Obtenir un jeton MFA

Obtenez un jeton MFA en suivant la procédure décrite dans S’authentifier avec Resource Owner Password Grant et MFA.

​

Récupérer les authentificateurs inscrits

Pour lancer une demande de vérification à l’utilisateur, vous avez besoin de l’authenticator_id du facteur que vous voulez interroger. Vous pouvez afficher tous les authentificateurs inscrits à l’aide du point de terminaison MFA Authenticators :

Vous obtiendrez une liste d’authentificateurs au format suivant :

[
    {
        "id": "recovery-code|dev_O4KYL4FtcLAVRsCl",
        "authenticator_type": "recovery-code",
        "active": true
    },
    {
        "id": "sms|dev_NU1Ofuw3Cw0XCt5x",
        "authenticator_type": "oob",
        "active": true,
        "oob_channel": "sms",
        "name": "XXXXXXXX8730"
    },
        {
        "id": "voice|dev_NU1Ofuw3Cw0XCt5x",
        "authenticator_type": "oob",
        "active": true,
        "oob_channel": "voice",
        "name": "XXXXXXXX8730"
    }
]

​

Demander une vérification par OTP à l’utilisateur

Pour déclencher une demande de vérification, envoyez une requête POST au point de terminaison MFA Challenge à l’aide de l’authenticator_id correspondant et du mfa_token.

​

Terminez l’authentification avec le code reçu

En cas de réussite, vous recevez la réponse suivante :

{
  "challenge_type": "oob",
  "oob_code": "asdae35fdt5...",
  "binding_method": "prompt"
}

Votre application doit inviter l’utilisateur à saisir le code à 6 chiffres envoyé dans le message et définir ce code dans le paramètre binding_code. Vous pouvez vérifier le code et obtenir des jetons d’authentification à l’aide du point de terminaison de jeton d’OAuth0, en précisant les valeurs binding_code et oob_code renvoyées par la requête précédente :

Si la requête a réussi, vous recevrez une réponse au format suivant, contenant le jeton d’accès :

{
  "id_token": "eyJ...i",
  "access_token": "eyJ...i",
  "expires_in": 600,
  "scope": "openid profile",
  "token_type": "Bearer"
}

Remarque : les SMS et les erreurs « code invalide » sont soumis à une limitation du débit. Les codes SMS peuvent être envoyés 10 fois et la limite se rétablit à raison d’une fois par heure, tandis que l’erreur « code invalide » peut être renvoyée 10 fois et la limite se rétablit à raison d’une fois toutes les six minutes.

​

Personnaliser la MFA

La MFA personnalisable avec les flux Resource Owner Password Grant, Embedded ou Refresh Token est en Early Access. En utilisant cette fonctionnalité, vous acceptez les conditions applicables de l’essai gratuit énoncées dans le Master Subscription Agreement d’Okta. Pour en savoir plus sur les étapes de lancement d’Auth0, consultez Product Release Stages. Pour participer à l’accès anticipé, communiquez avec Auth0 Support.

La MFA personnalisable permet aux utilisateurs d’inscrire les facteurs de leur choix pris en charge par votre application et de répondre aux demandes de vérification associées.

Lors de l’authentification au point de terminaison oauth/token, la réponse renvoie l’erreur mfa_required, qui inclut le mfa_token à utiliser avec la MFA API, ainsi que le paramètre mfa_requirements contenant une liste d’authentificateurs :

{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26...Ha",
  "mfa_requirements": {
    "challenge": [
      { "type": "otp" },
      { "type": "push-notification" },
      { "type": "phone" },
      { "type": "recovery-code" }
      { "type": "email"} //fonctionne uniquement avec challenge
    ]
  }
}

Utilisez le mfa_token pour envoyer une requête au point de terminaison mfa/authenticator afin d’obtenir la liste de tous les facteurs auxquels l’utilisateur s’est inscrit et de repérer un type pris en charge par votre application. Vous devez aussi obtenir l’authenticator_type correspondant pour lancer des demandes de vérification :

[
  {
    "type": "recovery-code",
    "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
    "authenticator_type": "recovery-code",
    "active": true
  },
  {
    "type": "otp",
    "id": "totp|dev_6NWz8awwC8brh2dN",
    "authenticator_type": "otp",
    "active": true
  }
]

Forcez la vérification MFA en appelant le point de terminaison request/mfa/challenge.

Personnalisez davantage votre processus MFA avec Auth0 Actions. Pour en savoir plus, consultez Déclencheurs d’Actions : post-challenge - objet API.

​

En savoir plus

• Gérer les facteurs d’authentification avec l’Authentication API
• Configurer les notifications SMS et d’appel vocal pour la MFA
• Vérification avec des codes de récupération
• Inscrire et vérifier les authentificateurs Email
• Inscrire et vérifier les authentificateurs OTP
• Inscrire et vérifier les authentificateurs push