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 à plusieurs facteurs.

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 d'une machine d'état. Les réponses de demande informent un client d'application de ce qui doit être fait ensuite plutôt que d'obliger les utilisateurs à activer les témoins tiers dans leur navigateur. Les cookies tiers activés dans les navigateurs peuvent poser des problèmes, en particulier pour les applications B2C où les contrôles sur le 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
  • Renforcez la sécurité de l'authentification basée sur un mot de passe à l'aide de l'authentification multifacteur en exigeant des vérifications supplémentaires, telles que 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 des facteurs d'authentification des utilisateurs.

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

Adhésion au facteur avec vérification

Adhésion au facteur avec vérification

Ces cas d'utilisation fournissent des exemples de demandes à 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 de l'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 d'authentification de 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 l'utilisation 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 d'inscription pour un utilisateur par userGUID

Cette étape obtient les facteurs d'inscription d'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 d'inscription 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 tel que "7b3d902ab05b4214"
  • USER_NAME- Par exemple, userId doit contenir USER_NAME tel que John.

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

L'exemple suivant montre l'exemple de demande pour obtenir les facteurs d'inscription d'un utilisateur en fonction de son 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 montre l'exemple de demande pour obtenir les facteurs d'inscription d'un utilisateur en fonction de son GUID 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 d'authentification de 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 de 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 de vérification des facteurs sans fournir userGUID, vous pouvez fournir un ID unique d'utilisateur tel que le nom d'utilisateur 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, userId doit contenir USER_GUID, par exemple "7b3d902ab05b4214"
  • USER_NAME - Par exemple, userId doit contenir USER_NAME tel que John.

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

Exemple de demande

L'exemple suivant montre 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 avoir lancé le 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 terminer la vérification des facteurs. factorId est l'appareil privilégié 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 du facteur SMS et EMAIL) est envoyé à l'aide de SMS à l'appareil mobile de l'utilisateur.

Étape 2 : Vérifier le facteur privilégié

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 des facteurs 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 d'authentification de 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 à la fois factorId et method dans la demande. Si vous devez utiliser l'API de vérification des facteurs sans fournir userGUID, vous pouvez fournir un ID unique d'utilisateur tel que le nom d'utilisateur 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, userId doit contenir USER_GUID, par exemple "7b3d902ab05b4214".
  • USER_NAME - Par exemple, userId doit contenir USER_NAME, par exemple Joe John.

L'attribut userId contient la valeur réelle des données d'identification d'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é liées aux facteurs de sauvegarde

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

Note

La valeur factorId privilégiée contient l'ID unique du facteur privilégié. Dans le cas de SECURITY_QUESTIONS, elle aura la chaîne fixe "SecurityQuestions".
{
    "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 terminer la vérification des facteurs. requestState contient les données contextuelles nécessaires pour traiter 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 terminer la vérification des facteurs. requestState contient les données contextuelles nécessaires pour traiter la demande. Dans cet exemple, une question est renvoyée à partir de la liste des questions auxquelles l'utilisateur doit répondre.

Exemple de demande pour vérifier les questions de sécurité liées aux facteurs 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 EMAIL

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

Exemple de demande pour lancer le facteur EMAIL

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 EMAIL

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 de 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 aviser l'utilisateur.

Téléchargez la collection d'exemples de cas d'utilisation d'authentification de 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 prises en charge / Exemples de valeurs Valeurs multiples Détails d'utilisation
userFlowControlledByExternalClient true / false fausse
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 Thumbprint

Lorsque cette option est spécifiée, 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 prises en charge / Exemples de valeurs Valeurs multiples Détails d'utilisation
otp

Carte

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

Lorsqu'il est présent dans la réponse, l'attribut contient le code secret à 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>"
           }
}

Adhésion 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 d'authentification de 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'adhésion avec facteur SMS

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

  • method : Définit le facteur SMS pour l'inscription
  • phoneNumber : Définit le numéro de téléphone où le texte SMS sera envoyé
  • countryCode : Définit le code de pays du numéro de téléphone où le texte 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 mot de passe à 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 en cours d'inscription
  • method: Méthode du facteur SMS
  • Identificateur unique factorId: généré pour le facteur en cours d'inscription
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 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."
        }
    ]
}

Adhésion 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 d'authentification de 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'adhésion 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 du facteur EMAIL

Le succès indique que :

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

Étape 1a : Renvoyer le mot de passe à 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 code secret à 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 en cours d'inscription à la méthode EMAIL
  • factorId : Identificateur unique généré pour le facteur en cours d'inscription

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 EMAIL 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."
        }
    ]
}