Dokumentacja interfejsu API uwierzytelniania natywnego
Dotyczy:
Dzierżawcy siły roboczej — dzierżawcy zewnętrzni 
(dowiedz się więcej)
Natywne uwierzytelnianie firmy Microsoft Entra 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. Aby uzyskać więcej informacji na temat korzystania z zestawu SDK, zobacz Samouczek: przygotowywanie aplikacji mobilnej systemu Android do uwierzytelniania natywnego i Samouczek: przygotowywanie aplikacji mobilnej dla systemu iOS/macOS na potrzeby 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 firmy Microsoft Entra obsługuje rejestrację i logowanie na potrzeby dwóch metod 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).
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
Dzierżawa zewnętrzna firmy Microsoft Entra. Jeśli jeszcze go nie masz, utwórz dzierżawę zewnętrzną.
Jeśli jeszcze tego nie zrobiono, zarejestruj aplikację w centrum administracyjnym firmy Microsoft Entra. Upewnij się, że udzielono delegowanych uprawnień i włączysz przepływy uwierzytelniania publicznego i natywnego klienta.
Jeśli jeszcze tego nie zrobiono, utwórz przepływ użytkownika w centrum administracyjnym firmy Microsoft Entra. Podczas tworzenia przepływu użytkownika zanotuj atrybuty użytkownika skonfigurowane zgodnie z wymaganiami, ponieważ te atrybuty są tymi, które firma Microsoft Entra oczekuje, że aplikacja zostanie przesłana.
Skojarz rejestrację aplikacji z przepływem użytkownika.
W przypadku przepływu logowania zarejestruj użytkownika klienta, którego używasz do testowania interfejsów API logowania. Alternatywnie możesz uzyskać tego użytkownika testowego po uruchomieniu przepływu rejestracji.
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ł.
Token kontynuacji
Za każdym razem, gdy wywołujesz punkt końcowy w dowolnych przepływach, logowaniu, rejestracji lub samoobsługowym resetowaniu hasła, punkt końcowy zawiera token kontynuacji w odpowiedzi. Token kontynuacji jest unikatowym identyfikatorem używanym przez firmę Microsoft Entra ID do zachowania stanu między wywołaniami do różnych punktów końcowych w ramach tego samego przepływu. Ten token należy uwzględnić w kolejnych żądaniach w tym samym przepływie.
Każdy token kontynuacji jest ważny przez określony okres i może być używany tylko dla kolejnych żądań w ramach tego samego przepływu.
Dokumentacja interfejsu API tworzenia konta
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.
Punkty końcowe interfejsu API tworzenia konta
| 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 firmę Microsoft Entra. |
/signup/v1.0/challenge |
Aplikacja wywołuje ten punkt końcowy z listą typów wyzwań obsługiwanych przez firmę Microsoft Entra. Firma Microsoft Entra 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 firmę Microsoft Entra. |
/token |
Aplikacja wywołuje ten punkt końcowy, aby w końcu zażądać tokenów zabezpieczających. Aplikacja musi dołączyć token kontynuacji uzyskany z ostatniego pomyślnego wywołania do punktu końcowego /signup/v1.0/continue . |
Typy wyzwań rejestracji
Interfejs API umożliwia aplikacji klienckiej anonsowanie obsługiwanych przez nią metod uwierzytelniania, gdy wykonuje wywołanie do firmy 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óre należy zastosować w przypadku 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 (wiadomość e-mail), hasło (w przypadku poczty e-mail z metodami 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 za pośrednictwem punktu końcowego /signup/v1.0/start . W takim przypadku aplikacja nie musi wykonywać wywołań i obsługiwać odpowiedzi dla opcjonalnych kroków.
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 firmy 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 redirect oob 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 o zasadach haseł firmy 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 firmy 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. Firma Microsoft Entra ignoruje wszystkie przesyłane atrybuty, które nie istnieją. |
Odpowiedź na powodzenie
Oto przykład pomyślnej odpowiedzi:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAA…",
}
| Parametr | Opis |
|---|---|
continuation_token |
Token kontynuacji zwracany przez firmę Microsoft Entra. |
Jeśli aplikacja nie może obsługiwać wymaganej metody uwierzytelniania przez firmę Microsoft Entra, wymagany jest powrót do przepływu uwierzytelniania opartego na sieci Web. W tym scenariuszu firma Microsoft Entra informuje aplikację, zwracając typ wyzwania przekierowania w odpowiedzi:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parametr | Opis |
|---|---|
challenge_type |
Firma 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"
}
| Parametr | 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 firmy Microsoft, które mogą pomóc w diagnozowaniu 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ść parametru 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 parametru error ):
| 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. Użyj parametru , suberror 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. Użyj parametru , suberror 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, firma Microsoft Entra zawiera suberror parametr w odpowiedzi. Poniżej przedstawiono możliwe wartości parametru suberror dla 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 o zasadach haseł firmy 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 o zasadach haseł firmy 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 o zasadach haseł firmy 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 o zasadach haseł firmy 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 o zasadach haseł firmy 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 o zasadach haseł firmy 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, firma Microsoft Entra zawiera suberror parametr w odpowiedzi. Poniżej przedstawiono możliwe wartości parametru suberror 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 . Firma Microsoft Entra nie żąda jawnie atrybutów opcjonalnych, 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 od firmy Microsoft Entra wybrania jednego 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 firmy 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 | Token kontynuacji zwrócony przez firmę Microsoft Entra w poprzednim żądaniu. |
Odpowiedź na powodzenie
Firma 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
}
| Parametr | Opis |
|---|---|
interval |
Czas w sekundach, przez który aplikacja musi czekać, zanim podejmie próbę ponownego uruchomienia protokołu OTP. |
continuation_token |
Token kontynuacji zwracany przez firmę Microsoft Entra. |
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 generowanego przez firmę Microsoft Entra. |
Jeśli aplikacja nie może obsługiwać wymaganej metody uwierzytelniania przez firmę Microsoft Entra, wymagany jest powrót do przepływu uwierzytelniania opartego na sieci Web. W tym scenariuszu firma Microsoft Entra informuje aplikację, zwracając typ wyzwania przekierowania w odpowiedzi:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parametr | Opis |
|---|---|
challenge_type |
Firma 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"
}
| Parametr | 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 firmy Microsoft, które mogą pomóc w diagnozowaniu 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 parametru error ):
| 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 na potrzeby 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 | Token kontynuacji zwrócony przez firmę Microsoft Entra w poprzednim żądaniu. |
client_id |
Tak | Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym firmy 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 (dla poczty e-mail z metodą uwierzytelniania haseł) za pośrednictwem /signup/v1.0/start punktu końcowego, a żadne atrybuty nie są skonfigurowane w centrum administracyjnym firmy Microsoft Entra lub wszystkie wymagane atrybuty użytkownika są przesyłane za pośrednictwem punktu końcowego /signup/v1.0/start . |
Firma Microsoft Entra wystawia token kontynuacji. Aplikacja może użyć tokenu kontynuacji, aby zażądać tokenów zabezpieczających, jak pokazano w kroku 5. |
Aplikacja pomyślnie przesyła hasło użytkownika (na potrzeby poczty e-mail z metodą uwierzytelniania haseł) za pośrednictwem /signup/v1.0/startmetody , ale nie wszystkie wymagane atrybuty użytkownika, Microsoft Entra wskazuje atrybuty, które aplikacja musi przesłać, jak pokazano w wymaganych atrybutach 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. |
Odpowiedź firmy Microsoft Entra wskazuje, że wymagane jest poświadczenie. Zobacz odpowiedź. Ta odpowiedź jest możliwa w przypadku poczty e-mail z metodą uwierzytelniania haseł. |
Response
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "credential_required",
"error_description": "AADSTS55103: Credential required. Trace ID: d6966055-...-80500 Correlation ID: 3944-...-60d6 Timestamp: yy-mm-dd 02:37:33Z",
"error_codes": [
55103
],
"timestamp": "yy-mm-dd 02:37:33Z",
"trace_id": "d6966055-...-80500",
"correlation_id": "3944-...-60d6",
"continuation_token": "AQABEQEAAAA..."
}
| Parametr | 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 firmy Microsoft, które mogą pomóc w diagnozowaniu 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 |
Token kontynuacji zwracany przez firmę Microsoft Entra. |
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 parametru error ):
| 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, firma Microsoft Entra zawiera suberror parametr w odpowiedzi. Poniżej przedstawiono możliwe wartości parametru suberror dla 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 na potrzeby 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 firmy 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 | Token kontynuacji zwrócony przez firmę Microsoft Entra w poprzednim żądaniu. |
Odpowiedź na powodzenie
Jeśli hasło jest metodą uwierzytelniania skonfigurowaną dla użytkownika w centrum administracyjnym firmy 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..."
}
| Parametr | Opis |
|---|---|
challenge_type |
Hasło jest zwracane w odpowiedzi dla wymaganego poświadczenia. |
continuation_token |
Token kontynuacji zwracany przez firmę Microsoft Entra. |
Jeśli aplikacja nie może obsługiwać wymaganej metody uwierzytelniania przez firmę Microsoft Entra, wymagany jest powrót do przepływu uwierzytelniania opartego na sieci Web. W tym scenariuszu firma Microsoft Entra informuje aplikację, zwracając typ wyzwania przekierowania w odpowiedzi:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parametr | Opis |
|---|---|
challenge_type |
Firma 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órego firma Microsoft zażądała 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 na potrzeby 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 | Token kontynuacji zwrócony przez firmę Microsoft Entra w poprzednim kroku. |
client_id |
Tak | Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym firmy 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 o zasadach haseł firmy Microsoft Entra. |
Odpowiedź na powodzenie
Jeśli żądanie zakończy się pomyślnie, ale żadne atrybuty nie zostały skonfigurowane w centrum administracyjnym firmy 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 kroku 5. W przeciwnym razie odpowiedź firmy Microsoft Entra wskazuje, że aplikacja musi przesłać wymagane atrybuty. Te atrybuty, wbudowane lub niestandardowe, zostały skonfigurowane w centrum administracyjnym firmy Microsoft Entra przez administratora dzierżawy.
Wymagane atrybuty użytkownika
Ta odpowiedź żąda od aplikacji przesłania wartości nazw, *wieku i atrybutów 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 rozszerzeń to 2588a-bcdwh-tfeehj-jeeqw-ertc i nazwa atrybutu jest hobby, atrybut niestandardowy ma nazwę asextension_2588abcdwhtfeehjjeeqwertc_hobbies. Dowiedz się więcej o atrybutach niestandardowych i aplikacji rozszerzenia.
| Parametr | Opis |
|---|---|
error |
Ten atrybut jest ustawiany, jeśli firma Microsoft Entra nie może 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 firmy Microsoft, które mogą pomóc w diagnozowaniu 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 |
Token kontynuacji zwracany przez firmę Microsoft Entra. |
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. Firma 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 parametru error ):
| 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. |
Jeśli aplikacja nie może obsługiwać wymaganej metody uwierzytelniania przez firmę Microsoft Entra, wymagany jest powrót do przepływu uwierzytelniania opartego na sieci Web. W tym scenariuszu firma Microsoft Entra informuje aplikację, zwracając typ wyzwania przekierowania w odpowiedzi:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parametr | Opis |
|---|---|
challenge_type |
Firma 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"
}
| Parametr | 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 firmy Microsoft, które mogą pomóc w diagnozowaniu 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 parametru error ):
| 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. Użyj parametru , suberror 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, firma Microsoft Entra zawiera suberror parametr w odpowiedzi. Poniżej przedstawiono możliwe wartości parametru suberror :
| 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 o zasadach haseł firmy Microsoft Entra. |
password_too_short |
Nowe hasło ma mniej niż 8 znaków. Dowiedz się więcej o zasadach haseł firmy Microsoft Entra. |
password_too_long |
Nowe hasło jest dłuższe niż 256 znaków. Dowiedz się więcej o zasadach haseł firmy Microsoft Entra. |
password_recently_used |
Nowe hasło nie może być takie samo jak ostatnio używane. Dowiedz się więcej o zasadach haseł firmy Microsoft Entra. |
password_banned |
Nowe hasło zawiera słowo, frazę lub wzorzec, który jest zabroniony. Dowiedz się więcej o zasadach haseł firmy Microsoft Entra. |
password_is_invalid |
Hasło jest nieprawidłowe, na przykład ponieważ używa niedozwolonych znaków. Dowiedz się więcej o zasadach haseł firmy 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 na potrzeby 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}", "postaCode": "{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 | Token kontynuacji zwrócony przez firmę Microsoft Entra w poprzednim żądaniu. |
client_id |
Tak | Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym firmy 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 firmy 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. Firma Microsoft Entra ignoruje wszystkie przesyłane atrybuty, które nie istnieją. |
Odpowiedź na powodzenie
Jeśli żądanie zakończy się pomyślnie, firma Microsoft Entra wystawia token kontynuacji, którego aplikacja może użyć do żądania tokenów zabezpieczających.
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAAYn..."
}
| Parametr | Opis |
|---|---|
continuation_token |
Token kontynuacji zwracany przez firmę Microsoft Entra. |
Jeśli aplikacja nie może obsługiwać wymaganej metody uwierzytelniania przez firmę Microsoft Entra, wymagany jest powrót do przepływu uwierzytelniania opartego na sieci Web. W tym scenariuszu firma Microsoft Entra informuje aplikację, zwracając typ wyzwania przekierowania w odpowiedzi:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parametr | Opis |
|---|---|
challenge_type |
Firma 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"
}
| Parametr | 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 firmy Microsoft, które mogą pomóc w diagnozowaniu 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 |
Token kontynuacji zwracany przez firmę Microsoft Entra. |
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ć. Firma Microsoft Entra uwzględnia ten parametr w odpowiedzi, gdy error wartość parametru 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ść parametru 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 parametru error ):
| 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ę. Użyj parametru , suberror 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, firma Microsoft Entra zawiera suberror parametr w odpowiedzi. Poniżej przedstawiono możliwe wartości parametru suberror dla 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. Żądanie tokenów zabezpieczających
Aplikacja wysyła żądanie POST do punktu końcowego /token i udostępnia token kontynuacji uzyskany z poprzedniego 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=ABAAEAAAAtyo...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&username=contoso-consumer@contoso.com
&scope={scopes}
&grant_type=continuation_token
| 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 firmy Microsoft Entra. |
grant_type |
Tak | Wartość parametru musi być tokenem kontynuacji. |
continuation_token |
Tak | Token kontynuacji zwrócony przez firmę Microsoft Entra w poprzednim kroku. |
scope |
Tak | Rozdzielona spacjami lista zakresów, dla których token dostępu jest prawidłowy. Zastąp {scopes} ciąg prawidłowymi zakresami, dla których zwraca token dostępu Microsoft Entra. |
username |
Tak | Adres e-mail użytkownika klienta, którego chcesz zarejestrować, na przykład contoso-consumer@contoso.com. |
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..."
}
| Parametr | Opis |
|---|---|
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. |
token_type |
Wskazuje wartość typu tokenu. Jedynym typem, który obsługuje firma Microsoft Entra, jest Bearer. |
expires_in |
Czas w sekundach, przez który token dostępu pozostaje prawidłowy. |
scopes |
Rozdzielona spacjami lista zakresów, dla których token dostępu jest prawidłowy. |
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, zapoznaj się z artykułem Odświeżanie tokenu dostępu. Uwaga: wystawiono tylko wtedy, gdy zażądano zakresu offline_access . |
id_token |
Token internetowy JSON (Jwt) używany do identyfikowania użytkownika klienta. Aplikacja może dekodować token, aby odczytać informacje 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. Uwaga: jest wystawiany tylko wtedy, gdy zażądano zakresu openid . |
Odpowiedź błędna
Przykład:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The client doesn't have consent for the requested scopes.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parametr | 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 firmy Microsoft, które mogą pomóc w diagnozowaniu 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 parametru error ):
| Wartość błędu | opis |
|---|---|
invalid_request |
Weryfikacja parametru żądania nie powiodła się, na przykład klient/aplikacja, nie ma zgody dla żądanych zakresów. |
invalid_grant |
Token kontynuacji 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. |
Przesyłanie atrybutów użytkownika do punktów końcowych
W centrum administracyjnym firmy Microsoft Entra można skonfigurować atrybuty użytkownika zgodnie z wymaganiami lub opcjonalnie. Ta konfiguracja określa, jak firma Microsoft Entra reaguje 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 punktów końcowych firmy Microsoft Entra.
| 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 firmy 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 firmy Microsoft Entra.
| Typ danych wejściowych użytkownika | Format przesłanych wartości |
|---|---|
| TextBox | 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 firmy Microsoft Entra różnią się od sposobu odwoływania się do nich w natywnym interfejsie API uwierzytelniania.
Na przykład nazwa wyświetlana w centrum administracyjnym firmy Microsoft Entra jest przywoływana 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.
Dokumentacja interfejsu API logowania
Użytkownicy muszą zalogować się przy użyciu metody uwierzytelniania, której używają. 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, /initiatei /challenge /token.
Punkty końcowe interfejsu API logowania
| Punkt końcowy | opis |
|---|---|
/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 firmę Microsoft Entra, ta odpowiedź punktu końcowego może wskazywać na twoją aplikację, że musi korzystać z przepływu uwierzytelniania opartego na przeglądarce. |
/challenge |
Aplikacja wywołuje ten punkt końcowy z listą typów wyzwań obsługiwanych przez usługę tożsamości. Nasza usługa tożsamości generuje, a następnie wysyła jednorazowy kod dostępu do wybranego kanału wyzwania, takiego jak wiadomość e-mail. Jeśli aplikacja wielokrotnie wywołuje ten punkt końcowy, za każdym razem, gdy zostanie wykonane wywołanie, zostanie wysłana nowa funkcja OTP. |
/token |
Ten punkt końcowy weryfikuje jednorazowy kod dostępu odbierany z aplikacji, a następnie wystawia tokeny zabezpieczające do aplikacji. |
Typy wyzwań logowania
Interfejs API umożliwia aplikacji anonsowanie obsługiwanych przez nią metod uwierzytelniania, gdy wykonuje wywołanie do firmy 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, które aplikacja wysyła do firmy Microsoft 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.
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. Firma Microsoft Entra ponownie przesyła kolejny jednorazowy kod dostępu, jeśli poprzedni kod dostępu nie został zweryfikowany. Gdy firma Microsoft Entra ponownie wysyła jednorazowy kod dostępu, unieważnia wcześniej wysłany kod.
W poniższych sekcjach podsumujemy przepływ diagramu sekwencji 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 na potrzeby 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
| 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 firmy 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. |
Odpowiedź na powodzenie
Oto przykład pomyślnej odpowiedzi:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| Parametr | Opis |
|---|---|
continuation_token |
Token kontynuacji zwracany przez firmę Microsoft Entra. |
Jeśli aplikacja nie może obsługiwać wymaganej metody uwierzytelniania przez firmę Microsoft Entra, wymagany jest powrót do przepływu uwierzytelniania opartego na sieci Web. W tym scenariuszu firma Microsoft Entra informuje aplikację, zwracając typ wyzwania przekierowania w odpowiedzi:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parametr | Opis |
|---|---|
challenge_type |
Firma 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"
}
| Parametr | 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 firmy Microsoft, które mogą pomóc w diagnozowaniu 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 parametru error ):
| 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. Użyj parametru , suberror 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, firma Microsoft Entra zawiera suberror parametr w odpowiedzi. Poniżej przedstawiono możliwe wartości parametru suberror 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 poprosić firmę Microsoft Entra o wybranie jednego z obsługiwanych typów wyzwań dla użytkownika do uwierzytelnienia. Aplikacja wysyła żądanie POST do punktu końcowego /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 firmy Microsoft Entra. |
continuation_token |
Tak | Token kontynuacji zwrócony przez firmę Microsoft Entra w poprzednim żądaniu. |
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. |
Odpowiedź na powodzenie
Jeśli administrator dzierżawy skonfigurował jednorazowy kod dostępu e-mail w centrum administracyjnym firmy Microsoft Entra jako metodę uwierzytelniania użytkownika, firma Microsoft Entra wysyła jednorazowy kod dostępu do poczty e-mail użytkownika, a następnie odpowiada za pomocą typu zadania oob i udostępnia więcej informacji o jednorazowym kodzie 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
}
| Parametr | Opis |
|---|---|
continuation_token |
Token kontynuacji zwracany przez firmę Microsoft Entra. |
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 generowanego przez firmę Microsoft Entra. |
Jeśli aplikacja nie może obsługiwać wymaganej metody uwierzytelniania przez firmę Microsoft Entra, wymagany jest powrót do przepływu uwierzytelniania opartego na sieci Web. W tym scenariuszu firma Microsoft Entra informuje aplikację, zwracając typ wyzwania przekierowania w odpowiedzi:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parametr | Opis |
|---|---|
challenge_type |
Firma 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"
}
| Parametr | 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 firmy Microsoft, które mogą pomóc w diagnozowaniu 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 parametru error ):
| 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 /token i udostępnia poświadczenia użytkownika wybrane w poprzednim kroku, w tym przypadku hasło, w celu uzyskania tokenów zabezpieczających.
Oto przykład żądania (przedstawiamy przykładowe żądanie w wielu wierszach na potrzeby 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 firmy Microsoft Entra. |
continuation_token |
Tak | Token kontynuacji zwrócony przez firmę Microsoft Entra w poprzednim żądaniu. |
grant_type |
Tak | Wartość musi być hasłem dla poczty e-mail z metodą uwierzytelniania haseł i obiektem oob dla jednorazowej metody uwierzytelniania kodu dostępu wiadomości e-mail. |
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 firma Microsoft Entra wystawiła token identyfikatora. Aplikacja musi zawierać offline_access zakres dla firmy Microsoft Entra w celu wystawienia tokenu odświeżania. Dowiedz się więcej na temat uprawnień i zgody w Platforma tożsamości Microsoft. |
password |
Tak (w przypadku wiadomości e-mail z hasłem) |
Wartość hasła zbierana przez aplikację od użytkownika klienta. Zastąp {secure_password} wartość hasłem zbieraną przez aplikację od użytkownika klienta. |
oob |
Tak (w przypadku jednorazowego kodu dostępu wiadomości e-mail) |
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 /challenge . |
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..."
}
| Parametr | Opis |
|---|---|
token_type |
Wskazuje wartość typu tokenu. Jedynym typem, który obsługuje firma 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, zapoznaj się z artykułem 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 klienta. 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. 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"
}
| Parametr | 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 firmy Microsoft, które mogą pomóc w diagnozowaniu 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 parametru error ):
| 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 uwzględniony w żądaniu jest nieprawidłowy lub poświadczenia logowania użytkownika klienta zawarte w żądaniu są nieprawidłowe lub typ dotacji 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. |
Jeśli parametr błędu ma wartość invalid_grant, firma Microsoft Entra zawiera suberror parametr w odpowiedzi. Poniżej przedstawiono możliwe wartości parametru suberror dla błędu invalid_grant :
| Wartość błędu podrzędnego | opis |
|---|---|
invalid_oob_value |
Wartość jednorazowego kodu dostępu jest nieprawidłowa. Ten błąd podrzędny dotyczy tylko jednorazowego kodu dostępu poczty e-mail |
Samoobsługowe resetowanie hasła
Jeśli używasz poczty e-mail i hasła jako metody uwierzytelniania w aplikacji, użyj interfejsu API samoobsługowego resetowania hasła (SSPR), aby umożliwić użytkownikom klienta resetowanie hasła. Użyj tego interfejsu API w przypadku scenariuszy zapomnianych haseł lub zmiany hasła.
Samoobsługowe punkty końcowe interfejsu API resetowania haseł
Aby użyć tego interfejsu API, aplikacja współdziała z punktem końcowym pokazanym w poniższej tabeli:
| Punkt końcowy | opis |
|---|---|
/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 firmę Microsoft Entra, ta odpowiedź punktu końcowego może wskazywać na twoją aplikację, że musi korzystać z przepływu uwierzytelniania opartego na przeglądarce. |
/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 firmę Microsoft Entra, ta odpowiedź punktu końcowego może wskazywać na twoją aplikację, że musi korzystać z przepływu uwierzytelniania opartego na przeglądarce. |
/continue |
Weryfikuje wyzwanie wystawione przez /challenge punkt końcowy, a następnie zwraca token kontynuacji dla /submit punktu końcowego lub wystawia inne wyzwanie użytkownikowi. |
/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. |
/poll_completion |
Na koniec aplikacja może użyć tokenu kontynuacji wystawionego /submit przez punkt końcowy, aby sprawdzić stan żądania resetowania hasła. |
Typy wyzwań dotyczących samoobsługowego resetowania hasła
Interfejs API umożliwia aplikacji anonsowanie obsługiwanych przez nią metod uwierzytelniania, gdy wykonuje wywołanie do firmy 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 /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 /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 firmy 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ść . |
Odpowiedź na powodzenie
Przykład:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| Parametr | Opis |
|---|---|
continuation_token |
Token kontynuacji zwracany przez firmę Microsoft Entra. |
Jeśli aplikacja nie może obsługiwać wymaganej metody uwierzytelniania przez firmę Microsoft Entra, wymagany jest powrót do przepływu uwierzytelniania opartego na sieci Web. W tym scenariuszu firma Microsoft Entra informuje aplikację, zwracając typ wyzwania przekierowania w odpowiedzi:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parametr | Opis |
|---|---|
challenge_type |
Firma 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"
}
| Parametr | 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 firmy Microsoft, które mogą pomóc w diagnozowaniu 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 parametru error ):
| 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. Użyj parametru , suberror 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, firma Microsoft Entra zawiera suberror parametr w odpowiedzi. Poniżej przedstawiono możliwe wartości parametru suberror 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 poprosić firmę Microsoft Entra o wybranie jednego z obsługiwanych typów wyzwań dla użytkownika do uwierzytelnienia. Aplikacja wysyła żądanie POST do punktu końcowego /challenge . Jeśli to żądanie zakończy się pomyślnie, firma 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=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 firmy Microsoft Entra. |
continuation_token |
Tak | Token kontynuacji zwrócony przez firmę Microsoft Entra 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
}
| Parametr | Opis |
|---|---|
continuation_token |
Token kontynuacji zwracany przez firmę Microsoft Entra. |
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 generowanego przez firmę Microsoft Entra. |
Jeśli aplikacja nie może obsługiwać wymaganej metody uwierzytelniania przez firmę Microsoft Entra, wymagany jest powrót do przepływu uwierzytelniania opartego na sieci Web. W tym scenariuszu firma Microsoft Entra informuje aplikację, zwracając typ wyzwania przekierowania w odpowiedzi:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Parametr | Opis |
|---|---|
challenge_type |
Firma 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"
}
| Parametr | 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 firmy Microsoft, które mogą pomóc w diagnozowaniu 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 parametru error ):
| 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 /continue . W żądaniu aplikacja musi uwzględnić poświadczenia użytkownika wybrane w poprzednim kroku i token kontynuacji wystawiony z punktu końcowego /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 | Token kontynuacji zwrócony przez firmę Microsoft Entra w poprzednim żądaniu. |
client_id |
Tak | Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym firmy 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 /challenge . |
Odpowiedź na powodzenie
Przykład:
HTTP/1.1 200 OK
Content-Type: application/json
{
"expires_in": 600,
"continuation_token": "czZCaGRSa3F0MzpnW...",
}
| Parametr | Opis |
|---|---|
expires_in |
Czas w sekundach przed wygaśnięciem continuation_token . Maksymalna wartość to expires_in 600 sekund. |
continuation_token |
Token kontynuacji zwracany przez firmę Microsoft Entra. |
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"
}
| Parametr | 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 firmy Microsoft, które mogą pomóc w diagnozowaniu 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 parametru error ):
| Wartość błędu | opis |
|---|---|
invalid_request |
Sprawdzanie poprawności parametru żądania nie powiodło się, takie jak niepowodzenie weryfikacji 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ł samoobsługowego resetowania 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. Użyj parametru , suberror aby poznać dokładną przyczynę błędu. |
expired_token |
Token kontynuacji wygasł. |
Jeśli parametr błędu ma wartość invalid_grant, firma Microsoft Entra zawiera suberror parametr w odpowiedzi. Poniżej przedstawiono możliwe wartości parametru suberror dla błędu invalid_grant :
| Wartość błędu podrzędnego | opis |
|---|---|
invalid_oob_value |
Jednorazowy kod dostępu dostarczony przez użytkownika jest nieprawidłowy. |
Krok 4. Przesyłanie nowego hasła
Aplikacja zbiera nowe hasło od użytkownika, a następnie używa tokenu kontynuacji wystawionego przez /continue punkt końcowy do przesłania hasła przez wysłanie żądania POST do punktu końcowego /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 | Token kontynuacji zwrócony przez firmę Microsoft Entra w poprzednim żądaniu. |
client_id |
Tak | Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym firmy 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 o zasadach haseł firmy Microsoft Entra. |
Odpowiedź na powodzenie
Przykład:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"poll_interval": 2
}
| Parametr | Opis |
|---|---|
continuation_token |
Token kontynuacji zwracany przez firmę Microsoft Entra. |
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 /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"
}
| Parametr | 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 firmy Microsoft, które mogą pomóc w diagnozowaniu 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 parametru error ):
| 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. Użyj parametru , suberror aby poznać dokładną przyczynę błędu. |
Jeśli parametr błędu ma wartość invalid_grant, firma Microsoft Entra zawiera suberror parametr w odpowiedzi. Poniżej przedstawiono możliwe wartości parametru suberror :
| 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 o zasadach haseł firmy Microsoft Entra. |
password_too_short |
Nowe hasło ma mniej niż 8 znaków. Dowiedz się więcej o zasadach haseł firmy Microsoft Entra. |
password_too_long |
Nowe hasło jest dłuższe niż 256 znaków. Dowiedz się więcej o zasadach haseł firmy Microsoft Entra. |
password_recently_used |
Nowe hasło nie może być takie samo jak ostatnio używane. Dowiedz się więcej o zasadach haseł firmy Microsoft Entra. |
password_banned |
Nowe hasło zawiera słowo, frazę lub wzorzec, który jest zabroniony. Dowiedz się więcej o zasadach haseł firmy Microsoft Entra. |
password_is_invalid |
Hasło jest nieprawidłowe, na przykład ponieważ używa niedozwolonych znaków. Dowiedz się więcej o zasadach haseł firmy 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ć /poll_completion punktu końcowego do sondowania stanu resetowania hasła przez firmę Microsoft Entra. Minimalny czas w sekundach oczekiwania aplikacji między żądaniami sondowania jest zwracany z punktu końcowego /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 | Token kontynuacji zwrócony przez firmę Microsoft Entra w poprzednim żądaniu. |
client_id |
Tak | Identyfikator aplikacji (klienta) aplikacji zarejestrowanej w centrum administracyjnym firmy Microsoft Entra. |
Odpowiedź na powodzenie
Przykład:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "succeeded",
"continuation_token":"czZCaGRSa3F0..."
}
| Parametr | Opis |
|---|---|
status |
Stan żądania resetowania hasła. Jeśli firma Microsoft Entra zwróci stan niepowodzenia, aplikacja może ponownie przesłać nowe hasło, wysyłając kolejne żądanie do /submit punktu końcowego i dołączając nowy token kontynuacji. |
continuation_token |
Token kontynuacji zwracany przez firmę Microsoft Entra. Jeśli stan zakończył się pomyślnie, aplikacja może użyć tokenu kontynuacji, który firma Microsoft Entra zwraca do żądania tokenów zabezpieczających za pośrednictwem punktu końcowego, zgodnie z opisem /token w kroku 5 przepływu rejestracji. 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 zwracane przez firmę Microsoft Entra (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 /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"
}
| Parametr | 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 firmy Microsoft, które mogą pomóc w diagnozowaniu 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 parametru error ):
| 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ł. |
Powiązana zawartość
- Skonfiguruj niestandardowego dostawcę oświadczeń.