Documentazione dell'infrastruttura Oracle Cloud

Iscrizione a 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 a più fattori (MFA) utilizzando il fattore SMS.

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 GitHub idm-samples, 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 Generazione del token di accesso mediante l'API di autenticazione.

In questo caso d'uso sono previste tre fasi. Ogni passo contiene esempi di richiesta e risposta:
Nota

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

Step1: creazione dell'iscrizione self-service mediante 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 riportato di seguito 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 risposta errore

L'esempio seguente mostra il messaggio di errore in formato JSON quando userId non è valido. Si ottiene 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 è errato. Si ottiene 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 l'iscrizione self-service mediante OTP tramite SMS

Questo passo richiede che l'OTP venga inviato 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 riportato di seguito 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 utilizzando SMS al dispositivo mobile dell'utente. Nella risposta deviceId e requestId devono essere passati nel passo successivo.

2a. Avvia richiesta di iscrizione Self Service per reinviare OTP tramite SMS

Nel caso in cui l'utente desideri che il server invii nuovamente l'OTP, lo stesso payload indicato nel Passo 2 deve essere inviato di nuovo al server.

Esempio di richiesta

L'esempio riportato di seguito 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 è iscritto all'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 risposta errore

L'esempio seguente mostra il messaggio di errore in formato JSON se l'OTP non è corretto. Si ottiene un codice di risposta HTTP 401 e l'iscrizione 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"
  }
}