Riferimento API di autenticazione nativa

Si applica a: Tenant della forza lavoro Tenant esterni (altre informazioni)

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

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

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

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

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

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

Prerequisiti

1. Tenant esterno Microsoft Entra. Se non si dispone già di un tenant esterno, crearne uno.

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

3. Se non lo si è già fatto, creare un flusso utente nell'interfaccia di amministrazione di Microsoft Entra. Quando si crea il flusso utente, prendere nota degli attributi utente configurati necessari, in quanto sono quelli che Microsoft Entra prevede che l'app invii.

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

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

6. 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.

Token di continuazione

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

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

Informazioni di riferimento API di iscrizione

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

Endpoint dell'API di iscrizione

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

Passaggio 1: Richiedere di avviare il flusso di iscrizione

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

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

Esempio 1:

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

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

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

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

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&password={secure_password}
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postalCode": "{user_postal_code}"}
&username=contoso-consumer@contoso.com 

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…",
} 

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

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

{     
   "challenge_type": "redirect" 
} 

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"
} 

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

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

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

Passaggio 2: Selezionare un metodo di autenticazione

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

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

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

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…

Risposta in caso di esito positivo

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

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

{
    "interval": 300,
    "continuation_token": "AQABAAEAAAYn...",
    "challenge_type": "oob",
    "binding_method": "prompt",
    "challenge_channel": "email",
    "challenge_target_label": "c***r@co**o**o.com",
    "code_length": 8
} 

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

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

{
   "challenge_type": "redirect"
}

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"
} 

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

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}

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

Response

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

{
    "error": "credential_required",
    "error_description": "AADSTS55103: Credential required. Trace ID: d6966055-...-80500 Correlation ID: 3944-...-60d6 Timestamp: yy-mm-dd 02:37:33Z",
    "error_codes": [
        55103
    ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABEQEAAAA..."
} 

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

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

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…

Risposta in caso di esito positivo

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

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

{
    "challenge_type": "password",
    "continuation_token": " AQABAAEAAAAty..."
}

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

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

{     
    "challenge_type": "redirect" 
} 

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

Passaggio 4: Autenticare e ottenere il token per iscriversi

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

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

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

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=password 
&password={secure_password}

Risposta in caso di esito positivo

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

Attributi utente obbligatori

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

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

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

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

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

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

{     
   "challenge_type": "redirect" 
} 

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"
}

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

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

Inviare attributi utente

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

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

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

&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=attributes 
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postaCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...

Risposta in caso di esito positivo

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

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

{  
    "continuation_token": "AQABAAEAAAYn..."
} 

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

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

{     
   "challenge_type": "redirect" 
} 

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" 
}

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

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

Passaggio 5: Richiedere token di sicurezza

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

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

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
 
continuation_token=ABAAEAAAAtyo... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&username=contoso-consumer@contoso.com
&scope={scopes}
&grant_type=continuation_token 

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..."
}

Risposta con errore

Esempio:

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

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The client doesn't have consent for the requested scopes.\r\nTrace ID: 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"
} 

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

Invio di attributi utente agli endpoint

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

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

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.

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

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

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

Come fare riferimento agli attributi utente

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

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

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

Informazioni di riferimento API di accesso

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

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

Endpoint dell'API di accesso

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.

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

Passaggio 1: Richiedere di avviare il flusso di accesso

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

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

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

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

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..."
}

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

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

{     
   "challenge_type": "redirect" 
} 

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"
} 

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

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

Passaggio 2: Selezionare un metodo di autenticazione

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

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

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

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect 
&continuation_token=uY29tL2F1dGhlbnRpY... 

Risposta in caso di esito positivo

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
} 

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

{   
   "continuation_token": "uY29tL2F1dGhlbnRpY",   
   "challenge_type": "password" 
} 

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

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

{     
   "challenge_type": "redirect" 
} 

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"
} 

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

Passaggio 3: Richiedere token di sicurezza

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

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

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

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=password 
&password={secure_password}
&scope=openid offline_access 

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..."
}

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"
} 

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

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

Reimpostazione della password self-service

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

Endpoint API di reimpostazione della password self-service

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

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 /submit ove è necessaria.

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

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

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

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

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

Risposta in caso di esito positivo

Esempio:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

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

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

{     
   "challenge_type": "redirect" 
} 

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"
} 

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

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

Passaggio 2: Selezionare un metodo di autenticazione

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

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

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

client_id=client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY... 

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
} 

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

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

{     
   "challenge_type": "redirect" 
} 

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"
} 

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

Passaggio 3: Inviare un passcode monouso

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

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

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

continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=oob 
&oob={otp_code}

Risposta in caso di esito positivo

Esempio:

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

{ 
    "expires_in": 600,
    "continuation_token": "czZCaGRSa3F0MzpnW...",
} 

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"
} 

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

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

Passaggio 4: Inviare una nuova password

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

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

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

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0Mzp...
&new_password={new_password}

Risposta in caso di esito positivo

Esempio:

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "poll_interval": 2
}

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"
} 

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

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

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

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

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

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

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0... 

Risposta in caso di esito positivo

Esempio:

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

{
    "status": "succeeded",
    "continuation_token":"czZCaGRSa3F0..."
} 

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

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"
} 

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

Contenuto correlato

• Configurare un provider di attestazioni personalizzato.