Dokumentacja interfejsu API uwierzytelniania natywnego

Dotyczy: Najemcy zewnętrzni (dowiedz się więcej)

Microsoft Entra native authentication umożliwia hostowanie interfejsu użytkownika aplikacji w aplikacji klienckiej zamiast delegowania uwierzytelniania do przeglądarek, co powoduje natywnie zintegrowane środowisko uwierzytelniania. Jako deweloper masz pełną kontrolę nad wyglądem i działaniem interfejsu logowania.

W tym artykule dokumentacji interfejsu API opisano szczegóły wymagane tylko w przypadku ręcznego wykonywania nieprzetworzonych żądań HTTP w celu wykonania przepływu. Nie zalecamy jednak tego podejścia. Dlatego, jeśli to możliwe, użyj zestawu SDK uwierzytelniania utworzonego przez firmę Microsoft i obsługiwanego przez firmę Microsoft. Dowiedz się więcej o zestawach SDK uwierzytelniania natywnego. Po pomyślnym wywołaniu punktów końcowych interfejsu API otrzymasz zarówno token identyfikatora do identyfikacji użytkownika, jak i token dostępu w celu wywołania chronionych interfejsów API. Wszystkie odpowiedzi z interfejsu API są w formacie JSON.

Natywny interfejs API uwierzytelniania Microsoft Entra obsługuje rejestrację i logowanie w dwóch przepływach uwierzytelniania:

• Wiadomość e-mail z hasłem, która obsługuje rejestrację i logowanie przy użyciu poczty e-mail i hasła oraz samoobsługowego resetowania hasła (SSPR).

  • Użytkownicy logujący się za pomocą adresu e-mail i hasła, mogą również logować się pod nazwą użytkownika i hasłem.

• Jednorazowy kod dostępu poczty e-mail, który obsługuje rejestrację i logowanie przy użyciu jednorazowego kodu dostępu poczty e-mail.

Uwaga

Obecnie punkty końcowe interfejsu API uwierzytelniania natywnego nie obsługują współużytkowania zasobów między źródłami (CORS).

Wymagania wstępne

1. Dzierżawa zewnętrzna Microsoft Entra. Jeśli jeszcze go nie masz, utwórz dzierżawę zewnętrzną.

2. Jeśli jeszcze tego nie zrobiono, Register aplikacji w centrum administracyjnym Microsoft Entra. Upewnij się, że:

   • Zapisz identyfikator aplikacji (klienta) i identyfikator katalogu (najemcy) do późniejszego użycia.
   • Udziel zgody administratora aplikacji.
   • Włącz przepływy uwierzytelniania publicznego i natywnego klienta.

3. Jeśli jeszcze tego nie zrobiono, Utwórz przepływ użytkownika w centrum administracyjnym Microsoft Entra. Podczas tworzenia przepływu użytkownika zanotuj atrybuty użytkownika skonfigurowane zgodnie z wymaganiami, ponieważ te atrybuty są tymi, które Microsoft Entra oczekuje przesłania aplikacji.

4. Skojarz rejestrację aplikacji z przepływem użytkownika.

5. W przepływie logowania zarejestruj użytkownika klienta, którego używasz do testowania przepływu. Alternatywnie możesz uzyskać tego użytkownika testowego po uruchomieniu przepływu rejestracji.

6. W przypadku przepływu samoobsługowego resetowania hasła włącz samoobsługowe resetowanie haseł dla użytkowników klientów w dzierżawie zewnętrznej. Samoobsługowe resetowanie hasła jest dostępne dla użytkowników klientów korzystających z poczty e-mail z metodą uwierzytelniania haseł.

7. Jeśli chcesz umożliwić użytkownikom logującym się za pomocą adresu e-mail i hasła na logowanie się także za pomocą nazwy użytkownika i hasła, skorzystaj z kroków w artykule Zaloguj się z aliasem lub nazwą użytkownika :

   1. Włącz nazwę użytkownika podczas logowania.
   2. Utwórz użytkowników z nazwą użytkownika w centrum administracyjnym lub zaktualizuj istniejących użytkowników, dodając nazwę użytkownika. Alternatywnie możesz również automate tworzenia i aktualizowania użytkownika w aplikacji przy użyciu witryny Microsoft Graph API.

8. Aby wymusić uwierzytelnianie wieloskładnikowe (MFA) dla klientów, wykonaj kroki opisane w artykule Dodawanie uwierzytelniania wieloskładnikowego (MFA) do aplikacji w celu dodania uwierzytelniania wieloskładnikowego do przepływu logowania. Uwierzytelnianie natywne obsługuje jednorazowy kod dostępu poczty e-mail i wiadomość SMS jako drugi czynnik dla uwierzytelniania wieloskładnikowego.

Token kontynuacji

Za każdym razem, gdy wywołujesz punkt końcowy logowania, rejestracji lub samoobsługowego resetowania hasła, odpowiedź zawiera token kontynuacji. Ten token jednoznacznie identyfikuje bieżący przepływ i pozwala Microsoft Entra ID zachować stan w swoich punktach końcowych. Uwzględnij token w każdym kolejnym żądaniu w tym przepływie. Jest on ważny tylko przez ograniczony czas i może być używany tylko dla kolejnych żądań w ramach tego samego przepływu.

Referencja API do rejestracji

Aby ukończyć przepływ rejestracji użytkownika dla jednej z metod uwierzytelniania, aplikacja wchodzi w interakcję z czterema punktami końcowymi, /signup/v1.0/start, , /signup/v1.0/challenge/signup/v1.0/continuei /token.

Endpointy API do rejestracji

Punkt końcowy	opis
/signup/v1.0/start	Ten punkt końcowy uruchamia przepływ rejestracji. Przekazujesz prawidłowy identyfikator aplikacji, nową nazwę użytkownika i typ wyzwania, a następnie otrzymujesz nowy token kontynuacji. Punkt końcowy może zwrócić odpowiedź wskazującą aplikacji na użycie przepływu uwierzytelniania internetowego, jeśli wybrane metody uwierzytelniania aplikacji nie są obsługiwane przez Microsoft Entra.
/signup/v1.0/challenge	Aplikacja wywołuje ten punkt końcowy z listą typów challenge obsługiwanych przez Microsoft Entra. Microsoft Entra następnie wybiera jedną z obsługiwanych metod uwierzytelniania dla użytkownika do uwierzytelnienia.
/signup/v1.0/continue	Ten punkt końcowy pomaga kontynuować przepływ w celu utworzenia konta użytkownika lub przerwania przepływu z powodu brakujących wymagań, takich jak wymagania dotyczące zasad haseł lub nieprawidłowe formaty atrybutów. Ten punkt końcowy generuje token kontynuacji, a następnie zwraca go do aplikacji. Punkt końcowy może zwrócić odpowiedź wskazującą aplikacji na użycie przepływu uwierzytelniania opartego na sieci Web, jeśli aplikacja nie wybierze metody uwierzytelniania wybranej przez Microsoft Entra.
oauth/v2.0/token	Aplikacja wywołuje ten punkt końcowy, aby w końcu zażądać tokenów zabezpieczających. Aplikacja musi użyć tokenu kontynuacji, który uzyskuje z ostatniego pomyślnego wywołania do punktu końcowego /signup/v1.0/continue .

Typy wyzwań rejestracji

Interfejs API umożliwia aplikacji klienckiej anonsować obsługiwane przez nią metody uwierzytelniania, gdy wykonuje wywołanie Microsoft Entra. W tym celu aplikacja używa parametru challenge_type w żądaniu aplikacji. Ten parametr zawiera wstępnie zdefiniowane wartości, które reprezentują różne metody uwierzytelniania.

Dowiedz się więcej o typach wyzwań w typach wyzwań uwierzytelniania natywnego. W tym artykule wyjaśniono wartości typu wyzwania, których należy użyć dla metody uwierzytelniania.

Szczegóły protokołu przepływu rejestracji

Diagram sekwencji przedstawia przepływ procesu rejestracji.

Ten diagram wskazuje, że aplikacja zbiera nazwę użytkownika (adres e-mail), hasło (w przypadku poczty e-mail z przepływem uwierzytelniania haseł) i atrybuty od użytkownika w różnym czasie (i ewentualnie na oddzielnych ekranach). Możesz jednak zaprojektować aplikację, aby zebrać nazwę użytkownika (adres e-mail), hasło i wszystkie wymagane wartości atrybutów oraz opcjonalne wartości atrybutów na tym samym ekranie, a następnie przesłać wszystkie z nich do punktu końcowego /signup/v1.0/start . Jeśli aplikacja przesyła wszystkie wymagane informacje do punktu końcowego /signup/v1.0/start , aplikacja nie musi wykonywać wywołań i obsługiwać odpowiedzi w opcjonalnych krokach.

W kroku 21 użytkownik jest już zarejestrowany. Jeśli jednak aplikacja wymaga automatycznego logowania użytkownika po utworzeniu konta, aplikacja wywołuje oauth/v2.0/token punkt końcowy w celu żądania tokenów zabezpieczających.

Krok 1. Żądanie uruchomienia przepływu rejestracji

Przepływ rejestracji rozpoczyna się od aplikacji wysyłającej żądanie POST do /signup/v1.0/start punktu końcowego w celu uruchomienia przepływu rejestracji.

Oto przykłady żądania (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

Przykład 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 

Przykład 2 (uwzględnij atrybuty użytkownika i hasło w żądaniu):

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 

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.
username	Tak	Adres e-mail użytkownika klienta, którego chcesz zarejestrować, na przykład contoso-consumer@contoso.com.
challenge_type	Tak	Rozdzielona spacjami lista ciągów typu wyzwania autoryzacji obsługiwana przez aplikację, na przykład oob password redirect. Lista musi zawsze zawierać redirect typ wyzwania. Wartość jest oczekiwana lub oob redirectoob password redirect dla wiadomości e-mail z metodą uwierzytelniania haseł.
password	Nie.	Wartość hasła zbierana przez aplikację od użytkownika klienta. Hasło użytkownika można przesłać za pośrednictwem /signup/v1.0/start adresu lub nowszego w punkcie /signup/v1.0/continue końcowym. Zastąp {secure_password} wartość hasłem zbieraną przez aplikację od użytkownika klienta. Twoim zadaniem jest potwierdzenie, że użytkownik zna hasło, którego chce użyć, podając pole potwierdzenia hasła w interfejsie użytkownika aplikacji. Należy również upewnić się, że użytkownik jest świadomy tego, co stanowi silne hasło zgodnie z zasadami organizacji. Dowiedz się więcej na temat zasad haseł Microsoft Entra. Ten parametr ma zastosowanie tylko do poczty e-mail z metodą uwierzytelniania haseł.
attributes	Nie.	Użytkownik przypisuje wartości zbierane przez aplikację od użytkownika klienta. Wartość jest ciągiem, ale sformatowanym jako obiekt JSON, którego wartości klucza są programowalnymi nazwami atrybutów użytkownika. Te atrybuty mogą być wbudowane lub niestandardowe oraz wymagane lub opcjonalne. Nazwy kluczy obiektu zależą od atrybutów skonfigurowanych przez administratora w centrum administracyjnym Microsoft Entra. Niektóre lub wszystkie atrybuty użytkownika można przesłać za pośrednictwem punktu końcowego /signup/v1.0/start lub nowszego w punkcie /signup/v1.0/continue końcowym. Jeśli przesyłasz wszystkie wymagane atrybuty za pośrednictwem punktu końcowego /signup/v1.0/start , nie musisz przesyłać żadnych atrybutów w punkcie /signup/v1.0/continue końcowym. Jeśli jednak prześlesz niektóre wymagane atrybuty za pośrednictwem /signup/v1.0/start punktu końcowego, możesz przesłać pozostałe wymagane atrybuty później w punkcie /signup/v1.0/continue końcowym. Zastąp {given_name}wartości , {user_age} i {postal_code} nazwami, wiekami i kodami pocztowymi, które aplikacja zbiera od użytkownika klienta. Microsoft Entra ignoruje wszelkie przesyłane atrybuty, które nie istnieją.
capabilities	Nie.	Flagi rozdzielone spacjami, które opisują możliwości aplikacji klienckiej. Podczas challenge_type definiowania metod, które mogą być kwestionowane, poinformuj natywny interfejs API uwierzytelniania, capabilities które dodatkowe przepływy może obsłużyć aplikacja kliencka i które interfejsy użytkownika mogą być wyświetlane użytkownikowi. Na przykład oznacza inną mfa_required pętlę i /challenge ; /token oznacza, registration_required że aplikacja kliencka wywołuje interfejsy API rejestracji i wyświetla interfejs użytkownika rejestracji. Jeśli wymagana funkcja nie jest anonsowana przez aplikację kliencką, interfejs API zwraca przekierowanie. Obsługiwane wartości to mfa_required i registration_required. Dowiedz się więcej o możliwościach.

Odpowiedź na powodzenie

Oto przykład pomyślnej odpowiedzi:

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

{
    "continuation_token": "AQABAAEAAA…",
} 

Majątek	opis
continuation_token	Tokencontinuation który Microsoft Entra zwraca.

Odpowiedź przekierowania

Jeśli aplikacja kliencka nie obsługuje metody uwierzytelniania lub możliwości, które Microsoft Entra wymagają, wymagany jest rezerwowy przepływ uwierzytelniania oparty na sieci Web. W tym scenariuszu Microsoft Entra informuje aplikację, zwracając redirect w odpowiedzi:

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

{     
   "challenge_type": "redirect" 
} 

Majątek	opis
challenge_type	Microsoft Entra zwraca odpowiedź, która ma typ wyzwania. Wartość tego typu wyzwania to przekierowanie, co umożliwia aplikacji korzystanie z przepływu uwierzytelniania internetowego.

Ta odpowiedź jest uznawana za pomyślną, ale aplikacja jest wymagana do przełączenia się do przepływu uwierzytelniania internetowego. W takim przypadku zalecamy użycie utworzonej i obsługiwanej przez firmę Microsoft biblioteki uwierzytelniania.

Odpowiedź błędna

Przykład:

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

Majątek	opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów i reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu przyczyny błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla Microsoft Entra, które mogą ułatwić diagnozowanie błędów.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnozowaniu błędów.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.
invalid_attributes	Lista (tablica obiektów) atrybutów, które zakończyły się niepowodzeniem weryfikacji. Ta odpowiedź jest możliwa, jeśli aplikacja przesyła atrybuty użytkownika, a suberror wartość właściwości jest attribute_validation_failed.
suberror	Ciąg kodu błędu, który może służyć do dalszego klasyfikowania typów błędów.

Poniżej przedstawiono możliwe błędy, które można napotkać (możliwe wartości error właściwości):

Wartość błędu	opis
invalid_request	Sprawdzanie poprawności parametru żądania nie powiodło się, na przykład gdy wartość parametru challenge_type zawiera nieobsługiwaną metodę uwierzytelniania lub żądanie nie zawiera client_id parametru wartość identyfikatora klienta jest pusta lub nieprawidłowa. Użyj parametru , error_description aby poznać dokładną przyczynę błędu.
invalid_client	Identyfikator klienta, który aplikacja zawiera w żądaniu, dotyczy aplikacji, która nie ma natywnej konfiguracji uwierzytelniania, takiej jak nie jest klientem publicznym lub nie jest włączona na potrzeby uwierzytelniania natywnego. suberror Użyj właściwości , aby poznać dokładną przyczynę błędu.
unauthorized_client	Identyfikator klienta używany w żądaniu ma prawidłowy format identyfikatora klienta, ale nie istnieje w dzierżawie zewnętrznej lub jest niepoprawny.
unsupported_challenge_type	Wartość challenge_type parametru redirect nie zawiera typu wyzwania.
user_already_exists	Użytkownik już istnieje.
invalid_grant	Hasło przesyłane przez aplikację nie spełnia wszystkich wymagań dotyczących złożoności, takich jak hasło, jest zbyt krótkie. suberror Użyj właściwości , aby poznać dokładną przyczynę błędu. Ten parametr ma zastosowanie tylko do poczty e-mail z metodą uwierzytelniania haseł.

Jeśli parametr błędu ma wartość invalid_grant, Microsoft Entra zawiera właściwość suberror w odpowiedzi. Poniżej przedstawiono możliwe wartości suberror właściwości błędu invalid_grant :

Wartość błędu podrzędnego	opis
password_too_weak	Hasło jest zbyt słabe, ponieważ nie spełnia wymagań dotyczących złożoności. Dowiedz się więcej na temat zasad haseł Microsoft Entra. Ta odpowiedź jest możliwa, jeśli aplikacja przesyła hasło użytkownika.
password_too_short	Nowe hasło ma mniej niż 8 znaków. Dowiedz się więcej na temat zasad haseł Microsoft Entra. Ta odpowiedź jest możliwa, jeśli aplikacja przesyła hasło użytkownika.
password_too_long	Nowe hasło jest dłuższe niż 256 znaków. Dowiedz się więcej na temat zasad haseł Microsoft Entra. Ta odpowiedź jest możliwa, jeśli aplikacja przesyła hasło użytkownika.
password_recently_used	Nowe hasło nie może być takie samo jak ostatnio używane. Dowiedz się więcej na temat zasad haseł Microsoft Entra. Ta odpowiedź jest możliwa, jeśli aplikacja przesyła hasło użytkownika.
password_banned	Nowe hasło zawiera słowo, frazę lub wzorzec, który jest zabroniony. Dowiedz się więcej na temat zasad haseł Microsoft Entra. Ta odpowiedź jest możliwa, jeśli aplikacja przesyła hasło użytkownika.
password_is_invalid	Hasło jest nieprawidłowe, na przykład ponieważ używa niedozwolonych znaków. Dowiedz się więcej na temat zasad haseł Microsoft Entra. Ta odpowiedź jest możliwa, jeśli aplikacja przesyła hasło użytkownika.

Jeśli parametr błędu ma wartość invalid_client, Microsoft Entra zawiera właściwość suberror w odpowiedzi. Poniżej przedstawiono możliwe wartości suberror właściwości dla błędu invalid_client :

Wartość błędu podrzędnego	opis
nativeauthapi_disabled	Identyfikator klienta aplikacji, która nie jest włączona na potrzeby uwierzytelniania natywnego.

Uwaga

Jeśli przesyłasz wszystkie wymagane atrybuty za pośrednictwem /signup/v1.0/start punktu końcowego, ale nie wszystkie atrybuty opcjonalne, nie będzie można później przesłać żadnych dodatkowych atrybutów opcjonalnych za pośrednictwem punktu końcowego /signup/v1.0/continue . Microsoft Entra nie żąda jawnie opcjonalnych atrybutów, ponieważ nie są one obowiązkowe do ukończenia przepływu rejestracji. Zobacz tabelę w sekcji Przesyłanie atrybutów użytkownika do punktów końcowych , aby poznać atrybuty użytkownika, które można przesłać do /signup/v1.0/start punktów końcowych i /signup/v1.0/continue .

Krok 2. Wybieranie metody uwierzytelniania

Aplikacja żąda Microsoft Entra, aby wybrać jeden z obsługiwanych typów wyzwań dla użytkownika do uwierzytelnienia. W tym celu aplikacja wykonuje wywołanie punktu końcowego /signup/v1.0/challenge . Aplikacja musi uwzględnić token kontynuacji uzyskany z punktu końcowego /signup/v1.0/start w żądaniu.

Oto przykład żądania (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

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…

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.
challenge_type	Nie.	Rozdzielona spacjami lista ciągów typu wyzwania autoryzacji obsługiwana przez aplikację, na przykład oob password redirect. Lista musi zawsze zawierać redirect typ wyzwania. Wartość powinna dotyczyć oob redirect jednorazowego kodu dostępu wiadomości e-mail i oob password redirect wiadomości e-mail z metodą uwierzytelniania haseł.
continuation_token	Tak	Tokencontinuation który Microsoft Entra zwrócony w poprzednim żądaniu.

Odpowiedź na powodzenie

Microsoft Entra wysyła jednorazowy kod dostępu do wiadomości e-mail użytkownika, a następnie odpowiada za pomocą typu wyzwania o wartości oob i dodatkowych informacji o jednorazowym kodzie dostępu:

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
} 

Majątek	opis
interval	Czas w sekundach, przez który aplikacja musi czekać, zanim podejmie próbę ponownego uruchomienia protokołu OTP.
continuation_token	Tokencontinuation który Microsoft Entra zwraca.
challenge_type	Typ wyzwania wybrany dla użytkownika do uwierzytelnienia.
binding_method	Jedyną prawidłową wartością jest monit. Tego parametru można użyć w przyszłości, aby zaoferować użytkownikowi więcej sposobów wprowadzania jednorazowego kodu dostępu. Wystawione, jeśli challenge_type jest obiektem oob
challenge_channel	Typ kanału, za pośrednictwem którego został wysłany jednorazowy kod dostępu. Obecnie obsługiwany jest tylko kanał poczty e-mail.
challenge_target_label	Zaciemniony adres e-mail, w którym wysłano jednorazowy kod dostępu.
code_length	Długość jednorazowego kodu dostępu, który Microsoft Entra generuje.

Odpowiedź przekierowania

Jeśli aplikacja kliencka nie obsługuje metody uwierzytelniania lub możliwości, które Microsoft Entra wymagają, wymagany jest rezerwowy przepływ uwierzytelniania oparty na sieci Web. W tym scenariuszu Microsoft Entra informuje aplikację, zwracając redirect w odpowiedzi:

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

{
   "challenge_type": "redirect"
}

Majątek	opis
challenge_type	Microsoft Entra zwraca odpowiedź, która ma typ wyzwania. Wartość tego typu wyzwania to przekierowanie, co umożliwia aplikacji korzystanie z przepływu uwierzytelniania internetowego.

Ta odpowiedź jest uznawana za pomyślną, ale aplikacja jest wymagana do przełączenia się do przepływu uwierzytelniania internetowego. W takim przypadku zalecamy użycie utworzonej i obsługiwanej przez firmę Microsoft biblioteki uwierzytelniania.

Odpowiedź błędna

Przykład:

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

Majątek	opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów i reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu przyczyny błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla Microsoft Entra, które mogą ułatwić diagnozowanie błędów.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnozowaniu błędów.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.

Poniżej przedstawiono możliwe błędy, które można napotkać (możliwe wartości error właściwości):

Wartość błędu	opis
invalid_request	Weryfikacja parametru żądania nie powiodła się, na przykład identyfikator klienta jest pusty lub nieprawidłowy.
expired_token	Token kontynuacji wygasł.
unsupported_challenge_type	Wartość challenge_type parametru redirect nie zawiera typu wyzwania.
invalid_grant	Token kontynuacji jest nieprawidłowy.

Krok 3. Przesyłanie jednorazowego kodu dostępu

Aplikacja przesyła jednorazowy kod dostępu wysyłany do wiadomości e-mail użytkownika. Ponieważ przesyłamy jednorazowy kod dostępu, oob wymagany jest parametr, a grant_type parametr musi mieć wartość oob.

Oto przykład żądania (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

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}

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
continuation_token	Tak	Tokencontinuation który Microsoft Entra zwrócony w poprzednim żądaniu.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.
grant_type	Tak	Żądanie do punktu końcowego /signup/v1.0/continue może służyć do przesyłania jednorazowego kodu dostępu, hasła lub atrybutów użytkownika. W tym przypadku grant_type wartość jest używana do rozróżnienia między tymi trzema przypadkami użycia. Możliwe wartości dla grant_type to oob, hasło, atrybuty. W tym wywołaniu, ponieważ wysyłamy jednorazowy kod dostępu, oczekiwana wartość to oob.
oob	Tak	Jednorazowy kod dostępu otrzymany przez użytkownika klienta w wiadomości e-mail. Zastąp element {otp_code} jednorazowymi wartościami kodu dostępu, które użytkownik klienta otrzymał w wiadomości e-mail. Aby ponownie wysłać jednorazowy kod dostępu, aplikacja musi ponownie wysłać żądanie do punktu końcowego /signup/v1.0/challenge .

Po pomyślnym przesłaniu przez aplikację jednorazowego kodu dostępu przepływ rejestracji zależy od scenariuszy, jak pokazano w tabeli:

Scenariusz	Jak kontynuować
Aplikacja pomyślnie przesyła hasło użytkownika (w przypadku poczty e-mail z metodą uwierzytelniania haseł) za pośrednictwem punktu końcowego /signup/v1.0/start i nie skonfigurowano żadnych atrybutów w centrum administracyjnym Microsoft Entra lub wszystkie wymagane atrybuty użytkownika są przesyłane za pośrednictwem punktu końcowego /signup/v1.0/start.	Microsoft Entra wystawia token kontynuacji. Aplikacja może użyć tokenu kontynuacji, aby zażądać tokenów zabezpieczających, jak pokazano w artykule Żądanie tokenów zabezpieczających.
Aplikacja pomyślnie przesyła hasło użytkownika (dla poczty e-mail z metodą uwierzytelniania haseł) za pośrednictwem /signup/v1.0/start, ale nie wszystkie wymagane atrybuty użytkownika, Microsoft Entra wskazuje atrybuty, które aplikacja musi przesłać, jak pokazano w wymagane atrybuty użytkownika.	Aplikacja musi przesłać wymagane atrybuty użytkownika za pośrednictwem punktu końcowego /signup/v1.0/continue . Odpowiedź jest podobna do tej w wymaganych atrybutach użytkownika. Prześlij atrybuty użytkownika wyświetlane w przesłaniu atrybutów użytkownika.
Aplikacja nie przesyła hasła użytkownika (w przypadku poczty e-mail z metodą uwierzytelniania haseł) za pośrednictwem /signup/v1.0/start punktu końcowego.	Microsoft Entra odpowiedzi wskazuje, że wymagane jest poświadczenie. Zobacz odpowiedź. Ta odpowiedź jest możliwa w przypadku poczty e-mail z metodą uwierzytelniania haseł.

Odpowiedź

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

Majątek	opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów i reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu przyczyny błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla Microsoft Entra, które mogą ułatwić diagnozowanie błędów.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnozowaniu błędów.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.
continuation_token	Tokencontinuation który Microsoft Entra zwraca.
suberror	Ciąg kodu błędu, który może służyć do dalszego klasyfikowania typów błędów.

Poniżej przedstawiono możliwe błędy, które można napotkać (możliwe wartości error właściwości):

Wartość błędu	opis
credential_required	Do utworzenia konta wymagane jest uwierzytelnianie, dlatego należy wykonać wywołanie punktu końcowego /signup/v1.0/challenge w celu określenia poświadczeń, które użytkownik musi podać.
invalid_request	Sprawdzanie poprawności parametru żądania nie powiodło się, takie jak weryfikacja tokenu kontynuacji lub żądanie nie zawiera client_id parametru wartość identyfikatora klienta jest pusta lub nieprawidłowa lub administrator dzierżawy zewnętrznej nie włączył protokołu OTP poczty e-mail dla wszystkich użytkowników dzierżawy.
invalid_grant	Typ dotacji uwzględniony w żądaniu jest nieprawidłowy lub obsługiwany lub wartość OTP jest nieprawidłowa.
expired_token	Token kontynuacji uwzględniony w żądaniu wygasł.

Jeśli parametr błędu ma wartość invalid_grant, Microsoft Entra zawiera właściwość suberror w odpowiedzi. Poniżej przedstawiono możliwe wartości suberror właściwości błędu invalid_grant :

Wartość błędu podrzędnego	opis
invalid_oob_value	Wartość jednorazowego kodu dostępu jest nieprawidłowa.

Aby poświadczenia hasła zostały zebrane od użytkownika, aplikacja musi wykonać wywołanie /signup/v1.0/challenge punktu końcowego w celu określenia poświadczeń, które użytkownik musi podać.

Oto przykład żądania (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

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…

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.
challenge_type	Nie.	Rozdzielona spacjami lista ciągów typu wyzwania autoryzacji obsługiwana przez aplikację, na przykład oob password redirect. Lista musi zawsze zawierać redirect typ wyzwania. W przypadku przepływu rejestracji przy użyciu hasła wartość powinna zawierać password redirectwartość .
continuation_token	Tak	Tokencontinuation który Microsoft Entra zwrócony w poprzednim żądaniu.

Odpowiedź na powodzenie

Jeśli hasło jest metodą uwierzytelniania skonfigurowaną dla użytkownika w centrum administracyjnym Microsoft Entra, zostanie zwrócona odpowiedź powodzenia z tokenem kontynuacji do aplikacji.

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

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

Majątek	opis
challenge_type	Hasło jest zwracane w odpowiedzi dla wymaganego poświadczenia.
continuation_token	Tokencontinuation który Microsoft Entra zwraca.

Odpowiedź przekierowania

Jeśli aplikacja kliencka nie obsługuje metody uwierzytelniania lub możliwości, które Microsoft Entra wymagają, wymagany jest rezerwowy przepływ uwierzytelniania oparty na sieci Web. W tym scenariuszu Microsoft Entra informuje aplikację, zwracając redirect w odpowiedzi:

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

{     
    "challenge_type": "redirect" 
} 

Majątek	opis
challenge_type	Microsoft Entra zwraca odpowiedź, która ma typ wyzwania. Wartość tego typu wyzwania to przekierowanie, co umożliwia aplikacji korzystanie z przepływu uwierzytelniania internetowego.

Ta odpowiedź jest uznawana za pomyślną, ale aplikacja jest wymagana do przełączenia się do przepływu uwierzytelniania internetowego. W takim przypadku zalecamy użycie utworzonej i obsługiwanej przez firmę Microsoft biblioteki uwierzytelniania.

Krok 4. Uwierzytelnianie i uzyskiwanie tokenu w celu zarejestrowania się

Aplikacja musi przesłać poświadczenia użytkownika, w tym przypadku hasło, które Microsoft Entra żądane w poprzednim kroku. Jeśli aplikacja nie zrobiła tego za pośrednictwem punktu końcowego /signup/v1.0/start , musi przesłać poświadczenie hasła. Aplikacja wysyła żądanie do punktu końcowego /signup/v1.0/continue w celu przesłania hasła. Ponieważ przesyłamy hasło, password wymagany jest parametr, a grant_type parametr musi mieć hasło wartości.

Oto przykład żądania (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

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}

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
continuation_token	Tak	Tokencontinuation który Microsoft Entra zwrócony w poprzednim kroku.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.
grant_type	Tak	Żądanie do punktu końcowego /signup/v1.0/continue może służyć do przesyłania jednorazowego kodu dostępu, hasła lub atrybutów użytkownika. W tym przypadku grant_type wartość jest używana do rozróżnienia między tymi trzema przypadkami użycia. Możliwe wartości dla grant_type to oob, hasło, atrybuty. W tym wywołaniu, ponieważ wysyłamy hasło użytkownika, wartość powinna być hasłem.
password	Tak	Wartość hasła zbierana przez aplikację od użytkownika klienta. Zastąp {secure_password} wartość hasłem zbieraną przez aplikację od użytkownika klienta. Twoim zadaniem jest potwierdzenie, że użytkownik zna hasło, którego chce użyć, podając pole potwierdzenia hasła w interfejsie użytkownika aplikacji. Należy również upewnić się, że użytkownik jest świadomy tego, co stanowi silne hasło zgodnie z zasadami organizacji. Dowiedz się więcej na temat zasad haseł Microsoft Entra.

Odpowiedź na powodzenie

Jeśli żądanie zakończy się pomyślnie, ale żadne atrybuty nie zostały skonfigurowane w centrum administracyjnym Microsoft Entra lub wszystkie wymagane atrybuty zostały przesłane za pośrednictwem punktu końcowego /signup/v1.0/start, aplikacja otrzymuje token kontynuacji bez przesyłania żadnych atrybutów. Aplikacja może użyć tokenu kontynuacji, aby zażądać tokenów zabezpieczających, jak pokazano w artykule Żądanie tokenów zabezpieczających. W przeciwnym razie odpowiedź Microsoft Entra wskazuje, że aplikacja musi przesłać wymagane atrybuty. Te atrybuty, wbudowane lub niestandardowe, zostały skonfigurowane w centrum administracyjnym Microsoft Entra przez administratora dzierżawy.

Wymagane atrybuty użytkownika

Ta odpowiedź żąda od aplikacji przesłania wartości atrybutów nazwy, wieku i telefonu .

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]*$"
            }
        }
    ],
}

Uwaga

Atrybuty niestandardowe (nazywane również rozszerzeniami katalogu) są nazwane przy użyciu konwencji extension_{appId-without-hyphens}_{attribute-name} , w której {appId-without-hyphens} jest usuniętą wersją identyfikatora klienta dla aplikacji rozszerzeń. Jeśli na przykład identyfikator klienta aplikacji Dowiedz się więcej o atrybutach niestandardowych i aplikacji rozszerzenia.

Majątek	opis
error	Ten atrybut jest ustawiany, jeśli Microsoft Entra nie można utworzyć konta użytkownika, ponieważ atrybut musi zostać zweryfikowany lub przesłany.
error_description	Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu przyczyny błędu.
error_codes	Lista kodów błędów specyficznych dla Microsoft Entra, które mogą ułatwić diagnozowanie błędów.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnozowaniu błędów.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.
continuation_token	Tokencontinuation który Microsoft Entra zwraca.
required_attributes	Lista (tablica obiektów) atrybutów, które aplikacja musi przesłać następne wywołanie, aby kontynuować. Te atrybuty to dodatkowe atrybuty, które aplikacja musi przesyłać niezależnie od nazwy użytkownika. Microsoft Entra zawiera ten parametr jest odpowiedzią, jeśli wartość parametru error jest attributes_required.

Poniżej przedstawiono możliwe błędy, które można napotkać (możliwe wartości error właściwości):

Wartość błędu	opis
invalid_request	Weryfikacja parametru żądania nie powiodła się, na przykład weryfikacja tokenu kontynuacji nie powiodła się lub żądanie nie zawiera client_id parametru, którego wartość identyfikatora klienta jest pusta lub nieprawidłowa.
invalid_grant	Typ udzielenia uwzględniony w żądaniu jest nieprawidłowy lub obsługiwany. Możliwe wartości grant_type to oob, hasło, atrybuty
expired_token	Token kontynuacji uwzględniony w żądaniu wygasł.
attributes_required	Wymagany jest co najmniej jeden atrybut użytkownika.

Odpowiedź przekierowania

Jeśli aplikacja kliencka nie obsługuje metody uwierzytelniania lub możliwości, które Microsoft Entra wymagają, wymagany jest rezerwowy przepływ uwierzytelniania oparty na sieci Web. W tym scenariuszu Microsoft Entra informuje aplikację, zwracając redirect w odpowiedzi:

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

{     
   "challenge_type": "redirect" 
} 

Majątek	opis
challenge_type	Microsoft Entra zwraca odpowiedź, która ma typ wyzwania. Wartość tego typu wyzwania to przekierowanie, co umożliwia aplikacji korzystanie z przepływu uwierzytelniania internetowego.

Ta odpowiedź jest uznawana za pomyślną, ale aplikacja jest wymagana do przełączenia się do przepływu uwierzytelniania internetowego. W takim przypadku zalecamy użycie utworzonej i obsługiwanej przez firmę Microsoft biblioteki uwierzytelniania.

Odpowiedź błędna

Przykład:

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

Majątek	opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów i reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu przyczyny błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla Microsoft Entra, które mogą ułatwić diagnozowanie błędów.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnozowaniu błędów.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.
suberror	Ciąg kodu błędu, który może służyć do dalszego klasyfikowania typów błędów.

Poniżej przedstawiono możliwe błędy, które można napotkać (możliwe wartości error właściwości):

Wartość błędu	opis
invalid_request	Sprawdzanie poprawności parametru żądania nie powiodło się, na przykład wtedy, gdy challenge_type parametr zawiera nieprawidłowy typ wyzwania.
invalid_grant	Przesłane przyznanie jest nieprawidłowe, na przykład przesłane hasło jest zbyt krótkie. suberror Użyj właściwości , aby poznać dokładną przyczynę błędu.
expired_token	Token kontynuacji wygasł.
attributes_required	Wymagany jest co najmniej jeden atrybut użytkownika.

Jeśli parametr błędu ma wartość invalid_grant, Microsoft Entra zawiera właściwość suberror w odpowiedzi. Poniżej przedstawiono możliwe wartości suberror właściwości:

Wartość błędu podrzędnego	opis
password_too_weak	Hasło jest zbyt słabe, ponieważ nie spełnia wymagań dotyczących złożoności. Dowiedz się więcej na temat zasad haseł Microsoft Entra.
password_too_short	Nowe hasło ma mniej niż 8 znaków. Dowiedz się więcej na temat zasad haseł Microsoft Entra.
password_too_long	Nowe hasło jest dłuższe niż 256 znaków. Dowiedz się więcej na temat zasad haseł Microsoft Entra.
password_recently_used	Nowe hasło nie może być takie samo jak ostatnio używane. Dowiedz się więcej na temat zasad haseł Microsoft Entra.
password_banned	Nowe hasło zawiera słowo, frazę lub wzorzec, który jest zabroniony. Dowiedz się więcej na temat zasad haseł Microsoft Entra.
password_is_invalid	Hasło jest nieprawidłowe, na przykład ponieważ używa niedozwolonych znaków. Dowiedz się więcej na temat zasad haseł Microsoft Entra. Ta odpowiedź jest możliwa, jeśli aplikacja przesyła hasło użytkownika.

Przesyłanie atrybutów użytkownika

Aby kontynuować przepływ, aplikacja musi wykonać wywołanie punktu końcowego /signup/v1.0/continue , aby przesłać wymagane atrybuty użytkownika. Ponieważ przesyłamy atrybuty, attributes wymagany jest parametr, a grant_type parametr musi mieć wartość równą atrybutom.

Oto przykład żądania (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

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

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
continuation_token	Tak	Tokencontinuation który Microsoft Entra zwrócony w poprzednim żądaniu.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.
grant_type	Tak	Żądanie do punktu końcowego /signup/v1.0/continue może służyć do przesyłania jednorazowego kodu dostępu, hasła lub atrybutów użytkownika. W tym przypadku grant_type wartość jest używana do rozróżnienia między tymi trzema przypadkami użycia. Możliwe wartości dla grant_type to oob, hasło, atrybuty. W tym wywołaniu, ponieważ wysyłamy atrybuty użytkownika, wartość powinna być atrybutami.
attributes	Tak	Wartości atrybutów użytkownika zbierane przez aplikację od użytkownika klienta. Wartość jest ciągiem, ale sformatowanym jako obiekt JSON, którego kluczowe wartości to nazwy atrybutów użytkownika, wbudowane lub niestandardowe. Nazwy kluczy obiektu zależą od atrybutów skonfigurowanych przez administratora w centrum administracyjnym Microsoft Entra. Zastąp {given_name}wartości , {user_age} i {postal_code} nazwami, wiekami i kodami pocztowymi, które aplikacja zbiera od użytkownika klienta. Microsoft Entra ignoruje wszelkie przesyłane atrybuty, które nie istnieją.

Odpowiedź na powodzenie

Jeśli żądanie zakończy się pomyślnie, Microsoft Entra zarejestruje użytkownika, a następnie uruchomi token kontynuacji. Aplikacja może użyć tokenu kontynuacji, aby zażądać tokenów zabezpieczających z punktu końcowego oauth/v2.0/token .

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

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

Majątek	opis
continuation_token	Tokencontinuation który Microsoft Entra zwraca.

Odpowiedź przekierowania

Jeśli aplikacja kliencka nie obsługuje metody uwierzytelniania lub możliwości, które Microsoft Entra wymagają, wymagany jest rezerwowy przepływ uwierzytelniania oparty na sieci Web. W tym scenariuszu Microsoft Entra informuje aplikację, zwracając redirect w odpowiedzi:

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

{     
   "challenge_type": "redirect" 
} 

Majątek	opis
challenge_type	Microsoft Entra zwraca odpowiedź, która ma typ wyzwania. Wartość tego typu wyzwania to przekierowanie, co umożliwia aplikacji korzystanie z przepływu uwierzytelniania internetowego.

Ta odpowiedź jest uznawana za pomyślną, ale aplikacja jest wymagana do przełączenia się do przepływu uwierzytelniania internetowego. W takim przypadku zalecamy użycie utworzonej i obsługiwanej przez firmę Microsoft biblioteki uwierzytelniania.

Odpowiedź błędna

Przykład:

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

Majątek	opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów i reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu przyczyny błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla Microsoft Entra, które mogą ułatwić diagnozowanie błędów.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnozowaniu błędów.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.
continuation_token	Tokencontinuation który Microsoft Entra zwraca.
unverified_attributes	Lista (tablica obiektów) nazw kluczy atrybutów, które należy zweryfikować. Ten parametr jest uwzględniony w odpowiedzi, gdy error wartość parametru jest verification_required.
required_attributes	Lista (tablica obiektów) atrybutów, które aplikacja musi przesłać. Microsoft Entra zawiera ten parametr w odpowiedzi, gdy wartość parametru error jest attributes_required.
invalid_attributes	Lista (tablica obiektów) atrybutów, które zakończyły się niepowodzeniem weryfikacji. Ten parametr jest uwzględniony w odpowiedzi, gdy suberror wartość właściwości jest attribute_validation_failed.
suberror	Ciąg kodu błędu, który może służyć do dalszego klasyfikowania typów błędów.

Poniżej przedstawiono możliwe błędy, które można napotkać (możliwe wartości error właściwości):

Wartość błędu	opis
invalid_request	Weryfikacja parametru żądania nie powiodła się, na przykład weryfikacja tokenu kontynuacji nie powiodła się lub żądanie nie zawiera client_id parametru, którego wartość identyfikatora klienta jest pusta lub nieprawidłowa.
invalid_grant	Podany typ dotacji nie jest prawidłowy lub obsługiwany lub nie powiodło się walidacji, na przykład sprawdzanie poprawności atrybutów nie powiodło się. suberror Użyj właściwości , aby poznać dokładną przyczynę błędu.
expired_token	Token kontynuacji uwzględniony w żądaniu wygasł.
attributes_required	Wymagany jest co najmniej jeden atrybut użytkownika.

Jeśli parametr błędu ma wartość invalid_grant, Microsoft Entra zawiera właściwość suberror w odpowiedzi. Poniżej przedstawiono możliwe wartości suberror właściwości błędu invalid_grant :

Wartość błędu podrzędnego	opis
attribute_validation_failed	Walidacja atrybutu użytkownika nie powiodła się. invalid_attributes parametr zawiera listę (tablicę obiektów) atrybutów, które nie powiodły się walidacji.

Krok 5. Automatyczne logowanie po zarejestrowaniu

Jeśli użytkownik musi automatycznie zalogować się po zarejestrowaniu, aplikacja wysyła żądanie POST do oauth/v2.0/token punktu końcowego i udostępnia token kontynuacji uzyskany z poprzedniego kroku w celu uzyskania tokenów zabezpieczających. Dowiedz się , jak wywołać punkt końcowy tokenu.

Przesyłanie atrybutów użytkownika do punktów końcowych

W centrum administracyjnym Microsoft Entra można skonfigurować atrybuty użytkownika zgodnie z wymaganiami lub opcjonalnie. Ta konfiguracja określa, jak Microsoft Entra odpowiada podczas wykonywania wywołania do jego punktów końcowych. Opcjonalne atrybuty nie są obowiązkowe do ukończenia przepływu rejestracji. W związku z tym, gdy wszystkie atrybuty są opcjonalne, muszą zostać przesłane przed zweryfikowaniem nazwy użytkownika. W przeciwnym razie rejestracja zostanie ukończona bez opcjonalnych atrybutów.

Poniższa tabela zawiera podsumowanie, kiedy można przesłać atrybuty użytkownika do Microsoft Entra punktów końcowych.

Punkt końcowy	Wymagane atrybuty	Atrybuty opcjonalne	Atrybuty wymagane i opcjonalne
/signup/v1.0/start punkt końcowy	Tak	Tak	Tak
/signup/v1.0/continue punkt końcowy przed weryfikacją nazwy użytkownika	Tak	Tak	Tak
/signup/v1.0/continue punkt końcowy po weryfikacji nazwy użytkownika	Tak	Nie.	Tak

Format wartości atrybutów użytkownika

Należy określić informacje, które chcesz zebrać od użytkownika, konfigurując ustawienia przepływu użytkownika w centrum administracyjnym Microsoft Entra. Skorzystaj z artykułu Zbieranie atrybutów użytkownika niestandardowego podczas rejestracji , aby dowiedzieć się, jak zbierać wartości zarówno dla atrybutów wbudowanych, jak i niestandardowych.

Można również określić typ danych wejściowych użytkownika dla skonfigurowanych atrybutów. W poniższej tabeli przedstawiono podsumowanie obsługiwanych typów danych wejściowych użytkownika oraz sposób przesyłania wartości zebranych przez kontrolki interfejsu użytkownika do Microsoft Entra.

Typ danych wejściowych użytkownika	Format przesłanych wartości
Pole tekstowe	Pojedyncza wartość, taka jak stanowisko, inżynier oprogramowania.
SingleRadioSelect	Pojedyncza wartość, taka jak Language, Norwegian.
CheckboxMultiSelect	Jedna lub wiele wartości, takich jak hobby lub hobby, Taniec lub Taniec, Pływanie, Podróże.

Oto przykładowe żądanie pokazujące sposób przesyłania wartości atrybutów:

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

Dowiedz się więcej o typach wejściowych atrybutów użytkownika w artykule Niestandardowe typy danych wejściowych atrybutów użytkownika.

Jak odwoływać się do atrybutów użytkownika

Podczas tworzenia przepływu użytkownika rejestracji należy skonfigurować atrybuty użytkownika, które mają być zbierane od użytkownika podczas rejestracji. Nazwy atrybutów użytkownika w centrum administracyjnym Microsoft Entra różnią się od sposobu odwoływania się do nich w natywnym interfejsie API uwierzytelniania.

Na przykład Display Name w centrum administracyjnym Microsoft Entra jest przywoływany jako displayName w interfejsie API.

Skorzystaj z artykułu Atrybuty profilu użytkownika, aby dowiedzieć się, jak odwoływać się zarówno do wbudowanych, jak i niestandardowych atrybutów użytkownika w natywnym interfejsie API uwierzytelniania.

Referencja API dla przepływu logowania

Użytkownicy muszą zalogować się przy użyciu metody uwierzytelniania używanej do rejestracji. Na przykład użytkownicy, którzy zarejestrują się przy użyciu poczty e-mail przy użyciu metody uwierzytelniania haseł, muszą zalogować się do poczty e-mail i hasła.

Aby zażądać tokenów zabezpieczających, aplikacja współdziała z trzema punktami końcowymi, oauth/v2.0/initiate, oauth/v2.0/challenge, oauth/v2.0/tokeni opcjonalnie oauth/v2.0/introspect.

Endpointy API do logowania

Punkt końcowy	opis
oauth/v2.0/initiate	Ten punkt końcowy inicjuje przepływ logowania. Jeśli aplikacja wywołuje ją przy użyciu nazwy użytkownika, która już istnieje, zwraca odpowiedź powodzenia z tokenem kontynuacji. Jeśli aplikacja żąda użycia metod uwierzytelniania, które nie są obsługiwane przez Microsoft Entra, ta odpowiedź punktu końcowego może wskazywać aplikacji, że musi używać przepływu uwierzytelniania opartego na przeglądarce.
oauth/v2.0/challenge	Aplikacja wywołuje ten punkt końcowy, aby zażądał Microsoft Entra wybrania jednego z obsługiwanych typów wyzwań przypisania aby użytkownik uwierzytelnił się. Jeśli administrator dzierżawy wymusza uwierzytelnianie wieloskładnikowe dla użytkowników klientów, aplikacja wywołuje ten punkt końcowy, aby zakwestionować użytkownika w przypadku metody uwierzytelniania drugiego czynnika.
oauth/v2.0/token	Ten punkt końcowy weryfikuje poświadczenia użytkownika odbierane z aplikacji, a następnie wystawia tokeny zabezpieczające do aplikacji. Odpowiedź z tego punktu końcowego może również wskazywać, czy użytkownik musi wykonać wyzwanie uwierzytelniania wieloskładnikowego, czy zarejestrować metodę silnego uwierzytelniania.
oauth/v2.0/introspect	Aplikacja wywołuje ją, aby zażądać listy zarejestrowanych metod silnego uwierzytelniania na potrzeby uwierzytelniania wieloskładnikowego (MFA). Dowiedz się , jak używać punktu końcowego introspect

Typy wyzwań logowania

Interfejs API umożliwia aplikacji anonsować obsługiwane przez nią metody uwierzytelniania, gdy wykonuje wywołanie Microsoft Entra. W tym celu aplikacja używa parametru challenge_type w żądaniach. Ten parametr zawiera wstępnie zdefiniowane wartości, które reprezentują różne metody uwierzytelniania.

W przypadku danej metody uwierzytelniania wartości typu wyzwania wysyłane przez aplikację do Microsoft Entra podczas przepływu rejestracji są takie same jak w przypadku logowania aplikacji. Na przykład wiadomość e-mail z metodą uwierzytelniania haseł używa wartości typu zadania oob, hasła i przekierowania dla przepływów rejestracji i logowania.

Dowiedz się więcej o typach wyzwań w artykule dotyczącym typów wyzwań uwierzytelniania natywnego.

Szczegóły protokołu przepływu logowania

Diagram sekwencji przedstawia przepływ procesu logowania. Przepływ logowania zależy od metody uwierzytelniania użytkownika.

Jednorazowy kod dostępu poczty e-mail

Gdy aplikacja zweryfikuje adres e-mail użytkownika za pomocą protokołu OTP, otrzyma tokeny zabezpieczające. Jeśli dostarczanie jednorazowego kodu dostępu opóźnia się lub nigdy nie jest dostarczane do wiadomości e-mail użytkownika, użytkownik może zażądać wysłania innego jednorazowego kodu dostępu. Microsoft Entra ponownie wysłać kolejny jednorazowy kod dostępu, jeśli poprzedni kod dostępu nie został zweryfikowany. Gdy Microsoft Entra ponownie wysyła jednorazowy kod dostępu, unieważnia wcześniej wysłany kod.

E-mail z hasłem

• Ten diagram wskazuje, że aplikacja zbiera nazwę użytkownika (adres e-mail) i hasło od użytkownika w różnym czasie (i prawdopodobnie na oddzielnych ekranach). Możesz jednak zaprojektować aplikację, aby zebrać dwie wartości na tym samym ekranie.
• Jeśli zbierzesz nazwę użytkownika (wiadomość e-mail) i hasło na tym samym ekranie, kroki dwa i trzy zostaną scalone z krokami ośmiu i dziewięciu. W takim przypadku aplikacja przechowuje hasło, a następnie przesyła je w kroku 1 , gdzie jest to wymagane.

Jeśli administrator dzierżawy włączy uwierzytelnianie wieloskładnikowe dla użytkowników dzierżawy, odpowiedź z /oauth2/v2.0/token punktu końcowego zależy od tego, czy użytkownik ma już zarejestrowaną metodę silnego uwierzytelniania:

• Jeśli użytkownik ma zarejestrowaną metodę silnego uwierzytelniania, ukończ przepływ wyzwania uwierzytelniania wieloskładnikowego.
• Jeśli użytkownik nie zarejestrował metody silnego uwierzytelniania, ukończ rejestrację dla przepływu metody silnego uwierzytelniania .

Ten diagram sekwencji przedstawia ścieżkę uwierzytelniania wieloskładnikowego. Obejmuje ona oba przypadki: (1) użytkownik ma już zarejestrowaną metodę silnego uwierzytelniania lub (2) użytkownik nie ma żadnej i musi zarejestrować jeden just-in-time. Przepływ rozpoczyna się po zebraniu przez aplikację poprawnego hasła od użytkownika i wywołaniu /oauth2/v2.0/token, który następnie odpowiada wskazującym, czy użytkownik musi ukończyć uwierzytelnianie wieloskładnikowe, czy zarejestrować metodę silnego uwierzytelniania.

W poniższych sekcjach podsumujemy przepływ logowania do trzech podstawowych kroków.

Krok 1. Żądanie uruchomienia przepływu logowania

Przepływ uwierzytelniania rozpoczyna się od aplikacji wysyłającej żądanie POST do punktu końcowego /initiate w celu uruchomienia przepływu logowania.

Oto przykład żądania (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

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

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.
username	Tak	Adres e-mail użytkownika klienta, taki jak contoso-consumer@contoso.com.
challenge_type	Tak	Rozdzielona spacjami lista ciągów typu wyzwania autoryzacji obsługiwana przez aplikację, na przykład oob password redirect. Lista musi zawsze zawierać redirect typ wyzwania. Wartość powinna dotyczyć oob redirect jednorazowego kodu dostępu wiadomości e-mail i password redirect wiadomości e-mail z hasłem.
capabilities	Nie.	Flagi rozdzielone spacjami, które opisują gotowość "jak" aplikacji klienckiej. Podczas challenge_type definiowania metod, które mogą być kwestionowane, poinformuj natywny interfejs API uwierzytelniania, capabilities które dodatkowe przepływy może obsłużyć aplikacja kliencka i które interfejsy użytkownika mogą wyświetlać. Na przykład oznacza mfa_required, /introspecti /challenge pętlę; /token oznacza, registration_required że aplikacja kliencka wywołuje interfejsy API rejestracji i wyświetla interfejs użytkownika rejestracji. Jeśli wymagana funkcja nie jest uwzględniona przez aplikację kliencka, interfejs API zwraca przekierowanie. Obsługiwane wartości to mfa_required i registration_required. Dowiedz się więcej o możliwościach.

Odpowiedź na powodzenie

Oto przykład pomyślnej odpowiedzi:

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

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

Majątek	opis
continuation_token	Tokencontinuation który Microsoft Entra zwraca.

Odpowiedź przekierowania

Jeśli aplikacja kliencka nie obsługuje metody uwierzytelniania lub możliwości, które Microsoft Entra wymagają, wymagany jest rezerwowy przepływ uwierzytelniania oparty na sieci Web. W tym scenariuszu Microsoft Entra informuje aplikację, zwracając redirect w odpowiedzi:

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

{     
   "challenge_type": "redirect" 
} 

Majątek	opis
challenge_type	Microsoft Entra zwraca odpowiedź, która ma typ wyzwania. Wartość tego typu wyzwania to przekierowanie, co umożliwia aplikacji korzystanie z przepływu uwierzytelniania internetowego.

Ta odpowiedź jest uznawana za pomyślną, ale aplikacja jest wymagana do przełączenia się do przepływu uwierzytelniania internetowego. W takim przypadku zalecamy użycie utworzonej i obsługiwanej przez firmę Microsoft biblioteki uwierzytelniania.

Odpowiedź błędna

Przykład:

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

Majątek	opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów i reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu przyczyny błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla Microsoft Entra, które mogą ułatwić diagnozowanie błędów.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnozowaniu błędów.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.

Poniżej przedstawiono możliwe błędy, które można napotkać (możliwe wartości error właściwości):

Wartość błędu	opis
invalid_request	Sprawdzanie poprawności parametru żądania nie powiodło się, na przykład wtedy, gdy challenge_type parametr zawiera nieprawidłowy typ wyzwania. lub żądanie nie zawiera client_id parametru, wartość identyfikatora klienta jest pusta lub nieprawidłowa. Użyj parametru , error_description aby poznać dokładną przyczynę błędu.
unauthorized_client	Identyfikator klienta używany w żądaniu ma prawidłowy format identyfikatora klienta, ale nie istnieje w dzierżawie zewnętrznej lub jest niepoprawny.
invalid_client	Identyfikator klienta, który aplikacja zawiera w żądaniu, dotyczy aplikacji, która nie ma natywnej konfiguracji uwierzytelniania, takiej jak nie jest klientem publicznym lub nie jest włączona na potrzeby uwierzytelniania natywnego. suberror Użyj właściwości , aby poznać dokładną przyczynę błędu.
user_not_found	Nazwa użytkownika nie istnieje.
unsupported_challenge_type	Wartość challenge_type parametru redirect nie zawiera typu wyzwania.

Jeśli parametr błędu ma wartość invalid_client, Microsoft Entra zawiera właściwość suberror w odpowiedzi. Poniżej przedstawiono możliwe wartości suberror właściwości dla błędu invalid_client :

Wartość błędu podrzędnego	opis
nativeauthapi_disabled	Identyfikator klienta aplikacji, która nie jest włączona na potrzeby uwierzytelniania natywnego.

Krok 2. Wybieranie metody uwierzytelniania

Aby kontynuować przepływ, aplikacja używa tokenu kontynuacji uzyskanego z poprzedniego kroku, aby zażądać Microsoft Entra, aby wybrać jeden z obsługiwanych typów wyzwań dla użytkownika w celu uwierzytelnienia lub ukończenia wyzwania uwierzytelniania wieloskładnikowego. Aplikacja wysyła żądanie POST do punktu końcowego /oauth2/v2.0/challenge .

Oto przykład żądania (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

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

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.
continuation_token	Tak	Tokencontinuation który Microsoft Entra zwrócony w poprzednim żądaniu. Poprzednie żądanie wywołuje /oauth2/v2.0/initiate punkt końcowy lub /oauth2/v2.0/introspect punkt końcowy, jeśli użytkownik ukończy wyzwanie uwierzytelniania wieloskładnikowego.
challenge_type	Nie.	Rozdzielona spacjami lista ciągów typu wyzwania autoryzacji obsługiwana przez aplikację, na przykład oob password redirect. Lista musi zawsze zawierać redirect typ wyzwania. Wartość powinna dotyczyć oob redirect jednorazowego kodu dostępu wiadomości e-mail i password redirect wiadomości e-mail z hasłem.
id	Nie.	Identyfikator ciągu metody silnego uwierzytelniania zwróconej z punktu końcowego /oauth2/v2.0/introspect . Ten parametr jest wymagany, gdy aplikacja kliencka wyzywuje użytkownika na potrzeby uwierzytelniania drugiego czynnika. Dowiedz się , jak używać punktu końcowego introspect.

Odpowiedź na powodzenie

Odpowiedź na powodzenie zależy od metody uwierzytelniania użytkownika.

Jednorazowy kod dostępu poczty e-mail

Jeśli administrator dzierżawy skonfigurował jednorazowy kod dostępu poczty e-mail w centrum administracyjnym Microsoft Entra jako metodę uwierzytelniania użytkownika, Microsoft Entra wysyła jednorazowy kod dostępu do adresu e-mail użytkownika, a następnie odpowiada za pomocą typu wyzwania oob i zawiera więcej informacji na temat jednorazowego kodu dostępu.

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
} 

Majątek	opis
continuation_token	Tokencontinuation który Microsoft Entra zwraca.
challenge_type	Typ wyzwania wybrany dla użytkownika do uwierzytelnienia.
binding_method	Jedyną prawidłową wartością jest monit. Tego parametru można użyć w przyszłości, aby zaoferować użytkownikowi więcej sposobów wprowadzania jednorazowego kodu dostępu. Wystawione, jeśli challenge_type jest obiektem oob
challenge_channel	Typ kanału, za pośrednictwem którego został wysłany jednorazowy kod dostępu. W tej chwili obsługujemy pocztę e-mail.
challenge_target_label	Zaciemniony adres e-mail, w którym wysłano jednorazowy kod dostępu.
code_length	Długość jednorazowego kodu dostępu, który Microsoft Entra generuje.

E-mail z hasłem

Jeśli administrator dzierżawy skonfigurował wiadomość e-mail z hasłem w centrum administracyjnym Microsoft Entra jako metodę uwierzytelniania użytkownika, odpowiedź zależy od tego, czy żądanie do punktu końcowego /oauth2/v2.0/challenge ma wybrać metodę uwierzytelnienia użytkownika za pomocą lub do ukończenia żądania uwierzytelniania wieloskładnikowego.

Odpowiedź, jeśli żądanie ma wybrać metodę uwierzytelniania

Jeśli żądanie do punktu końcowego /oauth2/v2.0/challenge ma wybrać metodę uwierzytelnienia użytkownika (uwierzytelnianie pierwszego czynnika), Microsoft Entra zwraca odpowiedź powodzenia, która zawiera typ wyzwania password.

Przykład:

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

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

Majątek	opis
continuation_token	Tokencontinuation który Microsoft Entra zwraca.
challenge_type	Microsoft Entra zwraca obsługiwany typ wyzwania skonfigurowany dla użytkownika w centrum administracyjnym Microsoft Entra. W takim przypadku wartości powinny być hasłami.

Odpowiedź, jeśli żądanie ma zakończyć wyzwanie uwierzytelniania wieloskładnikowego

Jeśli żądanie do punktu końcowego /oauth2/v2.0/challenge ma zakończyć wyzwanie uwierzytelniania wieloskładnikowego (drugie uwierzytelnianie współczynnika), Microsoft Entra wysyła jednorazowy kod dostępu do wybranego kanału wyzwania uwierzytelniania wieloskładnikowego użytkownika i zawiera więcej informacji na temat jednorazowego kodu dostępu.

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
} 

Majątek	opis
continuation_token	Tokencontinuation który Microsoft Entra zwraca.
challenge_type	Typ wyzwania wybrany dla użytkownika w celu ukończenia uwierzytelniania wieloskładnikowego.
binding_method	Jedyną prawidłową wartością jest monit. Tego parametru można użyć w przyszłości, aby zaoferować użytkownikowi więcej sposobów wprowadzania jednorazowego kodu dostępu. Wystawione, jeśli challenge_type jest obiektem oob
challenge_channel	Typ kanału wyzwania uwierzytelniania wieloskładnikowego, za pośrednictwem którego wysłano jednorazowy kod dostępu. Obsługiwane wartości: poczta e-mail, wiadomość SMS.
challenge_target_label	Zaciemniony adres e-mail, w którym wysłano jednorazowy kod dostępu.
code_length	Długość jednorazowego kodu dostępu, który Microsoft Entra generuje.

Odpowiedź przekierowania

W następujących scenariuszach może być potrzebny powrót do przepływu uwierzytelniania opartego na sieci Web:

• Aplikacja kliencka nie obsługuje metody uwierzytelniania ani możliwości, których Microsoft Entra wymaga.
• Użytkownik próbuje użyć wiadomości SMS jako silnej metody uwierzytelniania, ale ochrona przed oszustwami blokuje żądanie, jeśli uzna je za wysokie ryzyko (tylko w wiadomości e-mail z uwierzytelnianiem haseł).

W tych scenariuszach Microsoft Entra informuje aplikację, zwracając redirect typ wyzwania:

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

{     
   "challenge_type": "redirect" 
} 

Majątek	opis
challenge_type	Microsoft Entra zwraca odpowiedź, która ma typ wyzwania. Wartość tego typu wyzwania to przekierowanie, co umożliwia aplikacji korzystanie z przepływu uwierzytelniania internetowego.

Ta odpowiedź jest uznawana za pomyślną, ale aplikacja jest wymagana do przełączenia się do przepływu uwierzytelniania internetowego. W takim przypadku zalecamy użycie utworzonej i obsługiwanej przez firmę Microsoft biblioteki uwierzytelniania.

Odpowiedź błędna

Przykład:

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

Majątek	opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów i reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu przyczyny błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla Microsoft Entra, które mogą ułatwić diagnozowanie błędów.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnozowaniu błędów.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.

Poniżej przedstawiono możliwe błędy, które można napotkać (możliwe wartości error właściwości):

Wartość błędu	opis
invalid_request	Sprawdzanie poprawności parametru żądania nie powiodło się, na przykład wtedy, gdy challenge_type parametr zawiera nieprawidłowy typ wyzwania.
invalid_grant	Token kontynuacji uwzględniony w żądaniu jest nieprawidłowy.
expired_token	Token kontynuacji uwzględniony w żądaniu wygasł.
unsupported_challenge_type	Wartość challenge_type parametru redirect nie zawiera typu wyzwania.

Krok 3. Żądanie tokenów zabezpieczających

Aplikacja wysyła żądanie POST do punktu końcowego oauth2/v2.0/token i udostępnia poświadczenia użytkownika wybrane w poprzednim kroku w celu uzyskania tokenów zabezpieczających.

Oto przykład żądania (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

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 

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.
continuation_token	Tak	Tokencontinuation który Microsoft Entra zwrócony w poprzednim żądaniu.
grant_type	Tak	Typ grantu. Po wywołaniu punktu końcowego tokenu ta wartość musi być następująca: - hasło do poczty e-mail z metodą uwierzytelniania haseł w przepływie logowania w celu zweryfikowania uwierzytelniania pierwszego czynnika użytkownika. - oob dla jednorazowej metody uwierzytelniania kodu dostępu poczty e-mail w przepływie logowania. - continuation_token na potrzeby automatycznego logowania po przepływie rejestracji. - continuation_token na potrzeby automatycznego logowania po przepływie samoobsługowego resetowania hasła. - continuation_token po przepływie rejestracji metody silnego uwierzytelniania. - mfa_oob podczas weryfikowania uwierzytelniania drugiego czynnika użytkownika.
scope	Tak	Rozdzielona spacjami lista zakresów. Wszystkie zakresy muszą pochodzić z jednego zasobu wraz z zakresami OpenID Connect (OIDC), takimi jak profile, openid i email. Aplikacja musi zawierać zakres openid, aby Microsoft Entra wystawiać token identyfikatora. Aplikacja musi zawierać zakres offline_access aby Microsoft Entra wystawiać token odświeżania. Dowiedz się więcej na temat uprawnień i zgody w Platforma tożsamości Microsoft.
password	Nie.	Wartość hasła zbierana przez aplikację od użytkownika. Zastąp {secure_password} wartość hasłem zbieraną przez aplikację od użytkownika. Ten parametr jest wymagany , jeśli metoda uwierzytelniania jest adresem e-mail z hasłem.
oob	Nie.	Jednorazowy kod dostępu, który użytkownik otrzymuje pocztą e-mail. Wymagane, jeśli: — podstawowa metoda uwierzytelniania to jednorazowy kod dostępu poczty e-mail. — Aplikacja przesyła jednorazowy kod dostępu do wiadomości e-mail, aby spełnić wyzwanie uwierzytelniania wieloskładnikowego, gdy podstawowa metoda uwierzytelniania to wiadomość e-mail z hasłem. Aby ponownie wysłać jednorazowy kod dostępu, ponownie wywołaj /challenge punkt końcowy.
username	Nie.	Adres e-mail użytkownika, którego chcesz zarejestrować, na przykład contoso-consumer@contoso.com. Ten parametr jest wymagany w przepływie rejestracji.

Odpowiedź pomyślna

Oto przykład pomyślnej odpowiedzi:

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

Majątek	opis
token_type	Wskazuje wartość typu tokenu. Jedynym typem, który obsługuje Microsoft Entra, jest Bearer.
scopes	Rozdzielona spacjami lista zakresów, dla których token dostępu jest prawidłowy.
expires_in	Czas w sekundach, przez który token dostępu pozostaje prawidłowy.
access_token	Token dostępu żądany przez aplikację z punktu końcowego /token . Aplikacja może użyć tego tokenu dostępu, aby zażądać dostępu do zabezpieczonych zasobów, takich jak internetowe interfejsy API.
refresh_token	Token odświeżania OAuth 2.0. Aplikacja może użyć tego tokenu do uzyskania innych tokenów dostępu po wygaśnięciu bieżącego tokenu dostępu. Tokeny odświeżania są długotrwałe. Mogą oni utrzymywać dostęp do zasobów przez dłuższy czas. Aby uzyskać więcej informacji na temat odświeżania tokenu dostępu, zobacz Odświeżanie tokenu dostępu. Uwaga: wystawiane tylko w przypadku żądania offline_access zakresu.
id_token	Token internetowy JSON (Jwt) używany do identyfikowania użytkownika. Aplikacja może dekodować token, aby zażądać informacji o użytkowniku, który się zalogował. Aplikacja może buforować wartości i wyświetlać je, a poufne klienci mogą używać tego tokenu do autoryzacji. Aby uzyskać więcej informacji na temat tokenów identyfikatorów, zobacz Tokeny identyfikatorów na platformie tożsamości firmy Microsoft. Uwaga: wystawiane tylko wtedy, gdy zażądasz zakresu openid .

Odpowiedź błędna

Przykład:

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

Majątek	opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów i reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu przyczyny błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla Microsoft Entra, które mogą ułatwić diagnozowanie błędów.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnozowaniu błędów.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.

Poniżej przedstawiono możliwe błędy, które można napotkać (możliwe wartości error właściwości):

Wartość błędu	opis
invalid_request	Sprawdzanie poprawności parametru żądania nie powiodło się. Aby zrozumieć, co się stało, użyj komunikatu w opisie błędu.
invalid_grant	Token kontynuacji zawarty w żądaniu jest nieprawidłowy, poświadczenia logowania użytkownika zawarte w żądaniu są nieprawidłowe, dalsza interakcja wymagana od użytkownika lub typ udzielania uwzględniony w żądaniu jest nieznany.
invalid_client	Identyfikator klienta uwzględniony w żądaniu nie jest przeznaczony dla klienta publicznego.
expired_token	Token kontynuacji uwzględniony w żądaniu wygasł.
invalid_scope	Co najmniej jeden zakres uwzględniony w żądaniu jest nieprawidłowy.
unauthorized_client	Identyfikator klienta uwzględniony w żądaniu jest nieprawidłowy lub nie istnieje.
unsupported_grant_type	Typ dotacji uwzględniony w żądaniu nie jest obsługiwany lub jest niepoprawny.

Jeśli parametr błędu ma wartość invalid_grant, Microsoft Entra zawiera właściwość suberror w odpowiedzi. Poniżej przedstawiono możliwe wartości suberror właściwości błędu invalid_grant :

Wartość błędu podrzędnego	opis
invalid_oob_value	Wartość jednorazowego kodu dostępu przesyłanego przez aplikację jest nieprawidłowa.
mfa_required	Uwierzytelnianie wieloskładnikowe jest wymagane. Odpowiedź zawiera token kontynuacji. Wywołaj punkt końcowy, oauth2/v2.0/introspect aby uzyskać zarejestrowane przez użytkownika metody silnego uwierzytelniania. Ten poderror występuje tylko wtedy, gdy podstawowa metoda uwierzytelniania użytkownika to wiadomość e-mail z hasłem. Zobacz, jak uzyskać zarejestrowane przez użytkownika metody silnego uwierzytelniania. Uwaga: W niektórych przypadkach uwierzytelnianie wieloskładnikowe jest wymagane, ale uwierzytelnianie natywne nie zwraca wartości mfa_required. lub na przykład jeśli przepływ rejestracji metody silnego uwierzytelniania poprzedza wywołanie /oauth2/v2.0/token metody i jedyną dostępną metodą (e-mail) została już zweryfikowana podczas tego przepływu.
registration_required	Użytkownik musi wykonać wyzwanie uwierzytelniania wieloskładnikowego, ale nie ma zarejestrowanej metody silnego uwierzytelniania. Monituj użytkownika o zarejestrowanie go. Ten błąd występuje, gdy podstawowa metoda uwierzytelniania użytkownika to wiadomość e-mail z hasłem. Dowiedz się, jak zarejestrować metodę silnego uwierzytelniania.

Odpowiedź przekierowania

Jeśli aplikacja kliencka nie obsługuje metody uwierzytelniania lub możliwości, których Microsoft Entra wymaga, wymagany jest rezerwowy przepływ uwierzytelniania oparty na sieci Web. W tym scenariuszu Microsoft Entra informuje aplikację, zwracając redirect typ wyzwania:

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

{     
    "challenge_type": "redirect",
    "redirect_reason": "Client is missing registration_required capability"
} 

Majątek	opis
challenge_type	Microsoft Entra zwraca odpowiedź, która ma typ wyzwania. Wartość tego typu wyzwania to przekierowanie, co umożliwia aplikacji korzystanie z przepływu uwierzytelniania internetowego.
redirect_reason	Przyczyna, dla której wymagane jest przekierowanie. Na przykład Microsoft Entra wykrywa, że wymagana jest usługa MFA lub rejestracja metody silnego uwierzytelniania, ale aplikacja nie uwzględniła tych możliwości w żądaniu.

Ta odpowiedź jest uznawana za pomyślną, ale aplikacja jest wymagana do przełączenia się do przepływu uwierzytelniania internetowego. W takim przypadku zalecamy użycie utworzonej i obsługiwanej przez firmę Microsoft biblioteki uwierzytelniania.

Pobieranie metod silnego uwierzytelniania zarejestrowanego przez użytkownika

oauth2/v2.0/introspect Użyj punktu końcowego, aby zażądać listy zarejestrowanych metod silnego uwierzytelniania użytkownika.

Oto przykład żądania (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

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

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.
continuation_token	Tak	Tokencontinuation który Microsoft Entra zwrócony w poprzednim żądaniu.

Odpowiedź na powodzenie

Przykład:

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

Majątek	opis
continuation_token	Tokencontinuation który Microsoft Entra zwraca.
methods	Lista (obiektów) zarejestrowanych przez użytkownika metod silnego uwierzytelniania.

Obiekt metody MFA ma następujące właściwości:

Majątek	opis
id	Automatycznie wygenerowany unikatowy identyfikator ciągu dla metody uwierzytelniania wieloskładnikowego. Aplikacja używa tego ciągu tak, jak id podczas wywoływana punktu końcowego /oauth2/v2.0/challenge .
challenge_type	Typ wyzwania wybrany dla użytkownika jako metoda uwierzytelniania wieloskładnikowego. Bieżący obsługiwany typ wyzwania to oob.
challenge_channel	Typ kanału, do którego jest wysyłana metoda MFA. Bieżący obsługiwany kanał wyzwania to poczta e-mail.
login_hint	Wskazówka dotycząca metody silnego uwierzytelniania, takiej jak zaciemniony adres e-mail.

Odpowiedź przekierowania

Jeśli aplikacja kliencka nie obsługuje metody uwierzytelniania lub możliwości, które Microsoft Entra wymagają, wymagany jest rezerwowy przepływ uwierzytelniania oparty na sieci Web. W tym scenariuszu Microsoft Entra informuje aplikację, zwracając redirect w odpowiedzi:

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

{     
   "challenge_type": "redirect" 
} 

Odpowiedź błędna

Przykład:

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

Majątek	opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów i reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu przyczyny błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla Microsoft Entra, które mogą ułatwić diagnozowanie błędów.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnozowaniu błędów.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.

Poniżej przedstawiono możliwe błędy, które można napotkać (możliwe wartości error właściwości):

Wartość błędu	opis
invalid_request	Sprawdzanie poprawności parametru żądania nie powiodło się. Aby zrozumieć, co się stało, użyj komunikatu w opisie błędu.
invalid_client	Identyfikator klienta uwzględniony w żądaniu nie jest przeznaczony dla klienta publicznego.
expired_token	Token kontynuacji uwzględniony w żądaniu wygasł.
server_error	Wystąpił problem z żądaniem.

Gdy aplikacja kliencka pomyślnie pobierze listę metod silnego uwierzytelniania zarejestrowanych dla użytkownika, użytkownik wybierze metodę, której chce użyć do ukończenia zadania uwierzytelniania wieloskładnikowego. Następnie przepływ będzie kontynuowany w następujący sposób:

1. Aplikacja kliencka wywołuje metodę /oauth2/v2.0/challenge i zawiera token kontynuacji uzyskany z /oauth2/v2.0/introspect metody i id metody MFA do wyboru:

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

2. Microsoft Entra wysyła kod wyzwania do kanału wyzwania użytkownika, takiego jak wiadomość e-mail, a następnie odpowiada z powrotem do aplikacji klienckiej przy użyciu tokenu kontynuacji i szczegółów wyzwania uwierzytelniania wieloskładnikowego:

   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
   } 
   

3. Aplikacja może teraz wysyłać żądanie POST do punktu końcowego /oauth2/v2.0/token i zawiera token kontynuacji, prawidłowy typ dotacji i odpowiednie wartości typu udzielania w celu uzyskania tokenów zabezpieczających. Zobacz oczekiwaną odpowiedź w temacie Request for security tokens (Żądanie dotyczące tokenów zabezpieczających):

   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
   

Rejestrowanie dokumentacji interfejsu API metody silnego uwierzytelniania

Uwierzytelnianie natywne obsługuje rejestrację metody silnego uwierzytelniania. Gdy aplikacja wywołuje punkt końcowy /oauth2/v2.0/token i uwierzytelnianie wieloskładnikowe jest wymagane, ale użytkownik nie ma zarejestrowanej silnej metody, odpowiedź , registeration_required, informuje aplikację o zarejestrowaniu użytkownika przed wystawieniem tokenów.

Gdy aplikacja kliencka ukończy przepływ, aby zarejestrować metodę silnego uwierzytelniania, wywołuje /oauth2/v2.0/token punkt końcowy w celu żądania tokenów zabezpieczających.

Punkty końcowe rejestracji metody silnego uwierzytelniania

Aby użyć interfejsu API rejestracji metody silnego uwierzytelniania, aplikacja używa punktu końcowego pokazanego w poniższej tabeli:

Punkt końcowy	opis
/register/v1.0/introspect	Wywołaj ten punkt końcowy, aby pobrać listę metod silnego uwierzytelniania, które użytkownik może zarejestrować.
/register/v1.0/challenge	Wywołaj ten punkt końcowy, aby wysłać wyzwanie do użytkownika, takie jak jednorazowy kod dostępu e-mail.
/register/v1.0/continue	Wywołaj ten punkt końcowy, aby przesłać wyzwanie, które aplikacja zbiera od użytkownika, takiego jak jednorazowy kod dostępu, aby ukończyć przepływ w celu zarejestrowania metody silnego uwierzytelniania. Gdy wywołanie zakończy się pomyślnie i uzyskasz token kontynuacji, wywołaj /oauth2/v2.0/token punkt końcowy punktu końcowego, aby zażądać tokenów zabezpieczających. Dowiedz się, jak wywołać punkt końcowy tokenu.

Krok 1. Pobieranie listy metod silnego uwierzytelniania

Przepływ rejestracji rozpoczyna się, gdy aplikacja żąda listy metod silnego uwierzytelniania, które użytkownik może zarejestrować.

Oto przykład żądania (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

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  

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.

Odpowiedź na powodzenie

Oto przykład pomyślnej odpowiedzi:

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

Majątek	opis
continuation_token	Tokencontinuation który Microsoft Entra zwraca.
methods	Lista (obiektów) silnych metod uwierzytelniania dostępnych dla użytkownika do zarejestrowania.

Obiekt metody silnego uwierzytelniania ma następujące właściwości:

Majątek	opis
id	Klucz ciągu metody. Obsługiwane wartości e-mail, sms.
challenge_type	Typ wyzwania wybrany dla użytkownika jako metoda uwierzytelniania wieloskładnikowego. Bieżący obsługiwany typ wyzwania to oob.
challenge_channel	Typ kanału, do którego jest wysyłana metoda MFA. Obsługiwane wartości e-mail, sms.
login_hint	Wskazówka dotycząca metody silnego uwierzytelniania, takiej jak wiadomość e-mail. Ta wartość jest używana przez aplikację kliencą do wstępnego wypełniania pola tekstowego wiadomości e-mail.

Odpowiedź błędna

Przykład:

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

Majątek	opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów i reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu przyczyny błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla Microsoft Entra, które mogą ułatwić diagnozowanie błędów.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnozowaniu błędów.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.

Poniżej przedstawiono możliwe błędy, które można napotkać (możliwe wartości error właściwości):

Wartość błędu	opis
invalid_request	Sprawdzanie poprawności parametru żądania nie powiodło się, takie jak weryfikacja tokenu kontynuacji lub żądanie nie zawiera client_id parametru wartość identyfikatora klienta jest pusta lub nieprawidłowa lub administrator dzierżawy zewnętrznej nie włączył protokołu OTP poczty e-mail dla wszystkich użytkowników dzierżawy.
expired_token	Token kontynuacji uwzględniony w żądaniu wygasł.

Krok 2. Wybieranie metody silnego uwierzytelniania

W tym kroku prześlij metodę silnego uwierzytelniania, którą użytkownik chce zarejestrować. Microsoft Entra następnie wysyła do użytkownika wyzwanie, takie jak jednorazowy kod dostępu e-mail.

Oto przykład żądania (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

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 

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.
continuation_token	Tak	Token Continuation który Microsoft Entra powraca z punktu końcowego /register/v1.0/introspect
challenge_type	Tak	Typ wyzwania metody uwierzytelniania. Bieżący typ to oob.
challenge_target	Tak	Adres e-mail lub numer telefonu, który użytkownik chce zarejestrować.
challenge_channel	Nie.	Kanał do wysłania wyzwania. Obsługiwane wartości kanału wyzwania: poczta e-mail, wiadomość SMS.

Odpowiedź na powodzenie

Oto przykład pomyślnej odpowiedzi.

Przykład 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 
} 

Przykład 2:

Jeśli przepływ rejestracji poprzedza przepływ rejestracji metody silnego uwierzytelniania, a wiadomość e-mail przesłana do /register/v1.0/challenge punktu końcowego jest zgodna z tym, który został zweryfikowany w przepływie rejestracji, natywny interfejs API uwierzytelniania rejestruje metodę bez wysyłania wyzwania do użytkownika. W takim przypadku odpowiedź będzie wyglądać podobnie do następującego fragmentu kodu:

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

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY...",
  "challenge_type": "preverified" 
}

Majątek	opis
continuation_token	Tokencontinuation który Microsoft Entra zwraca.
challenge_type	Typ wyzwania wybrany dla użytkownika do uwierzytelniania, na przykład oob, lub wstępnie zgłoszony, jeśli silna metoda uwierzytelniania zostanie wstępnie wyzwerowana .
binding_method	Jedyną prawidłową wartością jest monit. Tego parametru można użyć w przyszłości, aby zaoferować użytkownikowi więcej sposobów wprowadzania jednorazowego kodu dostępu. Wystawiony, jeśli challenge_type jest obiektem oob , a silna metoda uwierzytelniania nie jest wstępnie wyzweryfikowana.
challenge_channel	Typ kanału, za pośrednictwem którego został wysłany jednorazowy kod dostępu. Obsługiwane wartości e-mail, sms. Zwracane, jeśli metoda silnego uwierzytelniania nie jest wstępnie określona.
code_length	Długość jednorazowego kodu dostępu, jeśli binding_method jest wyświetlany monit. Zwracane, jeśli metoda silnego uwierzytelniania nie jest wstępnie określona.
challenge_target	Cel, do którego wysłano wyzwanie. Jest to takie samo, jak dane wejściowe podane w żądaniu. Zwracane, jeśli metoda silnego uwierzytelniania nie jest wstępnie określona.
interval	Interwał (w sekundach) klient powinien czekać między sondowaniem /register/continue. Zwracane tylko wtedy, gdy prompt=none metoda silnego uwierzytelniania nie jest wstępnie wyzweryfikowana. Klienci powinni podwoić interwał za każdym razem, gdy otrzymują element HTTP 429 z natywnego interfejsu API uwierzytelniania.

Odpowiedź błędna

Błędy w tym miejscu są podobne do tych, które można napotkać podczas wywoływania punktu końcowego /register/v1.0/introspect . Jednak w przypadku rejestrowania numeru telefonu, jeśli numer telefonu jest uznawany za wysoki ryzyko, żądanie może zostać zablokowane.

Poniżej przedstawiono możliwe błędy, które można napotkać, jeśli żądanie jest zablokowane:

Wartość błędu	opis
access_denied	Wiadomość SMS została zablokowana.

Jeśli parametr błędu ma wartość access_denied, Microsoft Entra zawiera właściwość suberror w odpowiedzi. Poniżej przedstawiono możliwe wartości właściwości suberror dla błędu invalid_grant:

Wartość błędu podrzędnego	opis
provider_blocked_by_admin	Administrator dzierżawy zablokował region telefonu.
provider_blocked_by_rep	Metoda uwierzytelniania wieloskładnikowego jest zablokowana (numer telefonu został zablokowany przez narzędzie RepMap).

Krok 3. Przesyłanie wyzwania

W tym kroku wykonaj wywołanie punktu końcowego /register/v1.0/continue , aby ukończyć rejestrację metody silnego uwierzytelniania.

Oto przykład żądania (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

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}

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
continuation_token	Tak	Tokencontinuation który Microsoft Entra zwrócony w poprzednim żądaniu.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.
grant_type	Tak	Typ grantu. Bieżąca obsługiwana wartość to oob lub continuation_token , jeśli metoda silnego uwierzytelniania zostanie wstępnie wyzweryfikowana w punkcie /register/v1.0/challenge końcowym.
oob	Nie.	Jednorazowy kod dostępu otrzymany przez użytkownika klienta w wiadomości e-mail. Zastąp element {otp_code} jednorazowymi wartościami kodu dostępu, które użytkownik klienta otrzymał w wiadomości e-mail. Aby ponownie wysłać jednorazowy kod dostępu, aplikacja musi ponownie wysłać żądanie do punktu końcowego /register/v1.0/challenge . Wymagane, jeśli metoda silnego uwierzytelniania nie jest wstępnie określona w punkcie /register/v1.0/challenge końcowym.

Odpowiedź na powodzenie

Oto przykład pomyślnej odpowiedzi:

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

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

Majątek	opis
continuation_token	Token continuation który Microsoft Entra zwraca. Użyj tego tokenu kontynuacji, aby wywołać punkt końcowy w /oauth2/v2.0/token celu żądania tokenów zabezpieczających. Dowiedz się , jak wywołać punkt końcowy tokenu.

Odpowiedź błędna

Przykład:

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

Majątek	opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów i reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu przyczyny błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla Microsoft Entra, które mogą ułatwić diagnozowanie błędów.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnozowaniu błędów.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.

Poniżej przedstawiono możliwe błędy, które można napotkać (możliwe wartości error właściwości):

Wartość błędu	opis
invalid_request	Sprawdzanie poprawności parametru żądania nie powiodło się, takie jak weryfikacja tokenu kontynuacji lub żądanie nie zawiera client_id parametru wartość identyfikatora klienta jest pusta lub nieprawidłowa lub administrator dzierżawy zewnętrznej nie włączył protokołu OTP poczty e-mail dla wszystkich użytkowników dzierżawy.
invalid_grant	Typ dotacji uwzględniony w żądaniu jest nieprawidłowy lub obsługiwany lub wartość OTP jest nieprawidłowa.
expired_token	Token kontynuacji uwzględniony w żądaniu wygasł.

Jeśli parametr błędu ma wartość invalid_grant, Microsoft Entra zawiera właściwość suberror w odpowiedzi. Poniżej przedstawiono możliwe wartości suberror właściwości błędu invalid_grant :

Wartość błędu podrzędnego	opis
invalid_oob_value	Wartość jednorazowego kodu dostępu jest nieprawidłowa.

Samoobsługowe resetowanie hasła

W przypadku użytkowników, których podstawowa metoda uwierzytelniania to poczta e-mail z hasłem, użyj interfejsu API samoobsługowego resetowania hasła (SSPR), aby umożliwić użytkownikom klienta resetowanie hasła. Tego interfejsu API można używać do scenariuszy zapomnianych haseł lub zmiany hasła.

Endpointy API do samoobsługowego resetowania hasła

Aby użyć tego interfejsu API, aplikacja używa punktu końcowego pokazanego w poniższej tabeli:

Punkt końcowy	opis
/resetpassword/v1.0/start	Aplikacja wywołuje ten punkt końcowy, gdy użytkownik klienta wybierze pozycję Nie pamiętam hasła lub linku Zmień hasło lub przycisku w aplikacji. Ten punkt końcowy weryfikuje nazwę użytkownika (adres e-mail), a następnie zwraca token kontynuacji do użycia w przepływie resetowania hasła. Jeśli aplikacja żąda użycia metod uwierzytelniania, które nie są obsługiwane przez Microsoft Entra, ta odpowiedź punktu końcowego może wskazywać aplikacji, że musi używać przepływu uwierzytelniania opartego na przeglądarce.
/resetpassword/v1.0/challenge	Akceptuje listę typów wyzwań obsługiwanych przez klienta i token kontynuacji. Zadanie jest wystawiane jednemu z preferowanych poświadczeń odzyskiwania. Na przykład zadanie oob wystawia jednorazowy kod dostępu poza pasmem do wiadomości e-mail skojarzonej z kontem użytkownika klienta. Jeśli aplikacja żąda użycia metod uwierzytelniania, które nie są obsługiwane przez Microsoft Entra, ta odpowiedź punktu końcowego może wskazywać aplikacji, że musi używać przepływu uwierzytelniania opartego na przeglądarce.
/resetpassword/v1.0/continue	Weryfikuje wyzwanie wystawione przez /resetpassword/v1.0/challenge punkt końcowy, a następnie zwraca token kontynuacji dla /resetpassword/v1.0/submit punktu końcowego lub wystawia inne wyzwanie użytkownikowi.
/resetpassword/v1.0/submit	Akceptuje nowe dane wejściowe hasła przez użytkownika wraz z tokenem kontynuacji w celu ukończenia przepływu resetowania hasła. Ten punkt końcowy wystawia kolejny token kontynuacji.
/resetpassword/v1.0/poll_completion	Aplikacja może użyć tokenu kontynuacji wystawionego /resetpassword/v1.0/submit przez punkt końcowy, aby sprawdzić stan żądania resetowania hasła.
oauth2/v2.0/token	Jeśli resetowanie hasła zakończy się pomyślnie, aplikacja może użyć tokenu kontynuacji, który uzyskuje z /resetpassword/v1.0/poll_completion punktu końcowego, aby uzyskać tokeny zabezpieczające z punktu końcowego oauth2/v2.0/token .

Typy wyzwań dotyczących samoobsługowego resetowania hasła

Interfejs API umożliwia aplikacji anonsować obsługiwane przez nią metody uwierzytelniania, gdy wykonuje wywołanie Microsoft Entra. W tym celu aplikacja używa parametru challenge_type w żądaniach. Ten parametr zawiera wstępnie zdefiniowane wartości, które reprezentują różne metody uwierzytelniania.

W przypadku przepływu samoobsługowego resetowania hasła wartości typu wyzwania to oob i przekierowanie.

Dowiedz się więcej o typach wyzwań w typach wyzwań uwierzytelniania natywnego.

Szczegóły protokołu przepływu samoobsługowego resetowania hasła

Diagram sekwencji przedstawia przepływ procesu resetowania hasła.

Ten diagram wskazuje, że aplikacja zbiera nazwę użytkownika (adres e-mail) i hasło od użytkownika w różnym czasie (i prawdopodobnie na oddzielnych ekranach). Możesz jednak zaprojektować aplikację, aby zebrać nazwę użytkownika (adres e-mail) i nowe hasło na tym samym ekranie. W takim przypadku aplikacja przechowuje hasło, a następnie przesyła je za pośrednictwem punktu końcowego /resetpassword/v1.0/submit , w którym jest to wymagane.

Krok 1. Żądanie uruchomienia przepływu samoobsługowego resetowania hasła

Przepływ resetowania hasła rozpoczyna się od aplikacji wysyłającej żądanie POST do /resetpassword/v1.0/start punktu końcowego w celu uruchomienia przepływu samoobsługowego resetowania hasła.

Oto przykład żądania (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

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 

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.
username	Tak	Adres e-mail użytkownika klienta, taki jak contoso-consumer@contoso.com.
challenge_type	Tak	Rozdzielona spacjami lista ciągów typu wyzwania autoryzacji obsługiwana przez aplikację, na przykład oob password redirect. Lista musi zawsze zawierać redirect typ wyzwania. W przypadku tego żądania wartość powinna zawierać oob redirectwartość .
capabilities	Nie.	Flagi rozdzielone spacjami, które opisują gotowość "jak" aplikacji klienckiej. Podczas challenge_type definiowania metod, które mogą być kwestionowane, poinformuj natywny interfejs API uwierzytelniania, capabilities które dodatkowe przepływy może obsłużyć aplikacja kliencka i które interfejsy użytkownika mogą wyświetlać. Na przykład oznacza inną mfa_required pętlę i /challenge ; /token oznacza, registration_required że aplikacja kliencka wywołuje interfejsy API rejestracji i wyświetla interfejs użytkownika rejestracji. Jeśli wymagana funkcja nie jest anonsowana przez aplikację kliencką, interfejs API zwraca przekierowanie. Obsługiwane wartości to mfa_required i registration_required. Dowiedz się więcej o możliwościach.

Odpowiedź na powodzenie

Przykład:

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

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

Majątek	opis
continuation_token	Tokencontinuation który Microsoft Entra zwraca.

Odpowiedź przekierowania

Jeśli aplikacja kliencka nie obsługuje metody uwierzytelniania lub możliwości, które Microsoft Entra wymagają, wymagany jest rezerwowy przepływ uwierzytelniania oparty na sieci Web. W tym scenariuszu Microsoft Entra informuje aplikację, zwracając redirect w odpowiedzi:

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

{     
   "challenge_type": "redirect" 
} 

Majątek	opis
challenge_type	Microsoft Entra zwraca odpowiedź, która ma typ wyzwania. Wartość tego typu wyzwania to przekierowanie, co umożliwia aplikacji korzystanie z przepływu uwierzytelniania internetowego.

Ta odpowiedź jest uznawana za pomyślną, ale aplikacja jest wymagana do przełączenia się do przepływu uwierzytelniania internetowego. W takim przypadku zalecamy użycie utworzonej i obsługiwanej przez firmę Microsoft biblioteki uwierzytelniania.

Odpowiedź błędna

Przykład:

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

Majątek	opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów i reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu przyczyny błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla Microsoft Entra, które mogą ułatwić diagnozowanie błędów.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnozowaniu błędów.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.

Poniżej przedstawiono możliwe błędy, które można napotkać (możliwe wartości error właściwości):

Wartość błędu	opis
invalid_request	Sprawdzanie poprawności parametru żądania nie powiodło się, na przykład wtedy, gdy challenge_type parametr zawiera nieprawidłowy typ wyzwania lub żądanie nie zawiera client_id parametru, wartość identyfikatora klienta jest pusta lub nieprawidłowa. Użyj parametru , error_description aby poznać dokładną przyczynę błędu.
user_not_found	Nazwa użytkownika nie istnieje.
unsupported_challenge_type	Wartość challenge_type parametru redirect nie zawiera typu wyzwania.
invalid_client	Identyfikator klienta, który aplikacja zawiera w żądaniu, dotyczy aplikacji, która nie ma natywnej konfiguracji uwierzytelniania, takiej jak nie jest klientem publicznym lub nie jest włączona na potrzeby uwierzytelniania natywnego. suberror Użyj właściwości , aby poznać dokładną przyczynę błędu.
unauthorized_client	Identyfikator klienta używany w żądaniu ma prawidłowy format identyfikatora klienta, ale nie istnieje w dzierżawie zewnętrznej lub jest niepoprawny.

Jeśli parametr błędu ma wartość invalid_client, Microsoft Entra zawiera właściwość suberror w odpowiedzi. Poniżej przedstawiono możliwe wartości suberror właściwości dla błędu invalid_client :

Wartość błędu podrzędnego	opis
nativeauthapi_disabled	Identyfikator klienta aplikacji, która nie jest włączona na potrzeby uwierzytelniania natywnego.

Krok 2. Wybieranie metody uwierzytelniania

Aby kontynuować przepływ, aplikacja używa tokenu kontynuacji uzyskanego z poprzedniego kroku, aby zażądać Microsoft Entra, aby wybrać jeden z obsługiwanych typów wyzwań dla użytkownika do uwierzytelnienia. Aplikacja wysyła żądanie POST do punktu końcowego /resetpassword/v1.0/challenge . Jeśli to żądanie zakończy się pomyślnie, Microsoft Entra wyśle jednorazowy kod dostępu do adresu e-mail konta użytkownika. Obecnie obsługujemy tylko protokół OTP poczty e-mail.

Oto przykład (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

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

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.
continuation_token	Tak	Tokencontinuation który Microsoft Entra zwrócony w poprzednim żądaniu.
challenge_type	Nie.	Rozdzielona spacjami lista ciągów typu wyzwania autoryzacji obsługiwana przez aplikację, na przykład oob redirect. Lista musi zawsze zawierać redirect typ wyzwania. W przypadku tego żądania wartość powinna zawierać oob redirectwartość .

Odpowiedź na powodzenie

Przykład:

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
} 

Majątek	opis
continuation_token	Tokencontinuation który Microsoft Entra zwraca.
challenge_type	Typ wyzwania wybrany dla użytkownika do uwierzytelnienia.
binding_method	Jedyną prawidłową wartością jest monit. Tego parametru można użyć w przyszłości, aby zaoferować użytkownikowi więcej sposobów wprowadzania jednorazowego kodu dostępu. Wystawione, jeśli challenge_type jest obiektem oob
challenge_channel	Typ kanału, za pośrednictwem którego został wysłany jednorazowy kod dostępu. W tej chwili obsługujemy pocztę e-mail.
challenge_target_label	Zaciemniony adres e-mail, w którym wysłano jednorazowy kod dostępu. Jeśli usługa MFA jest włączona dla użytkownika, wiadomość e-mail zawierająca jednorazowy kod dostępu jest wysyłany do: — adres e-mail używany jako metoda silnego uwierzytelniania, gdy adres e-mail różni się od adresu e-mail konta. — adres e-mail konta, gdy silna metoda uwierzytelniania to SMS.
code_length	Długość jednorazowego kodu dostępu, który Microsoft Entra generuje.

Odpowiedź przekierowania

Jeśli aplikacja kliencka nie obsługuje metody uwierzytelniania lub możliwości, które Microsoft Entra wymagają, wymagany jest rezerwowy przepływ uwierzytelniania oparty na sieci Web. W tym scenariuszu Microsoft Entra informuje aplikację, zwracając redirect w odpowiedzi:

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

{     
   "challenge_type": "redirect" 
} 

Majątek	opis
challenge_type	Microsoft Entra zwraca odpowiedź, która ma typ wyzwania. Wartość tego typu wyzwania to przekierowanie, co umożliwia aplikacji korzystanie z przepływu uwierzytelniania internetowego.

Ta odpowiedź jest uznawana za pomyślną, ale aplikacja jest wymagana do przełączenia się do przepływu uwierzytelniania internetowego. W takim przypadku zalecamy użycie utworzonej i obsługiwanej przez firmę Microsoft biblioteki uwierzytelniania.

Odpowiedź błędna

Przykład:

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

Majątek	opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów i reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu przyczyny błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla Microsoft Entra, które mogą ułatwić diagnozowanie błędów.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnozowaniu błędów.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.

Poniżej przedstawiono możliwe błędy, które można napotkać (możliwe wartości error właściwości):

Wartość błędu	opis
invalid_request	Sprawdzanie poprawności parametru żądania nie powiodło się, na przykład wtedy, gdy challenge_type parametr zawiera nieprawidłowy typ wyzwania lub weryfikacja tokenu kontynuacji nie powiodła się.
expired_token	Token kontynuacji wygasł.
unsupported_challenge_type	Wartość challenge_type parametru redirect nie zawiera typu wyzwania.

Krok 3. Przesyłanie jednorazowego kodu dostępu

Następnie aplikacja wysyła żądanie POST do punktu końcowego /resetpassword/v1.0/continue . W żądaniu aplikacja musi uwzględnić poświadczenia użytkownika wybrane w poprzednim kroku i token kontynuacji wystawiony z punktu końcowego /resetpassword/v1.0/challenge .

Oto przykład żądania (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

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}

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
continuation_token	Tak	Tokencontinuation który Microsoft Entra zwrócony w poprzednim żądaniu.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.
grant_type	Tak	Jedyną prawidłową wartością jest oob.
oob	Tak	Jednorazowy kod dostępu otrzymany przez użytkownika klienta w wiadomości e-mail. Zastąp element {otp_code} jednorazowym kodem dostępu otrzymanym przez użytkownika klienta w wiadomości e-mail. Aby ponownie wysłać jednorazowy kod dostępu, aplikacja musi ponownie wysłać żądanie do punktu końcowego /resetpassword/v1.0/challenge .

Odpowiedź na powodzenie

Przykład:

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

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

Majątek	opis
expires_in	Czas w sekundach przed wygaśnięciem continuation_token . Maksymalna wartość to expires_in600 sekund.
continuation_token	Tokencontinuation który Microsoft Entra zwraca.

Odpowiedź błędna

Przykład:

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

Majątek	opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów i reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu przyczyny błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla Microsoft Entra, które mogą ułatwić diagnozowanie błędów.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnozowaniu błędów.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.
suberror	Ciąg kodu błędu, który może służyć do dalszego klasyfikowania typów błędów.

Poniżej przedstawiono możliwe błędy, które można napotkać (możliwe wartości error właściwości):

Wartość błędu	opis
invalid_request	Sprawdzanie poprawności parametru żądania nie powiodło się, takie jak niepowodzenie weryfikacji tokenuresetowania hasła i protokołu OTP poczty e-mail dla wszystkich użytkowników dzierżawy. Użyj parametru , error_description aby poznać dokładną przyczynę błędu.
invalid_grant	Typ dotacji jest nieznany lub nie jest zgodny z oczekiwaną wartością typu dotacji. suberror Użyj właściwości , aby poznać dokładną przyczynę błędu.
expired_token	Token kontynuacji wygasł.

Jeśli parametr błędu ma wartość invalid_grant, Microsoft Entra zawiera właściwość suberror w odpowiedzi. Poniżej przedstawiono możliwe wartości suberror właściwości błędu invalid_grant :

Wartość błędu podrzędnego	opis
invalid_oob_value	Wartość jednorazowego kodu dostępu jest nieprawidłowa.

Krok 4. Przesyłanie nowego hasła

Aplikacja zbiera nowe hasło od użytkownika, a następnie używa tokenu kontynuacji wystawionego przez /resetpassword/v1.0/continue punkt końcowy do przesłania hasła przez wysłanie żądania POST do punktu końcowego /resetpassword/v1.0/submit .

Oto przykład (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

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}

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
continuation_token	Tak	Tokencontinuation który Microsoft Entra zwrócony w poprzednim żądaniu.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.
new_password	Tak	Nowe hasło użytkownika. Zastąp {new_password} ciąg nowym hasłem użytkownika. Twoim zadaniem jest potwierdzenie, że użytkownik zna hasło, którego chce użyć, podając pole potwierdzenia hasła w interfejsie użytkownika aplikacji. Należy również upewnić się, że użytkownik jest świadomy tego, co stanowi silne hasło zgodnie z zasadami organizacji. Dowiedz się więcej na temat zasad haseł Microsoft Entra.

Odpowiedź na powodzenie

Przykład:

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

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

Majątek	opis
continuation_token	Tokencontinuation który Microsoft Entra zwraca.
poll_interval	Minimalny czas w sekundach oczekiwania aplikacji między żądaniami sondowania w celu sprawdzenia stanu żądania resetowania hasła za pośrednictwem punktu końcowego /resetpassword/v1.0/poll_completion , zobacz krok 5

Odpowiedź błędna

Przykład:

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

Majątek	opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów i reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu przyczyny błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla Microsoft Entra, które mogą ułatwić diagnozowanie błędów.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnozowaniu błędów.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.
suberror	Ciąg kodu błędu, który może służyć do dalszego klasyfikowania typów błędów.

Poniżej przedstawiono możliwe błędy, które można napotkać (możliwe wartości error właściwości):

Wartość błędu	opis
invalid_request	Walidacja parametru żądania nie powiodła się, na przykład weryfikacja tokenu kontynuacji nie powiodła się.
expired_token	Token kontynuacji wygasł.
invalid_grant	Przesłane przyznanie jest nieprawidłowe, na przykład przesłane hasło jest zbyt krótkie. suberror Użyj właściwości , aby poznać dokładną przyczynę błędu.

Jeśli parametr błędu ma wartość invalid_grant, Microsoft Entra zawiera właściwość suberror w odpowiedzi. Poniżej przedstawiono możliwe wartości suberror właściwości:

Wartość błędu podrzędnego	opis
password_too_weak	Hasło jest zbyt słabe, ponieważ nie spełnia wymagań dotyczących złożoności. Dowiedz się więcej na temat zasad haseł Microsoft Entra.
password_too_short	Nowe hasło ma mniej niż 8 znaków. Dowiedz się więcej na temat zasad haseł Microsoft Entra.
password_too_long	Nowe hasło jest dłuższe niż 256 znaków. Dowiedz się więcej na temat zasad haseł Microsoft Entra.
password_recently_used	Nowe hasło nie może być takie samo jak ostatnio używane. Dowiedz się więcej na temat zasad haseł Microsoft Entra.
password_banned	Nowe hasło zawiera słowo, frazę lub wzorzec, który jest zabroniony. Dowiedz się więcej na temat zasad haseł Microsoft Entra.
password_is_invalid	Hasło jest nieprawidłowe, na przykład ponieważ używa niedozwolonych znaków. Dowiedz się więcej na temat zasad haseł Microsoft Entra. Ta odpowiedź jest możliwa, jeśli aplikacja przesyła hasło użytkownika.

Krok 5. Sondowanie stanu resetowania hasła

Na koniec, ponieważ aktualizacja konfiguracji użytkownika przy użyciu nowego hasła powoduje pewne opóźnienie, aplikacja może użyć punktu końcowego /resetpassword/v1.0/poll_completion, aby sondować Microsoft Entra stanu resetowania hasła. Minimalny czas w sekundach oczekiwania aplikacji między żądaniami sondowania jest zwracany z punktu końcowego /resetpassword/v1.0/submit w parametrze poll_interval .

Oto przykład (przedstawiamy przykładowe żądanie w wielu wierszach w celu zapewnienia czytelności):

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

Parametr	Wymagania	opis
tenant_subdomain	Tak	Poddomena utworzonej dzierżawy zewnętrznej. W adresie URL zastąp ciąg {tenant_subdomain} poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy jest contoso.onmicrosoft.com, użyj nazwy contoso. Jeśli nie masz poddomeny dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.
continuation_token	Tak	Tokencontinuation który Microsoft Entra zwrócony w poprzednim żądaniu.
client_id	Tak	Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym Microsoft Entra.

Odpowiedź na powodzenie

Przykład:

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

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

Majątek	opis
status	Stan żądania resetowania hasła. Jeśli Microsoft Entra zwraca stan failed aplikacja może ponownie przesłać nowe hasło, wysyłając kolejne żądanie do punktu końcowego /resetpassword/v1.0/submit i dołączając nowy token kontynuacji.
continuation_token	Tokencontinuation który Microsoft Entra zwraca. Jeśli stan to succeededed aplikacja może użyć tokenu kontynuacji, który Microsoft Entra powróci do żądania tokenów zabezpieczających za pośrednictwem punktu końcowego oauth2/v2.0/token zgodnie z wyjaśnieniem w Request dla tokenów zabezpieczających. Oznacza to, że po pomyślnym zresetowaniu hasła użytkownik może bezpośrednio zalogować się do aplikacji bez inicjowania nowego przepływu logowania.

Poniżej przedstawiono możliwe stany, które Microsoft Entra zwraca (możliwe wartości parametru status):

Wartość błędu	opis
succeeded	Pomyślnie ukończono resetowanie hasła.
failed	Resetowanie hasła nie powiodło się. Aplikacja może ponownie przesłać nowe hasło, wysyłając kolejne żądanie do punktu końcowego /resetpassword/v1.0/submit .
not_started	Resetowanie hasła nie zostało uruchomione. Aplikacja może ponownie sprawdzić stan później.
in_progress	Trwa resetowanie hasła. Aplikacja może ponownie sprawdzić stan później.

Odpowiedź błędna

Przykład:

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

Majątek	opis
error	Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów i reagowania na błędy.
error_description	Określony komunikat o błędzie, który może pomóc w zidentyfikowaniu przyczyny błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla Microsoft Entra, które mogą ułatwić diagnozowanie błędów.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnozowaniu błędów.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.

Poniżej przedstawiono możliwe błędy, które można napotkać (możliwe wartości error właściwości):

Wartość błędu	opis
invalid_request	Weryfikacja parametru żądania nie powiodła się, na przykład weryfikacja tokenu kontynuacji nie powiodła się.
expired_token	Token kontynuacji wygasł.

Automatyczne logowanie po zresetowaniu hasła

Jeśli użytkownik musi zalogować się po pomyślnym zresetowaniu hasła. Aplikacja musi wywołać /oauth2/v2.0/token punkt końcowy. Dowiedz się , jak wywołać punkt końcowy tokenu.

Powiązana zawartość

• Konfigurowanie niestandardowego dostawcy roszczeń.