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 (altre informazioni)
Approccio di autenticazione: Autenticazione nativa incorporata.
La reimpostazione della password verifica il metodo di ripristino di un cliente, accetta una password sostitutiva ed esegue il polling di un aggiornamento asincrono. I metodi OTP (One-Time Passcode) di posta elettronica e SMS supportano il ripristino. I requisiti di autenticazione a più fattori (MFA) e di accesso condizionale possono essere applicati dopo la reimpostazione e prima del completamento dell'autorizzazione.
Per le integrazioni V1 esistenti, usare le informazioni di riferimento sulle API V1.
Prerequisites
Importante
L'API di autenticazione nativa V2 è disponibile in anteprima. L'API di autenticazione nativa V1 rimane disponibile a livello generale. Vedere le Condizioni per l'utilizzo supplementari per Microsoft Azure anteprime per le condizioni legali applicabili alle funzionalità di anteprima.
- Applicazione configurata per l'autenticazione nativa.
- La reimpostazione della password è abilitata per il tenant e il cliente, con un metodo di ripristino utilizzabile. Vedere Abilitare la reimpostazione della password self-service.
- Le autorizzazioni delegate e il consenso necessari per un'API di destinazione, se si richiede un ambito API.
Gli esempi usano un'autorità di dominio personalizzata verificata dal tenant.
custom_domain è il dominio di autenticazione ed tenant è il GUID del tenant.
Gli account OTP senza password non dispongono di una password da reimpostare.
Avviare la reimpostazione della password
Il diagramma mostra una sequenza di ripristino autonoma usando la verifica del passcode monouso tramite posta elettronica. Il ripristino inline usa invece il collegamento del recover metodo password all'interno della transazione di accesso attiva.
Avviare l'autorizzazione e seguire il collegamento reset-password restituito (resetPassword o reset_password). Non chiamare prima l'individuazione dell'accesso:
POST https://{custom_domain}/{tenant}/api/v2.0/resetpassword/start
Content-Type: application/json
Accept: application/hal+json
{
"username": "user@contoso.com",
"continuationToken": "******"
}
Inviare l'identificatore del cliente in username e il token di autorizzazione corrente in continuationToken. Nell'esempio viene usato un indirizzo di posta elettronica. Una risposta può annunciare un metodo di ripristino della posta elettronica:
{
"state": "interactionRequired",
"action": "challenge",
"continuationToken": "******",
"_links": {
"self": {
"href": "/{tenant}/api/v2.0/resetpassword/start"
}
},
"_embedded": {
"methods": [
{
"id": "{email_method_id}",
"type": "email",
"hint": "j****n@c****o",
"_links": {
"challenge": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/challenge"
},
"verify": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/verify"
}
}
}
]
}
}
Selezionare un metodo di recupero tramite posta elettronica o SMS restituito tramite la logica del flusso dell'utente o dell'applicazione. L'esempio mostra la posta elettronica; per SMS, seguire i collegamenti del metodo SMS restituito senza riscrivere l'URL di esempio. Usare l'hint mascherato in cui l'interfaccia richiede un'etichetta di destinazione.
Ripristino inline durante l'accesso
Offrire il ripristino inline solo quando un metodo password nella risposta di accesso corrente annuncia un recover collegamento. Seguire questo collegamento usando il token di continuazione di accesso corrente. Non avviare un'altra richiesta di autorizzazione o inviare di nuovo il nome utente o la password.
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/recover
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******"
}
Entrambi i punti di ingresso usano il metodo di ripristino, la verifica, la verifica, l'aggiornamento della password e le operazioni di polling restituite dal servizio.
Verifica e verifica del metodo di ripristino
Pubblicare nel collegamento del challenge metodo selezionato:
{
"continuationToken": "******"
}
Usare JSON e Accept: application/hal+json.
L'operazione di verifica condivisa restituisce il tipo di metodo corrente, mascherato hint, codeLengthe verify i collegamenti facoltativiresend.
Inserire il passcode immesso nel collegamento restituito verify :
{
"otp": "{one_time_passcode}",
"continuationToken": "******"
}
Usare il token più recente per ogni richiesta. Per un altro codice, usare il collegamento corrente resend e i limiti del servizio, non una coppia di URL/token di verifica precedente.
Una verifica riuscita può restituire il metodo password:
{
"state": "interactionRequired",
"action": "update",
"id": "{password_method_id}",
"type": "password",
"continuationToken": "******",
"_links": {
"update": {
"href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}"
}
}
}
Usare l'ID del metodo password dal collegamento restituito update , non l'ID del metodo di ripristino SMS o di posta elettronica. Il ripristino inline può mantenere l'ID del metodo password dall'accesso padre.
Aggiornare una password
Inviare la password sostitutiva con PUT, non POST:
PUT https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}
Content-Type: application/json
Accept: application/hal+json
{
"newPassword": "{new_password}",
"continuationToken": "******"
}
| Property | Type | Required | Description |
|---|---|---|---|
continuationToken |
Stringa. | Yes. | Token corrente che richiede l'aggiornamento della password. |
newPassword |
Stringa. | Yes. | Password sostitutiva. La conferma della password è locale per l'interfaccia, non un campo di richiesta aggiuntivo. |
Il servizio può restituire:
{
"state": "interactionRequired",
"action": "poll",
"pollInterval": "2",
"id": "{password_method_id}",
"type": "password",
"continuationToken": "******",
"_links": {
"poll": {
"href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/pollUpdate"
}
}
}
Indica un aggiornamento asincrono, non l'autorizzazione finale. Non inviare di nuovo la password durante l'attesa o ripetere automaticamente l'aggiornamento dopo un errore di rete ambiguo.
Aggiornamento della password di polling
Seguire il collegamento più recente poll :
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/pollUpdate
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******"
}
Mentre l'aggiornamento è in corso, il servizio restituisce interactionRequired con action: poll, un token aggiornato e un poll collegamento. Sostituire la risposta precedente prima del polling successivo.
Se incluso, pollInterval è una stringa contenente l'intervallo in secondi. Usare l'intervallo della risposta corrente per la richiesta successiva e rispettare le indicazioni sui tentativi del server. L'esempio "2" non è un intervallo di servizio fisso. Arrestare il polling quando l'azione cambia o viene restituito un errore e gestire qualsiasi autenticazione successiva richiesta dai criteri.
Una risposta di continuazione è:
{
"state": "continue",
"continuationToken": "******",
"_links": {
"continue": {
"href": "/{tenant}/oauth2/v2.0/authorize-challenge"
}
}
}
Completare i requisiti dei criteri e acquisire i token
La reimpostazione della password non ignora l'autenticazione a più fattori o l'accesso condizionale. Se viene restituita un'altra richiesta, completarla usando le operazioni del metodo condiviso. Lo scambio di token segue il completamento dei passaggi rimanenti dei criteri e della continuazione dell'autorizzazione.
Dopo state: continue, riprendere l'autorizzazione usando il token più recente e scambiare il codice. Gli ambiti e le attestazioni richiesti rimangono quelli stabiliti all'inizio della transazione.
Risultati ed errori
Usare la gestione degli errori condivisi. Il contratto di ripristino descrive questi risultati:
| Condition | Gestione dei risultati e dei client |
|---|---|
| Nome utente sconosciuto | Il ripristino non viene avviato. Usare un messaggio generico rivolto ai clienti. |
| Codice di posta elettronica o SMS non corretto | HTTP 400 invalidGrant con innerError.code: invalidOneTimeCode. Consentire all'utente di correggere il codice usando lo stato corrente utilizzabile o un nuovo invio annunciato. |
| Passcode mancante | HTTP 400 invalidRequest. Correggere l'input mancante. |
| Invia di nuovo | Viene inviato un nuovo passcode tramite il collegamento restituito resend . |
| Token di aggiornamento password scaduto | HTTP 400 expiredToken con innerError.code: expiredContinuationToken. Riavviare l'autorizzazione. |
| Password di sostituzione debole o comune | HTTP 400 invalidRequest con un errore interno applicabile, passwordTooWeak ad esempio o passwordTooCommon. Raccogliere una password conforme. |
| Aggiornamento in corso | Seguire le indicazioni più recenti sulla risposta di polling e sui tentativi del server. |
| Il polling ha esito negativo per i criteri password | HTTP 400 invalidRequest con un errore interno, passwordTooCommon ad esempio o passwordBannedByPolicy. Gestire l'errore anziché eseguire il polling indefinito. |
| Account bloccato o disabilitato durante il polling | HTTP 403 forbidden con innerError.code: accountLocked. Arrestare l'operazione di ripristino. |
| Il processo di aggiornamento delle password non riesce | HTTP 500 serverError. Mostra un errore non crittografato senza ripetere automaticamente l'aggiornamento della password. |
| Ripristino completato | Gestire le azioni dei criteri rimanenti, riprendere l'autorizzazione e richiedere i token. |
Questa tabella descrive risultati specifici, non un catalogo degli errori esaustivo. L'accettazione dell'aggiornamento delle password, il completamento del polling e il rilascio dei token sono limiti separati.
Non registrare passcode di ripristino, password sostitutive o token di transazione. Registrare solo ID di diagnostica sicuri, timestamp e stato HTTP. Non riprodurre automaticamente gli aggiornamenti della verifica o della password.