Condividi tramite

Informazioni di riferimento API di autenticazione nativa

  • Articolo

Si applica a: Cerchio bianco con un simbolo X grigio. Tenant della forza lavoro Cerchio verde con un segno di spunta bianco. Tenant esterni (altre informazioni)

L'autenticazione nativa di Microsoft Entra consente di ospitare l'interfaccia utente dell'app nell'applicazione client invece di delegare l'autenticazione ai browser, ottenendo un'esperienza di autenticazione integrata in modo nativo. Gli sviluppatori hanno il controllo completo sull'aspetto dell'interfaccia di accesso.

Questo articolo informativo sulle API illustra le informazioni dettagliate necessarie solo quando si effettuano manualmente richieste HTTP non elaborate per eseguire il flusso. Tuttavia, questo approccio non è consigliato. Quindi, quando possibile, usare un SDK di autenticazione Microsoft e supportato. Per altre informazioni su come usare l'SDK, vedere Esercitazione: Preparare l'app per dispositivi mobili Android per l'autenticazione nativa ed Esercitazione: Preparare l'app per dispositivi mobili iOS per l'autenticazione nativa.

Quando una chiamata agli endpoint API ha esito positivo, si riceve sia un token ID per l'identificazione dell'utente che un token di accesso per chiamare le API protette. Tutte le risposte dell'API sono in formato JSON.

L'API di autenticazione nativa di Microsoft Entra supporta l'iscrizione e l'accesso per due metodi di autenticazione:

  • Posta elettronica con password, che supporta l'iscrizione e l'accesso con un indirizzo e-mail e una password e la reimpostazione della password self-service (SSPR).

  • Passcode monouso tramite e-mail, che supporta l'iscrizione e l'accesso con passcode monouso tramite e-mail.

Nota

Attualmente, gli endpoint dell'API di autenticazione nativa non supportano la Condivisione di risorse tra le origini (CORS).

Prerequisiti

  1. Microsoft Entra per ID esterno per tenant clienti. Se non se ne dispone già, iscriversi per ottenere una versione di valutazione gratuita.

  2. Se non lo si ha già fatto, registrare un’applicazione nell'interfaccia di amministrazione di Microsoft Entra. Assicurarsi di concedere autorizzazioni delegate e abilitare flussi di autenticazione client pubblica e nativa.

  3. Se non lo si ha già fatto, creare un flusso utente nell'interfaccia di amministrazione di Microsoft Entra. Durante la creazione del flusso utente, prendere nota degli attributi utente configurati necessari, in quanto sono quelli che Microsoft Entra prevede che l'app invii. In Provider di identità selezionare l’opzione Invia passcode monouso per e-mail.

  4. Associare la registrazione dell'app al flusso utente.

  5. Per il flusso di accesso, registrare un utente cliente, che viene usato per testare le API di accesso. In alternativa, è possibile ottenere questo utente di test dopo aver eseguito il flusso di iscrizione.

  6. Per il flusso di reimpostazione della password self-service, abilitare la reimpostazione della password self-service per gli utenti clienti nel tenant clienti. La reimpostazione della password self-service è disponibile per gli utenti clienti che usano l’e-mail con il metodo di autenticazione della password.

Token di continuazione

Ogni volta che si chiama un endpoint in uno qualsiasi dei flussi, dell'accesso, dell'iscrizione o della reimpostazione della password self-service, l'endpoint include un token di continuazione nella risposta. Il token di continuazione è un identificatore univoco usato da Microsoft Entra ID per mantenere lo stato tra le chiamate a endpoint differenti all'interno dello stesso flusso. È necessario includere questo token nelle richieste successive all’interno dello stesso flusso.

Ogni token di continuazione è valido per un periodo specifico e può essere usato solo per le richieste successive all'interno dello stesso flusso.

Informazioni di riferimento API di iscrizione

Per completare un flusso di iscrizione utente per un metodo di autenticazione, l'app interagisce con quattro endpoint, /signup/v1.0/start, /signup/v1.0/challenge /signup/v1.0/continue, e /token.

Endpoint dell'API di iscrizione

Endpoint Descrizione
/signup/v1.0/start Questo endpoint avvia il flusso di iscrizione. Passare l'ID applicazione valido, il nuovo nome utente e il tipo di test per ricevere nuovamente un nuovo token di continuazione. L'endpoint può restituire una risposta per indicare all'applicazione di usare un flusso di autenticazione Web se i metodi di autenticazione scelti dall'applicazione non sono supportati da Microsoft Entra.
/signup/v1.0/challenge L'app chiama questo endpoint con un elenco di tipi di test supportati da Microsoft Entra. Microsoft Entra seleziona quindi uno dei metodi di autenticazione supportati per l'autenticazione dell'utente.
/signup/v1.0/continue Questo endpoint consente di continuare il flusso per creare l'account utente o interrompere il flusso a causa di requisiti mancanti, ad esempio requisiti dei criteri password o formati di attributo errati. Questo endpoint genera un token di continuazione, quindi lo restituisce all'app. L'endpoint può restituire una risposta per indicare all'applicazione di usare un flusso di autenticazione basato sul Web se l'applicazione non supporta un metodo di autenticazione selezionato da Microsoft Entra.
/token L'applicazione chiama questo endpoint per richiedere infine i token di sicurezza. L'app deve includere il token di continuazione acquisito dall'ultima chiamata riuscita all'endpoint /signup/v1.0/continue.

Tipi di test di iscrizione

L'API consente all'app client di annunciare i metodi di autenticazione supportati, quando effettua una chiamata a Microsoft Entra. A tale scopo, l'app usa il parametro challenge_type nella richiesta dell’app. Questo parametro contiene valori predefiniti, che rappresentano metodi di autenticazione differenti.

Ulteriori informazioni sui tipi di test nei tipi di test di autenticazione nativa. Questo articolo illustra i valori del tipo di verifica da usare per un metodo di autenticazione.

Dettagli del protocollo di flusso di iscrizione

Il diagramma di sequenza illustra il flusso del processo di iscrizione.

Diagramma del flusso di iscrizione all'autenticazione nativa.

Questo diagramma indica che l'app raccoglie il nome utente (indirizzo e-mail), la password (per l’e-mail con metodi di autenticazione della password) e gli attributi dell'utente in momenti diversi (e possibilmente in schermate separate). Tuttavia, è possibile progettare l'app per raccogliere il nome utente (e-mail), la password e tutti i valori di attributo obbligatori e facoltativi nella stessa schermata, per poi inviarli tutti tramite l'endpoint /signup/v1.0/start. In questo caso, l'app non deve effettuare chiamate e gestire le risposte per i passaggi facoltativi.

Passaggio 1: Richiedere di avviare il flusso di iscrizione

Il flusso di iscrizione inizia con l'applicazione che effettua una richiesta POST all'endpoint /signup/v1.0/start per avviare il flusso di iscrizione.

Di seguito sono riportati alcuni esempi della richiesta (la richiesta di esempio è suddivisa in diverse righe ai fini della leggibilità):

Esempio 1:

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&username=contoso-consumer@contoso.com

Esempio 2 (includere attributi utente e password nella richiesta):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&password={secure_password}
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postalCode": "{user_postal_code}"}
&username=contoso-consumer@contoso.com
Parametro Richiesto Descrizione
tenant_subdomain Sì Sottodominio del tenant esterno creato. Nell'URL sostituire {tenant_subdomain} con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se il sottodominio del tenant non è disponibile, vedere come leggere i dettagli del tenant.
client_id Sì ID applicazione (client) dell'app registrata nell'interfaccia di amministrazione di Microsoft Entra.
username Sì Indirizzo e-mail dell'utente cliente con cui desidera iscriversi, ad esempio contoso-consumer@contoso.com.
challenge_type Sì Elenco delimitato da spazi di stringhe di tipo di test di autorizzazione supportate dall'app, ad esempio oob password redirect. L'elenco deve includere sempre il tipo di test redirect. Si prevede che il valore sia oob redirect o oob password redirect per l’e-mail con il metodo di autenticazione della password.
password No Valore della password che l'app raccoglie dall'utente cliente. È possibile inviare la password di un utente tramite /signup/v1.0/start o versione successiva nell'endpoint /signup/v1.0/continue. Sostituire {secure_password} con il valore della password che l'app raccoglie dall'utente cliente. È responsabilità dell'utente confermare di essere a conoscenza della password che desidera usare fornendo il campo di conferma della password nell'interfaccia utente dell'app. È inoltre necessario assicurarsi che l'utente sia a conoscenza di ciò che costituisce una password complessa in base ai criteri dell'organizzazione. Ulteriori informazioni sui criteri sulle password di Microsoft Entra.
Questo parametro è applicabile solo per l’e-mail con il metodo di autenticazione della password.
attributes No I valori degli attributi utente raccolti dall'app dall'utente cliente. Il valore è una stringa, ma è formattato come oggetto JSON i cui valori chiave sono nomi programmabili di attributi utente. Questi attributi possono essere compilati o personalizzati e possono essere obbligatori o facoltativi. I nomi delle chiavi dell'oggetto dipendono dagli attributi configurati dall'amministratore nell'interfaccia di amministrazione di Microsoft Entra. È possibile inviare alcuni o tutti gli attributi utente tramite l'endpoint /signup/v1.0/start o versione successiva nell'endpoint /signup/v1.0/continue. Se si inviano tutti gli attributi necessari tramite l'endpoint /signup/v1.0/start, non è necessario inviare attributi nell'endpoint /signup/v1.0/continue. Tuttavia, se si inviano alcuni attributi obbligatori tramite l’endpoint /signup/v1.0/start, è possibile inviare gli attributi obbligatori rimanenti in un secondo momento nell'endpoint /signup/v1.0/continue. Sostituire {given_name}, {user_age} e {postal_code} con i valori nome, età e CAP rispettivamente raccolti dall'app dall'utente cliente. Microsoft Entra ignora eventuali attributi inviati che non esistono.

Risposta in caso di esito positivo

Ecco un esempio di risposta con esito positivo:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "AQABAAEAAA…",
}
Parametro Descrizione
continuation_token Token di continuazione restituito da Microsoft Entra.

Se un'app non supporta un metodo di autenticazione richiesto da Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un tipo di test di reindirizzamento nella risposta:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}
Parametro Descrizione
challenge_type Microsoft Entra restituisce una risposta con un tipo di test. Il valore di questo tipo di test è il reindirizzamento, che consente all'app di usare il flusso di autenticazione basato sul Web.

Questa risposta viene considerata riuscita, ma l'app deve passare a un flusso di autenticazione basato sul Web. In questo caso, è consigliabile usare una libreria di autenticazione predefinita e supportata da Microsoft.

Risposta con errore

Esempio:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "user_already_exists", 
    "error_description": "AADSTS1003037: It looks like you may already have an account.... .\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...", 
    "error_codes": [ 
        1003037 
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
}
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errore che si verificano e reagire ai suddetti.
error_description Messaggio di errore specifico che consente di identificare la causa di un errore di autenticazione.
error_codes Elenco di codici di errore specifici di Microsoft Entra che consentono di diagnosticare gli errori.
timestamp Data/ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta che consente di diagnosticare gli errori.
correlation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.
invalid_attributes Elenco (array di oggetti) di attributi che non sono stati convalidati. Questa risposta è possibile se l'app invia attributi utente e il valore del parametro suberror è attribute_validation_failed.
suberror Stringa di codice di errore che può essere usata per classificare ulteriormente i tipi di errore.

Di seguito sono riportati i possibili errori che è possibile riscontrare (valori possibili del parametro error) :

Valore di errore Descrizione
invalid_request La convalida del parametro della richiesta non è riuscita, ad esempio quando il valore del parametro challenge_type include un metodo di autenticazione non supportato o la richiesta non include il parametro client_id, il valore dell'ID client è vuoto o non valido. Usare il parametro error_description per apprendere la causa esatta dell'errore.
invalid_client L'ID client che l’app include nella richiesta è per un'app che non dispone della configurazione di autenticazione nativa, ad esempio non è un client pubblico oppure l'autenticazione nativa non è abilitata. Usare il parametro suberror per apprendere la causa esatta dell'errore.
unauthorized_client L'ID client usato nella richiesta ha un formato ID client valido, ma non è presente nel tenant esterno oppure non è corretto.
unsupported_challenge_type Il valore del parametro challenge_type non include il tipo di test redirect.
user_already_exists L'utente esiste già.
invalid_grant La password che l'app invia non soddisfa tutti i requisiti di complessità, ad esempio la password è troppo breve. Usare il parametro suberror per apprendere la causa esatta dell'errore.
Questo parametro è applicabile solo per l’e-mail con il metodo di autenticazione della password.

Se il parametro di errore ha un valore di invalid_grant, Microsoft Entra include un parametro suberror nella risposta. Di seguito sono riportati i valori possibili del parametro suberror per un errore di invalid_grant:

Valore sub-errore Descrizione
password_too_weak La password è troppo debole in quanto non soddisfa i requisiti di complessità. Ulteriori informazioni sui criteri sulle password di Microsoft Entra. Questa risposta è possibile se l'app invia una password utente.
password_too_short La nuova password contiene meno di 8 caratteri. Ulteriori informazioni sui criteri sulle password di Microsoft Entra. Questa risposta è possibile se l'app invia una password utente.
password_too_long La nuova password contiene più di 256 caratteri. Ulteriori informazioni sui criteri sulle password di Microsoft Entra. Questa risposta è possibile se l'app invia una password utente.
password_recently_used La nuova password non deve corrispondere a una usata di recente. Ulteriori informazioni sui criteri sulle password di Microsoft Entra. Questa risposta è possibile se l'app invia una password utente.
password_banned La nuova password contiene una parola, una frase o un criterio vietato. Ulteriori informazioni sui criteri sulle password di Microsoft Entra. Questa risposta è possibile se l'app invia una password utente.
password_is_invalid La password non è valida, ad esempio perché usa caratteri non consentiti. Ulteriori informazioni sui criteri sulle password di Microsoft Entra. Questa risposta è possibile se l'app invia una password utente.

Se il parametro di errore ha un valore di invalid_client, Microsoft Entra include un parametro suberror nella risposta. Di seguito sono riportati i valori possibili del parametro suberror per un errore di invalid_client:

Valore sub-errore Descrizione
nativeauthapi_disabled ID client per un'app che non è abilitato per l'autenticazione nativa.

Nota

Se si inviano tutti gli attributi necessari tramite l’endpoint /signup/v1.0/start, ma non tutti gli attributi facoltativi, non sarà possibile inviare altri attributi facoltativi in un secondo momento tramite l'endpoint /signup/v1.0/continue. Microsoft Entra non richiede esplicitamente attributi facoltativi perché non sono obbligatori per il completamento del flusso di iscrizione. Vedere la tabella nella sezione Invio degli attributi utente agli endpoint per informazioni sugli attributi utente che è possibile inviare agli endpoint /signup/v1.0/start e /signup/v1.0/continue.

Passaggio 2: Selezionare un metodo di autenticazione

L'app richiede a Microsoft Entra di selezionare uno dei tipi di verifica supportati per l'autenticazione dell'utente. A tale scopo, l'app effettua una chiamata all'endpoint /signup/v1.0/challenge. L'app deve includere il token di continuazione acquisito dall'endpoint /signup/v1.0/start nella richiesta.

Di seguito è riportato un esempio della richiesta (la richiesta di esempio è suddivisa in diverse righe ai fini della leggibilità).

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…
Parametro Richiesto Descrizione
tenant_subdomain Sì Sottodominio del tenant esterno creato. Nell'URL sostituire {tenant_subdomain} con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se il sottodominio del tenant non è disponibile, vedere come leggere i dettagli del tenant.
client_id Sì ID applicazione (client) dell'app registrata nell'interfaccia di amministrazione di Microsoft Entra.
challenge_type No Elenco delimitato da spazi di stringhe di tipo di test di autorizzazione supportate dall'app, ad esempio oob password redirect. L'elenco deve includere sempre il tipo di test redirect. Il valore previsto è oob redirect per il passcode monouso tramite e-mail e oob password redirect per l’e-mail con metodo di autenticazione password.
continuation_token Sì Token di continuazione restituito da Microsoft Entra nella richiesta precedente.

Risposta in caso di esito positivo

Microsoft Entra invia un passcode monouso all’e-mail dell'utente, quindi risponde con il tipo di test con il valore oob e informazioni aggiuntive sul passcode monouso:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "interval": 300,
    "continuation_token": "AQABAAEAAAYn...",
    "challenge_type": "oob",
    "binding_method": "prompt",
    "challenge_channel": "email",
    "challenge_target_label": "c***r@co**o**o.com",
    "code_length": 8
}
Parametro Descrizione
interval L'intervallo di tempo in secondi che l'app deve attendere prima di tentare di inviare nuovamente l’OTP.
continuation_token Token di continuazione restituito da Microsoft Entra.
challenge_type Tipo di test selezionato per l'autenticazione dell'utente.
binding_method L'unico valore valido è prompt. Questo parametro può essere usato in futuro per offrire più modi per l'utente di immettere il passcode monouso. Emesso se challenge_type è oob
challenge_channel Tipo del canale tramite il quale è stato inviato il passcode monouso. Al momento, è supportato solo il canale e-mail.
challenge_target_label Messaggio e-mail offuscato in cui è stato inviato il passcode monouso.
code_length Lunghezza del passcode monouso generato da Microsoft Entra.

Se un'app non supporta un metodo di autenticazione richiesto da Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un tipo di test di reindirizzamento nella risposta:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "challenge_type": "redirect"
}
Parametro Descrizione
challenge_type Microsoft Entra restituisce una risposta con un tipo di test. Il valore di questo tipo di test è il reindirizzamento, che consente all'app di usare il flusso di autenticazione basato sul Web.

Questa risposta viene considerata riuscita, ma l'app deve passare a un flusso di autenticazione basato sul Web. In questo caso, è consigliabile usare una libreria di autenticazione predefinita e supportata da Microsoft.

Risposta con errore

Esempio:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
}
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errore che si verificano e reagire ai suddetti.
error_description Messaggio di errore specifico che consente di identificare la causa di un errore di autenticazione.
error_codes Elenco di codici di errore specifici di Microsoft Entra che consentono di diagnosticare gli errori.
timestamp Data/ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta che consente di diagnosticare gli errori.
correlation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.

Di seguito sono riportati i possibili errori che è possibile riscontrare (valori possibili del parametro error) :

Valore di errore Descrizione
invalid_request La convalida dei parametri della richiesta non è riuscita, ad esempio l'ID client è vuoto o non valido.
expired_token Il token di continuazione è scaduto.
unsupported_challenge_type Il valore del parametro challenge_type non include il tipo di test redirect.
invalid_grant Il token di continuazione non è valido.

Passaggio 3: Inviare un passcode monouso

L'app invia il passcode monouso inviato all’e-mail dell'utente. Poiché si invia un passcode monouso, è necessario un parametro oob e il parametro grant_type deve avere un valore oob.

Di seguito è riportato un esempio della richiesta (la richiesta di esempio è suddivisa in diverse righe ai fini della leggibilità):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=oob 
&oob={otp_code}
Parametro Richiesto Descrizione
tenant_subdomain Sì Sottodominio del tenant esterno creato. Nell'URL sostituire {tenant_subdomain} con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se il sottodominio del tenant non è disponibile, vedere come leggere i dettagli del tenant.
continuation_token Sì Token di continuazione restituito da Microsoft Entra nella richiesta precedente.
client_id Sì ID applicazione (client) dell'app registrata nell'interfaccia di amministrazione di Microsoft Entra.
grant_type Sì Non è possibile usare una richiesta all'endpoint /signup/v1.0/continueper inviare passcode monouso, password o attributi utente. In questo caso, il valore grant_type viene usato per distinguere tra questi tre casi d'uso. I valori possibili per il grant_type sono oob, password, attributi. In questa chiamata, poiché si invia un passcode monouso, il valore dovrebbe essere oob.
oob Sì Passcode monouso ricevuto dall'utente cliente nel messaggio e-mail. Sostituire {otp_code} con i valori passcode monouso ricevuto dall'utente cliente nel messaggio e-mail. Per inviare nuovamente un passcode monouso, l'app deve effettuare nuovamente una richiesta all'endpoint /signup/v1.0/challenge.

Quando l'app invia correttamente il passcode monouso, il flusso di iscrizione dipende dagli scenari, come illustrato nella tabella:

Scenario Come procedere
L'app invia correttamente la password dell'utente (per l’e-mail con il metodo di autenticazione della password) tramite l'endpoint /signup/v1.0/start e non sono configurati attributi nell'interfaccia di amministrazione di Microsoft Entra o tutti gli attributi utente necessari sono inviati tramite l'endpoint /signup/v1.0/start. Microsoft Entra rilascia un token di continuazione. L'app può usare il token di continuazione per richiedere token di sicurezza, come illustrato nel passaggio 5.
L'app invia correttamente la password dell'utente (per l’e-mail con il metodo di autenticazione della password) tramite il /signup/v1.0/start, ma non tutti gli attributi utente necessari, Microsoft Entra indica gli attributi che l'app deve inviare come illustrato in attributi utente necessari. L'app deve inviare gli attributi utente necessari tramite l'endpoint /signup/v1.0/continue. La risposta è simile a quella in Attributi utente necessari. Inviare gli attributi utente visualizzati negli invia attributi utente.
L'app non invia la password dell'utente (per l’e-mail con il metodo di autenticazione della password) tramite l’endpoint /signup/v1.0/start. La risposta di Microsoft Entra indica che è necessaria la credenziale. Vedere la risposta.
Tale risposta è possibile per l’e-mail con il metodo di autenticazione della password.

Response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "credential_required",
    "error_description": "AADSTS55103: Credential required. Trace ID: d6966055-...-80500 Correlation ID: 3944-...-60d6 Timestamp: yy-mm-dd 02:37:33Z",
    "error_codes": [
        55103
    ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABEQEAAAA..."
}
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errore che si verificano e reagire ai suddetti.
error_description Messaggio di errore specifico che consente di identificare la causa di un errore di autenticazione.
error_codes Elenco di codici di errore specifici di Microsoft Entra che consentono di diagnosticare gli errori.
timestamp Data/ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta che consente di diagnosticare gli errori.
correlation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.
continuation_token Token di continuazione restituito da Microsoft Entra.
suberror Stringa di codice di errore che può essere usata per classificare ulteriormente i tipi di errore.

Di seguito sono riportati i possibili errori che è possibile riscontrare (valori possibili del parametro error) :

Valore di errore Descrizione
credential_required L'autenticazione è necessaria per la creazione dell'account, per cui è necessario effettuare una chiamata all'endpoint /signup/v1.0/challenge per determinare le credenziali che l'utente deve fornire.
invalid_request La convalida del parametro della richiesta non è riuscita, ad esempio una convalida del token di continuazione non è riuscita, oppure la richiesta non include il parametro client_id o il valore dell'ID client è vuoto o non valido o l’amministratore tenant esterno non ha abilitato l’OTP e-mail per tutti gli utenti tenant.
invalid_grant Il tipo di concessione incluso nella richiesta non è valido o supportato, oppure il valore OTP non è corretto.
expired_token Il token di continuazione incluso nella richiesta è scaduto.

Se il parametro di errore ha un valore di invalid_grant, Microsoft Entra include un parametro suberror nella risposta. Di seguito sono riportati i valori possibili del parametro suberror per un errore di invalid_grant:

Valore sub-errore Descrizione
invalid_oob_value Il valore del passcode monouso non è valido.

Affinché le credenziali della password vengano raccolte dall'utente, l'app deve effettuare una chiamata all'endpoint /signup/v1.0/challenge per determinare le credenziali che l'utente deve fornire.

Di seguito è riportato un esempio della richiesta (la richiesta di esempio è suddivisa in diverse righe ai fini della leggibilità):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…
Parametro Richiesto Descrizione
tenant_subdomain Sì Sottodominio del tenant esterno creato. Nell'URL sostituire {tenant_subdomain} con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se il sottodominio del tenant non è disponibile, vedere come leggere i dettagli del tenant.
client_id Sì ID applicazione (client) dell'app registrata nell'interfaccia di amministrazione di Microsoft Entra.
challenge_type No Elenco delimitato da spazi di stringhe di tipo di test di autorizzazione supportate dall'app, ad esempio oob password redirect. L'elenco deve includere sempre il tipo di test redirect. Per il flusso di iscrizione di e-mail con password, il valore dovrebbe contenere password redirect.
continuation_token Sì Token di continuazione restituito da Microsoft Entra nella richiesta precedente.

Risposta in caso di esito positivo

Se la password è il metodo di autenticazione configurato per l'utente nell'interfaccia di amministrazione di Microsoft Entra, all'app viene restituita una risposta di esito positivo con il token di continuazione.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "challenge_type": "password",
    "continuation_token": " AQABAAEAAAAty..."
}
Parametro Descrizione
challenge_type La password viene restituita nella risposta per le credenziali necessarie.
continuation_token Token di continuazione restituito da Microsoft Entra.

Se un'app non supporta un metodo di autenticazione richiesto da Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un tipo di test di reindirizzamento nella risposta:

HTTP/1.1 200 OK
Content-Type: application/json

{     
    "challenge_type": "redirect" 
}
Parametro Descrizione
challenge_type Microsoft Entra restituisce una risposta con un tipo di test. Il valore di questo tipo di test è il reindirizzamento, che consente all'app di usare il flusso di autenticazione basato sul Web.

Questa risposta viene considerata riuscita, ma l'app deve passare a un flusso di autenticazione basato sul Web. In questo caso, è consigliabile usare una libreria di autenticazione predefinita e supportata da Microsoft.

Passaggio 4: Autenticare e ottenere il token per iscriversi

L'app deve inviare le credenziali dell'utente, in questo caso password, richieste da Microsoft Entra nel passaggio precedente. L'app deve inviare credenziali password se non lo ha fatto tramite l'endpoint /signup/v1.0/start. L'app effettua una richiesta all'endpoint /signup/v1.0/continue per inviare la password. Poiché si invia una password, è necessario un parametro password e il parametro grant_type deve avere un valore password.

Di seguito è riportato un esempio della richiesta (la richiesta di esempio è suddivisa in diverse righe ai fini della leggibilità):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=password 
&password={secure_password}
Parametro Richiesto Descrizione
tenant_subdomain Sì Sottodominio del tenant esterno creato. Nell'URL sostituire {tenant_subdomain} con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se il sottodominio del tenant non è disponibile, vedere come leggere i dettagli del tenant.
continuation_token Sì Token di continuazione restituito da Microsoft Entra nel passaggio precedente.
client_id Sì ID applicazione (client) dell'app registrata nell'interfaccia di amministrazione di Microsoft Entra.
grant_type Sì Non è possibile usare una richiesta all'endpoint /signup/v1.0/continueper inviare passcode monouso, password o attributi utente. In questo caso, il valore grant_type viene usato per distinguere tra questi tre casi d'uso. I valori possibili per il grant_type sono oob, password, attributi. In questa chiamata, poiché si invia la password di un utente, il valore dovrebbe essere password.
password Sì Valore della password che l'app raccoglie dall'utente cliente. Sostituire {secure_password} con il valore della password che l'app raccoglie dall'utente cliente. È responsabilità dell'utente confermare di essere a conoscenza della password che desidera usare fornendo il campo di conferma della password nell'interfaccia utente dell'app. È inoltre necessario assicurarsi che l'utente sia a conoscenza di ciò che costituisce una password complessa in base ai criteri dell'organizzazione. Ulteriori informazioni sui criteri sulle password di Microsoft Entra.

Risposta in caso di esito positivo

Se la richiesta ha esito positivo, ma non sono stati configurati attributi nell'interfaccia di amministrazione di Microsoft Entra o tutti gli attributi necessari sono stati inviati tramite l'endpoint /signup/v1.0/start, l'app ottiene un token di continuazione senza inviare attributi. L'app può usare il token di continuazione per richiedere token di sicurezza, come illustrato nel passaggio 5. In caso contrario, la risposta di Microsoft Entra indica che l'app deve inviare attributi obbligatori. Tali attributi, incorporati o personalizzati, sono stati configurati nell'interfaccia di amministrazione di Microsoft Entra dall'amministratore tenant.

Attributi utente obbligatori

Questa risposta richiede all'app di inviare valori per gli attributi name, *age e phone.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "attributes_required",
    "error_description": "User attributes required",
    "error_codes": [
            55106
        ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABAAEAAAAtn...",
    "required_attributes": [
        {
            "name": "displayName",
            "type": "string",
            "required": true,
            "options": {
              "regex": ".*@.**$"
            }
        },
        {
            "name": "extension_2588abcdwhtfeehjjeeqwertc_age",
            "type": "string",
            "required": true
        },
        {
            "name": "postalCode",
            "type": "string",
            "required": true,
            "options": {
              "regex":"^[1-9][0-9]*$"
            }
        }
    ],
}

Nota

Gli attributi personalizzati (noti anche come estensioni di directory) vengono denominati usando la convenzione extension_{appId-without-hyphens}_{attribute-name} in cui {appId-without-hyphens} è la versione rimossa dell'ID client per l'app delle estensioni. Ad esempio, se l'ID client dell'app delle estensioni è 2588a-bcdwh-tfeehj-jeeqw-ertc e il nome dell'attributo è hobbies, l'attributo personalizzato viene denominato come extension_2588abcdwhtfeehjjeeqwertc_hobbies. Ulteriori informazioni sugli attributi personalizzati e sull'app delle estensioni .

Parametro Descrizione
error Questo attributo viene impostato se Microsoft Entra non riesce a creare l'account utente perché è necessario verificare o inviare un attributo.
error_description Messaggio di errore specifico che consente di identificare la causa dell'errore.
error_codes Elenco di codici di errore specifici di Microsoft Entra che consentono di diagnosticare gli errori.
timestamp Data/ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta che consente di diagnosticare gli errori.
correlation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.
continuation_token Token di continuazione restituito da Microsoft Entra.
required_attributes Elenco (array di oggetti) di attributi che l'app deve inviare alla chiamata successiva per continuare. Questi attributi sono gli attributi aggiuntivi che l'app deve inviare a parte il nome utente. Microsoft Entra include questo parametro come risposta se il valore del parametro error è attributes_required.

Di seguito sono riportati i possibili errori che è possibile riscontrare (valori possibili del parametro error) :

Valore di errore Descrizione
invalid_request La convalida del parametro della richiesta non è riuscita, ad esempio una convalida del token di continuazione non è riuscita, oppure la richiesta non include il parametro client_id o il valore dell'ID client è vuoto o non valido.
invalid_grant Il tipo di concessione incluso nella richiesta non è valido o supportato. I valori possibili per grant_type sono oob, password, attributi
expired_token Il token di continuazione incluso nella richiesta è scaduto.
attributes_required È necessario uno o più attributi utente.

Se un'app non supporta un metodo di autenticazione richiesto da Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un tipo di test di reindirizzamento nella risposta:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}
Parametro Descrizione
challenge_type Microsoft Entra restituisce una risposta con un tipo di test. Il valore di questo tipo di test è il reindirizzamento, che consente all'app di usare il flusso di autenticazione basato sul Web.

Questa risposta viene considerata riuscita, ma l'app deve passare a un flusso di autenticazione basato sul Web. In questo caso, è consigliabile usare una libreria di autenticazione predefinita e supportata da Microsoft.

Risposta con errore

Esempio:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "invalid_grant",
    "error_description": "New password is too weak",
    "error_codes": [
        399246
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6",
    "suberror": "password_too_weak"
}
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errore che si verificano e reagire ai suddetti.
error_description Messaggio di errore specifico che consente di identificare la causa di un errore di autenticazione.
error_codes Elenco di codici di errore specifici di Microsoft Entra che consentono di diagnosticare gli errori.
timestamp Data/ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta che consente di diagnosticare gli errori.
correlation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.
suberror Stringa di codice di errore che può essere usata per classificare ulteriormente i tipi di errore.

Di seguito sono riportati i possibili errori che è possibile riscontrare (valori possibili del parametro error) :

Valore di errore Descrizione
invalid_request La convalida dei parametri della richiesta non è riuscita, ad esempio quando il parametro challenge_type include un tipo di test non valido.
invalid_grant La concessione inviata non è valida, ad esempio la password inviata è troppo corta. Usare il parametro suberror per apprendere la causa esatta dell'errore.
expired_token Il token di continuazione è scaduto.
attributes_required È necessario uno o più attributi utente.

Se il parametro di errore ha un valore di invalid_grant, Microsoft Entra include un parametro suberror nella risposta. Ecco i valori possibili del parametro suberror:

Valore sub-errore Descrizione
password_too_weak La password è troppo debole in quanto non soddisfa i requisiti di complessità. Ulteriori informazioni sui criteri sulle password di Microsoft Entra.
password_too_short La nuova password contiene meno di 8 caratteri. Ulteriori informazioni sui criteri sulle password di Microsoft Entra.
password_too_long La nuova password contiene più di 256 caratteri. Ulteriori informazioni sui criteri sulle password di Microsoft Entra.
password_recently_used La nuova password non deve corrispondere a una usata di recente. Ulteriori informazioni sui criteri sulle password di Microsoft Entra.
password_banned La nuova password contiene una parola, una frase o un criterio vietato. Ulteriori informazioni sui criteri sulle password di Microsoft Entra.
password_is_invalid La password non è valida, ad esempio perché usa caratteri non consentiti. Ulteriori informazioni sui criteri sulle password di Microsoft Entra. Questa risposta è possibile se l'app invia una password utente.

Inviare attributi utente

Per continuare con il flusso, l'app deve effettuare una chiamata all'endpoint /signup/v1.0/continue per inviare gli attributi utente necessari. Poiché si inviano attributi, è necessario un parametro attributes e il parametro grant_type deve avere un valore pari a attributes.

Di seguito è riportato un esempio della richiesta (la richiesta di esempio è suddivisa in diverse righe ai fini della leggibilità):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded

&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=attributes 
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postaCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...
Parametro Richiesto Descrizione
tenant_subdomain Sì Sottodominio del tenant esterno creato. Nell'URL sostituire {tenant_subdomain} con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se il sottodominio del tenant non è disponibile, vedere come leggere i dettagli del tenant.
continuation_token Sì Token di continuazione restituito da Microsoft Entra nella richiesta precedente.
client_id Sì ID applicazione (client) dell'app registrata nell'interfaccia di amministrazione di Microsoft Entra.
grant_type Sì Non è possibile usare una richiesta all'endpoint /signup/v1.0/continueper inviare passcode monouso, password o attributi utente. In questo caso, il valore grant_type viene usato per distinguere tra questi tre casi d'uso. I valori possibili per il grant_type sono oob, password, attributi. In questa chiamata, poiché si inviano attributi di un utente, il valore dovrebbe essere attributes.
attributes Sì Valori dell'attributo utente raccolti dall'app dall'utente cliente. Il valore è una stringa, ma è formattato come oggetto JSON i cui valori chiave sono nomi di attributi utente, integrati o personalizzati. I nomi delle chiavi dell'oggetto dipendono dagli attributi configurati dall'amministratore nell'interfaccia di amministrazione di Microsoft Entra. Sostituire {given_name}, {user_age} e {postal_code} con i valori nome, età e CAP rispettivamente raccolti dall'app dall'utente cliente. Microsoft Entra ignora eventuali attributi inviati che non esistono.

Risposta in caso di esito positivo

Se la richiesta ha esito positivo, Microsoft Entra rilascia un token di continuazione, che l'app può usare per richiedere token di sicurezza.

HTTP/1.1 200 OK
Content-Type: application/json

{  
    "continuation_token": "AQABAAEAAAYn..."
}
Parametro Descrizione
continuation_token Token di continuazione restituito da Microsoft Entra.

Se un'app non supporta un metodo di autenticazione richiesto da Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un tipo di test di reindirizzamento nella risposta:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}
Parametro Descrizione
challenge_type Microsoft Entra restituisce una risposta con un tipo di test. Il valore di questo tipo di test è il reindirizzamento, che consente all'app di usare il flusso di autenticazione basato sul Web.

Questa risposta viene considerata riuscita, ma l'app deve passare a un flusso di autenticazione basato sul Web. In questo caso, è consigliabile usare una libreria di autenticazione predefinita e supportata da Microsoft.

Risposta con errore

Esempio:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "expired_token",
    "error_description": "AADSTS901007: The continuation_token is expired.  .\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...", 
    "error_codes": [
        552003
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6" 
}
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errore che si verificano e reagire ai suddetti.
error_description Messaggio di errore specifico che consente di identificare la causa di un errore di autenticazione.
error_codes Elenco di codici di errore specifici di Microsoft Entra che consentono di diagnosticare gli errori.
timestamp Data/ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta che consente di diagnosticare gli errori.
correlation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.
continuation_token Token di continuazione restituito da Microsoft Entra.
unverified_attributes Elenco (array di oggetti) di nomi di chiavi di attributi che occorre verificare. Questo parametro viene incluso nella risposta quando il error valore del parametro è verification_required.
required_attributes Elenco (array di oggetti) di attributi che l'app deve inviare. Microsoft Entra include questo parametro nella risposta quando il valore del parametro error è attributes_required.
invalid_attributes Elenco (array di oggetti) di attributi che non sono stati convalidati. Questo parametro viene incluso nella risposta quando il suberror valore del parametro è attribute_validation_failed.
suberror Stringa di codice di errore che può essere usata per classificare ulteriormente i tipi di errore.

Di seguito sono riportati i possibili errori che è possibile riscontrare (valori possibili del parametro error) :

Valore di errore Descrizione
invalid_request La convalida del parametro della richiesta non è riuscita, ad esempio una convalida del token di continuazione non è riuscita, oppure la richiesta non include il parametro client_id o il valore dell'ID client è vuoto o non valido.
invalid_grant Il tipo di concessione specificato non è valido o supportato, oppure non è stato possibile convalidarlo, ad esempio la convalida degli attributi non è riuscita. Usare il parametro suberror per apprendere la causa esatta dell'errore.
expired_token Il token di continuazione incluso nella richiesta è scaduto.
attributes_required È necessario uno o più attributi utente.

Se il parametro di errore ha un valore di invalid_grant, Microsoft Entra include un parametro suberror nella risposta. Di seguito sono riportati i valori possibili del parametro suberror per un errore di invalid_grant:

Valore sub-errore Descrizione
attribute_validation_failed La convalida dell'attributo utente non è riuscita. Il parametro invalid_attributes contiene l'elenco (array di oggetti) di attributi che non hanno superato la convalida.

Passaggio 5: Richiedere token di sicurezza

L'app effettua una richiesta POST all'endpoint /token e fornisce il token di continuazione ottenuto dal passaggio precedente per acquisire i token di sicurezza.

Di seguito è riportato un esempio della richiesta (la richiesta di esempio è suddivisa in diverse righe ai fini della leggibilità):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
 
continuation_token=ABAAEAAAAtyo... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&username=contoso-consumer@contoso.com
&scope={scopes}
&grant_type=continuation_token
Parametro Richiesto Descrizione
tenant_subdomain Sì Sottodominio del tenant esterno creato. Nell'URL sostituire {tenant_subdomain} con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se il sottodominio del tenant non è disponibile, vedere come leggere i dettagli del tenant.
client_id Sì ID applicazione (client) dell'app registrata nell'interfaccia di amministrazione di Microsoft Entra.
grant_type Sì Il valore del parametro deve essere il token di continuazione.
continuation_token Sì Token di continuazione restituito da Microsoft Entra nel passaggio precedente.
scope Sì Elenco delimitato da spazi degli ambiti per cui il token di accesso è valido. Sostituire {scopes} con gli ambiti validi per cui il token di accesso restituito da Microsoft Entra è valido.
username Sì Indirizzo e-mail dell'utente cliente con cui desidera iscriversi, ad esempio contoso-consumer@contoso.com.

Risposta con esito positivo

Ecco un esempio di risposta con esito positivo:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "token_type": "Bearer",
    "scope": "openid profile",
    "expires_in": 4141,
    "access_token": "eyJ0eXAiOiJKV1Qi...",
    "refresh_token": "AwABAAAA...",
    "id_token": "eyJ0eXAiOiJKV1Q..."
}
Parametro Descrizione
access_token Token di accesso richiesto dall'app dall'endpoint /token. L'app può usare questo token di accesso per richiedere l'accesso a risorse protette, ad esempio le API Web.
token_type Indica il valore del tipo di token. L'unico tipo supportato da Microsoft Entra è Bearer.
expires_in Il periodo di validità, in secondi, del token di accesso.
scopes Elenco delimitato da spazi degli ambiti per cui il token di accesso è valido.
refresh_token Token di aggiornamento di OAuth 2.0. L'app può usare questo token per acquisire altri token di accesso dopo la scadenza del token di accesso corrente. I token di aggiornamento sono di lunga durata. Possono mantenere l'accesso alle risorse per periodi prolungati. Per altre informazioni sull'aggiornamento di un token di accesso, vedere l'articolo Aggiornare il token di accesso.
Nota: emesso solo se è stato richiesto l’ambito offline_access.
id_token Token JSON Web (Jwt) usato per identificare l'utente cliente. L'app può decodificare il token per leggere informazioni sull'utente che ha eseguito l'accesso. L'app può memorizzare nella cache i valori e visualizzarli e i client riservati possono usare questo token per l'autorizzazione. Per altre informazioni sui token ID, vedere Token ID.
Nota: emesso solo se è richiesto l'ambito openid.

Risposta con errore

Esempio:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The client doesn't have consent for the requested scopes.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
}
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errore che si verificano e reagire ai suddetti.
error_description Messaggio di errore specifico che consente di identificare la causa di un errore di autenticazione.
error_codes Elenco di codici di errore specifici di Microsoft Entra che consentono di diagnosticare gli errori.
timestamp Data/ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta che consente di diagnosticare gli errori.
correlation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.

Di seguito sono riportati i possibili errori che è possibile riscontrare (valori possibili del parametro error) :

Valore di errore Descrizione
invalid_request La convalida dei parametri della richiesta non è riuscita, ad esempio il client o l'app non ha il consenso per gli ambiti richiesti.
invalid_grant Il token di continuazione incluso nella richiesta non è valido.
unauthorized_client L'ID client incluso nella richiesta non è valido o non esiste.
unsupported_grant_type Il tipo di concessione incluso nella richiesta non è supportato o non è corretto.

Invio di attributi utente agli endpoint

Nell'interfaccia di amministrazione di Microsoft Entra è possibile configurare gli attributi utente come obbligatori o facoltativi. Questa configurazione determina la modalità di risposta di Microsoft Entra quando si effettua una chiamata ai suoi endpoint. Gli attributi facoltativi non sono obbligatori per il completamento del flusso di iscrizione. Pertanto, quando tutti gli attributi sono facoltativi, devono essere inviati prima della verifica del nome utente. In caso contrario, l'iscrizione viene completata senza gli attributi facoltativi.

La tabella seguente riepiloga quando è possibile inviare attributi utente agli endpoint di Microsoft Entra.

Endpoint Attributi obbligatori Attributi facoltativi Attributi obbligatori e facoltativi
Endpoint /signup/v1.0/start Sì Sì Sì
Endpoint /signup/v1.0/continue prima della verifica del nome utente Sì Sì Sì
Endpoint /signup/v1.0/continue dopo la verifica del nome utente Sì No Sì

Formato dei valori degli attributi utente

Specificare le informazioni che si desidera raccogliere dall'utente configurando le impostazioni del flusso utente nell'interfaccia di amministrazione di Microsoft Entra. Consultare l'articolo Raccogliere attributi utente personalizzati durante l'iscrizione per informazioni su come raccogliere valori per attributi predefiniti e personalizzati.

È anche possibile specificare il tipo di input utente per gli attributi configurati. La tabella seguente riepiloga i tipi di input utente supportati e come inviare i valori raccolti dai controlli dell'interfaccia utente a Microsoft Entra.

Tipo di input utente Formato dei valori inviati
TextBox  Un singolo valore, ad esempio una posizione, Software Engineer.
SingleRadioSelect Valore singolo, ad esempio Lingua, Norvegese. 
CheckboxMultiSelect Uno o più valori come hobby o hobbies, Danza o Danza, nuoto, viaggi.

Ecco una richiesta di esempio che mostra come inviare i valori degli attributi:

POST /{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue HTTP/1.1
Host: {tenant_subdomain}.ciamlogin.com
Content-Type: application/x-www-form-urlencoded
 
continuation_token=ABAAEAAAAtfyo... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=attributes 
&attributes={"jobTitle": "Software Engineer", "extension_2588abcdwhtfeehjjeeqwertc_language": "Norwegian", "extension_2588abcdwhtfeehjjeeqwertc_hobbies": "Dancing,Swimming,Traveling"}
&continuation_token=AQABAAEAAAAtn...

Ulteriori informazioni sui tipi di input degli attributi utente sono disponibili nell'articolo Tipi di input degli attributi utente personalizzati.

Come fare riferimento agli attributi utente

Quando si crea un flusso utente di iscrizione, si configurano gli attributi utente che si desidera raccogliere dall'utente durante l'iscrizione. I nomi degli attributi utente nell'interfaccia di amministrazione di Microsoft Entra sono diversi dalla modalità in cui si fa loro riferimento nell'API di autenticazione nativa.

Ad esempio, si fa riferimento a Nome visualizzato nell'interfaccia di amministrazione di Microsoft Entra come displayName nell'API.

Consultare l'articolo Attributi del profilo utente per informazioni su come fare riferimento agli attributi utente predefiniti e personalizzati nell'API di autenticazione nativa.

Informazioni di riferimento API di accesso

Gli utenti devono accedere con il metodo di autenticazione usato per l'iscrizione. Ad esempio, gli utenti che effettuano l'iscrizione tramite e-mail con il metodo di autenticazione della password devono accedere all’e-mail e alla password.

Per richiedere token di sicurezza, l'app interagisce con tre endpoint, /initiate, /challenge e /token.

Endpoint dell'API di accesso

Endpoint Descrizione
/initiate Questo endpoint avvia il flusso di accesso. Se l'app lo chiama con un nome utente di un account utente già esistente, restituisce una risposta di esito positivo con un token di continuazione. Se l'app richiede di usare metodi di autenticazione non supportati da Microsoft Entra, questa risposta dell'endpoint può indicare all'app che è necessario usare un flusso di autenticazione basato su browser.
/challenge L'app chiama questo endpoint con un elenco di tipi di test supportati dal servizio delle identità. Il servizio delle identità genera e invia un passcode monouso al canale di verifica scelto, ad esempio l’e-mail. Se l'app chiama ripetutamente questo endpoint, viene inviato un nuovo OTP ogni volta che si effettua una chiamata.
/token Questo endpoint verifica il passcode monouso ricevuto dall'app, quindi rilascia i token di sicurezza all'app.

Tipi di test di accesso

L'API consente all'app di annunciare i metodi di autenticazione supportati, quando effettua una chiamata a Microsoft Entra. A tale scopo, l'app usa il parametro challenge_type nelle richieste. Questo parametro contiene valori predefiniti, che rappresentano metodi di autenticazione differenti.

Per un determinato metodo di autenticazione, i valori del tipo di verifica inviati da un'app a Microsoft Entra durante il flusso di iscrizione sono uguali a quando l'app esegue l'accesso. Ad esempio, l’e-mail con il metodo di autenticazione della password usa valori di tipo di test oob, password, reindirizza sia per i flussi di iscrizione che per quelli di accesso.

Ulteriori informazioni sui tipi di test nell’articolo sui tipi di test di autenticazione nativa.

Dettagli del protocollo del flusso di accesso

Il diagramma di sequenza illustra il flusso del processo di accesso.

Diagramma dell'accesso all'autenticazione nativa con passcode monouso tramite e-mail.

Dopo che l'app verifica l’e-mail dell'utente con OTP, riceve i token di sicurezza. In caso di ritardi nella consegna del passcode monouso o se il suddetto non viene mai recapitato all’e-mail dell'utente, quest’ultimo può richiedere l'invio di un altro passcode monouso. Microsoft Entra invia nuovamente un altro passcode monouso se quello precedente non è stato verificato. Quando Microsoft Entra invia nuovamente un passcode monouso, invalida il codice inviato in precedenza.

Nelle sezioni seguenti viene riepilogato il diagramma sequenza in tre passaggi di base.

Passaggio 1: Richiedere di avviare il flusso di accesso

Il flusso di autenticazione inizia con l'applicazione che effettua una richiesta POST all'endpoint /initiate per avviare il flusso di accesso.

Di seguito è riportato un esempio della richiesta (la richiesta di esempio è suddivisa in diverse righe ai fini della leggibilità):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/initiate
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect
&username=contoso-consumer@contoso.com
Parametro Richiesto Descrizione
tenant_subdomain Sì Sottodominio del tenant esterno creato. Nell'URL sostituire {tenant_subdomain} con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se il sottodominio del tenant non è disponibile, vedere come leggere i dettagli del tenant.
client_id Sì ID applicazione (client) dell'app registrata nell'interfaccia di amministrazione di Microsoft Entra.
username Sì Indirizzo e-mail dell'utente cliente, ad esempio contoso-consumer@contoso.com.
challenge_type Sì Elenco delimitato da spazi di stringhe di tipo di test di autorizzazione supportate dall'app, ad esempio oob password redirect. L'elenco deve includere sempre il tipo di test redirect. Il valore previsto è oob redirect per il passcode tramite e-mail e password redirect per l’e-mail con password.

Risposta in caso di esito positivo

Ecco un esempio di risposta con esito positivo:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}
Parametro Descrizione
continuation_token Token di continuazione restituito da Microsoft Entra.

Se un'app non supporta un metodo di autenticazione richiesto da Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un tipo di test di reindirizzamento nella risposta:

HTTP/1.1 200 OK
Content-Type: application/json


{     
   "challenge_type": "redirect" 
}
Parametro Descrizione
challenge_type Microsoft Entra restituisce una risposta con un tipo di test. Il valore di questo tipo di test è il reindirizzamento, che consente all'app di usare il flusso di autenticazione basato sul Web.

Questa risposta viene considerata riuscita, ma l'app deve passare a un flusso di autenticazione basato sul Web. In questo caso, è consigliabile usare una libreria di autenticazione predefinita e supportata da Microsoft.

Risposta con errore

Esempio:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
}
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errore che si verificano e reagire ai suddetti.
error_description Messaggio di errore specifico che consente di identificare la causa di un errore di autenticazione.
error_codes Elenco di codici di errore specifici di Microsoft Entra che consentono di diagnosticare gli errori.
timestamp Data/ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta che consente di diagnosticare gli errori.
correlation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.

Di seguito sono riportati i possibili errori che è possibile riscontrare (valori possibili del parametro error) :

Valore di errore Descrizione
invalid_request La convalida dei parametri della richiesta non è riuscita, ad esempio quando il parametro challenge_type include un tipo di test non valido. o la richiesta non includeva il parametro client_id il valore dell'ID client è vuoto o non valido. Usare il parametro error_description per apprendere la causa esatta dell'errore.
unauthorized_client L'ID client usato nella richiesta ha un formato ID client valido, ma non è presente nel tenant esterno oppure non è corretto.
invalid_client L'ID client che l’app include nella richiesta è per un'app che non dispone della configurazione di autenticazione nativa, ad esempio non è un client pubblico oppure l'autenticazione nativa non è abilitata. Usare il parametro suberror per apprendere la causa esatta dell'errore.
user_not_found Il nome utente non esiste.
unsupported_challenge_type Il valore del parametro challenge_type non include il tipo di test redirect.

Se il parametro di errore ha un valore di invalid_client, Microsoft Entra include un parametro suberror nella risposta. Di seguito sono riportati i valori possibili del parametro suberror per un errore di invalid_client:

Valore sub-errore Descrizione
nativeauthapi_disabled ID client per un'app che non è abilitato per l'autenticazione nativa.

Passaggio 2: Selezionare un metodo di autenticazione

Per continuare con il flusso, l'app usa il token di continuazione acquisito dal passaggio precedente per richiedere a Microsoft Entra di selezionare uno dei tipi di test supportati per l'autenticazione dell'utente. L'app effettua una richiesta POST all'endpoint /challenge.

Di seguito è riportato un esempio della richiesta (la richiesta di esempio è suddivisa in diverse righe ai fini della leggibilità):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect 
&continuation_token=uY29tL2F1dGhlbnRpY...
Parametro Richiesto Descrizione
tenant_subdomain Sì Sottodominio del tenant esterno creato. Nell'URL sostituire {tenant_subdomain} con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se il sottodominio del tenant non è disponibile, vedere come leggere i dettagli del tenant.
client_id Sì ID applicazione (client) dell'app registrata nell'interfaccia di amministrazione di Microsoft Entra.
continuation_token Sì Token di continuazione restituito da Microsoft Entra nella richiesta precedente.
challenge_type No Elenco delimitato da spazi di stringhe di tipo di test di autorizzazione supportate dall'app, ad esempio oob password redirect. L'elenco deve includere sempre il tipo di test redirect. Il valore previsto è oob redirect per il passcode tramite e-mail e password redirect per l’e-mail con password.

Risposta in caso di esito positivo

Se l'amministratore tenant ha configurato un passcode monouso e-mail nell'interfaccia di amministrazione di Microsoft Entra come metodo di autenticazione dell'utente, Microsoft Entra invia un passcode monouso all’e-mail dell'utente, quindi risponde con un tipo di test di oob e fornisce altre informazioni sul passcode monouso.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ", 
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
}
Parametro Descrizione
continuation_token Token di continuazione restituito da Microsoft Entra.
challenge_type Tipo di test selezionato per l'autenticazione dell'utente.
binding_method L'unico valore valido è prompt. Questo parametro può essere usato in futuro per offrire altri modi per consentire all'utente di immettere il passcode monouso. Emesso se challenge_type è oob
challenge_channel Tipo del canale tramite il quale è stato inviato il passcode monouso. Al momento, supportiamo l’e-mail.
challenge_target_label Messaggio e-mail offuscato in cui è stato inviato il passcode monouso.
code_length Lunghezza del passcode monouso generato da Microsoft Entra.

Se un'app non supporta un metodo di autenticazione richiesto da Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un tipo di test di reindirizzamento nella risposta:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}
Parametro Descrizione
challenge_type Microsoft Entra restituisce una risposta con un tipo di test. Il valore di questo tipo di test è il reindirizzamento, che consente all'app di usare il flusso di autenticazione basato sul Web.

Questa risposta viene considerata riuscita, ma l'app deve passare a un flusso di autenticazione basato sul Web. In questo caso, è consigliabile usare una libreria di autenticazione predefinita e supportata da Microsoft.

Risposta con errore

Esempio:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
}
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errore che si verificano e reagire ai suddetti.
error_description Messaggio di errore specifico che consente di identificare la causa di un errore di autenticazione.
error_codes Elenco di codici di errore specifici di Microsoft Entra che consentono di diagnosticare gli errori.
timestamp Data/ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta che consente di diagnosticare gli errori.
correlation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.

Di seguito sono riportati i possibili errori che è possibile riscontrare (valori possibili del parametro error) :

Valore di errore Descrizione
invalid_request La convalida dei parametri della richiesta non è riuscita, ad esempio quando il parametro challenge_type include un tipo di test non valido.
invalid_grant Il token di continuazione incluso nella richiesta non è valido.
expired_token Il token di continuazione incluso nella richiesta è scaduto.
unsupported_challenge_type Il valore del parametro challenge_type non include il tipo di test redirect.

Passaggio 3: Richiedere token di sicurezza

L'app effettua una richiesta POST all'endpoint /token e fornisce le credenziali dell'utente scelte nel passaggio precedente, in questo caso la password, per acquisire i token di sicurezza.

Di seguito è riportato un esempio della richiesta (la richiesta di esempio è suddivisa in diverse righe ai fini della leggibilità):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=password 
&password={secure_password}
&scope=openid offline_access
Parametro Richiesto Descrizione
tenant_subdomain Sì Sottodominio del tenant esterno creato. Nell'URL sostituire {tenant_subdomain} con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se il sottodominio del tenant non è disponibile, vedere come leggere i dettagli del tenant.
client_id Sì ID applicazione (client) dell'app registrata nell'interfaccia di amministrazione di Microsoft Entra.
continuation_token Sì Token di continuazione restituito da Microsoft Entra nella richiesta precedente.
grant_type Sì Il valore deve essere password per l’e-mail con metodo di autenticazione della password e oob per il metodo di autenticazione con passcode monouso tramite e-mail.
scope Sì Elenco di ambiti separato da spazi. Tutti gli ambiti devono provenire da una singola risorsa, insieme agli ambiti OpenID Connect (OIDC), ad esempio profilo, *openid e e-mail. L'app deve includere l'ambito openid per consentire a Microsoft Entra di emettere un token ID. L'app deve includere l’ambito offline_access per il rilascio di un token di aggiornamento da parte di Microsoft Entra. Ulteriori informazioni su Autorizzazioni e consenso in Microsoft Identity Platform.
password Sì
(per e-mail con password)		 Valore della password che l'app raccoglie dall'utente cliente. Sostituire {secure_password} con il valore della password che l'app raccoglie dall'utente cliente.
oob Sì
(per passcode monouso tramite e-mail)		 Passcode monouso ricevuto dall'utente cliente nel messaggio e-mail. Sostituire {otp_code} con il passcode monouso ricevuto dall'utente de cliente nel messaggio e-mail. Per inviare nuovamente un passcode monouso, l'app deve effettuare nuovamente una richiesta all'endpoint /challenge.

Risposta con esito positivo

Ecco un esempio di risposta con esito positivo:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "token_type": "Bearer",
    "scope": "openid profile",
    "expires_in": 4141,
    "access_token": "eyJ0eXAiOiJKV1Qi...",
    "refresh_token": "AwABAAAA...",
    "id_token": "eyJ0eXAiOiJKV1Q..."
}
Parametro Descrizione
token_type Indica il valore del tipo di token. L'unico tipo supportato da Microsoft Entra è Bearer.
scopes Elenco delimitato da spazi degli ambiti per cui il token di accesso è valido.
expires_in Il periodo di validità, in secondi, del token di accesso.
access_token Token di accesso richiesto dall'app dall'endpoint /token. L'app può usare questo token di accesso per richiedere l'accesso a risorse protette, ad esempio le API Web.
refresh_token Token di aggiornamento di OAuth 2.0. L'app può usare questo token per acquisire altri token di accesso dopo la scadenza del token di accesso corrente. I token di aggiornamento sono di lunga durata. Possono mantenere l'accesso alle risorse per periodi prolungati. Per altre informazioni sull'aggiornamento di un token di accesso, vedere l'articolo Aggiornare il token di accesso.
Nota: viene emesso solo se è richiesto l’ambito offline_access.
id_token Token JSON Web (Jwt) usato per identificare l'utente cliente. L'app può decodificare il token per richiedere informazioni sull'utente che ha eseguito l'accesso. L'app può memorizzare nella cache i valori e visualizzarli e i client riservati possono usare questo token per l'autorizzazione. Per altre informazioni sui token ID, vedere Token ID.
Nota: emesso solo se è richiesto l'ambito openid.

Risposta con errore

Esempio:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_grant", 
    "error_description": "AADSTS901007: Error validating credentials due to invalid username or password.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
}
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errore che si verificano e reagire ai suddetti.
error_description Messaggio di errore specifico che consente di identificare la causa di un errore di autenticazione.
error_codes Elenco di codici di errore specifici di Microsoft Entra che consentono di diagnosticare gli errori.
timestamp Data/ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta che consente di diagnosticare gli errori.
correlation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.

Di seguito sono riportati i possibili errori che è possibile riscontrare (valori possibili del parametro error) :

Valore di errore Descrizione
invalid_request La convalida del parametro di richiesta non è riuscita. Per comprendere cosa è successo, usare il messaggio contenuto nella descrizione dell'errore.
invalid_grant Il token di continuazione incluso nella richiesta non è valido o le credenziali di accesso utente cliente incluse nella richiesta non sono valide, oppure il tipo di concessione incluso nella richiesta è sconosciuto.
invalid_client L'ID client incluso nella richiesta non è per un client pubblico.
expired_token Il token di continuazione incluso nella richiesta è scaduto.
invalid_scope Uno o più degli ambiti inclusi nella richiesta non sono validi.

Se il parametro di errore ha un valore di invalid_grant, Microsoft Entra include un parametro suberror nella risposta. Di seguito sono riportati i valori possibili del parametro suberror per un errore di invalid_grant:

Valore sub-errore Descrizione
invalid_oob_value Il valore del passcode monouso non è valido. Questo sotto-errore applica solo il passcode monouso tramite e-mail

Reimpostazione della password self-service

Se si usa l’e-mail e la password come metodo di autenticazione nell'app, usare l'API di reimpostazione della password self-service (SSPR) per consentire agli utenti clienti di reimpostare la password. Usare questa API per la password dimenticata o modificare gli scenari di password.

Endpoint API di reimpostazione della password self-service

Per usare questa API, l'app interagisce con l'endpoint contenuto nella tabella seguente:

Endpoint Descrizione
/start L'app chiama questo endpoint quando l'utente cliente seleziona Password dimenticata o il pulsante Cambia password nell'app. Questo endpoint convalida il nome utente dell'utente (e-mail), quindi restituisce un token di continuazione da usare nel flusso di reimpostazione della password. Se l'app richiede di usare metodi di autenticazione non supportati da Microsoft Entra, questa risposta dell'endpoint può indicare all'app che è necessario usare un flusso di autenticazione basato su browser.
/challenge Accetta un elenco di tipi di test supportati dal client e dal token di continuazione. Viene emesso un test per una delle credenziali di ripristino preferite. Ad esempio, il test oob genera un passcode monouso fuori banda all’e-mail associato all'account utente cliente. Se l'app richiede di usare metodi di autenticazione non supportati da Microsoft Entra, questa risposta dell'endpoint può indicare all'app che è necessario usare un flusso di autenticazione basato su browser.
/continue Convalida il test emesso dall'endpoint /challenge, quindi restituisce un token di continuazione per l'endpoint /submit o rilascia un altro test all'utente.
/submit Accetta una nuova password immessa dall'utente insieme al token di continuazione per completare il flusso di reimpostazione della password. Questo endpoint rilascia un altro token di continuazione.
/poll_completion Infine, l'app può usare il token di continuazione emesso dall'endpoint /submit per controllare lo stato della richiesta di reimpostazione della password.

Tipi di test per la reimpostazione della password self-service

L'API consente all'app di annunciare i metodi di autenticazione supportati, quando effettua una chiamata a Microsoft Entra. A tale scopo, l'app usa il parametro challenge_type nelle richieste. Questo parametro contiene valori predefiniti, che rappresentano metodi di autenticazione differenti.

Per il flusso della reimpostazione della password self-service, i valori del tipo di test sono oobe redirect.

Ulteriori informazioni sui tipi di test nei tipi di test di autenticazione nativa.

Dettagli sul protocollo del flusso di reimpostazione della password self-service

Il diagramma sequenza illustra il flusso per il processo di reimpostazione della password.

Diagramma del flusso di reimpostazione della password self-service dell'autenticazione nativa.

Questo diagramma indica che l'app il raccoglie nome utente (e-mail) e la password dall'utente in momenti differenti (e possibilmente in schermate separate). È tuttavia possibile progettare l'app in moda da raccogliere il nome utente (e-mail) e la nuova password nella stessa schermata. In questo caso, l'app tiene la password, quindi la invia all’endpoint /submit ove è necessaria.

Passaggio 1: Richiedere di avviare il flusso di reimpostazione della password self-service

Il flusso di reimpostazione della password inizia con l’effettuazione di una richiesta POST da parte dell’app all'endpoint /start per avviare il flusso di reimpostazione della password self-service.

Di seguito è riportato un esempio della richiesta (la richiesta di esempio è suddivisa in diverse righe ai fini della leggibilità):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/start
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&challenge_type=oob redirect 
&username=contoso-consumer@contoso.com
Parametro Richiesto Descrizione
tenant_subdomain Sì Sottodominio del tenant esterno creato. Nell'URL sostituire {tenant_subdomain} con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se il sottodominio del tenant non è disponibile, vedere come leggere i dettagli del tenant.
client_id Sì ID applicazione (client) dell'app registrata nell'interfaccia di amministrazione di Microsoft Entra.
username Sì Indirizzo e-mail dell'utente cliente, ad esempio contoso-consumer@contoso.com.
challenge_type Sì Elenco delimitato da spazi di stringhe di tipo di test di autorizzazione supportate dall'app, ad esempio oob password redirect. L'elenco deve includere sempre il tipo di test redirect. Per questa richiesta, si prevede che il valore contenga oob redirect.

Risposta in caso di esito positivo

Esempio:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}
Parametro Descrizione
continuation_token Token di continuazione restituito da Microsoft Entra.

Se un'app non supporta un metodo di autenticazione richiesto da Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un tipo di test di reindirizzamento nella risposta:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}
Parametro Descrizione
challenge_type Microsoft Entra restituisce una risposta con un tipo di test. Il valore di questo tipo di test è il reindirizzamento, che consente all'app di usare il flusso di autenticazione basato sul Web.

Questa risposta viene considerata riuscita, ma l'app deve passare a un flusso di autenticazione basato sul Web. In questo caso, è consigliabile usare una libreria di autenticazione predefinita e supportata da Microsoft.

Risposta con errore

Esempio:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
}
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errore che si verificano e reagire ai suddetti.
error_description Messaggio di errore specifico che consente di identificare la causa di un errore di autenticazione.
error_codes Elenco di codici di errore specifici di Microsoft Entra che consentono di diagnosticare gli errori.
timestamp Data/ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta che consente di diagnosticare gli errori.
correlation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.

Di seguito sono riportati i possibili errori che è possibile riscontrare (valori possibili del parametro error) :

Valore di errore Descrizione
invalid_request La convalida del parametro della richiesta non è riuscita, ad esempio quando il parametro challenge_typeinclude un tipo di test non valido o la richiesta non include il parametro client_id e il valore dell'ID client è vuoto o non valido. Usare il parametro error_description per apprendere la causa esatta dell'errore.
user_not_found Il nome utente non esiste.
unsupported_challenge_type Il valore del parametro challenge_type non include il tipo di test redirect.
invalid_client L'ID client che l’app include nella richiesta è per un'app che non dispone della configurazione di autenticazione nativa, ad esempio non è un client pubblico oppure l'autenticazione nativa non è abilitata. Usare il parametro suberror per apprendere la causa esatta dell'errore.
unauthorized_client L'ID client usato nella richiesta ha un formato ID client valido, ma non è presente nel tenant esterno oppure non è corretto.

Se il parametro di errore ha un valore di invalid_client, Microsoft Entra include un parametro suberror nella risposta. Di seguito sono riportati i valori possibili del parametro suberror per un errore di invalid_client:

Valore sub-errore Descrizione
nativeauthapi_disabled ID client per un'app che non è abilitato per l'autenticazione nativa.

Passaggio 2: Selezionare un metodo di autenticazione

Per continuare con il flusso, l'app usa il token di continuazione acquisito dal passaggio precedente per richiedere a Microsoft Entra di selezionare uno dei tipi di test supportati per l'autenticazione dell'utente. L'app effettua una richiesta POST all'endpoint /challenge. Se la richiesta ha esito positivo, Microsoft Entra invia un passcode monouso all’e-mail dell'account dell'utente. Al momento, supportiamo solo l’OTP e-mail.

Di seguito è riportato un esempio (la richiesta di esempio è suddivisa in diverse righe ai fini della leggibilità):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/challenge
Content-Type: application/x-www-form-urlencoded

client_id=client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY...
Parametro Richiesto Descrizione
tenant_subdomain Sì Sottodominio del tenant esterno creato. Nell'URL sostituire {tenant_subdomain} con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se il sottodominio del tenant non è disponibile, vedere come leggere i dettagli del tenant.
client_id Sì ID applicazione (client) dell'app registrata nell'interfaccia di amministrazione di Microsoft Entra.
continuation_token Sì Token di continuazione restituito da Microsoft Entra nella richiesta precedente.
challenge_type No Elenco delimitato da spazi di stringhe di tipo di test di autorizzazione supportate dall'app, ad esempio oob redirect. L'elenco deve includere sempre il tipo di test redirect. Per questa richiesta, si prevede che il valore contenga oob redirect.

Risposta in caso di esito positivo

Esempio:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ", 
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
}
Parametro Descrizione
continuation_token Token di continuazione restituito da Microsoft Entra.
challenge_type Tipo di test selezionato per l'autenticazione dell'utente.
binding_method L'unico valore valido è prompt. Questo parametro può essere usato in futuro per offrire più modi per l'utente di immettere il passcode monouso. Emesso se challenge_type è oob
challenge_channel Tipo del canale tramite il quale è stato inviato il passcode monouso. Al momento, supportiamo l’e-mail.
challenge_target_label Messaggio e-mail offuscato in cui è stato inviato il passcode monouso.
code_length Lunghezza del passcode monouso generato da Microsoft Entra.

Se un'app non supporta un metodo di autenticazione richiesto da Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un tipo di test di reindirizzamento nella risposta:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
}
Parametro Descrizione
challenge_type Microsoft Entra restituisce una risposta con un tipo di test. Il valore di questo tipo di test è il reindirizzamento, che consente all'app di usare il flusso di autenticazione basato sul Web.

Questa risposta viene considerata riuscita, ma l'app deve passare a un flusso di autenticazione basato sul Web. In questo caso, è consigliabile usare una libreria di autenticazione predefinita e supportata da Microsoft.

Risposta con errore

Esempio:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
}
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errore che si verificano e reagire ai suddetti.
error_description Messaggio di errore specifico che consente di identificare la causa di un errore di autenticazione.
error_codes Elenco di codici di errore specifici di Microsoft Entra che consentono di diagnosticare gli errori.
timestamp Data/ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta che consente di diagnosticare gli errori.
correlation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.

Di seguito sono riportati i possibili errori che è possibile riscontrare (valori possibili del parametro error) :

Valore di errore Descrizione
invalid_request La convalida dei parametri della richiesta non è riuscita, ad esempio quando il parametro challenge_type include un tipo di verifica non valido o la convalida del token di continuazione non è riuscita.
expired_token Il token di continuazione è scaduto.
unsupported_challenge_type Il valore del parametro challenge_type non include il tipo di test redirect.

Passaggio 3: Inviare un passcode monouso

L'app effettua quindi una richiesta POST all'endpoint /continue. Nella richiesta l'app deve includere le credenziali dell'utente selezionate nel passaggio precedente e il token di continuazione emesso dall'endpoint /challenge.

Di seguito è riportato un esempio della richiesta (la richiesta di esempio è suddivisa in diverse righe ai fini della leggibilità):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/continue
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=oob 
&oob={otp_code}
Parametro Richiesto Descrizione
tenant_subdomain Sì Sottodominio del tenant esterno creato. Nell'URL sostituire {tenant_subdomain} con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se il sottodominio del tenant non è disponibile, vedere come leggere i dettagli del tenant.
continuation_token Sì Token di continuazione restituito da Microsoft Entra nella richiesta precedente.
client_id Sì ID applicazione (client) dell'app registrata nell'interfaccia di amministrazione di Microsoft Entra.
grant_type Sì L'unico valore valido è oob.
oob Sì Passcode monouso ricevuto dall'utente cliente nel messaggio e-mail. Sostituire {otp_code} con il passcode monouso ricevuto dall'utente de cliente nel messaggio e-mail. Per inviare nuovamente un passcode monouso, l'app deve effettuare nuovamente una richiesta all'endpoint /challenge.

Risposta in caso di esito positivo

Esempio:

HTTP/1.1 200 OK
Content-Type: application/json

{ 
    "expires_in": 600,
    "continuation_token": "czZCaGRSa3F0MzpnW...",
}
Parametro Descrizione
expires_in Tempo in secondi prima della scadenza di continuation_token. Il valore massimo di expires_in è 600 secondi.
continuation_token Token di continuazione restituito da Microsoft Entra.

Risposta con errore

Esempio:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS55200: The continuation_token is invalid.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        55200 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
}
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errore che si verificano e reagire ai suddetti.
error_description Messaggio di errore specifico che consente di identificare la causa di un errore di autenticazione.
error_codes Elenco di codici di errore specifici di Microsoft Entra che consentono di diagnosticare gli errori.
timestamp Data/ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta che consente di diagnosticare gli errori.
correlation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.
suberror Stringa di codice di errore che può essere usata per classificare ulteriormente i tipi di errore.

Di seguito sono riportati i possibili errori che è possibile riscontrare (valori possibili del parametro error) :

Valore di errore Descrizione
invalid_request La convalida del parametro della richiesta non è riuscita, ad esempio una convalida del token di continuazione non è riuscita, oppure la richiesta non include il parametro client_id o il valore dell'ID client è vuoto o non valido o l’amministratore tenant esterno non ha abilitato la reimpostazione della password self-service o l’OTP e-mail per tutti gli utenti tenant. Usare il parametro error_description per apprendere la causa esatta dell'errore.
invalid_grant Il tipo di concessione è sconosciuto o non corrisponde al valore del tipo di concessione previsto. Usare il parametro suberror per apprendere la causa esatta dell'errore.
expired_token Il token di continuazione è scaduto.

Se il parametro di errore ha un valore di invalid_grant, Microsoft Entra include un parametro suberror nella risposta. Di seguito sono riportati i valori possibili del parametro suberror per un errore di invalid_grant:

Valore sub-errore Descrizione
invalid_oob_value Il passcode monouso fornito dall'utente non è valido.

Passaggio 4: Inviare una nuova password

L'app raccoglie una nuova password dall'utente, quindi usa il token di continuazione emesso dall'endpoint /continue per inviare la password effettuando una richiesta POST all'endpoint /submit.

Di seguito è riportato un esempio (la richiesta di esempio è suddivisa in diverse righe ai fini della leggibilità):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/submit
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0Mzp...
&new_password={new_password}
Parametro Richiesto Descrizione
tenant_subdomain Sì Sottodominio del tenant esterno creato. Nell'URL sostituire {tenant_subdomain} con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se il sottodominio del tenant non è disponibile, vedere come leggere i dettagli del tenant.
continuation_token Sì Token di continuazione restituito da Microsoft Entra nella richiesta precedente.
client_id Sì ID applicazione (client) dell'app registrata nell'interfaccia di amministrazione di Microsoft Entra.
new_password Sì Nuova password dell'utente. Sostituire {new_password} con la nuova password dell'utente. È responsabilità dell'utente confermare di essere a conoscenza della password che desidera usare fornendo il campo di conferma della password nell'interfaccia utente dell'app. È inoltre necessario assicurarsi che l'utente sia a conoscenza di ciò che costituisce una password complessa in base ai criteri dell'organizzazione. Ulteriori informazioni sui criteri sulle password di Microsoft Entra.

Risposta in caso di esito positivo

Esempio:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "poll_interval": 2
}
Parametro Descrizione
continuation_token Token di continuazione restituito da Microsoft Entra.
poll_interval La quantità minima di tempo in secondi che l'app dovrebbe attendere tra le richieste di polling per verificare lo stato della richiesta di reimpostazione della password tramite l'endpoint /poll_completion, vedere il passaggio 5

Risposta con errore

Esempio:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        901007 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
}
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errore che si verificano e reagire ai suddetti.
error_description Messaggio di errore specifico che consente di identificare la causa di un errore di autenticazione.
error_codes Elenco di codici di errore specifici di Microsoft Entra che consentono di diagnosticare gli errori.
timestamp Data/ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta che consente di diagnosticare gli errori.
correlation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.
suberror Stringa di codice di errore che può essere usata per classificare ulteriormente i tipi di errore.

Di seguito sono riportati i possibili errori che è possibile riscontrare (valori possibili del parametro error) :

Valore di errore Descrizione
invalid_request La convalida dei parametri della richiesta non è riuscita, ad esempio una convalida del token di continuazione non è riuscita.
expired_token Il token di continuazione è scaduto.
invalid_grant La concessione inviata non è valida, ad esempio la password inviata è troppo corta. Usare il parametro suberror per apprendere la causa esatta dell'errore.

Se il parametro di errore ha un valore di invalid_grant, Microsoft Entra include un parametro suberror nella risposta. Ecco i valori possibili del parametro suberror:

Valore sub-errore Descrizione
password_too_weak La password è troppo debole in quanto non soddisfa i requisiti di complessità. Ulteriori informazioni sui criteri sulle password di Microsoft Entra.
password_too_short La nuova password contiene meno di 8 caratteri. Ulteriori informazioni sui criteri sulle password di Microsoft Entra.
password_too_long La nuova password contiene più di 256 caratteri. Ulteriori informazioni sui criteri sulle password di Microsoft Entra.
password_recently_used La nuova password non deve corrispondere a una usata di recente. Ulteriori informazioni sui criteri sulle password di Microsoft Entra.
password_banned La nuova password contiene una parola, una frase o un criterio vietato. Ulteriori informazioni sui criteri sulle password di Microsoft Entra.
password_is_invalid La password non è valida, ad esempio perché usa caratteri non consentiti. Ulteriori informazioni sui criteri sulle password di Microsoft Entra. Questa risposta è possibile se l'app invia una password utente.

Passaggio 5: Eseguire il polling dello stato di reimpostazione della password

Infine, poiché l'aggiornamento della configurazione dell'utente con la nuova password comporta un certo ritardo, l'app può usare l'endpoint /poll_completion per eseguire il polling dello stato di reimpostazione della password di Microsoft Entra. La quantità minima di tempo in secondi che l'app dovrebbe attendere tra le richieste di polling viene restituita dall'endpoint /submit nel parametro poll_interval.

Di seguito è riportato un esempio (la richiesta di esempio è suddivisa in diverse righe ai fini della leggibilità):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/poll_completion
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0...
Parametro Richiesto Descrizione
tenant_subdomain Sì Sottodominio del tenant esterno creato. Nell'URL sostituire {tenant_subdomain} con il sottodominio Directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se il sottodominio del tenant non è disponibile, vedere come leggere i dettagli del tenant.
continuation_token Sì Token di continuazione restituito da Microsoft Entra nella richiesta precedente.
client_id Sì ID applicazione (client) dell'app registrata nell'interfaccia di amministrazione di Microsoft Entra.

Risposta in caso di esito positivo

Esempio:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "succeeded",
    "continuation_token":"czZCaGRSa3F0..."
}
Parametro Descrizione
status Stato della richiesta di reimpostazione della password. Se Microsoft Entra restituisce uno stato non riuscito, l'app può inviare nuovamente la nuova password effettuando un'altra richiesta all'endpoint /submit e includendo il nuovo token di continuazione.
continuation_token Token di continuazione restituito da Microsoft Entra. Se lo stato è riuscito, l'app può usare il token di continuazione restituito da Microsoft Entra per richiedere token di sicurezza tramite l'endpoint /token, come illustrato nel passaggio 5 del flusso di iscrizione. Ciò significa, che dopo che un utente ha reimpostato correttamente la password, può accedere direttamente nell'app senza avviare un nuovo flusso di accesso.

Ecco i possibili stati restituiti da Microsoft Entra (possibili valori del parametro status):

Valore di errore Descrizione
succeeded La reimpostazione della password è stata completata correttamente.
failed La reimpostazione della password non è riuscita. L'app può inviare nuovamente la nuova password effettuando un'altra richiesta all'endpoint /submit.
not_started La reimpostazione della password non è stata avviata. L'app può verificare nuovamente lo stato in un secondo momento.
in_progress La reimpostazione della password è in corso. L'app può verificare nuovamente lo stato in un secondo momento.

Risposta con errore

Esempio:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "expired_token", 
    "error_description": "AADSTS901007: The continuation_token is expired.\r\nTrace ID: b386ad47-23ae-4092-...-1000000\r\nCorrelation ID: 72f57f26-...-3fa6\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        552003 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "b386ad47-...-0000", 
    "correlation_id": "72f57f26-...-3fa6"
}
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errore che si verificano e reagire ai suddetti.
error_description Messaggio di errore specifico che consente di identificare la causa di un errore di autenticazione.
error_codes Elenco di codici di errore specifici di Microsoft Entra che consentono di diagnosticare gli errori.
timestamp Data/ora in cui si è verificato l'errore.
trace_id Identificatore univoco per la richiesta che consente di diagnosticare gli errori.
correlation_id Identificatore univoco per la richiesta utile per la diagnostica tra i componenti.

Di seguito sono riportati i possibili errori che è possibile riscontrare (valori possibili del parametro error) :

Valore di errore Descrizione
invalid_request La convalida dei parametri della richiesta non è riuscita, ad esempio la convalida del token di continuazione non è riuscita.
expired_token Il token di continuazione è scaduto.

Contenuto correlato