Documentation sur Oracle Cloud Infrastructure

Utilisation de l'API d'authentification multifacteur sur demande pour développer une page de connexion personnalisée

Ce cas d'utilisation fournit un exemple étape par étape d'utilisation de l'API REST des domaines d'identité pour authentifier les utilisateurs et effectuer l'inscription et l'authentification multifacteur.

Note

Utilisez cette API d'authentification uniquement si vous créez votre propre expérience de connexion de bout en bout en développant une application de connexion personnalisée à utiliser par les domaines d'identité.
Note

Cette API d'authentification ne peut pas être utilisée pour intégrer vos applications à des domaines d'identité à des fins d'authentification unique.

L'API d'authentification multifacteur On Demand est basée sur le concept de machine à états. Les réponses aux demandes informent un client d'application de ce qui doit être fait ensuite plutôt que d'exiger que les utilisateurs aient activé les cookies tiers dans leur navigateur. Les témoins tiers activés dans les navigateurs peuvent poser des problèmes, en particulier pour les applications B2C où les contrôles du comportement de l'utilisateur final ne peuvent pas être appliqués. La valeur requestState fournie dans chaque réponse à la demande est utilisée dans la demande suivante, fournissant au client les informations dont il a besoin pour traiter la demande, puis fournissant le jeu d'opérations suivant autorisé.

L'API d'authentification multifacteur On Demand peut :
  • Prise en charge de l'inscription des utilisateurs avec les facteurs d'authentification multifacteur activés par l'administrateur
  • Renforcer la sécurité de l'authentification basée sur un mot de passe à l'aide de l'authentification multifacteur (AMF) en exigeant une vérification supplémentaire, comme l'utilisation d'un code secret à usage unique basé sur le temps ou d'un code secret SMS.
  • Effectuer l'inscription à l'authentification multifacteur, la vérification de l'authentification multifacteur et la gestion du facteur d'authentification de l'utilisateur.

Les exemples de jeu suivants sont inclus dans ce cas d'utilisation :

Adhésion au facteur avec vérification

Facteur d'inscription avec vérification

Ces cas d'utilisation fournissent des exemples de demande à l'aide de l'API REST des domaines d'identité qui permet à un utilisateur de s'inscrire à des facteurs d'authentification multifacteur.

Les cas d'utilisation suivants vous guident tout au long des étapes pour inscrire différents facteurs d'authentification multifacteur à l'aide d'une API REST :

Extraire les facteurs inscrits d'un utilisateur

Ce cas d'utilisation fournit un exemple étape par étape d'utilisation de l'API de vérification des domaines d'identité pour extraire les facteurs auxquels un utilisateur est inscrit.

Ces étapes supposent que les facteurs pertinents de l'authentification multifacteur sont activés à l'aide de Configurer les paramètres d'authentification multifacteur.

Téléchargez la collection d'exemples de cas d'utilisation pour l'authentification des domaines d'identité et le fichier de variables globales à partir du dossier idcs-factor-enrollment-api dans le référentiel idm-samples GitHub, puis importez-les dans Postman.

L'étape à suivre dans ce cas d'utilisation dépend de si vous voulez effectuer une demande à l'aide de userGUID ou de User Name :
Note

Les exemples de cette section utilisent userGUID dans les demandes. Vous pouvez demander userGUID et userOcid dans vos demandes.

Étape 1 : Obtenir les facteurs inscrits pour un utilisateur par userGUID

Cette étape obtient les facteurs inscrits pour un utilisateur en fonction de userGUID ou du nom d'utilisateur.

Exemple de demande 

GET {{HOST}}/mfa/v1/users/{{userGUID}}/factors

Exemple de réponse

L'exemple suivant montre le contenu de la réponse au format JSON :


{
    "userGUID": "7b3d902ab05b4214bae6b2924ca6be21",
    "status": "success",
    "preferredFactorId": "b3e04149d958437b9b801fa70c33ca70",
    "preferredMethod": "EMAIL",
    "factors": [
        {
            "factorId": "SecurityQuestions",
            "methods": [
                "SECURITY_QUESTIONS"
            ]
        },
        {
            "displayName": "+155XXXXX555",
            "factorId": "83889faeacaf4592a964405f87506fc6",
            "methods": [
                "SMS"
            ]
        },
        {
            "displayName": "uxxr1@example.com",
            "factorId": "b3e04149d958437b9b801fa70c33ca70",
            "methods": [
                "EMAIL"
            ]
        },
        {
            "factorId": "BypassCode",
            "methods": [
                "BYPASSCODE"
            ]
        }
    ]
}

La réponse contient userGUID, le facteur privilégié et les détails du facteur inscrit.

Étape 2 : Obtenir les facteurs inscrits pour un utilisateur à l'aide de filtres

Vous pouvez obtenir les facteurs d'inscription d'un utilisateur à l'aide du nom d'utilisateur ou du GUID d'utilisateur. Les valeurs userIdType suivantes sont acceptées :

  • USER_GUID- Par exemple, ici, userId doit contenir USER_GUID, par exemple "7b3d902ab05b4214"
  • USER_NAME- Par exemple, ici, userId doit contenir USER_NAME, par exemple John.

Exemple de demande pour extraire les facteurs inscrits en fonction du nom d'utilisateur

L'exemple suivant présente l'exemple de demande pour obtenir les facteurs inscrits d'un utilisateur en fonction de leur nom d'utilisateur au format JSON :

GET {{HOST}}/mfa/v1/users?userId=user1@example.com&userIdType=USER_NAME&attributes=factors

Exemple de réponse

L'exemple suivant montre le contenu de la réponse au format JSON : 

{
    "userGUID": "589879c55b7340518141eab82493f0cc",
    "status": "success",
    "preferredFactorId": "88178d80636a428393a5674ba46dc867",
    "preferredMethod": "SMS",
    "factors": [
        {
            "factorId": "BypassCode",
            "methods": [
                "BYPASSCODE"
            ]
        },
        {
            "displayName": "user1@example.com",
            "factorId": "30db2274140043918edb033d9fe29ff3",
            "methods": [
                "EMAIL"
            ]
        },
        {
            "displayName": "+1554455555",
            "factorId": "88178d80636a428393a5674ba46dc867",
            "methods": [
                "SMS"
            ]
        }
    ]
}

La réponse contient userGUID, le facteur privilégié et les détails du facteur inscrit.

Exemple de demande pour extraire les facteurs inscrits en fonction du GUID d'utilisateur

L'exemple suivant présente l'exemple de demande d'obtention des facteurs inscrits pour un utilisateur en fonction de leur GUID d'utilisateur au format JSON :

GET {{HOST}}/mfa/v1/users?userId=589879c55b7340518141eab82493f0cc&userIdType=USER_GUID&attributes=factors

Exemple de réponse

L'exemple suivant montre le contenu de la réponse au format JSON :

{
    "userGUID": "589879c55b7340518141eab82493f0cc",
    "status": "success",
    "preferredFactorId": "88178d80636a428393a5674ba46dc867",
    "preferredMethod": "SMS",
    "factors": [
        {
            "factorId": "BypassCode",
            "methods": [
                "BYPASSCODE"
            ]
        },
        {
            "displayName": "user1@example.com",
            "factorId": "30db2274140043918edb033d9fe29ff3",
            "methods": [
                "EMAIL"
            ]
        },
        {
            "displayName": "+1554455555",
            "factorId": "88178d80636a428393a5674ba46dc867",
            "methods": [
                "SMS"
            ]
        }
    ]
}

La réponse contient userGUID, le facteur privilégié et les détails du facteur inscrit.

Lancer et vérifier le facteur privilégié

Ce cas d'utilisation fournit un exemple étape par étape d'utilisation de l'API d'inscription de facteur de domaines d'identité pour l'inscription à l'authentification multifacteur avec vérification de facteur.

Ces étapes supposent que les facteurs pertinents de l'authentification multifacteur sont activés à l'aide de Configurer les paramètres d'authentification multifacteur.

Téléchargez la collection d'exemples de cas d'utilisation pour l'authentification des domaines d'identité et le fichier de variables globales à partir du dossier idcs-factor-verification-api dans le référentiel idm-samples GitHub, puis importez-les dans Postman.

Téléchargez la collection et le fichier des variables globales à partir du dossier idcs-factor-verification-api dans GitHub, puis importez-les dans Postman.

Pour le cas d'utilisation, procédez comme suit. Chaque étape contient des exemples de demande et de réponse :
Note

Les exemples de cette section utilisent userGUID dans les demandes. Vous pouvez demander userGUID et userOcid dans vos demandes.

Step1 : Lancer la vérification du facteur privilégié

Cette étape lance la vérification du facteur préféré d'un utilisateur. Si vous devez utiliser l'API du facteur de vérification sans fournir userGUID, vous pouvez fournir un ID unique d'utilisateur tel que le nom d'utilisateur comme userId. La valeur userIdType dans la demande indique le type de données d'identification que l'utilisateur transmet en tant que valeur pour userId. Les valeurs userIdType suivantes sont acceptées :

  • USER_GUID - Par exemple, ici, userId doit contenir USER_GUID, par exemple "7b3d902ab05b4214"
  • USER_NAME - Par exemple, ici, userId doit contenir USER_NAME, par exemple John.

L'attribut userId contient la valeur réelle des données d'identification de l'utilisateur transmises.

Exemple de demande

L'exemple suivant présente la demande POST au point d'extrémité {{HOST}}/mfa/v1/requests au format JSON.

{
   "userId":"{{userGUID}}",
   "userIdType": "USER_GUID"
}

Exemple de réponse

L'exemple suivant montre le contenu de la réponse POST au point d'extrémité {{HOST}}/mfa/v1/requests au format JSON après le lancement du facteur privilégié pour l'ID privilégié :


{     
"status": "success",
"requestId": "f843736e-cbd8-4548-b41f-343b624a79fc",
"userGUID": "589879c55b7340518141eab82493f0cc",  
"factorId": "88178d80636a428393a5674ba46dc867",   
"method": "SMS",   
"displayName": "+4455665455",   
"requestState": "GwHJr3RvycjNEv.....MhQTLmWYzA/LVp0s"
}

Dans la réponse, la valeur requestId est l'identificateur unique généré pour cette demande. Incluez requestId dans chaque appel suivant pour effectuer la vérification du facteur. factorId est l'appareil préféré sur lequel il a été lancé. method est le facteur que l'utilisateur a lancé. requestState contient les données contextuelles nécessaires au traitement de la demande.

Dans cet exemple, un otpCode (dans le cas d'un facteur SMS et EMAIL) est envoyé par SMS à l'appareil mobile de l'utilisateur.

Étape 2 : Vérifier le facteur préféré

Cette étape vérifie le facteur en transmettant otpCode dans une demande PATCH à {{HOST}}/mfa/v1/requests/{{requestId}}.

Le client doit inclure les attributs suivants :

  • otpCode: le code reçu par l'utilisateur sur son appareil
  • requestState : Réception dans la réponse de l'étape 1
  • requestId : Réception dans la réponse de l'étape 1

Exemple de demande

L'exemple suivant montre le contenu de la demande PATCH au format JSON : 

{  
"otpCode":"170230", 
"requestState": "{{requestState}}" 
}

Exemple de réponse

L'exemple suivant montre le contenu de la réponse au format JSON : 

{"status":"success"}

La réussite indique que la vérification a réussi.

Lancer et vérifier un facteur de sauvegarde

Ce cas d'utilisation fournit un exemple étape par étape d'utilisation de l'API de vérification des domaines d'identité pour effectuer la vérification du facteur de sauvegarde.

Ces étapes supposent que les facteurs pertinents de l'authentification multifacteur sont activés à l'aide de Configurer les paramètres d'authentification multifacteur.

Téléchargez la collection d'exemples de cas d'utilisation pour l'authentification des domaines d'identité et le fichier de variables globales à partir du dossier idcs-factor-verification-api dans le référentiel idm-samples GitHub, puis importez-les dans Postman.

Pour le cas d'utilisation, procédez comme suit. Chaque étape contient des exemples de demande et de réponse :
Note

Les exemples de cette section utilisent userGUID dans les demandes. Vous pouvez demander userGUID et userOcid dans vos demandes.

Étape 1 : Lancer et vérifier les questions de sécurité relatives au facteur de sauvegarde

Cette étape lance la vérification du facteur de sauvegarde d'un utilisateur. Le client doit fournir factorId et method dans la demande. Si vous devez utiliser l'API du facteur de vérification sans fournir userGUID, vous pouvez fournir un ID unique d'utilisateur tel que le nom d'utilisateur comme userId. La valeur userIdType dans la demande indique le type de données d'identification que l'utilisateur transmet en tant que valeur pour userId. Les valeurs userIdType suivantes sont acceptées :

  • USER_GUID - Par exemple, ici, userId doit contenir USER_GUID, par exemple "7b3d902ab05b4214".
  • USER_NAME - Par exemple, ici, userId doit contenir USER_NAME, par exemple Joe John.

L'attribut userId contient la valeur réelle des données d'identification de l'utilisateur transmises.

Pour obtenir la liste des facteurs inscrits et leurs ID pour un utilisateur, voir le cas d'utilisation Extraire les facteurs inscrits d'un utilisateur. Dans cet exemple, le facteur de sauvegarde choisi est Questions de sécurité.

Exemple de demande pour lancer des questions de sécurité sur le facteur de sauvegarde

L'exemple suivant montre le contenu de la demande POST au point d'extrémité {{HOST}}/mfa/v1/requests/ au format JSON :

Note

Le paramètre factorId privilégié contient l'ID unique du facteur privilégié. Dans le cas de SECURITY_QUESTIONS, la chaîne fixe "SecurityQuestions" apparaît.
{
    "userId":"{{userID}}",
    "userIdType":"USER_GUID",
    "factorId":"{{factorID}}",
    "method":"SECURITY_QUESTIONS"
}

Dans la réponse, la valeur requestId est l'identificateur unique généré pour cette demande. Incluez requestId dans chaque appel suivant pour effectuer la vérification du facteur. requestState contient les données contextuelles nécessaires au traitement de la demande.

Exemple de réponse

L'exemple suivant montre le contenu de la réponse au format JSON pour la méthode de sauvegarde SEQURITY_QUESTIONS : 

{
    "status": "success",
    "requestId": "8da79411-5388-41ee-990e-935e74cb40f3",
    "userGUID": "589879c55b7340518141eab82493f0cc",
    "factorId": "SecurityQuestions",
    "method": "SECURITY_QUESTIONS",
    "requestState": "hBJIvkyfsXBv....movYarft8HlYANV3c+0",
    "securityQuestions": [
        {
            "id": "MaidenName",
            "localizedText": "What's your mother's maiden name?"
        }
    ]
}

Dans la réponse, la valeur requestId est l'identificateur unique généré pour cette demande. Incluez requestId dans chaque appel suivant pour effectuer la vérification du facteur. requestState contient les données contextuelles nécessaires au traitement de la demande. Dans cet exemple, une question est renvoyée de la liste des questions inscrites auxquelles l'utilisateur doit répondre.

Exemple de demande pour vérifier les questions de sécurité relatives au facteur de sauvegarde

Cette étape vérifie le facteur de sauvegarde en transmettant la réponse à la question de sécurité dans une demande PATCH à {{HOST}}/mfa/v1/requests/{{requestID}}. Le client doit inclure les attributs suivants :

  • requestState: reçu dans la réponse de l'étape 1
  • securityQuestions id/answers : Défini par l'utilisateur lors de l'inscription

Exemple de demande

L'exemple suivant montre le contenu de la demande PATCH au format JSON pour SECURITY_QUESTIONS : 
{
 "securityQuestions":[
        {
            "id":"MaidenName",
            "answer":"Smith"
        }
    ],
"requestState": "{{requestState}}"
 }

Exemple de réponse

L'exemple suivant montre le contenu de la réponse au format JSON : 

{"status":"success"}

La réussite indique que la vérification a réussi.

Étape 2 : Lancer et vérifier le facteur de sauvegarde par courriel

Cette étape lance la vérification d'un facteur de sauvegarde EMAIL.

Exemple de demande pour lancer le facteur de courriel

L'exemple suivant montre l'exemple de demande au format JSON pour la méthode préférée "EMAIL" :

{
    "userId":"{{userID}}",
    "userIdType":"USER_GUID",
    "factorId":"{{factorID}}",
    "method":"EMAIL"
}

Exemple de réponse

L'exemple suivant présente l'exemple de réponse pour lancer le facteur EMAIL au format JSON :

{ 
 "status":"success",
 "requestId":"<Request ID>",
 "userGUID":"<User GUID>",
 "factorId":"factorID",
 "method":"EMAIL",
 "displayName":"Joe John",
 "requestState":"QYV81R9eoagwWQ"
 }

Exemple de demande pour vérifier le facteur de courriel

L'exemple suivant montre la demande PATCH au format JSON pour le facteur EMAIL :

{
    "otpCode":"170230"
     "requestState": "QYV81R9eoagwWQ"
 }

Exemple de réponse

L'exemple suivant montre le contenu de la réponse au format JSON pour vérifier le facteur EMAIL : 

{"status":"success"}

La réussite indique que la vérification a réussi.

Retourner les facteurs du mot de passe à usage unique sans aviser l'utilisateur

Ce cas d'utilisation fournit un exemple de lancement de l'API d'authentification multifacteur On Demand pour retourner des facteurs de code secret à usage unique (SMS, courriel ou appel téléphonique) dans une réponse sans en aviser l'utilisateur.

Téléchargez la collection d'exemples de cas d'utilisation pour l'authentification des domaines d'identité et le fichier de variables globales à partir du dossier idcs-factor-verification-api dans le référentiel idm-samples GitHub, puis importez-les dans Postman.

Ces étapes supposent que les facteurs pertinents de l'authentification multifacteur sont activés à l'aide de Configurer les paramètres d'authentification multifacteur.

Données utiles de la demande
Attribut Valeurs/échantillons pris en charge Valeurs multiples Détails de l'utilisation
userFlowControlledByExternalClient true / false faux
Régler cette option à 
true
et le mot de passe à usage unique sera retourné dans la réponse dans le format chiffré spécifié.

Note : Le certificat utilisé pour le chiffrement est chargé à l'avance dans l'application et référencé à l'aide de l'attribut x5t dans l'exemple de demande, comme indiqué ci-dessous.
x5t Chaîne / X509 SHA-1 Certificat Empreinte

Lorsqu'il est spécifié, le service utilise ce certificat chargé pour chiffrer les données du code secret à usage unique.

Note : L'attribut "x5t" doit correspondre au certificat chargé.
Exemple de demande
{
    "userId":"<Unique Id>",
    "userIdType":"USER_NAME/USER_GUID",
    "userFlowControlledByExternalClient": true,
    "x5t" :"<certificate thumbprint>"
}
Données utiles de la réponse
Attribut Valeurs/échantillons pris en charge Valeurs multiples Détails de l'utilisation
otp

Carte

"otp": {
    "value": "IMCw==",
    "alg": "RSAES-OAEP",
      "x5t": "<certificate thumbprint>"
 }
faux

Lorsqu'il est présent dans la réponse, l'attribut contient le mot de passe à usage unique chiffré avec les détails suivants.

  • valeur : Valeur chiffrée.
  • alg : Algorithme utilisé pour le chiffrement.
  • x5t : Empreinte SHA-1 X509 du certificat utilisé pour le chiffrement.

Exemple de réponse

{
    "status": "success",
    "requestId": "<Request ID>",
    "userGUID": "<User GUID>",
    "factorId": "<SMS/EMAIL/PHONE_CALL factor GUID>",
    "method": "SMS/EMAIL/PHONE_CALL",
    "displayName": "+91XXXXXXXX984",
    "requestState": "4p7ViEzP2bP1MIM",
    "otp": {
        "value": "<Encrypted OTP value>",
        "alg": "<Encryption algorithm>",
        "x5t": "<x5t of the certificate used to encrypt the OTP>"
           }
}

Inscription au facteur d'authentification avec vérification de facteur - SMS

Ce cas d'utilisation fournit un exemple étape par étape d'utilisation de l'API d'inscription de facteur de domaines d'identité pour l'inscription à l'authentification multifacteur avec vérification de facteur.

Ces étapes supposent que les facteurs pertinents de l'authentification multifacteur sont activés à l'aide de Configurer les paramètres d'authentification multifacteur.

Téléchargez la collection d'exemples de cas d'utilisation pour l'authentification des domaines d'identité et le fichier de variables globales à partir du dossier idcs-factor-enrollment-api dans le référentiel idm-samples GitHub, puis importez-les dans Postman.

Pour le cas d'utilisation, procédez comme suit. Chaque étape contient des exemples de demande et de réponse :
Note

Les exemples de cette section utilisent userGUID dans les demandes. Vous pouvez demander userGUID et userOcid dans vos demandes.

Étape 1 : Lancer l'inscription au facteur SMS

Cette étape lance l'inscription par SMS. Le client doit inclure les attributs suivants :

  • method : Définit l'inscription au facteur SMS
  • phoneNumber : Définit le numéro de téléphone où le texte du SMS sera envoyé.
  • countryCode : Définit le code de pays du numéro de téléphone où le texte du SMS sera envoyé.

Exemple de demande

L'exemple suivant montre la demande POST au point d'extrémité {{HOST}}/mfa/v1/users/{{userGUID}}/factors au format JSON :

{ 
"method": "SMS",
"countryCode": "+44", 
"mobileNumber": "1122334455", 
}

Exemple de réponse

L'exemple suivant montre le contenu de la réponse au format JSON : 

{
"status": "success", 
"factorId": "88178d80636a428393a5674ba46dc867",
"factorStatus": "ENROLLMENT_INITIATED", 
"methods": [ "SMS" ],
"displayName": "+1122334455", 
"requestState": "QK1.....y+OFP//0" 
}

displayName est le numéro de cellulaire. Un otpCode sera envoyé à l'appareil mobile des utilisateurs, qui est utilisé pour terminer l'inscription.

Étape 1a : Renvoyer le code secret à usage unique

Si l'utilisateur ne reçoit pas le code secret à usage unique, cet exemple montre comment demander qu'un code secret à usage unique soit renvoyé. Le client doit inclure les attributs suivants :

requestState: reçu dans la réponse de l'étape 1

resendOtp: Booléen pour indiquer que le mot de passe à usage unique est reçu

Exemple de demande

L'exemple suivant montre la demande PATCH au point d'extrémité {{HOST}}/mfa/v1/users/{{userGUID}}/factors/{{factorID}} au format JSON :

{
 "resendOtp":true,
 "requestState": "QK1.....y+OFP//0"
}

Exemple de réponse

L'exemple suivant montre le contenu de la réponse au format JSON :

{ 
"status": "success",
"factorId": "88178d80636a428393a5674ba46dc867", 
"factorStatus": "ENROLLMENT_INITIATED",
"methods": [ "SMS" ],
"displayName": "+445544455",
"requestState": "+HFVV...qgMUI" 
}

La réponse contient les paramètres suivants :

  • requestState: qui doit être transmis par le client à l'étape suivante
  • displayName: est le numéro de cellulaire inscrit
  • method: Méthode du facteur SMS
  • Identificateur unique factorId: généré pour le facteur inscrit
Le succès indique que :
  • La valeur userGUID fournie est valide
  • L'utilisateur est actif
  • Le compte d'utilisateur n'est pas verrouillé
  • Le facteur SMS est activé

Étape 2 : Activation du facteur SMS

Cette étape active l'inscription par SMS pour l'utilisateur, dans une demande PATCH au point d'extrémité /mfa/v1/users/{{userGUID}}/factors/{{factorID}}.

Le client doit inclure les attributs suivants :

  • otpCode: le code reçu par l'utilisateur sur son appareil
  • requestState : Réception dans la réponse de l'étape 1

Exemple de demande

L'exemple suivant montre le contenu de la demande PATCH au format JSON : 

{  
"otpCode":"170230", 
"requestState": "{{requestState}}"
 }

Exemple de réponse

L'exemple suivant montre le contenu de la réponse au format JSON : 

{"status":"success"}

Le succès indique que :

  • OTP est valide
  • La valeur userGUID fournie est valide
  • L'utilisateur est actif
  • Le compte d'utilisateur n'est pas verrouillé
  • Le facteur SMS est activé et le facteur est inscrit avec succès

Exemples de réponse d'erreur

L'exemple suivant montre le message d'erreur au format JSON lorsque userGUID n'est pas valide. Vous obtenez un code de réponse HTTP 404 si userGUID n'est pas valide.
{
    "status": "failed",
    "ecId": "0d1QwglU0000Fy",
    "cause": [
        {
            "code": "AUTH-3018",
            "message": "User not found."
        }
    ]
}

L'exemple suivant montre le message d'erreur au format JSON lorsque l'utilisateur est verrouillé. Vous obtenez un code de réponse HTTP 401.

{
    "status": "failed",
    "ecId": "0ISDCif1Qy6wg0000A8",
    "cause": [
        {
            "code": "AUTH-1010",
            "message": "Your account is locked.Contact your system administrator."
        }
    ]
}

Inscription au facteur d'authentification avec vérification de facteur - Courriel

Ce cas d'utilisation fournit un exemple étape par étape d'utilisation de l'API d'inscription de facteur de domaines d'identité pour l'inscription à l'authentification multifacteur avec vérification de facteur.

Ces étapes supposent que les facteurs pertinents de l'authentification multifacteur sont activés à l'aide de Configurer les paramètres d'authentification multifacteur.

Téléchargez la collection d'exemples de cas d'utilisation pour l'authentification des domaines d'identité et le fichier de variables globales à partir du dossier idcs-factor-enrollment-api dans le référentiel idm-samples GitHub, puis importez-les dans Postman.

Pour le cas d'utilisation, procédez comme suit. Chaque étape contient des exemples de demande et de réponse :
Note

Les exemples de cette section utilisent userGUID dans les demandes. Vous pouvez demander userGUID et userOcid dans vos demandes.

Étape 1 : Lancer l'inscription au facteur de courriel

Cette étape lance l'inscription par courriel. Le client doit inclure l'attribut suivant :

  • method : Définit l'inscription au courriel. L'utilisateur ne transmettra pas l'ID courriel. L'ID courriel principal est automatiquement extrait du profil de l'utilisateur.

Exemple de demande

L'exemple suivant montre le contenu de la demande POST au point d'extrémité {{HOST}}/mfa/v1/users/{{userGUID}}/factors au format JSON : 

{ 
"method": "EMAIL",
}

Exemple de réponse

L'exemple suivant montre le contenu de la réponse au format JSON : 

{
    "status": "success",
    "factorId": "30db2274140043918edb033d9fe29ff3",
    "factorStatus": "ENROLLMENT_INITIATED",
    "methods": [
        "EMAIL"
    ],
    "displayName": "user1@example.com",
    "requestState": "Vxar...bWTTA"
}

Un message otpCode sera envoyé à l'ID courriel de l'utilisateur, qui est utilisé pour terminer l'inscription.

La réponse contient :

  • requestState: qui doit être transmis par le client à l'étape suivante
  • ID courriel displayName: de l'utilisateur inscrit
  • method: Méthode de facteur EMAIL

Le succès indique que :

L'inscription au facteur a été lancée.

Étape 1a : Renvoyer le code secret à usage unique

L'exemple suivant montre la demande PATCH au point d'extrémité {{HOST}}/mfa/v1/users/{{userGUID}}/factors/{{factorID}} au format JSON.

Si l'utilisateur ne reçoit pas le code secret à usage unique, cet exemple montre comment demander qu'un code secret à usage unique soit renvoyé. Le client doit inclure les attributs suivants :

  • requestState: reçu dans la réponse de l'étape 1
  • resendOtp: pour indiquer que le mot de passe à usage unique est reçu

Exemple de demande

L'exemple suivant montre le contenu de la demande PATCH au format JSON : 

{  
"resendOtp":true, 
 "requestState": "QK1.....y+OFP//0"
 }

L'exemple suivant montre le contenu de la réponse au format JSON : 

{    
"status": "success",     
"factorId": "30db2274140043918edb033d9fe29ff3",
"factorStatus": "ENROLLMENT_INITIATED",   
"methods": ["EMAIL"],
"displayName": "username@example.com", 
"requestState": "AmgsMN.....2sk4SI" 
}

La réponse contient :

  • requestState : qui doit être transmis par le client à l'étape suivante
  • displayName : ID courriel extrait du profil de l'utilisateur
  • method : Liste des méthodes inscrites à la méthode EMAIL
  • factorId : Identificateur unique généré pour le facteur inscrit

Le succès indique que :

  • La valeur userGUID ou userOcid fournie est valide
  • L'utilisateur est actif
  • Le compte d'utilisateur n'est pas verrouillé
  • Le facteur EMAIL est activé

Étape 2 : Activer le facteur EMAIL

Cette étape active l'inscription par courriel pour l'utilisateur, dans une demande PATCH au point d'extrémité /mfa/v1/users/{{userGUID}}/factors/{{factorID}}.

Le client doit inclure les attributs suivants :

  • otpCode: le code reçu par l'utilisateur sur son ID courriel
  • requestState : Réception dans la réponse de l'étape 1

Exemple de demande

L'exemple suivant montre le contenu de la demande PATCH au format JSON : 

{
"otpCode":"710130", 
"requestState": "{{requestState}}"
}

Exemple de réponse

L'exemple suivant montre le contenu de la réponse au format JSON : 

{"status":"success"}

Le succès indique que :

  • OTP est valide
  • La valeur userGUID ou userOcid fournie est valide
  • L'utilisateur est actif
  • Le compte d'utilisateur n'est pas verrouillé
  • Le facteur EMAIL est activé et le facteur est inscrit avec succès

Exemples de réponse d'erreur

L'exemple suivant montre le message d'erreur au format JSON lorsque userGUID n'est pas valide. Vous obtenez un code de réponse HTTP 404 si userGUID ou userOcid n'est pas valide.
{
    "status": "failed",
    "ecId": "0d1QwglU0000Fy",
    "cause": [
        {
            "code": "AUTH-3018",
            "message": "User not found."
        }
    ]
}

L'exemple suivant montre le message d'erreur au format JSON lorsque le courriel est désactivé. Vous obtenez un code de réponse HTTP 401.

{
    "status": "failed",
    "ecId": "0000M00000A",
    "cause": [
        {
            "code": "AUTH-1125",
            "message": "The EMAIL factor has been disabled."
        }
    ]
}