Documentazione dell'infrastruttura Oracle Cloud

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 API di autenticazione solo se si sta creando una propria esperienza di login end-to-end mediante lo sviluppo di un'applicazione di accesso personalizzata che deve essere utilizzata dai domini di identità.
Nota

Questa API di autenticazione non può essere utilizzata per integrare le applicazioni con i domini di identità a scopo di Single Sign-On.

L'API MFA On Demand si basa sul concetto di computer di stato. Le risposte alle richieste informano un client dell'applicazione che 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 creare problemi, in particolare per le applicazioni B2C in cui i controlli sul comportamento dell'utente finale non possono essere applicati. Il requestState fornito in ogni risposta di richiesta 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'utilizzo di un passcode monouso basato sul tempo o di un passcode SMS.
  • Esegue l'iscrizione MFA, la verifica MFA e la gestione del fattore di autenticazione utente.

In questo caso d'uso sono inclusi i set di esempio riportati di seguito.

Iscrizione fattore con verifica

Iscrizione fattore con verifica

Questi casi d'uso forniscono richieste di esempio utilizzando l'API REST dei domini di Identity che consente a un utente di registrarsi per i fattori MFA.

I seguenti casi d'uso illustrano i passi per registrare diversi fattori MFA utilizzando l'API REST:

Recupera fattori registrati di un utente

Questo caso d'uso fornisce un esempio dettagliato dell'uso 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 utilizzando 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 GitHub idm-samples, quindi importarli in Postman.

Il passo da seguire in questo caso d'uso dipende dal fatto che si desidera richiedere utilizzando il userGUID o il User Name:
Nota

Gli esempi riportati in questa sezione utilizzano userGUID nelle richieste. È possibile richiedere sia userGUID che userOcid nelle richieste.

Passo 1: ottenere i fattori registrati 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 userGUID, il fattore preferito e i dettagli del fattore iscritto.

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

È possibile ottenere i fattori registrati per un utente utilizzando Nome utente o GUID utente. Sono accettati i seguenti valori userIdType:

  • USER_GUID- Ad esempio, qui userId deve contenere USER_GUID, ad esempio "7b3d902ab05b4214"
  • USER_NAME- Ad esempio, qui userId deve contenere USER_NAME come 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 relativo 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 userGUID, il fattore preferito e i dettagli del fattore iscritto.

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 userGUID, il fattore preferito e i dettagli del fattore iscritto.

Avvia e verifica fattore preferito

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

Questi passi presuppongono che i fattori rilevanti dell'autenticazione MFA siano abilitati utilizzando 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 GitHub idm-samples, quindi importarli in Postman.

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

Attenersi alla procedura riportata di seguito per lo use case. Ogni passo contiene esempi di richiesta e risposta:
Nota

Gli esempi riportati in questa sezione utilizzano userGUID nelle richieste. È possibile richiedere sia userGUID che userOcid nelle 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 fornire 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 seguenti valori userIdType:

  • 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 Giovanni.

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 seguente 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 avviato dall'utente. Il file requestState contiene i dati contestuali necessari per elaborare la richiesta.

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

Passo 2: Verifica il fattore preferito

Questo passo verifica il fattore passando il 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"}

Operazione riuscita indica che la verifica è riuscita.

Avvia e verifica un fattore di backup

Questo caso d'uso fornisce un esempio dettagliato di 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 utilizzando 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 GitHub idm-samples, quindi importarli in Postman.

Attenersi alla procedura riportata di seguito per lo use case. Ogni passo contiene esempi di richiesta e risposta:
Nota

Gli esempi riportati in questa sezione utilizzano userGUID nelle richieste. È possibile richiedere sia userGUID che userOcid nelle 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 factorId che il method nella richiesta. Se è necessario utilizzare l'API del fattore di verifica senza fornire 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 seguenti valori userIdType:

  • 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 registrati di un utente. In questo esempio, il fattore di backup scelto è Domande di sicurezza.

Esempio di richiesta per avviare le domande di sicurezza dei fattori di backup

L'esempio seguente mostra il contenuto della richiesta POST a {{HOST}}/mfa/v1/requests/endpoint in formato JSON:

Nota

La factorId preferita 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. requestState contiene i dati contestuali necessari per elaborare la richiesta.

Esempio di risposta

L'esempio seguente 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. requestState contiene i dati contestuali necessari per elaborare la richiesta. In questo esempio, viene inviata una domanda dall'elenco delle domande registrate a cui l'utente deve rispondere.

Esempio di richiesta di verifica delle domande di sicurezza dei fattori 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"}

Operazione riuscita indica che la verifica è riuscita.

Passo 2: avvio e verifica del fattore di backup EMAIL

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

Esempio di richiesta per avviare il 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 di verifica del fattore EMAIL

L'esempio riportato di seguito 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 la verifica del fattore EMAIL: 

{"status":"success"}

Operazione riuscita indica che la verifica è riuscita.

Restituisci fattori OTP senza avvisare l'utente

Questo caso d'uso fornisce un esempio di avvio dell'API MFA On Demand per restituire i fattori di 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 GitHub idm-samples, quindi importarli in Postman.

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

Payload richieste
Attribute Valori supportati/valori di esempio Più valori Dettagli sull'utilizzo
userFlowControlledByExternalClient true / false falso
Imposta questa opzione su 
true
e l'OTP verrà restituito nella risposta nel formato cifrato specificato.

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

Se 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
Attribute Valori supportati/valori di esempio Più valori Dettagli sull'utilizzo
otp

Mappa

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

Quando è presente nella risposta, l'attributo contiene l'OTP cifrato con i seguenti dettagli.

  • valore: valore cifrato.
  • alg: algoritmo utilizzato per la cifratura.
  • x5t: SHA-1 X509 Thumbprint 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 autenticazione con verifica fattore - SMS

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

Questi passi presuppongono che i fattori rilevanti dell'autenticazione MFA siano abilitati utilizzando 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 GitHub idm-samples, quindi importarli in Postman.

Attenersi alla procedura riportata di seguito per lo use case. Ogni passo contiene esempi di richiesta e risposta:
Nota

Gli esempi riportati in questa sezione utilizzano userGUID nelle richieste. È possibile richiedere sia userGUID che userOcid nelle richieste.

Passo 1: Avvia iscrizione 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 otpCode al dispositivo mobile degli utenti, che viene utilizzato per completare l'iscrizione.

Passo 1a: inviare di nuovo l'OTP

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

requestState: ricevuto nella risposta del passo 1

resendOtp: Valore booleano per indicare che l'OTP viene ricevuto

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 passo successivo
  • displayName: è il numero di cellulare registrato
  • Metodo del fattore SMS method:
  • Identificativo univoco factorId: generato per il fattore da registrare
Il successo indica che:
  • L'indirizzo userGUID fornito è valido
  • L'utente è attivo
  • L'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
  • L'indirizzo userGUID fornito è valido
  • L'utente è attivo
  • L'account utente non è bloccato
  • Il fattore SMS è abilitato e il fattore è stato registrato correttamente

Esempi di risposta 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. Si ottiene un codice di risposta HTTP 401.

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

Iscrizione fattore autenticazione con e-mail verifica fattore

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

Questi passi presuppongono che i fattori rilevanti dell'autenticazione MFA siano abilitati utilizzando 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 GitHub idm-samples, quindi importarli in Postman.

Attenersi alla procedura riportata di seguito per lo use case. Ogni passo contiene esempi di richiesta e risposta:
Nota

Gli esempi riportati in questa sezione utilizzano userGUID nelle richieste. È possibile richiedere sia userGUID che userOcid nelle richieste.

Passo 1: Avvia iscrizione fattore e-mail

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

  • method: definisce l'iscrizione all'e-mail. L'utente non passerà l'ID e-mail. 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 otpCode all'ID e-mail dell'utente, utilizzato per completare l'iscrizione.

La risposta contiene:

  • requestState: che deve essere passato dal client nel passo successivo
  • ID e-mail displayName: dell'utente registrato
  • method: Metodo del fattore EMAIL

Il successo indica che:

Iscrizione fattore 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 reinvio di un OTP. Il client deve includere i seguenti attributi:

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

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 passo successivo
  • displayName: ID e-mail recuperato dal profilo dell'utente
  • method: elenco dei metodi iscritti al metodo EMAIL
  • factorId: identificativo univoco generato per il fattore da registrare

Il successo indica che:

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

Passo 2: attivazione del 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 email
  • 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 file userGUID o userOcid fornito è valido
  • L'utente è attivo
  • L'account utente non è bloccato
  • Il fattore EMAIL è abilitato e il fattore è stato registrato correttamente

Esempi di risposta 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. Si ottiene un codice di risposta HTTP 401.

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