Documentazione di Oracle Cloud Infrastructure

Iscrizione all'autenticazione MFA mediante il fattore SMS mediante Self Service

Questo caso d'uso fornisce un esempio dettagliato dell'utilizzo dell'API REST dei domini di Identity per la registrazione self-service nell'autenticazione con più fattori (MFA) mediante SMS Factor.

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

Come passo prerequisito, è necessario ottenere un token ME prima di seguire questi passi. Per informazioni su come ottenere un token ME, vedere Generating Access Token Using Authentication API.

Ci sono tre passaggi in questo caso d'uso. Ogni passo contiene esempi di richieste e risposte:
Nota

In questi passi si presuppone che i fattori rilevanti dell'autenticazione MFA siano abilitati utilizzando Configura impostazioni di autenticazione con più fattori.

Step1: Creare la registrazione Self Service utilizzando il fattore SMS

Questo passo avvia la registrazione SMS in una richiesta POST all'endpoint /admin/v1/MyAuthenticationFactorEnroller. Il client deve includere i seguenti attributi:

  • value: definisce l'ID utente. È possibile effettuare una chiamata GET a {{HOST}}/admin/v1/Me per ottenere il valore "id".
  • displayName: definisce il nome visualizzato del dispositivo
  • countryCode: definisce il prefisso internazionale del numero di telefono in cui verrà inviato il testo SMS
  • phoneNumber: definisce il numero di telefono in cui verrà inviato il testo SMS

Esempio di richiesta

L'esempio seguente mostra il contenuto del corpo della richiesta POST in formato JSON. 

{
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorEnroller"
  ],
  "user": {
    "value": "c810ff4522eb437abac013291c1984d1"
  },
  "displayName": "Joe's Personal Phone",
  "countryCode": "+44",
  "phoneNumber": "1122334455",
  "authnFactors": [
    "SMS"
  ]
}

Esempio di risposta

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

{
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorEnroller"
    ],
    "user": {
        "value": "c810ff4522eb437abac013291c1984d1",
        "$ref": "https://example.identitycloud.com/admin/v1/Users/c810ff4522eb437abac013291c1984d1"
    },
    "displayName": "Joe's Personal Phone",
    "countryCode": "+44",
    "phoneNumber": "XXXXXXX455",
    "authnFactors": [
        "SMS"
    ],
    "meta": {
        "resourceType": "MyAuthenticationFactorEnroller",
        "location": "https://example.identitycloud.com/admin/v1/MyAuthenticationFactorEnroller"
    },
    "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
    "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179"
}

Nella risposta, deviceId e requestId devono essere passati nel passo successivo.

Esempi di risposte di errore

L'esempio seguente mostra il messaggio di errore in formato JSON quando userId non è valido. Viene visualizzato un codice di risposta HTTP 400. 
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error",
        "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error"
    ],
    "detail": "AuthenticationFactorEnroller.user references a User with ID 1fa35f74491d44ef5a7cc25bfdb1c8b1c that does not exist.",
    "status": "400",
    "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error": {
        "messageId": "error.common.validation.invalidReferenceResource"
    }
}

L'esempio seguente mostra il messaggio di errore in formato JSON se un valore phoneNumber non è corretto. Viene visualizzato un codice di risposta HTTP 400.

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error",
        "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error"
    ],
    "detail": "Your phone number +91123 is not valid.",
    "status": "400",
    "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error": {
        "messageId": "error.ssocommon.auth.invalidPhoneNumber",
        "additionalData": {
            "params": "+91123",
            "msgId": "error.ssocommon.auth.invalidPhoneNumber"
        }
    }
}

Passo 2: avviare la registrazione Self Service mediante OTP tramite SMS

Questo passo richiede l'invio di OTP tramite SMS in una richiesta POST all'endpoint /admin/v1/MyAuthenticationFactorInitiator. Il client deve includere i seguenti attributi:

requestId: ricevuto nella risposta del passo 1

deviceId: ricevuto nella risposta del passo 1

userName: nome utente dell'utente

Esempio di richiesta

L'esempio seguente mostra il contenuto del corpo della richiesta POST in formato JSON.

{
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorInitiator"
  ],
  "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
  "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
  "userName": "jbloggs",
  "authFactor": "SMS"
}

Esempio di risposta

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

{
    "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
    "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
    "authFactor": "SMS",
    "userName": "jbloggs",
    "displayName": "Joe's Personal Phone",
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorInitiator"
    ]
}

Un codice OTP viene inviato tramite SMS al dispositivo mobile dell'utente. Nella risposta deviceId e requestId devono essere passati nel passo successivo.

2a. Avvia la richiesta di iscrizione Self Service per inviare nuovamente OTP tramite SMS

Se l'utente desidera che il server invii di nuovo l'OTP, lo stesso payload indicato nel Passo 2 deve essere inviato di nuovo al server.

Esempio di richiesta

L'esempio seguente mostra il contenuto del corpo della richiesta POST in formato JSON.

{
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorInitiator"
  ],
  "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
  "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
  "userName": "jbloggs",
  "authFactor": "SMS"
}

Esempio di risposta

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

{ 
    "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
    "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
    "authFactor": "SMS",
    "userName": "jbloggs",
    "displayName": "Joe's Personal Phone",
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorInitiator"
    ]
}

Un codice OTP viene inviato tramite SMS al dispositivo mobile dell'utente. Nella risposta deviceId e requestId devono essere passati nel passo successivo.

Passo 3: Convalida dell'iscrizione Self Service mediante OTP

Questo passo convalida la registrazione SMS di un utente in una richiesta POST all'endpoint /admin/v1/MyAuthenticationFactorValidator.

Il client deve includere i seguenti attributi:

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

Esempio di richiesta

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

{
  "schemas": [
    "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorValidator"
  ],
  "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
  "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
  "otpCode": "191224",
  "authFactor": "SMS",
  "scenario": "ENROLLMENT"
}

Esempio di risposta

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

{
    "authFactor": "SMS",
    "deviceId": "92142250e2ab4608b5c6532eb73e3d7c",
    "requestId": "a0a7f9bf-13a8-43f3-bcc7-2087dc3f7a18o-o1548346179",
    "scenario": "ENROLLMENT",
    "status": "SUCCESS",
    "displayName": "Joe's Personal Phone",
    "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorValidator"
    ],
    "mfaStatus": "ENROLLED",
    "mfaPreferredDevice": "2b27b8c072d64b899d41c8470acea32a",
    "mfaPreferredAuthenticationFactor": "SMS",
    "securityQuestionsPresent": false,
    "devicesCount": 3,
    "emailFactorEnrolled": true
}
Nella risposta, l'attributo mfaStaus:"ENROLLED" indica che l'utente si è registrato per l'autenticazione MFA. L'attributo mfapreferredAuthenticationFactor indica il fattore impostato come metodo preferito. In questo caso, è SMS.
Nota

Questo valore può essere diverso se il primo fattore registrato è diverso da SMS.

Esempi di risposte di errore

L'esempio seguente mostra il messaggio di errore in formato JSON se OTP è errato. Si ottiene un codice di risposta HTTP 401 e la registrazione non riesce.

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error",
    "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error"
  ],
  "detail": "Invalid passcode.",
  "status": "401",
  "urn:ietf:params:scim:api:oracle:idcs:extension:messages:Error": {
    "messageId": "error.ssocommon.auth.invalidPasscode"
  }
}