Documentazione di Oracle Cloud Infrastructure

Utilizzo dell'API MFA su richiesta per sviluppare la pagina di accesso personalizzata

Questo caso d'uso fornisce un esempio dettagliato dell'utilizzo dell'API REST dei domini di Identity per autenticare gli utenti ed eseguire la registrazione e l'autenticazione con più fattori.

Nota

Utilizzare questa interfaccia API di autenticazione solo se si sta creando un'esperienza di login end-to-end personalizzata sviluppando un'applicazione di accesso personalizzata che deve essere utilizzata dai domini di Identity.
Nota

Questa interfaccia API di autenticazione non può essere utilizzata per integrare le applicazioni con i domini di Identity ai fini del Single Sign-On.

L'API MFA On Demand si basa sul concetto di macchina statale. Le risposte alle richieste informano un client dell'applicazione cosa deve essere fatto dopo piuttosto che richiedere agli utenti di abilitare i cookie di terze parti nei loro browser. I cookie di terze parti abilitati nei browser possono presentare problemi, soprattutto per le applicazioni B2C in cui i controlli sul comportamento dell'utente finale non possono essere applicati. Il valore requestState fornito in ogni risposta alla richiesta successiva viene utilizzato nella richiesta successiva, fornendo al client le informazioni necessarie per elaborare la richiesta e quindi fornire il set successivo di operazioni consentite.

L'API MFA On Demand può:
  • Supporta la registrazione degli utenti con fattori MFA abilitati dall'amministratore
  • Rafforza la sicurezza dell'autenticazione basata su password utilizzando l'autenticazione a più fattori (MFA) richiedendo ulteriori verifiche, come l'uso di un passcode monouso basato sul tempo o di un passcode SMS.
  • Esegui iscrizione MFA, verifica MFA e gestione del fattore di autenticazione utente.

In questo caso d'uso sono inclusi i seguenti set di esempio:

Iscrizione fattore con verifica

Iscrizione fattore con verifica

Questi casi d'uso forniscono richieste di esempio che utilizzano l'API REST dei domini di Identity e consentono a un utente di iscriversi ai fattori MFA.

I casi d'uso riportati di seguito illustrano i passi da seguire per registrare diversi fattori MFA mediante l'API REST.

Recupera fattori iscritti di un utente

Questo caso d'uso fornisce un esempio dettagliato dell'utilizzo dell'API di verifica dei domini di Identity per recuperare i fattori a cui un utente è iscritto.

Questi passi presuppongono che i fattori rilevanti dell'autenticazione MFA siano abilitati mediante Configura impostazioni di autenticazione con più fattori.

Scaricare la raccolta di esempi di casi d'uso di autenticazione dei domini di Identity e il file delle variabili globali dalla cartella idcs-factor-enrollment-api all'interno del repository idm-samples GitHub, quindi importarli in Postman.

Il passo da seguire in questo caso d'uso dipende dal fatto che si desideri effettuare una richiesta utilizzando userGUID o User Name:
Nota

Gli esempi in questa sezione utilizzano userGUID nelle richieste. Puoi richiedere sia userGUID che userOcid nelle tue richieste.

Passo 1: ottenere i fattori iscritti per un utente da userGUID

Questo passo recupera i fattori registrati per un utente in base al nome utente o userGUID.

Esempio di richiesta 

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

Esempio di risposta

L'esempio seguente mostra il contenuto della risposta in formato 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 risposta contiene i dettagli userGUID, il fattore preferito e il fattore registrato.

Passo 2: ottenere i fattori registrati per un utente utilizzando i filtri

È possibile ottenere i fattori registrati per un utente utilizzando il nome utente o il GUID utente. Sono accettati i valori userIdType riportati di seguito:

  • USER_GUID: ad esempio, qui userId deve contenere USER_GUID, ad esempio "7b3d902ab05b4214"
  • USER_NAME: ad esempio, qui userId deve contenere USER_NAME, ad esempio John.

Esempio di richiesta per recuperare i fattori registrati in base al nome utente

L'esempio riportato di seguito mostra l'esempio di richiesta per ottenere i fattori registrati per un utente in base al nome utente in formato JSON.

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

Esempio di risposta

L'esempio seguente mostra il contenuto della risposta in formato 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 risposta contiene i dettagli userGUID, il fattore preferito e il fattore registrato.

Esempio di richiesta per recuperare i fattori registrati in base al GUID utente

L'esempio riportato di seguito mostra l'esempio di richiesta per ottenere i fattori registrati per un utente in base al GUID utente in formato JSON.

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

Esempio di risposta

L'esempio seguente mostra il contenuto della risposta in formato 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 risposta contiene i dettagli userGUID, il fattore preferito e il fattore registrato.

Avvia e verifica fattore preferito

Questo caso d'uso fornisce un esempio dettagliato dell'utilizzo dell'API di registrazione dei fattori dei domini di Identity per iscriversi all'autenticazione con più fattori (MFA) con verifica dei fattori.

Questi passi presuppongono che i fattori rilevanti dell'autenticazione MFA siano abilitati mediante Configura impostazioni di autenticazione con più fattori.

Scaricare la raccolta di esempi di casi d'uso di autenticazione dei domini di Identity e il file delle variabili globali dalla cartella idcs-factor-verification-api all'interno del repository idm-samples GitHub, quindi importarli in Postman.

Scaricare la raccolta e il file delle variabili globali dalla cartella idcs-factor-verification-api all'interno di GitHub, quindi importarli in Postman.

Per il caso d'uso, attenersi alla procedura riportata di seguito. Ogni passo contiene esempi di richieste e risposte:
Nota

Gli esempi in questa sezione utilizzano userGUID nelle richieste. Puoi richiedere sia userGUID che userOcid nelle tue richieste.

Step1: Avvia verifica del fattore preferito

Questo passo avvia la verifica del fattore preferito di un utente. Se è necessario utilizzare l'API del fattore di verifica senza specificare userGUID, è possibile fornire un ID univoco utente, ad esempio il nome utente userId. Il valore userIdType nella richiesta indica il tipo di credenziale che l'utente sta passando come valore per userId. Sono accettati i valori userIdType riportati di seguito:

  • USER_GUID: ad esempio, qui userId deve contenere USER_GUID, ad esempio "7b3d902ab05b4214"
  • USER_NAME: ad esempio, qui userId deve contenere USER_NAME, ad esempio John.

L'attributo userId contiene il valore effettivo della credenziale utente passata.

Esempio di richiesta

L'esempio riportato di seguito mostra la richiesta POST all'endpoint {{HOST}}/mfa/v1/requests in formato JSON.

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

Esempio di risposta

L'esempio riportato di seguito mostra il contenuto della risposta POST all'endpoint {{HOST}}/mfa/v1/requests in formato JSON dopo l'avvio del fattore preferito nell'ID preferito:


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

Nella risposta, il valore requestId è l'identificativo univoco generato per questa richiesta. Includere requestId in ogni chiamata successiva per completare la verifica dei fattori. factorId è il dispositivo preferito su cui è stato avviato. method è il fattore che l'utente ha avviato. Il file requestState contiene i dati contestuali necessari per elaborare la richiesta.

In questo esempio, viene inviato un messaggio otpCode (in caso di fattore SMS ed EMAIL) tramite SMS al dispositivo mobile dell'utente.

Passo 2: verificare il fattore preferito

Questo passo verifica il fattore passando il valore otpCode in una richiesta PATCH a {{HOST}}/mfa/v1/requests/{{requestId}}.

Il client deve includere i seguenti attributi:

  • otpCode: il codice ricevuto dall'utente sul proprio dispositivo
  • requestState: ricevuto nella risposta del passo 1
  • requestId: ricevuto nella risposta del passo 1

Esempio di richiesta

L'esempio seguente mostra il contenuto della richiesta PATCH in formato JSON. 

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

Esempio di risposta

L'esempio seguente mostra il contenuto della risposta in formato JSON. 

{"status":"success"}

Il successo indica che la verifica è riuscita.

Avvia e verifica un fattore di backup

Questo caso d'uso fornisce un esempio dettagliato dell'utilizzo dell'API di verifica dei domini di Identity per completare la verifica dei fattori del fattore di backup.

Questi passi presuppongono che i fattori rilevanti dell'autenticazione MFA siano abilitati mediante Configura impostazioni di autenticazione con più fattori.

Scaricare la raccolta di esempi di casi d'uso di autenticazione dei domini di Identity e il file delle variabili globali dalla cartella idcs-factor-verification-api all'interno del repository idm-samples GitHub, quindi importarli in Postman.

Per il caso d'uso, attenersi alla procedura riportata di seguito. Ogni passo contiene esempi di richieste e risposte:
Nota

Gli esempi in questa sezione utilizzano userGUID nelle richieste. Puoi richiedere sia userGUID che userOcid nelle tue richieste.

Passo 1: avviare e verificare le domande di sicurezza del fattore di backup

Questo passo avvia la verifica del fattore di backup di un utente. Il client deve fornire sia il file factorId che il file method nella richiesta. Se è necessario utilizzare l'API del fattore di verifica senza specificare userGUID, è possibile fornire un ID univoco utente, ad esempio il nome utente userId. Il valore userIdType nella richiesta indica il tipo di credenziale che l'utente sta passando come valore per userId. Sono accettati i valori userIdType riportati di seguito:

  • USER_GUID: ad esempio, qui userId deve contenere USER_GUID, ad esempio "7b3d902ab05b4214".
  • USER_NAME: ad esempio, qui userId deve contenere USER_NAME, ad esempio Joe John.

L'attributo userId contiene il valore effettivo della credenziale utente passata.

Per ottenere un elenco dei fattori registrati e dei relativi ID per un utente, vedere il caso d'uso Recupera fattori iscritti di un utente. In questo esempio, il fattore di backup scelto è Domande di sicurezza.

Richiedi un esempio per avviare le domande di sicurezza del fattore di backup

L'esempio riportato di seguito mostra il contenuto della richiesta POST in {{HOST}}/mfa/v1/requests/endpoint in formato JSON.

Nota

Il valore factorId preferito contiene l'ID univoco del fattore preferito. Nel caso di SECURITY_QUESTIONS, avrà la stringa fissa "SecurityQuestions".
{
    "userId":"{{userID}}",
    "userIdType":"USER_GUID",
    "factorId":"{{factorID}}",
    "method":"SECURITY_QUESTIONS"
}

Nella risposta, il valore requestId è l'identificativo univoco generato per questa richiesta. Includere requestId in ogni chiamata successiva per completare la verifica dei fattori. Il file requestState contiene i dati contestuali necessari per elaborare la richiesta.

Esempio di risposta

L'esempio riportato di seguito mostra il contenuto della risposta in formato JSON per il metodo di backup 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?"
        }
    ]
}

Nella risposta, il valore requestId è l'identificativo univoco generato per questa richiesta. Includere requestId in ogni chiamata successiva per completare la verifica dei fattori. Il file requestState contiene i dati contestuali necessari per elaborare la richiesta. In questo esempio, una domanda viene inviata di nuovo dall'elenco delle domande registrate a cui l'utente deve rispondere.

Esempio di richiesta per verificare le domande di sicurezza del fattore di backup

Questo passo verifica il fattore di backup passando la risposta alla domanda di sicurezza in una richiesta PATCH a {{HOST}}/mfa/v1/requests/{{requestID}}. Il client deve includere i seguenti attributi:

  • requestState: ricevuto nella risposta del passo 1
  • securityQuestions id/answers: definito dall'utente durante l'iscrizione

Esempio di richiesta

L'esempio seguente mostra il contenuto della richiesta PATCH in formato JSON per SECURITY_QUESTIONS: 
{
 "securityQuestions":[
        {
            "id":"MaidenName",
            "answer":"Smith"
        }
    ],
"requestState": "{{requestState}}"
 }

Esempio di risposta

L'esempio seguente mostra il contenuto della risposta in formato JSON. 

{"status":"success"}

Il successo indica che la verifica è riuscita.

Passo 2: Avviare e verificare il fattore di backup EMAIL

Questo passo avvia la verifica di un fattore di backup EMAIL.

Esempio di richiesta per l'avvio del fattore EMAIL

L'esempio seguente mostra l'esempio di richiesta in formato JSON per il metodo preferito "EMAIL":

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

Esempio di risposta

L'esempio riportato di seguito mostra l'esempio di risposta per avviare il fattore EMAIL in formato JSON.

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

Esempio di richiesta per verificare il fattore EMAIL

L'esempio seguente mostra la richiesta PATCH in formato JSON per il fattore EMAIL:

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

Esempio di risposta

L'esempio seguente mostra il contenuto della risposta in formato JSON per verificare il fattore EMAIL: 

{"status":"success"}

Il successo indica che la verifica è riuscita.

Restituisci fattori OTP senza notificare all'utente

Questo caso d'uso fornisce un esempio di avvio dell'API MFA On Demand per restituire i fattori del passcode monouso (OTP, SMS, e-mail o chiamata telefonica) in una risposta senza avvisare l'utente.

Scaricare la raccolta di esempi di casi d'uso di autenticazione dei domini di Identity e il file delle variabili globali dalla cartella idcs-factor-verification-api all'interno del repository idm-samples GitHub, quindi importarli in Postman.

Questi passi presuppongono che i fattori rilevanti dell'autenticazione MFA siano abilitati mediante Configura impostazioni di autenticazione con più fattori.

Payload richieste
Attributo Valori supportati/Valori di esempio A più valori Dettagli d'uso
userFlowControlledByExternalClient true / falso false
Impostare questa opzione su 
true
e l'OTP verrà restituito nella risposta nel formato cifrato specificato.

Nota: il certificato utilizzato per la cifratura viene caricato nell'applicazione in anticipo e viene fatto riferimento utilizzando l'attributo x5t nell'esempio di richiesta, come indicato di seguito.
x5t Stringa / X509 SHA-1 Certificato Thumbprint

Quando specificato, il servizio utilizza questo certificato caricato per cifrare i dati OTP.

Nota: l'attributo "x5t" deve corrispondere al certificato caricato.
Esempio di richiesta
{
    "userId":"<Unique Id>",
    "userIdType":"USER_NAME/USER_GUID",
    "userFlowControlledByExternalClient": true,
    "x5t" :"<certificate thumbprint>"
}
Payload risposte
Attributo Valori supportati/Valori di esempio A più valori Dettagli d'uso
otp

Mappa

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

Se presente nella risposta, l'attributo contiene l'OTP cifrato con i dettagli riportati di seguito.

  • valore: valore cifrato.
  • alg: algoritmo utilizzato per la cifratura.
  • x5t: Thumbprint SHA-1 X509 del certificato utilizzato per la cifratura.

Esempio di risposta

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

Iscrizione fattore di autenticazione con verifica fattore - SMS

Questo caso d'uso fornisce un esempio dettagliato dell'utilizzo dell'API di registrazione dei fattori dei domini di Identity per iscriversi all'autenticazione con più fattori (MFA) con verifica dei fattori.

Questi passi presuppongono che i fattori rilevanti dell'autenticazione MFA siano abilitati mediante Configura impostazioni di autenticazione con più fattori.

Scaricare la raccolta di esempi di casi d'uso di autenticazione dei domini di Identity e il file delle variabili globali dalla cartella idcs-factor-enrollment-api all'interno del repository idm-samples GitHub, quindi importarli in Postman.

Per il caso d'uso, attenersi alla procedura riportata di seguito. Ogni passo contiene esempi di richieste e risposte:
Nota

Gli esempi in questa sezione utilizzano userGUID nelle richieste. Puoi richiedere sia userGUID che userOcid nelle tue richieste.

Passo 1: Avvia registrazione fattore SMS

Questo passo avvia la registrazione SMS. Il client deve includere i seguenti attributi:

  • method: definisce l'iscrizione al fattore SMS
  • phoneNumber: definisce il numero di telefono in cui verrà inviato il testo SMS
  • countryCode: definisce il prefisso internazionale del numero di telefono in cui verrà inviato il testo SMS

Esempio di richiesta

L'esempio riportato di seguito mostra la richiesta POST all'endpoint {{HOST}}/mfa/v1/users/{{userGUID}}/factors in formato JSON.

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

Esempio di risposta

L'esempio seguente mostra il contenuto della risposta in formato JSON. 

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

displayName è il numero di cellulare. Verrà inviato un messaggio otpCode al dispositivo mobile degli utenti, utilizzato per completare la registrazione.

Passo 1a: inviare di nuovo l'OTP

Se l'utente non riceve l'OTP, questo esempio mostra come richiedere il nuovo invio di un OTP. Il client deve includere i seguenti attributi:

requestState: ricevuto nella risposta del passo 1

resendOtp: Valore booleano che indica che viene ricevuto l'OTP

Esempio di richiesta

L'esempio riportato di seguito mostra la richiesta PATCH all'endpoint {{HOST}}/mfa/v1/users/{{userGUID}}/factors/{{factorID}} in formato JSON.

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

Esempio di risposta

L'esempio seguente mostra il contenuto della risposta in formato JSON.

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

La risposta contiene i seguenti parametri:

  • requestState: che deve essere passato dal client nel passaggio successivo
  • displayName: è il numero di cellulare registrato
  • method: metodo fattore SMS
  • Identificativo univoco factorId: generato per il fattore da registrare
Il successo indica che:
  • Il valore userGUID fornito è valido
  • L'utente è attivo
  • Account utente non bloccato
  • Il fattore SMS è abilitato

Passo 2: Attivazione del fattore SMS

Questo passo attiva la registrazione SMS per l'utente in una richiesta PATCH all'endpoint /mfa/v1/users/{{userGUID}}/factors/{{factorID}}.

Il client deve includere i seguenti attributi:

  • otpCode: il codice ricevuto dall'utente sul proprio dispositivo
  • requestState: ricevuto nella risposta del passo 1

Esempio di richiesta

L'esempio seguente mostra il contenuto della richiesta PATCH in formato JSON. 

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

Esempio di risposta

L'esempio seguente mostra il contenuto della risposta in formato JSON. 

{"status":"success"}

Il successo indica che:

  • OTP è valido
  • Il valore userGUID fornito è valido
  • L'utente è attivo
  • Account utente non bloccato
  • Il fattore SMS è abilitato e la registrazione del fattore è riuscita

Esempi di risposte di errore

L'esempio seguente mostra il messaggio di errore in formato JSON quando userGUID non è valido. Si ottiene un codice di risposta HTTP 404 se userGUID non è valido.
{
    "status": "failed",
    "ecId": "0d1QwglU0000Fy",
    "cause": [
        {
            "code": "AUTH-3018",
            "message": "User not found."
        }
    ]
}

L'esempio seguente mostra il messaggio di errore in formato JSON quando l'utente è bloccato. Viene visualizzato un codice di risposta HTTP 401.

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

Registrazione fattore di autenticazione con verifica fattore - E-mail

Questo caso d'uso fornisce un esempio dettagliato dell'utilizzo dell'API di registrazione dei fattori dei domini di Identity per iscriversi all'autenticazione con più fattori (MFA) con verifica dei fattori.

Questi passi presuppongono che i fattori rilevanti dell'autenticazione MFA siano abilitati mediante Configura impostazioni di autenticazione con più fattori.

Scaricare la raccolta di esempi di casi d'uso di autenticazione dei domini di Identity e il file delle variabili globali dalla cartella idcs-factor-enrollment-api all'interno del repository idm-samples GitHub, quindi importarli in Postman.

Per il caso d'uso, attenersi alla procedura riportata di seguito. Ogni passo contiene esempi di richieste e risposte:
Nota

Gli esempi in questa sezione utilizzano userGUID nelle richieste. Puoi richiedere sia userGUID che userOcid nelle tue richieste.

Passo 1: Avvia iscrizione fattore e-mail

Questo passo avvia la registrazione e-mail. Il client deve includere il seguente attributo:

  • method: definisce l'iscrizione all'e-mail. L'utente non passerà l'ID di posta elettronica. L'ID e-mail principale viene recuperato automaticamente dal profilo dell'utente.

Esempio di richiesta

L'esempio riportato di seguito mostra il contenuto della richiesta POST all'endpoint {{HOST}}/mfa/v1/users/{{userGUID}}/factors in formato JSON. 

{ 
"method": "EMAIL",
}

Esempio di risposta

L'esempio seguente mostra il contenuto della risposta in formato JSON. 

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

Verrà inviato un messaggio otpCode all'ID e-mail dell'utente, utilizzato per completare la registrazione.

La risposta contiene:

  • requestState: che deve essere passato dal client nel passaggio successivo
  • displayName: ID di posta elettronica dell'utente iscritto
  • method: Metodo fattore EMAIL

Il successo indica che:

L'iscrizione al fattore è stata avviata.

Passo 1a: inviare di nuovo l'OTP

L'esempio riportato di seguito mostra la richiesta PATCH all'endpoint {{HOST}}/mfa/v1/users/{{userGUID}}/factors/{{factorID}} in formato JSON.

Se l'utente non riceve l'OTP, questo esempio mostra come richiedere il nuovo invio di un OTP. Il client deve includere i seguenti attributi:

  • requestState: ricevuto nella risposta del passo 1
  • resendOtp: per indicare che viene ricevuto l'OTP

Esempio di richiesta

L'esempio seguente mostra il contenuto della richiesta PATCH in formato JSON. 

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

L'esempio seguente mostra il contenuto della risposta in formato JSON. 

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

La risposta contiene:

  • requestState: deve essere passato dal client nel passaggio successivo
  • displayName: ID e-mail recuperato dal profilo dell'utente
  • method: l'elenco dei metodi da iscrivere al metodo EMAIL
  • factorId: identificativo univoco generato per il fattore da registrare

Il successo indica che:

  • Il valore userGUID o userOcid fornito è valido
  • L'utente è attivo
  • Account utente non bloccato
  • Il fattore EMAIL è abilitato

Passo 2: Attivare il fattore EMAIL

Questo passo attiva la registrazione EMAIL per l'utente, in una richiesta PATCH all'endpoint /mfa/v1/users/{{userGUID}}/factors/{{factorID}}.

Il client deve includere i seguenti attributi:

  • otpCode: il codice ricevuto dall'utente sul proprio ID e-mail
  • requestState: ricevuto nella risposta del passo 1

Esempio di richiesta

L'esempio seguente mostra il contenuto della richiesta PATCH in formato JSON. 

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

Esempio di risposta

L'esempio seguente mostra il contenuto della risposta in formato JSON. 

{"status":"success"}

Il successo indica che:

  • OTP è valido
  • Il valore userGUID o userOcid fornito è valido
  • L'utente è attivo
  • Account utente non bloccato
  • Il fattore EMAIL è abilitato e il fattore viene registrato correttamente

Esempi di risposte di errore

L'esempio seguente mostra il messaggio di errore in formato JSON quando userGUID non è valido. Si ottiene un codice di risposta HTTP 404 se userGUID o userOcid non è valido.
{
    "status": "failed",
    "ecId": "0d1QwglU0000Fy",
    "cause": [
        {
            "code": "AUTH-3018",
            "message": "User not found."
        }
    ]
}

L'esempio seguente mostra il messaggio di errore in formato JSON quando l'EMAIL è disabilitato. Viene visualizzato un codice di risposta HTTP 401.

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