Inscrire des authentificateurs push et lancer une demande de vérification

Décrit comment créer vos propres flux MFA en utilisant le push comme facteur d’authentification.

Auth0 fournit un flux intégré d’inscription et d’authentification MFA avec Universal Login. Toutefois, si vous souhaitez créer votre propre interface utilisateur, vous pouvez utiliser la MFA API pour y parvenir.

Vous pouvez inscrire les utilisateurs et leur envoyer une demande de vérification au moyen de notifications push avec l’application Guardian ou le SDK à l’aide de la MFA API.

​

Prérequis

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

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

​

Configurer la notification push

​

Obtenir un jeton MFA

Selon le moment où vous déclenchez 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 le Resource Owner Password Grant et la MFA.
• Si vous voulez permettre à l’utilisateur d’inscrire un facteur à tout moment, consultez Gérer les inscriptions aux facteurs MFA.

​

Inscrire l’authentificateur

Effectuez une requête POST vers le point de terminaison MFA Associate pour inscrire l’authentificateur de l’utilisateur. Le jeton Bearer requis par ce point de terminaison est le jeton MFA obtenu à l’étape précédente.

Pour inscrire avec push, définissez le paramètre authenticator_types sur [oob] et le paramètre oob_channels sur [auth0].

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

{
    "authenticator_type": "oob",
    "barcode_uri": "otpauth://totp/tenant:user?enrollment_tx_id=qfjn2eiNYSjU3xID7dBYeCBSrdREWJPY&base_url=tenan",
    "recovery_codes": [
        "ALKE6EJZ4853BJYLM2DM2WU7"
    ],
    "oob_channel": "auth0",
    "oob_code": "Fe26.2...SYAg"
}

Si vous obtenez une erreur User is already enrolled, c’est que l’utilisateur a déjà un facteur MFA inscrit. Avant d’associer un autre facteur à l’utilisateur, vous devez d’abord lui envoyer une demande de 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 inclut 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 authentification à deux facteurs. Ces codes sont à usage unique, et de nouveaux codes sont générés au besoin.

​

Confirmer l’inscription par notification push

Pour confirmer l’inscription, l’utilisateur final devra scanner un code QR avec le barcode_uri dans l’application Guardian au cours des 5 prochaines minutes.

Une fois cela fait, l’application Guardian informera Auth0 que l’utilisateur a été inscrit avec succès. Pour vérifier si cela s’est produit, interrogez de façon répétée le point de terminaison des jetons d’Auth0 Point de terminaison des jetons avec le oob_code renvoyé par la requête au point de terminaison MFA Associate.

Si l’utilisateur n’a pas scanné le code, une réponse authorization_pending sera renvoyée, ce qui indique que vous devez faire une nouvelle requête à oauth_token dans quelques secondes :

{
    "error": "authorization_pending",
    "error_description": "Authorization pending: please repeat the request in a few seconds."
}

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

À ce stade, l’authentificateur est bien associé et prêt à être utilisé, et vous disposez des jetons d’authentification de l’utilisateur.

Vous pouvez vérifier à tout moment si un authentificateur a été confirmé en effectuant une requête à l’endpoint MFA Authenticators. Si l’authentificateur est confirmé, la valeur renvoyée pour active est true.

​

Demande d’authentification par notification push

​

Obtenir un jeton MFA

Obtenez un jeton MFA en suivant les étapes décrites dans S’authentifier à l’aide du Resource Owner Password Grant et de la MFA.

​

Récupérer les authentificateurs inscrits

Pour la demande de vérification de l’utilisateur, vous avez besoin de l’authenticator_id du facteur que vous souhaitez vérifier. Vous pouvez obtenir la liste de 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_Ahb2Tb0ujX3w7ilC",
        "authenticator_type": "recovery-code",
        "active": true
    },
    {
        "id": "push|dev_ZUla9SQ6tAIHSz6y",
        "authenticator_type": "oob",
        "active": true,
        "oob_channel": "auth0",
        "name": "user's device name"
    },
    {
        "id": "totp|dev_gJ6Y6vpSrjnKeT67",
        "authenticator_type": "otp",
        "active": true
    }
]

Lorsque les utilisateurs s’inscrivent avec la fonctionnalité push, ils sont également inscrits à OTP, puisque Guardian prend en charge la demande de vérification par OTP lorsque l’utilisateur n’a pas de connexion.

​

Lancer une demande d’authentification push pour l’utilisateur

Pour déclencher une demande d’authentification push, envoyez une requête POST au point de terminaison de MFA Challenge en utilisant le authenticator_id correspondant et le mfa_token.

​

Terminer l’authentification à l’aide du code reçu

Si l’authentification réussit, vous recevez la réponse suivante :

{
    "challenge_type": "oob",
    "oob_code": "Fe26...jGco"
}

Votre application doit commencer à effectuer des requêtes périodiques vers le endpoint de jeton OAuth0 jusqu’à ce que l’utilisateur accepte la notification push.

La requête peut renvoyer l’un des résultats suivants :

Résultat	Description
authorization_pending	Error : Si la demande de vérification n’a été ni acceptée ni rejetée.
slow_down	Error : Si l’interrogation est trop fréquente.
access_token and refresh_token	Si la demande de vérification a été acceptée; l’interrogation doit être arrêtée à ce stade.
invalid_grant	Error : Si la demande de vérification a été rejetée; l’interrogation doit être arrêtée à ce stade.

​

Personnaliser la MFA

La MFA personnalisable avec les flux Resource Owner Password Grant, Embedded ou Refresh Token est en accès anticipé. En utilisant cette fonctionnalité, vous acceptez les conditions d’essai gratuit applicables é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’enregistrer et de valider les facteurs de leur choix pris en charge par votre application.

Pendant l’authentification à l’endpoint 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 que l’utilisateur a déjà configurés et de repérer celui du même type que votre application prend en charge. Vous devez aussi obtenir l’authenticator_type correspondant pour déclencher des vérifications :

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

Imposez la vérification MFA en appelant le endpoint request/mfa/challenge.

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

​

En savoir plus

• Gérer les facteurs d’authentification avec l’Authentication API
• Configurer les notifications push pour la MFA
• Vérification à l’aide de 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 SMS et Voice