Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Dotyczy:
Dzierżawy zewnętrzne (dowiedz się więcej)
Metoda uwierzytelniania: Osadzone uwierzytelnianie natywne.
Resetowanie hasła weryfikuje metodę odzyskiwania klienta, akceptuje zastępcze hasło i sonduje aktualizację asynchroniczną. Metody jednorazowego kodu dostępu (OTP) poczty e-mail i wiadomości SMS obsługują odzyskiwanie. Wymagania dotyczące uwierzytelniania wieloskładnikowego (MFA) i dostępu warunkowego mogą być stosowane po zakończeniu resetowania i przed ukończeniem autoryzacji.
W przypadku istniejących integracji w wersji 1 użyj dokumentacji interfejsu API w wersji 1.
Prerequisites
Important
Interfejs API uwierzytelniania natywnego w wersji 2 jest w wersji zapoznawczej. Interfejs API uwierzytelniania natywnego w wersji 1 pozostaje ogólnie dostępny. Zapoznaj się z dodatkowymi warunkami użytkowania dotyczącymi wersji zapoznawczej Microsoft Azure, aby uzyskać postanowienia prawne dotyczące funkcji w wersji zapoznawczej.
- Aplikacja skonfigurowana do uwierzytelniania natywnego.
- Resetowanie hasła włączone dla dzierżawy i klienta z użyciem metody odzyskiwania. Zobacz Włączanie samoobsługowego resetowania hasła.
- Delegowane uprawnienia i zgoda wymagane dla docelowego interfejsu API, jeśli zażądasz zakresu interfejsu API.
W przykładach użyto zweryfikowanego przez dzierżawę urzędu niestandardowej domeny.
custom_domain jest domeną uwierzytelniania i tenant jest identyfikatorem GUID dzierżawy.
Bez hasła konta e-mail OTP nie mają hasła do zresetowania.
Uruchom resetowanie hasła
Diagram przedstawia autonomiczną sekwencję odzyskiwania przy użyciu jednorazowej weryfikacji kodu dostępu poczty e-mail. Odzyskiwanie wbudowane używa linku metody recover hasła w ramach aktywnej transakcji logowania.
Uruchom autoryzację i postępuj zgodnie z zwróconym linkiem resetowania hasła (resetPassword lub reset_password). Nie należy najpierw wywoływać odnajdywania logowania:
POST https://{custom_domain}/{tenant}/api/v2.0/resetpassword/start
Content-Type: application/json
Accept: application/hal+json
{
"username": "user@contoso.com",
"continuationToken": "******"
}
Wyślij identyfikator klienta i username bieżący token autoryzacji w pliku continuationToken. W przykładzie użyto adresu e-mail. Odpowiedź może anonsować metodę odzyskiwania wiadomości e-mail:
{
"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"
}
}
}
]
}
}
Wybierz zwróconą metodę odzyskiwania wiadomości e-mail lub SMS za pomocą wyboru użytkownika lub logiki przepływu aplikacji. W przykładzie pokazano wiadomość e-mail; w przypadku wiadomości SMS postępuj zgodnie z zwróconymi linkami metody SMS bez ponownego zapisania przykładowego adresu URL. Użyj maskowanej wskazówki, w której interfejs potrzebuje etykiety docelowej.
Wbudowane odzyskiwanie podczas logowania
Zapewnij wbudowane odzyskiwanie tylko wtedy, gdy metoda hasła w bieżącej odpowiedzi logowania anonsuje recover link. Użyj tego linku, używając bieżącego tokenu kontynuacji logowania. Nie uruchamiaj innego żądania autoryzacji ani nie przesyłaj ponownie nazwy użytkownika lub hasła.
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/recover
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******"
}
Oba punkty wejścia używają metody odzyskiwania, wyzwania, weryfikacji, aktualizacji hasła i operacji sondowania zwracanych przez usługę.
Wyzwanie i zweryfikowanie metody odzyskiwania
Opublikuj link do wybranej challenge metody:
{
"continuationToken": "******"
}
Użyj formatu JSON i Accept: application/hal+json.
Wspólna operacja wyzwania zwraca bieżący typ metody, zamaskowane hintcodeLength, i verify opcjonalne resend linki.
Opublikuj wprowadzony kod dostępu do zwróconego verify linku:
{
"otp": "{one_time_passcode}",
"continuationToken": "******"
}
Użyj najnowszego tokenu dla każdego żądania. W przypadku innego kodu użyj bieżącego resend linku i limitów usługi, a nie wcześniejszego adresu URL wyzwania/pary tokenów.
Pomyślna weryfikacja może zwrócić metodę hasła:
{
"state": "interactionRequired",
"action": "update",
"id": "{password_method_id}",
"type": "password",
"continuationToken": "******",
"_links": {
"update": {
"href": "/{tenant}/api/v2.0/auth/methods/password/{password_method_id}"
}
}
}
Użyj identyfikatora metody hasła z zwróconego update linku, a nie identyfikatora metody odzyskiwania wiadomości e-mail ani wiadomości SMS. Odzyskiwanie wbudowane może zachować identyfikator metody hasła z logowania nadrzędnego.
Aktualizowanie hasła
Prześlij zastępcze hasło za pomocą PUTpolecenia , a nie 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 | Typ | Required | Description |
|---|---|---|---|
continuationToken |
Struna. | Yes. | Bieżący token żądający aktualizacji hasła. |
newPassword |
Struna. | Yes. | Hasło zastępcze. Potwierdzenie hasła jest lokalne dla interfejsu, a nie dodatkowe pole żądania. |
Usługa może zwrócić następujące jednostki:
{
"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"
}
}
}
Oznacza to aktualizację asynchroniczną, a nie ostateczną autoryzację. Nie przesyłaj hasła ponownie podczas oczekiwania lub automatycznego powtarzania aktualizacji po niejednoznacznym błędzie sieci.
Aktualizacja hasła sondowania
Postępuj zgodnie z najnowszym poll linkiem:
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{password_method_id}/pollUpdate
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******"
}
Gdy aktualizacja jest w toku, usługa zwraca interactionRequired wartość , action: pollzaktualizowany token i poll link. Zastąp poprzednią odpowiedź przed następnym ankietą.
W przypadku dołączenia pollInterval jest ciągiem zawierającym interwał w sekundach. Użyj interwału bieżącej odpowiedzi dla następnego żądania i honoruj wskazówki dotyczące ponawiania prób serwera.
"2" Przykład nie jest stałym interwałem usługi. Zatrzymaj sondowanie, gdy akcja ulegnie zmianie lub zostanie zwrócony błąd, i obsłuż wszelkie późniejsze uwierzytelnianie wymagane przez zasady.
Odpowiedź kontynuacji to:
{
"state": "continue",
"continuationToken": "******",
"_links": {
"continue": {
"href": "/{tenant}/oauth2/v2.0/authorize-challenge"
}
}
}
Spełnianie wymagań dotyczących zasad i uzyskiwanie tokenów
Resetowanie hasła nie pomija uwierzytelniania wieloskładnikowego ani dostępu warunkowego. Jeśli zostanie zwrócone inne wyzwanie, ukończ je przy użyciu operacji metody udostępnionej. Wymiana tokenów następuje po ukończeniu pozostałych kroków zasad i kontynuacji autoryzacji.
Po state: continueprogramie wznów autoryzację przy użyciu najnowszego tokenu i wymiany kodu. Żądane zakresy i oświadczenia pozostają ustalone na początku transakcji.
Wyniki i błędy
Użyj obsługi współużytkowanych błędów. Kontrakt odzyskiwania opisuje następujące wyniki:
| Warunek | Wynik i obsługa klienta |
|---|---|
| Nieznana nazwa użytkownika | Odzyskiwanie nie jest uruchamiane. Użyj ogólnego komunikatu dostępnego dla klienta. |
| Niepoprawny kod dostępu wiadomości e-mail lub SMS | Http 400 invalidGrant z .innerError.code: invalidOneTimeCode Pozwól użytkownikowi poprawić kod przy użyciu bieżącego stanu użytecznego lub anonsowanego ponownego wysłanie. |
| Brak kodu dostępu | HTTP 400 invalidRequest. Popraw brakujące dane wejściowe. |
| Wyślij ponownie | Nowy kod dostępu jest wysyłany za pośrednictwem zwróconego resend linku. |
| Wygasły token aktualizacji hasła | Http 400 expiredToken z .innerError.code: expiredContinuationToken Uruchom ponownie autoryzację. |
| Słabe lub typowe hasło zastępcze | Http 400 invalidRequest z odpowiednim błędem wewnętrznym, takim jak passwordTooWeak lub passwordTooCommon. Zbierz zgodne hasło. |
| Aktualizowanie w toku | Postępuj zgodnie z najnowszymi wskazówkami dotyczącymi sondowania i ponawiania prób serwera. |
| Zasady hasła sondowania kończą się niepowodzeniem | Http 400 invalidRequest z błędem wewnętrznym, takim jak passwordTooCommon lub passwordBannedByPolicy. Obsługa błędu zamiast sondowania w nieskończoność. |
| Konto zablokowane lub wyłączone podczas sondowania | Http 403 forbidden z .innerError.code: accountLocked Zatrzymaj operację odzyskiwania. |
| Zadanie aktualizacji hasła kończy się niepowodzeniem | HTTP 500 serverError. Pokaż wyraźny błąd bez automatycznego powtarzania aktualizacji hasła. |
| Ukończono odzyskiwanie | Obsługa pozostałych akcji zasad, wznawianie autoryzacji i tokenów żądań. |
W tej tabeli opisano konkretne wyniki, a nie wyczerpujący wykaz błędów. Akceptacja aktualizacji haseł, uzupełnianie sondowania i wystawianie tokenów są oddzielnymi granicami.
Nie rejestruj kodów dostępu odzyskiwania, zastępczych haseł ani tokenów transakcji. Rejestruj tylko bezpieczne identyfikatory diagnostyczne, znaczniki czasu i stan HTTP. Nie powtarzaj automatycznie weryfikacji ani aktualizacji haseł.