Kommentar
Åtkomst till den här sidan kräver auktorisering. Du kan prova att logga in eller ändra kataloger.
Åtkomst till den här sidan kräver auktorisering. Du kan prova att ändra kataloger.
Gäller för:
Externa klienter (läs mer)
Autentiseringsmetod: Inbäddad intern autentisering.
Lösenordsåterställning verifierar en kunds återställningsmetod, godkänner ett ersättningslösenord och avsöker en asynkron uppdatering. E-post- och SMS-metoder för engångslösenord (OTP) stöder återställning. Kraven för multifaktorautentisering (MFA) och villkorsstyrd åtkomst kan tillämpas efter återställningen och innan auktoriseringen har slutförts.
Använd V1 API-referensen för befintliga V1-integreringar.
Prerequisites
Important
API V2 för intern autentisering är i förhandsversion. API V1 för intern autentisering är fortfarande allmänt tillgängligt. Se kompletterande användningsvillkor för Microsoft Azure förhandsversioner för juridiska villkor som gäller för förhandsversionsfunktioner.
- Ett program som har konfigurerats för intern autentisering.
- Lösenordsåterställning aktiverad för klientorganisationen och kunden med en användbar återställningsmetod. Se Aktivera lösenordsåterställning med självbetjäning.
- Delegerade behörigheter och medgivande som krävs för ett mål-API, om du begär ett API-omfång.
Exemplen använder en klientverifierad anpassad domänutfärdare.
custom_domain är autentiseringsdomänen och tenant är klientorganisationens GUID.
Lösenordslösa e-post-OTP-konton har inget lösenord att återställa.
Starta lösenordsåterställning
Diagrammet visar en fristående återställningssekvens med hjälp av verifiering av engångslösenord via e-post. Infogad återställning använder i stället lösenordsmetodens recover länk i den aktiva inloggningstransaktionen.
Starta auktoriseringen och följ den returnerade länken för återställningslösenord (resetPassword eller reset_password). Anropa inte inloggningsidentifiering först:
POST https://{custom_domain}/{tenant}/api/v2.0/resetpassword/start
Content-Type: application/json
Accept: application/hal+json
{
"username": "user@contoso.com",
"continuationToken": "******"
}
Skicka kundens identifierare i username och den aktuella auktoriseringstoken i continuationToken. I exemplet används en e-postadress. Ett svar kan annonsera en återställningsmetod för e-post:
{
"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"
}
}
}
]
}
}
Välj en returnerad e-post- eller SMS-återställningsmetod via användarval eller programflödeslogik. Exemplet visar e-post; för SMS följer du den returnerade SMS-metodens länkar utan att skriva om exempel-URL:en. Använd det maskerade tipset där gränssnittet behöver en måletikett.
Infogad återställning vid inloggning
Erbjud endast infogad återställning när en lösenordsmetod i det aktuella inloggningssvaret annonserar en recover länk. Följ länken med den aktuella inloggningsfortsättningstoken. Starta inte en annan auktoriseringsbegäran eller skicka användarnamnet eller lösenordet igen.
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/recover
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******"
}
Båda startpunkterna använder återställningsmetod, utmaning, verifiering, lösenordsuppdatering och avsökningsåtgärder som returneras av tjänsten.
Utmana och verifiera återställningsmetoden
Publicera till den valda metodens challenge länk:
{
"continuationToken": "******"
}
Använd JSON och Accept: application/hal+json. Den delade utmaningsåtgärden returnerar den aktuella metodtypen, maskerade hint, codeLengthoch verify valfria resend länkar.
Publicera det angivna lösenordet till den returnerade verify länken:
{
"otp": "{one_time_passcode}",
"continuationToken": "******"
}
Använd den senaste token för varje begäran. För en annan kod använder du de aktuella resend länk- och tjänstgränserna, inte ett tidigare utmanings-URL/tokenpar.
En lyckad verifiering kan returnera lösenordsmetoden:
{
"state": "interactionRequired",
"action": "update",
"id": "{password_method_id}",
"type": "password",
"continuationToken": "******",
"_links": {
"update": {
"href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}"
}
}
}
Använd lösenordsmetod-ID:t från den returnerade update länken, inte e-post- eller SMS-återställningsmetodens ID. Infogad återställning kan behålla lösenordsmetod-ID:t från den överordnade inloggningen.
Uppdatera ett lösenord
Skicka ersättningslösenordet med PUT, inte 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 |
Sträng. | Yes. | Aktuell token som begär lösenordsuppdatering. |
newPassword |
Sträng. | Yes. | Ersättningslösenord. Lösenordsbekräftelsen är lokal för ditt gränssnitt, inte ett ytterligare begärandefält. |
Tjänsten kan returnera:
{
"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"
}
}
}
Detta indikerar en asynkron uppdatering, inte slutlig auktorisering. Skicka inte lösenordet igen medan du väntar eller upprepa uppdateringen automatiskt efter ett tvetydigt nätverksfel.
Uppdatering av avsökningslösenord
Följ den senaste poll länken:
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/pollUpdate
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******"
}
Medan uppdateringen pågår returnerar interactionRequired tjänsten med action: poll, en uppdaterad token och en poll länk. Ersätt föregående svar före nästa omröstning.
När det ingår pollInterval är en sträng som innehåller intervallet i sekunder. Använd det aktuella svarets intervall för nästa begäran och följ riktlinjerna för serverförsök igen. Exemplet "2" är inte ett fast tjänstintervall. Stoppa avsökningen när åtgärden ändras eller ett fel returneras och hantera eventuell senare autentisering som krävs av principen.
Ett fortsättningssvar är:
{
"state": "continue",
"continuationToken": "******",
"_links": {
"continue": {
"href": "/{tenant}/oauth2/v2.0/authorize-challenge"
}
}
}
Slutför principkrav och hämta token
Lösenordsåterställning kringgår inte MFA eller villkorsstyrd åtkomst. Om en annan utmaning returneras slutför du den med hjälp av de delade metodåtgärderna. Tokenutbytet följer slutförandet av de återstående principstegen och auktoriseringsfortsättningen.
Efter state: continueåterupptar du auktoriseringen med den senaste token och byter ut koden. De begärda omfången och anspråken förblir de som upprättades i början av transaktionen.
Resultat och fel
Använd den delade felhanteringen. Återställningskontraktet beskriver följande resultat:
| Condition | Resultat- och klienthantering |
|---|---|
| Okänt användarnamn | Återställningen startar inte. Använd ett allmänt kundbaserat meddelande. |
| Felaktig e-post eller SMS-lösenord | HTTP 400 invalidGrant med innerError.code: invalidOneTimeCode. Låt användaren korrigera koden med hjälp av det användbara aktuella tillståndet eller en annonserad återsändelse. |
| Lösenord saknas | HTTP 400 invalidRequest. Korrigera de indata som saknas. |
| Skicka om | Ett nytt lösenord skickas via den returnerade resend länken. |
| Token för lösenordsuppdatering har upphört att gälla | HTTP 400 expiredToken med innerError.code: expiredContinuationToken. Starta om auktorisering. |
| Svagt eller vanligt ersättningslösenord | HTTP 400 invalidRequest med ett tillämpligt inre fel som passwordTooWeak eller passwordTooCommon. Samla in ett kompatibelt lösenord. |
| Uppdatering pågår | Följ de senaste riktlinjerna för avsökningssvar och serverförsök. |
| Avsökningen misslyckas med lösenordsprincipen | HTTP 400 invalidRequest med ett inre fel som passwordTooCommon eller passwordBannedByPolicy. Hantera felet i stället för att avsöka på obestämd tid. |
| Konto låst eller inaktiverat under avsökning | HTTP 403 forbidden med innerError.code: accountLocked. Stoppa återställningsåtgärden. |
| Det går inte att uppdatera lösenord | HTTP 500 serverError. Visa ett tydligt fel utan att automatiskt upprepa lösenordsuppdateringen. |
| Slutförd återställning | Hantera eventuella återstående principåtgärder, återuppta auktorisering och begärandetoken. |
Den här tabellen beskriver specifika resultat, inte en fullständig felkatalog. Godkännande av lösenordsuppdateringar, slutförande av avsökningar och utfärdande av token är separata gränser.
Logga inte återställningslösenord, ersättningslösenord eller transaktionstoken. Registrera endast säkra diagnostik-ID:er, tidsstämplar och HTTP-status. Spela inte upp verifierings- eller lösenordsuppdateringar automatiskt.