Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Si applica a: 
Tenant esterni (maggiori informazioni)
L'autenticazione native di Microsoft Entra consente di ospitare l'interfaccia utente dell'app nell'applicazione client anziché 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. Altre informazioni sugli SDK di 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 flussi 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).
- Gli utenti che accedono con un indirizzo email e una password possono anche accedere con un nome utente e una password.
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
Un tenant esterno Microsoft Entra. Se non si dispone già di un tenant esterno, crearne uno.
Se non è già stato fatto, Registrare un'applicazione nell'interfaccia di amministrazione di Microsoft Entra. Assicurarsi di:
- Registrare l'ID applicazione (client) e l'ID directory (tenant) per un uso successivo.
- Concedere il consenso dell'amministratore all'applicazione.
- Abilitare il client pubblico e i flussi di autenticazione nativi.
Se non è già stato fatto, Creare un flusso utente nell'interfaccia di amministrazione di Microsoft Entra. Quando si crea il flusso utente, prendere nota degli attributi utente configurati in base alle esigenze in quanto questi attributi sono quelli che Microsoft Entra si aspetta che l'app invii.
Per il flusso di accesso, registra un utente cliente, che usi per testare il flusso. In alternativa, è possibile ottenere questo utente di test dopo aver eseguito il flusso di registrazione.
Per il flusso di reimpostazione della password self-service, abilitare la reimpostazione della password self-service per gli utenti clienti nel tenant esterno. La reimpostazione della password self-service è disponibile per gli utenti clienti che usano l'e-mail con il metodo di autenticazione della password.
Se vuoi permettere agli utenti che accedono con indirizzo email e password di accedere anche con nome utente e password, usa i passaggi nell'articolo Accedi con un alias o username :
Per applicare l'autenticazione a più fattori (MFA) per i clienti, seguire la procedura descritta in Aggiungere l'autenticazione a più fattori (MFA) a un'app per aggiungere MFA al flusso di accesso. L'autenticazione nativa supporta il passcode monouso della posta elettronica e l'SMS come secondo fattore per MFA.
Token di continuazione
Ogni volta che si chiama un endpoint di accesso, iscrizione o reimpostazione della password self-service, la risposta include un token di continuazione. Questo token identifica in modo univoco il flusso corrente e consente Microsoft Entra ID mantenere lo stato tra gli endpoint. Includere il token in ogni richiesta successiva in tale flusso. È valido solo per un periodo di tempo limitato e può essere usato solo per le richieste successive all'interno dello stesso flusso.
Riferimento API per l'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 API per l'iscrizione
| Punto finale | 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 challenge supportati da Microsoft Entra. Microsoft Entra quindi seleziona 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 ha un metodo di autenticazione scelto da Microsoft Entra. |
oauth/v2.0/token |
L'applicazione chiama questo endpoint per richiedere infine i token di sicurezza. L'app deve usare 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.
Questo diagramma indica che l'app raccoglie il nome utente (indirizzo di posta elettronica), la password (per la posta elettronica con flusso 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 (indirizzo di posta elettronica), la password e tutti i valori obbligatori e facoltativi degli attributi nella stessa schermata, quindi inviarli tutti all'endpoint /signup/v1.0/start . Se l'app invia tutte le informazioni necessarie all'endpoint /signup/v1.0/start , l'app non deve effettuare chiamate e gestire le risposte nei passaggi facoltativi.
Nel passaggio 21 l'utente è già iscritto. Tuttavia, se l'app richiede di accedere automaticamente a un utente dopo l'iscrizione, l'app chiama l'endpoint oauth/v2.0/token per richiedere token di sicurezza.
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 esempi della richiesta (è presente la richiesta di esempio in più righe per la 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.
Altre informazioni sui criteri 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 tutti gli attributi inviati, che non esistono. |
capabilities |
NO | Flag separati da spazi che descrivono le funzionalità dell'app client. Anche se challenge_type definisce i metodi che è possibile verificare, capabilities indicare all'API di autenticazione nativa quali flussi aggiuntivi l'app client può gestire e quali interfacce utente possono essere visualizzate all'utente. Ad esempio, mfa_required significa un altro /challenge ciclo e /token , registration_required significa che l'app client chiama le API di registrazione e mostra l'interfaccia utente di registrazione. Se una funzionalità necessaria non viene pubblicizzata dall'app client, l'API restituisce il reindirizzamento. I valori supportati sono mfa_required e registration_required.
Altre informazioni sulle funzionalità. |
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…",
}
| Proprietà | Descrizione |
|---|---|
continuation_token |
Tokencontinuation restituito dal Microsoft Entra. |
Risposta di reindirizzamento
Se l'app client non supporta il metodo di autenticazione o le funzionalità necessarie Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un redirect tipo di richiesta nella risposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Proprietà | Descrizione |
|---|---|
challenge_type |
Microsoft Entra restituisce una risposta con un tipo di verifica. 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
1003037
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Proprietà | 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 suberror valore della proprietà è 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 della error proprietà):
| 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. Utilizzare la suberror proprietà 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. Utilizzare la suberror proprietà 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 invalid_grant, Microsoft Entra include una proprietà suberror nella risposta. Ecco i valori possibili della suberror proprietà 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à. Altre informazioni sui criteri 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. Altre informazioni sui criteri 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. Altre informazioni sui criteri 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. Altre informazioni sui criteri 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. Altre informazioni sui criteri 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. Altre informazioni sui criteri password di Microsoft Entra. Questa risposta è possibile se l'app invia una password utente. |
Se il parametro di errore ha un valore
| 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 in modo esplicito gli 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 Microsoft Entra di selezionare uno dei tipi di richiesta 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ì | Tokencontinuation Microsoft Entra restituito nella richiesta precedente. |
Risposta in caso di esito positivo
Microsoft Entra invia un passcode monouso al messaggio di posta elettronica dell'utente, quindi risponde con il tipo di richiesta con 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
}
| Proprietà | Descrizione |
|---|---|
interval |
L'intervallo di tempo in secondi che l'app deve attendere prima di tentare di inviare nuovamente l’OTP. |
continuation_token |
Tokencontinuation restituito dal 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 Microsoft Entra. |
Risposta di reindirizzamento
Se l'app client non supporta il metodo di autenticazione o le funzionalità necessarie Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un redirect tipo di richiesta nella risposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Proprietà | Descrizione |
|---|---|
challenge_type |
Microsoft Entra restituisce una risposta con un tipo di verifica. 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Proprietà | 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 della error proprietà):
| 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ì | Tokencontinuation Microsoft Entra restituito 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:
| Sceneggiatura | Come procedere |
|---|---|
L'app invia correttamente la password dell'utente (per la posta elettronica con il metodo di autenticazione della password) tramite l'endpoint /signup/v1.0/start e non vengono configurati attributi nell'interfaccia di amministrazione di Microsoft Entra o tutti gli attributi utente necessari vengono 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 in Richiesta di token di sicurezza. |
L'app invia correttamente la password dell'utente per la posta elettronica 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 utente attributi obbligatori. |
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. |
Microsoft Entra risposta indica che le credenziali sono necessarie. Vedere la risposta. Tale risposta è possibile per l’e-mail con il metodo di autenticazione della password. |
Risposta
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..."
}
| Proprietà | 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 |
Tokencontinuation restituito dal 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 della error proprietà):
| 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 invalid_grant, Microsoft Entra include una proprietà suberror nella risposta. Ecco i valori possibili della suberror proprietà 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ì | Tokencontinuation Microsoft Entra restituito nella richiesta precedente. |
Risposta in caso di esito positivo
Se la password è il metodo di autenticazione configurato per l'utente nell'interfaccia di amministrazione Microsoft Entra, viene restituita all'app una risposta con esito positivo con il token di continuazione.
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "password",
"continuation_token": " AQABAAEAAAAty..."
}
| Proprietà | Descrizione |
|---|---|
challenge_type |
La password viene restituita nella risposta per le credenziali necessarie. |
continuation_token |
Tokencontinuation restituito dal Microsoft Entra. |
Risposta di reindirizzamento
Se l'app client non supporta il metodo di autenticazione o le funzionalità necessarie Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un redirect tipo di richiesta nella risposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Proprietà | Descrizione |
|---|---|
challenge_type |
Microsoft Entra restituisce una risposta con un tipo di verifica. 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 la password, che Microsoft Entra richiesta 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ì | Tokencontinuation Microsoft Entra restituito 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.
Altre informazioni sui criteri 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 in Richiesta di token di sicurezza. In caso contrario, Microsoft Entra risposta indica che l'app deve inviare attributi obbligatori. Questi attributi, incorporati o personalizzati, sono stati configurati nell'interfaccia di amministrazione Microsoft Entra dall'amministratore tenant.
Attributi utente obbligatori
Questa risposta richiede all'app di inviare valori per gli attributi nome, età e telefono .
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 .
| Proprietà | Descrizione |
|---|---|
error |
Questo attributo viene impostato se Microsoft Entra non può 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 |
Tokencontinuation restituito dal 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 è la risposta se il valore del parametro error è attributes_required. |
Di seguito sono riportati i possibili errori che è possibile riscontrare (valori possibili della error proprietà):
| 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. |
Risposta di reindirizzamento
Se l'app client non supporta il metodo di autenticazione o le funzionalità necessarie Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un redirect tipo di richiesta nella risposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Proprietà | Descrizione |
|---|---|
challenge_type |
Microsoft Entra restituisce una risposta con un tipo di verifica. 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": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
"suberror": "password_too_weak"
}
| Proprietà | 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 della error proprietà):
| 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. Utilizzare la suberror proprietà 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 invalid_grant, Microsoft Entra include una proprietà suberror nella risposta. Ecco i valori possibili della suberror proprietà:
| Valore sub-errore | Descrizione |
|---|---|
password_too_weak |
La password è troppo debole in quanto non soddisfa i requisiti di complessità. Altre informazioni sui criteri password di Microsoft Entra. |
password_too_short |
La nuova password contiene meno di 8 caratteri. Altre informazioni sui criteri password di Microsoft Entra. |
password_too_long |
La nuova password contiene più di 256 caratteri. Altre informazioni sui criteri password di Microsoft Entra. |
password_recently_used |
La nuova password non deve corrispondere a una usata di recente. Altre informazioni sui criteri password di Microsoft Entra. |
password_banned |
La nuova password contiene una parola, una frase o un criterio vietato. Altre informazioni sui criteri password di Microsoft Entra. |
password_is_invalid |
La password non è valida, ad esempio perché usa caratteri non consentiti. Altre informazioni sui criteri 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}", "postalCode": "{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ì | Tokencontinuation Microsoft Entra restituito 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 tutti gli attributi inviati, che non esistono. |
Risposta in caso di esito positivo
Se la richiesta ha esito positivo, Microsoft Entra iscriversi all'utente, rilascia un token di continuazione. L'app può usare il token di continuazione per richiedere token di sicurezza dall'endpoint oauth/v2.0/token .
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAAYn..."
}
| Proprietà | Descrizione |
|---|---|
continuation_token |
Tokencontinuation restituito dal Microsoft Entra. |
Risposta di reindirizzamento
Se l'app client non supporta il metodo di autenticazione o le funzionalità necessarie Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un redirect tipo di richiesta nella risposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Proprietà | Descrizione |
|---|---|
challenge_type |
Microsoft Entra restituisce una risposta con un tipo di verifica. 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
552003
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Proprietà | 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 |
Tokencontinuation restituito dal 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 della proprietà è 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 della error proprietà):
| 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. Utilizzare la suberror proprietà 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 invalid_grant, Microsoft Entra include una proprietà suberror nella risposta. Ecco i valori possibili della suberror proprietà 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: Accedere automaticamente dopo l'iscrizione
Se l'utente deve accedere automaticamente dopo l'iscrizione, l'app effettua una richiesta POST all'endpoint oauth/v2.0/token e fornisce il token di continuazione ottenuto dal passaggio precedente per acquisire i token di sicurezza. Informazioni su come chiamare l'endpoint del token.
Invio di attributi utente agli endpoint
Nell'interfaccia di amministrazione di Microsoft Entra è possibile configurare gli attributi utente come richiesto o facoltativo. Questa configurazione determina il modo in cui Microsoft Entra risponde quando si effettua una chiamata agli 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 Microsoft Entra.
| Punto finale | 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 |
|---|---|
| Casella di testo | 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 da come farvi riferimento nell'API di autenticazione nativa.
Ad esempio, Nome di riproduzione nell'interfaccia di amministrazione di Microsoft Entra viene fatto riferimento 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.
Riferimento API per il flusso di accesso
Gli utenti devono accedere con il metodo di autenticazione usato per iscriversi. 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, oauth/v2.0/initiate, oauth/v2.0/challenge, oauth/v2.0/tokene facoltativamente oauth/v2.0/introspect.
Endpoint API per il login
| Punto finale | Descrizione |
|---|---|
oauth/v2.0/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 deve usare un flusso di autenticazione basato su browser. |
oauth/v2.0/challenge |
L'app chiama questo endpoint per richiedere Microsoft Entra di selezionare uno dei tipi di verifica di accesso supportati con cui l'utente deve eseguire l'autenticazione. Se l'amministratore tenant applica l'autenticazione a più fattori per gli utenti dei clienti, l'app chiama questo endpoint per sfidare l'utente per il secondo metodo di autenticazione a fattori. |
oauth/v2.0/token |
Questo endpoint verifica le credenziali dell'utente che riceve dall'app, quindi rilascia i token di sicurezza all'app. Una risposta da questo endpoint può anche indicare se l'utente deve completare una richiesta di autenticazione a più fattori o registrare un metodo di autenticazione avanzata. |
oauth/v2.0/introspect |
L'app lo chiama per richiedere un elenco di metodi di autenticazione avanzata registrati per l'autenticazione a più fattori (MFA). Informazioni su come usare l'endpoint introspettivo |
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. Il flusso di accesso dipende dal metodo di autenticazione dell'utente.
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 flusso di accesso 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
&capabilities=registration_required mfa_required
| 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. |
capabilities |
NO | Flag separati da spazi che descrivono l'idoneità "how" dell'app client. Anche se challenge_type definisce i metodi che è possibile verificare, capabilities indicare all'API di autenticazione nativa quali flussi aggiuntivi l'app client può gestire e quali interfacce utente può mostrare. Ad esempio, mfa_required significa /introspect, /challengee /token ciclo; registration_required significa che l'app client chiama le API di registrazione e mostra l'interfaccia utente di registrazione. Se la funzionalità necessaria non è inclusa dall'app client, l'API restituisce il reindirizzamento. I valori supportati sono mfa_required e registration_required.
Altre informazioni sulle funzionalità. |
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..."
}
| Proprietà | Descrizione |
|---|---|
continuation_token |
Tokencontinuation restituito dal Microsoft Entra. |
Risposta di reindirizzamento
Se l'app client non supporta il metodo di autenticazione o le funzionalità necessarie Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un redirect tipo di richiesta nella risposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Proprietà | Descrizione |
|---|---|
challenge_type |
Microsoft Entra restituisce una risposta con un tipo di verifica. 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Proprietà | 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 della error proprietà):
| 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. Utilizzare la suberror proprietà 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
| 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 Microsoft Entra di selezionare uno dei tipi di verifica supportati per l'autenticazione o il completamento di una richiesta di autenticazione a più fattori. L'app effettua una richiesta POST all'endpoint /oauth2/v2.0/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ì |
Tokencontinuation Microsoft Entra restituito nella richiesta precedente. La richiesta precedente chiama l'endpoint /oauth2/v2.0/initiate o l'endpoint /oauth2/v2.0/introspect se l'utente completa una richiesta di autenticazione a più fattori. |
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. |
id |
NO | Identificatore di stringa del metodo di autenticazione avanzata restituito dall'endpoint /oauth2/v2.0/introspect . Questo parametro è obbligatorio quando l'app client sfida l'utente per un secondo fattore di autenticazione. Informazioni su come usare l'endpoint di introspezione. |
Risposta in caso di esito positivo
La risposta di esito positivo dipende dal metodo di autenticazione dell'utente.
Se l'amministratore del tenant ha configurato il passcode monouso nell'interfaccia di amministrazione di Microsoft Entra come metodo di autenticazione dell'utente, Microsoft Entra invia un passcode monouso al messaggio di posta elettronica dell'utente, risponde con un tipo di richiesta di ob 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
}
| Proprietà | Descrizione |
|---|---|
continuation_token |
Tokencontinuation restituito dal 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 Microsoft Entra. |
Risposta di reindirizzamento
È possibile che sia necessario un fallback a un flusso di autenticazione basato sul Web negli scenari seguenti:
- L'app client non supporta il metodo o le funzionalità di autenticazione richieste Microsoft Entra.
- L'utente tenta di usare SMS come metodo di autenticazione avanzata, ma la protezione dalle frodi blocca la richiesta se lo ritiene ad alto rischio (solo nella posta elettronica con autenticazione della password).
In questi scenari, Microsoft Entra informa l'app restituendo un redirect tipo di richiesta nella risposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Proprietà | Descrizione |
|---|---|
challenge_type |
Microsoft Entra restituisce una risposta con un tipo di verifica. 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Proprietà | 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 della error proprietà):
| 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 oauth2/v2.0/token e fornisce le credenziali dell'utente scelte nel 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=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ì | Tokencontinuation Microsoft Entra restituito nella richiesta precedente. |
grant_type |
Sì | Tipo di concessione. Quando si chiama l'endpoint del token, questo valore deve essere: - password per la posta elettronica con metodo di autenticazione della password in un flusso di accesso per verificare il primo fattore di autenticazione dell'utente. - oob per il metodo di autenticazione con passcode monouso tramite posta elettronica in un flusso di accesso. - continuation_token per l'accesso automatico dopo un flusso di iscrizione. - continuation_token per l'accesso automatico dopo il flusso di reimpostazione della password self-service. - continuation_token dopo un flusso di registrazione del metodo di autenticazione avanzata. - mfa_oob quando si verifica la seconda autenticazione a fattori dell'utente. |
scope |
Sì | Elenco di ambiti separato da spazi. Tutti gli ambiti devono essere di una singola risorsa, insieme agli ambiti OIDC (OpenID Connect), ad esempio profilo, openid e posta elettronica. L'app deve includere openid ambito per Microsoft Entra rilasciare un token ID. L'app deve includere offline_access ambito per Microsoft Entra rilasciare un token di aggiornamento. Ulteriori informazioni su Autorizzazioni e consenso in Microsoft Identity Platform. |
password |
NO | Valore della password che l'app raccoglie dall'utente. Sostituire {secure_password} con il valore della password che l'app raccoglie dall'utente. Questo parametro è obbligatorio se il metodo di autenticazione è un messaggio di posta elettronica con password. |
oob |
NO | Passcode monouso ricevuto dall'utente tramite posta elettronica. Obbligatorio se: - Il metodo di autenticazione principale è un passcode monouso tramite posta elettronica. - L'app invia il passcode monouso tramite posta elettronica per soddisfare una richiesta di autenticazione a più fattori quando il metodo di autenticazione principale viene inviato tramite posta elettronica con password. Per inviare nuovamente un passcode monouso, chiamare di nuovo l'endpoint /challenge . |
username |
NO | Indirizzo di posta elettronica dell'utente con cui si vuole iscriversi, ad esempio contoso-consumer@contoso.com. Questo parametro è obbligatorio in un flusso di iscrizione. |
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..."
}
| Proprietà | Descrizione |
|---|---|
token_type |
Indica il valore del tipo di token. L'unico tipo supportato da Microsoft Entra è Bearer. |
scopes |
Elenco delimitato da spazi di ambiti per i quali 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 altri dettagli sull'aggiornamento di un token di accesso, vedere 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. 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 in Microsoft Identity Platform. 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Proprietà | Descrizione |
|---|---|
error |
Stringa di codice di errore che può essere usata per classificare i tipi di errori e reagire agli errori. |
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 della error proprietà):
| 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, le credenziali di accesso utente incluse nella richiesta non sono valide, un'ulteriore interazione richiesta dall'utente o 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ù ambiti inclusi nella richiesta non sono validi. |
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. |
Se il parametro di errore ha un valore invalid_grant, Microsoft Entra include una proprietà suberror nella risposta. Ecco i valori possibili della suberror proprietà per un errore di invalid_grant :
| Valore sub-errore | Descrizione |
|---|---|
invalid_oob_value |
Il valore di passcode monouso inviato dall'app non è valido. |
mfa_required |
L'autenticazione a più fattori è obbligatoria. La risposta include un token di continuazione. Chiamare l'endpoint oauth2/v2.0/introspect per ottenere i metodi di autenticazione avanzata registrati dall'utente. Questo sottoerrore si verifica solo quando il metodo di autenticazione principale dell'utente è un messaggio di posta elettronica con password. Vedere come ottenere i metodi di autenticazione avanzata registrati di un utente. Nota: in alcuni casi l'autenticazione a più fattori è obbligatoria, ma l'autenticazione nativa non restituisce mfa_required. oppure, se un flusso di registrazione del metodo di autenticazione avanzata precede una chiamata a /oauth2/v2.0/token e l'unico metodo disponibile (messaggio di posta elettronica) è già stato verificato durante tale flusso. |
registration_required |
L'utente deve completare una richiesta di autenticazione a più fattori, ma non ha un metodo di autenticazione avanzata registrato. Chiedere all'utente di registrare uno. Questo errore si verifica quando il metodo di autenticazione principale dell'utente è un messaggio di posta elettronica con password. Informazioni su come registrare un metodo di autenticazione avanzata. |
Risposta di reindirizzamento
Se l'app client non supporta il metodo di autenticazione o la funzionalità necessaria Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un redirect tipo di richiesta nella risposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect",
"redirect_reason": "Client is missing registration_required capability"
}
| Proprietà | Descrizione |
|---|---|
challenge_type |
Microsoft Entra restituisce una risposta con un tipo di verifica. Il valore di questo tipo di test è il reindirizzamento, che consente all'app di usare il flusso di autenticazione basato sul Web. |
redirect_reason |
Motivo per cui è necessario un reindirizzamento. Ad esempio, Microsoft Entra rileva che è necessaria l'autenticazione a più fattori o una registrazione per un metodo di autenticazione avanzata, ma l'app non include queste funzionalità nella richiesta. |
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.
Ottenere i metodi di autenticazione avanzata registrati dall'utente
Usare l'endpoint oauth2/v2.0/introspect per richiedere l'elenco di metodi di autenticazione avanzata registrati dell'utente.
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/introspect
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
| 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ì | Tokencontinuation Microsoft Entra restituito nella richiesta precedente. |
Risposta in caso di esito positivo
Esempio:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"methods":[
{
"id":"0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c",
"challenge_type":"oob",
"challenge_channel":"email",
"login_hint":"c***r@co**o**o.com"
},
{
"id": "1b1b1b1b-2222-cccc-3333-4d4d4d4d4d4d",
"challenge_type": "oob",
"challenge_channel": "sms",
"login_hint": "+1********6"
}
]
}
| Proprietà | Descrizione |
|---|---|
continuation_token |
Tokencontinuation restituito dal Microsoft Entra. |
methods |
Elenco (di oggetti) di metodi di autenticazione avanzata registrati dall'utente. |
L'oggetto metodo MFA ha le proprietà seguenti:
| Proprietà | Descrizione |
|---|---|
id |
Identificatore di stringa univoco generato automaticamente per il metodo MFA. L'app usa questa stringa come id quando chiama l'endpoint /oauth2/v2.0/challenge . |
challenge_type |
Tipo di richiesta selezionato per l'utente da usare come metodo MFA. Il tipo di verifica supportato corrente è oob. |
challenge_channel |
Tipo del canale a cui viene inviato il metodo MFA. Il canale di verifica supportato corrente è la posta elettronica. |
login_hint |
Hint per il metodo di autenticazione avanzata, ad esempio un messaggio di posta elettronica offuscato. |
Risposta di reindirizzamento
Se l'app client non supporta il metodo di autenticazione o le funzionalità necessarie Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un redirect tipo di richiesta nella risposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
Risposta con errore
Esempio:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Proprietà | 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 della error proprietà):
| 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_client |
L'ID client incluso nella richiesta non è per un client pubblico. |
expired_token |
Il token di continuazione incluso nella richiesta è scaduto. |
server_error |
Si è verificato un problema con la richiesta. |
Dopo che l'app client recupera correttamente un elenco di metodi di autenticazione avanzata registrati per l'utente, l'utente seleziona un metodo da usare per completare la richiesta di autenticazione a più fattori. Il flusso procede quindi come segue:
L'app client chiama
/oauth2/v2.0/challengee include il token di continuazione ottenuto da/oauth2/v2.0/introspecte iliddel metodo MFA scelto: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 &id=0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c &continuation_token=uY29tL2F1dGhlbnRpY...Microsoft Entra invia un codice di verifica al canale di verifica dell'utente, ad esempio la posta elettronica, e quindi risponde all'app client con un token di continuazione e i dettagli della richiesta di autenticazione a più fattori:
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 }L'app può ora effettuare una richiesta POST all'endpoint
/oauth2/v2.0/tokene include un token di continuazione, un tipo di concessione corretto e i valori del tipo di concessione corrispondenti per ottenere i token di sicurezza. Vedere la risposta prevista nella richiesta di token di sicurezza:POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token Content-Type: application/x-www-form-urlencoded client_id=00001111-aaaa-2222-bbbb-3333cccc4444 &continuation_token=uY29tL2F1dGhlbnRpY... &grant_type=mfa_oob &oob={otp_code} &scope=openid offline_access
Registrare un riferimento all'API del metodo di autenticazione avanzata
L'autenticazione nativa supporta la registrazione del metodo di autenticazione avanzata. Quando l'app chiama l'endpoint /oauth2/v2.0/token e l'autenticazione a più fattori è necessaria, ma l'utente non ha un metodo sicuro registrato, la risposta registeration_required indica all'app di registrare uno prima che i token possano essere rilasciati.
Dopo che l'app client ha completato il flusso per registrare un metodo di autenticazione avanzata, chiama l'endpoint /oauth2/v2.0/token per richiedere token di sicurezza.
Endpoint di registrazione del metodo di autenticazione avanzata
Per usare l'API di registrazione del metodo di autenticazione avanzata, l'app usa l'endpoint illustrato nella tabella seguente:
| Punto finale | Descrizione |
|---|---|
/register/v1.0/introspect |
Chiamare questo endpoint per recuperare un elenco di metodi di autenticazione avanzata che l'utente può registrare. |
/register/v1.0/challenge |
Chiamare questo endpoint per inviare la richiesta di verifica all'utente, ad esempio un passcode monouso tramite posta elettronica. |
/register/v1.0/continue |
Chiamare questo endpoint per inviare la richiesta di verifica che l'app raccoglie dall'utente, ad esempio un passcode monouso, per completare un flusso per registrare un metodo di autenticazione avanzata. Dopo che la chiamata ha esito positivo e si ottiene un token di continuazione, chiamare l'endpoint dell'endpoint /oauth2/v2.0/token per richiedere i token di sicurezza.
Informazioni su come chiamare l'endpoint del token. |
Passaggio 1: Ottenere l'elenco dei metodi di autenticazione avanzata
Il flusso di registrazione inizia quando l'app richiede l'elenco di metodi di autenticazione avanzata che l'utente può registrare.
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/register/v1.0/introspect
Content-Type: application/x-www-form-urlencoded
?continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
| 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. |
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...",
"methods":[
{
"id":"email",
"challenge_type":"oob",
"challenge_channel":"email",
"login_hint":"caseyjensen@contoso.com"
},
{
"id": "sms",
"challenge_type": "oob",
"challenge_channel": "sms"
}
]
}
| Proprietà | Descrizione |
|---|---|
continuation_token |
Tokencontinuation restituito dal Microsoft Entra. |
methods |
Elenco (di oggetti) di metodi di autenticazione avanzata disponibili per la registrazione dell'utente. |
L'oggetto metodi di autenticazione avanzata ha le proprietà seguenti:
| Proprietà | Descrizione |
|---|---|
id |
Chiave stringa del metodo. Valori supportati tramite posta elettronica, sms. |
challenge_type |
Tipo di richiesta selezionato per l'utente da usare come metodo MFA. Il tipo di verifica supportato corrente è oob. |
challenge_channel |
Tipo del canale a cui viene inviato il metodo MFA. Valori supportati tramite posta elettronica, sms. |
login_hint |
Hint per il metodo di autenticazione avanzata, ad esempio un messaggio di posta elettronica. Questo valore viene usato dall'app client per prepopopolare la casella di testo di posta elettronica. |
Risposta con errore
Esempio:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Proprietà | 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 della error proprietà):
| 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 l’OTP e-mail per tutti gli utenti tenant. |
expired_token |
Il token di continuazione incluso nella richiesta è scaduto. |
Passaggio 2: Selezionare un metodo di autenticazione avanzata
In questo passaggio inviare il metodo di autenticazione avanzata che l'utente vuole registrare. Microsoft Entra quindi invia una richiesta di verifica, ad esempio un passcode monouso tramite posta elettronica, all'utente.
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/register/v1.0/challenge
?continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob
&challenge_channel=email
&challenge_target=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. |
continuation_token |
Sì | Token Continuation restituito dall'endpoint Microsoft Entra /register/v1.0/introspect |
challenge_type |
Sì | Tipo di richiesta del metodo di autenticazione. Il tipo corrente è oob. |
challenge_target |
Sì | Indirizzo di posta elettronica o numero di telefono che l'utente vuole registrare. |
challenge_channel |
NO | Canale su cui inviare la richiesta. Valori del canale di verifica supportati: posta elettronica, sms. |
Risposta in caso di esito positivo
Di seguito è riportato un esempio di risposta riuscita.
Esempio 1:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"challenge_type": "oob",
"binding_method": "prompt",
"challenge_target": "contoso-consumer@contoso.com",
"challenge_channel": "email",
"code_length": 8
}
Esempio 2:
Se il flusso di iscrizione precede il flusso di registrazione del metodo di autenticazione avanzata e il messaggio di posta elettronica inviato all'endpoint /register/v1.0/challenge corrisponde a quello verificato nel flusso di iscrizione, l'API di autenticazione nativa registra il metodo senza inviare una richiesta di verifica all'utente. In questo caso, la risposta sarà simile al frammento di codice seguente:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"challenge_type": "preverified"
}
| Proprietà | Descrizione |
|---|---|
continuation_token |
Tokencontinuation restituito dal Microsoft Entra. |
challenge_type |
Tipo di richiesta selezionato per l'autenticazione da parte dell'utente, ad esempio oob o preverficato se il metodo di autenticazione avanzata viene verificato in modo preliminare. |
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 e il metodo di autenticazione avanzata non viene preverficato. |
challenge_channel |
Tipo del canale tramite il quale è stato inviato il passcode monouso. Valori supportati tramite posta elettronica, sms. Restituito se il metodo di autenticazione avanzata non è preverficato. |
code_length |
Lunghezza del passcode monouso se binding_method richiesto. Restituito se il metodo di autenticazione avanzata non è preverficato. |
challenge_target |
Destinazione a cui è stata inviata la sfida. Corrisponde all'input fornito nella richiesta. Restituito se il metodo di autenticazione avanzata non è preverficato. |
interval |
L'intervallo (in secondi) che il client deve attendere tra il polling di /register/continue. Restituito solo se prompt=none e il metodo di autenticazione avanzata non viene verificato. I client devono raddoppiare l'intervallo ogni volta che ricevono un oggetto HTTP 429 dall'API di autenticazione nativa. |
Risposta con errore
Gli errori riportati di seguito sono simili a quelli che è possibile riscontrare quando si chiama l'endpoint /register/v1.0/introspect . Tuttavia, quando si registra il numero di telefono, se il numero di telefono è considerato ad alto rischio, la richiesta potrebbe essere bloccata.
Di seguito sono riportati i possibili errori che è possibile riscontrare se la richiesta è bloccata:
| Valore di errore | Descrizione |
|---|---|
access_denied |
L'SMS è stato bloccato. |
Se il parametro di errore ha un valore access_denied, Microsoft Entra include una proprietà suberror nella risposta. Ecco i valori possibili della proprietà suberror per un errore invalid_grant:
| Valore sub-errore | Descrizione |
|---|---|
provider_blocked_by_admin |
L'amministratore tenant ha bloccato l'area telefonica. |
provider_blocked_by_rep |
Il metodo di autenticazione a più fattori è bloccato (il numero di telefono è stato bloccato da RepMap). |
Passaggio 3: Inviare una richiesta
In questo passaggio effettuare una chiamata all'endpoint /register/v1.0/continue per completare la registrazione del metodo di autenticazione avanzata.
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/register/v1.0/continue
?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ì | Tokencontinuation Microsoft Entra restituito nella richiesta precedente. |
client_id |
Sì | ID applicazione (client) dell'app registrata nell'interfaccia di amministrazione di Microsoft Entra. |
grant_type |
Sì | Tipo di concessione. Il valore supportato corrente è oob o continuation_token se il metodo di autenticazione avanzata viene verificato nell'endpoint /register/v1.0/challenge . |
oob |
NO | 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 /register/v1.0/challenge. Obbligatorio se il metodo di autenticazione avanzata non viene verificato nell'endpoint /register/v1.0/challenge . |
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..."
}
| Proprietà | Descrizione |
|---|---|
continuation_token |
Token di continuation restituito Microsoft Entra. Usare questo token di continuazione per chiamare l'endpoint /oauth2/v2.0/token per richiedere token di sicurezza. Informazioni su come chiamare l'endpoint del token. |
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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
55200
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Proprietà | 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 della error proprietà):
| 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 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 invalid_grant, Microsoft Entra include una proprietà suberror nella risposta. Ecco i valori possibili della suberror proprietà per un errore di invalid_grant :
| Valore sub-errore | Descrizione |
|---|---|
invalid_oob_value |
Il valore del passcode monouso non è valido. |
Reimpostazione della password self-service
Per gli utenti il cui metodo di autenticazione primario è la posta elettronica con password, usare l'API di reimpostazione della password self-service (SSPR) per consentire agli utenti dei clienti di reimpostare la password. È possibile usare questa API per la password dimenticata o modificare gli scenari di password.
Endpoint API per il reset della password in autoservizio
Per usare questa API, l'app usa l'endpoint illustrato nella tabella seguente:
| Punto finale | Descrizione |
|---|---|
/resetpassword/v1.0/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 (indirizzo di posta elettronica), 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 deve usare un flusso di autenticazione basato su browser. |
/resetpassword/v1.0/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 deve usare un flusso di autenticazione basato su browser. |
/resetpassword/v1.0/continue |
Convalida il test emesso dall'endpoint /resetpassword/v1.0/challenge, quindi restituisce un token di continuazione per l'endpoint /resetpassword/v1.0/submit o rilascia un altro test all'utente. |
/resetpassword/v1.0/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. |
/resetpassword/v1.0/poll_completion |
L'app può usare il token di continuazione rilasciato dall'endpoint /resetpassword/v1.0/submit per controllare lo stato della richiesta di reimpostazione della password. |
oauth2/v2.0/token |
Se la reimpostazione della password ha esito positivo, l'app può usare il token di continuazione ottenuto dall'endpoint /resetpassword/v1.0/poll_completion per ottenere i token di sicurezza dall'endpoint oauth2/v2.0/token . |
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.
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 /resetpassword/v1.0/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 /resetpassword/v1.0/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. |
capabilities |
NO | Flag separati da spazi che descrivono l'idoneità "how" dell'app client. Anche se challenge_type definisce i metodi che è possibile verificare, capabilities indicare all'API di autenticazione nativa quali flussi aggiuntivi l'app client può gestire e quali interfacce utente può mostrare. Ad esempio, mfa_required significa un altro /challenge ciclo e /token , registration_required significa che l'app client chiama le API di registrazione e mostra l'interfaccia utente di registrazione. Se una funzionalità necessaria non viene pubblicizzata dall'app client, l'API restituisce il reindirizzamento. I valori supportati sono mfa_required e registration_required.
Altre informazioni sulle funzionalità. |
Risposta in caso di esito positivo
Esempio:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| Proprietà | Descrizione |
|---|---|
continuation_token |
Tokencontinuation restituito dal Microsoft Entra. |
Risposta di reindirizzamento
Se l'app client non supporta il metodo di autenticazione o le funzionalità necessarie Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un redirect tipo di richiesta nella risposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Proprietà | Descrizione |
|---|---|
challenge_type |
Microsoft Entra restituisce una risposta con un tipo di verifica. 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Proprietà | 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 della error proprietà):
| 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. Utilizzare la suberror proprietà 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
| Valore sub-errore | Descrizione |
|---|---|
nativeauthapi_disabled |
ID client per un'app non abilitata 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 Microsoft Entra di selezionare uno dei tipi di verifica supportati per l'autenticazione dell'utente. L'app effettua una richiesta POST all'endpoint /resetpassword/v1.0/challenge. Se la richiesta ha esito positivo, Microsoft Entra invia un passcode monouso al messaggio di posta elettronica 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=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ì | Tokencontinuation Microsoft Entra restituito 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
}
| Proprietà | Descrizione |
|---|---|
continuation_token |
Tokencontinuation restituito dal 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. Se l'autenticazione a più fattori è abilitata per l'utente, il messaggio di posta elettronica contenente il passcode monouso viene inviato a: - Indirizzo di posta elettronica usato come metodo di autenticazione avanzata quando l'indirizzo di posta elettronica è diverso dall'indirizzo di posta elettronica dell'account. : indirizzo di posta elettronica dell'account quando il metodo di autenticazione avanzata è SMS. |
code_length |
Lunghezza del passcode monouso generato Microsoft Entra. |
Risposta di reindirizzamento
Se l'app client non supporta il metodo di autenticazione o le funzionalità necessarie Microsoft Entra, è necessario un fallback al flusso di autenticazione basato sul Web. In questo scenario, Microsoft Entra informa l'app restituendo un redirect tipo di richiesta nella risposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Proprietà | Descrizione |
|---|---|
challenge_type |
Microsoft Entra restituisce una risposta con un tipo di verifica. 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Proprietà | 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 della error proprietà):
| 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 /resetpassword/v1.0/continue. Nella richiesta l'app deve includere le credenziali dell'utente selezionate nel passaggio precedente e il token di continuazione emesso dall'endpoint /resetpassword/v1.0/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ì | Tokencontinuation Microsoft Entra restituito 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 /resetpassword/v1.0/challenge. |
Risposta in caso di esito positivo
Esempio:
HTTP/1.1 200 OK
Content-Type: application/json
{
"expires_in": 600,
"continuation_token": "czZCaGRSa3F0MzpnW...",
}
| Proprietà | Descrizione |
|---|---|
expires_in |
Tempo in secondi prima della scadenza di continuation_token. Il valore massimo di expires_in è 600 secondi. |
continuation_token |
Tokencontinuation restituito dal 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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
55200
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Proprietà | 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 della error proprietà):
| 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. Utilizzare la suberror proprietà per apprendere la causa esatta dell'errore. |
expired_token |
Il token di continuazione è scaduto. |
Se il parametro di errore ha un valore invalid_grant, Microsoft Entra include una proprietà suberror nella risposta. Ecco i valori possibili della suberror proprietà per un errore di invalid_grant :
| Valore sub-errore | Descrizione |
|---|---|
invalid_oob_value |
Il valore del passcode monouso 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 /resetpassword/v1.0/continue per inviare la password effettuando una richiesta POST all'endpoint /resetpassword/v1.0/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ì | Tokencontinuation Microsoft Entra restituito 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.
Altre informazioni sui criteri 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
}
| Proprietà | Descrizione |
|---|---|
continuation_token |
Tokencontinuation restituito dal 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 /resetpassword/v1.0/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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Proprietà | 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 della error proprietà):
| 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. Utilizzare la suberror proprietà per apprendere la causa esatta dell'errore. |
Se il parametro di errore ha un valore invalid_grant, Microsoft Entra include una proprietà suberror nella risposta. Ecco i valori possibili della suberror proprietà:
| Valore sub-errore | Descrizione |
|---|---|
password_too_weak |
La password è troppo debole in quanto non soddisfa i requisiti di complessità. Altre informazioni sui criteri password di Microsoft Entra. |
password_too_short |
La nuova password contiene meno di 8 caratteri. Altre informazioni sui criteri password di Microsoft Entra. |
password_too_long |
La nuova password contiene più di 256 caratteri. Altre informazioni sui criteri password di Microsoft Entra. |
password_recently_used |
La nuova password non deve corrispondere a una usata di recente. Altre informazioni sui criteri password di Microsoft Entra. |
password_banned |
La nuova password contiene una parola, una frase o un criterio vietato. Altre informazioni sui criteri password di Microsoft Entra. |
password_is_invalid |
La password non è valida, ad esempio perché usa caratteri non consentiti. Altre informazioni sui criteri 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 /resetpassword/v1.0/poll_completion per eseguire il polling di Microsoft Entra per lo stato di reimpostazione della password. La quantità minima di tempo in secondi che l'app dovrebbe attendere tra le richieste di polling viene restituita dall'endpoint /resetpassword/v1.0/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ì | Tokencontinuation Microsoft Entra restituito 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..."
}
| Proprietà | Descrizione |
|---|---|
status |
Stato della richiesta di reimpostazione della password. Se Microsoft Entra restituisce lo stato failed, l'app può inviare nuovamente la nuova password effettuando un'altra richiesta all'endpoint /resetpassword/v1.0/submit e includere il nuovo token di continuazione. |
continuation_token |
Tokencontinuation restituito dal Microsoft Entra. Se lo stato è |
Ecco i possibili stati restituiti Microsoft Entra (valori possibili 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 /resetpassword/v1.0/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: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
552003
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Proprietà | 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 della error proprietà):
| 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. |
Accesso automatico dopo la reimpostazione della password
Se l'utente deve accedere dopo la reimpostazione della password. L'app deve chiamare l'endpoint /oauth2/v2.0/token . Informazioni su come chiamare l'endpoint del token.