Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Dotyczy:
Dzierżawy zewnętrzne (dowiedz się więcej)
Metoda uwierzytelniania: Osadzone uwierzytelnianie natywne.
Interfejs API uwierzytelniania natywnego używa przepływu opartego na odpowiedzi w Tożsamość zewnętrzna Microsoft Entra dzierżawach zewnętrznych. Rozpocznij autoryzację, ukończ zwrócone interakcje uwierzytelniania, wznów autoryzację i wymień kod autoryzacji dla tokenów. To odwołanie definiuje operacje udostępnione; odwołania specyficzne dla podróży definiują odnajdywanie logowania, atrybuty rejestracji i resetowanie hasła.
W przypadku istniejącej integracji w wersji 1 użyj dokumentacji interfejsu API w wersji 1. Zobacz Migrowanie z wersji 1 do wersji 2 , aby uzyskać informacje o wersjach pakietów, wymaganiach migracji i szczegółach integracji zestawu SDK.
Prerequisites
Important
Interfejs API uwierzytelniania natywnego w wersji 2 jest w wersji zapoznawczej. Interfejs API uwierzytelniania natywnego w wersji 1 pozostaje ogólnie dostępny. Zapoznaj się z dodatkowymi warunkami użytkowania dotyczącymi wersji zapoznawczej Microsoft Azure, aby uzyskać postanowienia prawne dotyczące funkcji w wersji zapoznawczej.
- Dzierżawa zewnętrzna i aplikacja skonfigurowana dla klientów publicznych i przepływów uwierzytelniania natywnego. Zobacz Konfigurowanie aplikacji.
- Przepływ użytkownika skojarzony z aplikacją.
- W przypadku aplikacji opartych na przeglądarce, takich jak spA, domena niestandardowego adresu URL zweryfikowana przez dzierżawę skonfigurowana na potrzeby wywołań interfejsu API usługi.
- Delegowane uprawnienia i zgoda wymagane przez zasób docelowy, jeśli zażądasz dostępu do interfejsu API.
- W przypadku umów SPA z osadzonym uwierzytelnianiem natywnym i witrynami internetowymi środowiska użytkownika BYO zasady serwera proxy lub brzegu, które implementują wymagania serwera proxy przeglądarki.
Operacje i urząd
W przykładach użyto elementu https://{custom_domain}/{tenant}, gdzie custom_domain jest domeną uwierzytelniania zweryfikowanego przez dzierżawę, taką jak login.contoso.com, i tenant jest identyfikatorem katalogu (dzierżawy), identyfikatorem GUID.
client_id to identyfikator aplikacji (klienta). W tych przykładach wszystkie adresy URL wywołań interfejsu API usługi używają tej domeny niestandardowej, w tym wyzwań związanych z autoryzacją i wymiany tokenów.
Interfejs API uwierzytelniania natywnego w wersji 2 wymaga domeny niestandardowej zweryfikowanej przez dzierżawę dla aplikacji opartych na przeglądarce, takich jak spA, aby chronić przed fałszerstwa żądaniami między witrynami (CSRF). Klienci bez przeglądarki, tacy jak aplikacje dla systemów iOS i Android korzystające z natywnych transportów HTTP, nie wymagają domeny niestandardowej. Przeglądarka osadzona lub widok internetowy nie jest natywnym transportem HTTP. Interfejs użytkownika BYO pozostaje oparty na przeglądarce i wymaga domeny niestandardowej zweryfikowanej przez dzierżawę. Zobacz Konfigurowanie urzędu interfejsu API.
Z wyjątkiem początkowego żądania autoryzacji i wymiany tokenów, użyj adresu URL anonsowanego przez bieżącą odpowiedź. Identyfikatory metod są nieprzezroczyste. Rozwiąż względne łącza względem skonfigurowanego źródła urzędu, zweryfikuj lokalizację docelową i zachowaj zwróconą ścieżkę i kwerendę bez zmian.
Poniżej opisano uruchamianie, wznawianie autoryzacji i wymianę kodu osadzonego uwierzytelniania natywnego. Zamiast tego strona środowiska użytkownika BYO używa swojego przekazywania przeglądarki i zwracanego linku zakończenia wokół udostępnionych natywnych operacji interakcji. Nie uruchamiaj ani nie wznawiaj /authorize-challenge w ramach tej transakcji środowiska użytkownika BYO.
| Operation | Metoda | Ścieżka lub link |
|---|---|---|
| Rozpocznij autoryzację | POST |
/{tenant}/oauth2/v2.0/authorize-challenge |
| Wznawianie autoryzacji | POST |
Zwrócony continue link. |
| Rozpoczynanie logowania | POST |
Zwrócony sign_in link; przykłady używają elementu /{tenant}/api/v2.0/signin/start. |
| Rozpoczynanie rejestracji | POST |
Zwrócony sign_up link; przykłady używają elementu /{tenant}/api/v2.0/signup/start. |
| Przesyłanie atrybutów rejestracji | POST |
Zwrócony submitAttributes link. |
| Uruchom resetowanie hasła | POST |
Zwrócony link reset-password; przykłady używają polecenia /{tenant}/api/v2.0/resetpassword/start. |
| Rozpoczynanie wbudowanego resetowania hasła | POST |
Zwrócony recover link metody hasła. |
| Rejestrowanie metody uwierzytelniania | POST |
Zwrócony enroll link wybranej metody. |
| Aktywowanie metody uwierzytelniania | POST |
Zwrócony activate link. |
| Wyzwanie lub ponowne wysłanie | POST |
Zwrócony challenge lub resend link. |
| Weryfikowanie poświadczeń | POST |
Zwrócony verify link. |
| Aktualizowanie hasła | PUT |
Zwrócony update link. |
| Aktualizacja hasła sondowania | POST |
Zwrócony poll link. |
| Exchange kod autoryzacji | POST |
/{tenant}/oauth2/v2.0/token |
Przykłady natywne używają ; /api/v2.0 Operacje OAuth używają polecenia /oauth2/v2.0. Użyj identyfikatora GUID dzierżawy w tych przykładach urzędu. Postępuj zgodnie z zwracanych linków bez ponownego zapisywania ich ścieżek, wersji lub parametrów zapytania.
Nagłówki
Operacje uwierzytelniania OAuth i natywnego uwierzytelniania używają różnych kodowań treści.
| Header | Używanie |
|---|---|
Content-Type: application/x-www-form-urlencoded |
Wymagane do żądania autoryzacji i tokenu. |
Content-Type: application/json |
Wymagane dla natywnych jednostek żądań uwierzytelniania. |
Accept: application/hal+json |
Zalecane w przypadku natywnych żądań uwierzytelniania. |
client-request-id: {guid} |
Zalecane. Wygeneruj nową wartość dla każdego przepływu i zachowaj ją do diagnostyki. |
Wymagania dotyczące serwera proxy przeglądarki
Te wymagania dotyczą wywołań interfejsu API przeglądarki z umów SPA z osadzonym uwierzytelnianiem natywnym i witrynami internetowymi środowiska użytkownika BYO. Aplikacje dla systemów Android i iOS korzystające z natywnych transportów HTTP nie wymagają konfiguracji mechanizmu CORS ani serwera proxy CORS.
Trasy uwierzytelniania natywnego obsługują metodę OPTIONS, ale nie udzielają dostępu do źródła przeglądarki za pośrednictwem usługi Access-Control-Allow-Origin. W związku z tym integracja przeglądarki między źródłami wymaga konfiguracji serwera proxy lub krawędzi, która:
- Przekazuje pomyślną odpowiedź wstępną usługi i stosuje skonfigurowane zasady źródła przeglądarki.
- Zwraca
Access-Control-Allow-Originwartość dla tego dokładnego dozwolonego źródła, a nie*. - Umożliwia wymaganą
POSToperację lubPUTmetodę oraz nagłówki żądań używane przez integrację. - Zachowuje treść żądań, kody stanu odpowiedzi, typy zawartości i linki transakcji bez buforowania odpowiedzi uwierzytelniania.
- Obsługuje pochodzenie i routing spójnie między autoryzacją, operacjami natywnymi i wymianą tokenów.
- Zachowuje wskazówki dotyczące ponawiania prób, w tym
Retry-After, i uwidacznia je w kodzie przeglądarki w razie potrzeby.
Zobacz Pojęcia dotyczące mechanizmu CORS uwierzytelniania natywnego dla granicy przeglądarki i konfiguracji lokalnego serwera proxy na potrzeby programowania.
Tokeny kontynuacji
Token kontynuacji reprezentuje transakcję uwierzytelniania na bieżącym etapie. Jest ona powiązana z dzierżawą, klientem, scenariuszem i akcją.
| Format wiadomości | Pole |
|---|---|
| OAuth | continuation_token |
| Interfejs API uwierzytelniania natywnego | continuationToken |
Użyj tylko bieżącego tokenu z operacją zidentyfikowaną przez tę samą odpowiedź. Nie należy analizować, modyfikować, rejestrować ani utrwalać go poza aktywną transakcją. Gdy odpowiedź dostarcza zamiennik, przestań używać wcześniejszego tokenu. Nie przenoś tokenu do innego użytkownika ani podróży. Uruchom ponownie autoryzację po wygaśnięciu.
Udokumentowana domyślna ważność wynosi 10 minut dla pojedynczego tokenu kontynuacji. Obsługa wygaśnięcia zgodnie z odpowiedzią usługi; nowszy token nie jest gwarancją rozszerzenia całej podróży. Token i jednorazowy kod dostępu mają oddzielne okresy istnienia. Kody autoryzacji są krótkotrwałe i jednorazowe; nie interpretuj odpowiedzi expires_in tokenu jako okresu istnienia kodu autoryzacji.
Model odpowiedzi
Pomyślne operacje interakcji natywnych zwracają kod JSON HAL. Kolejna akcja może się różnić nawet w przypadku kolejnych wywołań do tego samego punktu końcowego. Pola są specyficzne dla odpowiedzi: na przykład przekierowanie może zawierać tylko state.
| Członek | Purpose |
|---|---|
continuationToken |
Token dla następnego dozwolonego żądania, jeśli zostanie uwzględniony. |
state |
Bieżący stan transakcji. |
action |
Wymagana interakcja interactionRequired dla odpowiedzi. |
_links |
Adresy URL dozwolonych operacji. |
_embedded |
Powiązane zasoby, w tym dostępne metody. |
Koncepcja przepływu zawiera opis stanów i akcji. W przypadku interactionRequiredprogramu obsłuż zwróconą akcję przy użyciu dozwolonej operacji. W przypadku continueprogramu wznów autoryzację za pośrednictwem zwróconego linku. Stan pojedynczej completed operacji nie potwierdza, że wystawiono tokeny.
Transakcja natywna, która nie może kontynuować, może zwrócić następujące metryki:
{
"state": "redirect"
}
Ta odpowiedź nie dostarcza tokenu kontynuacji, linków ani adresu URL przekazywania przeglądarki. Zatrzymaj żądania natywne i zaoferuj oddzielnie skonfigurowane logowanie przeglądarki lub wyraźny błąd. Logowanie przeglądarki powoduje ponowne uruchomienie uwierzytelniania; nie wznawia postępu natywnego.
Akcja wyboru konta
Note
Wybór konta nie jest istotny w osadzonym uwierzytelnianiu natywnym i nie jest jeszcze obsługiwany dla stron samodzielnie hostowanych przez środowisko użytkownika BYO.
disambiguate identyfikuje wybór konta w obszarze state: interactionRequired.
Relacje linków
Użyj linków z najnowszej odpowiedzi i zweryfikuj swoje uprawnienia przed przekazaniem wpisów tajnych.
| Relacja | Purpose |
|---|---|
self |
Bieżący zasób lub operacja. |
discover |
Prześlij identyfikator logowania. |
challenge |
Uruchom zadanie wybranej metody. |
verify |
Sprawdź hasło lub jednorazowy kod dostępu. |
resend |
Zażądaj innego jednorazowego kodu dostępu. |
submitAttributes |
Prześlij żądane wartości rejestracji. |
recover |
Uruchom odzyskiwanie hasła w ramach aktywnej transakcji logowania. |
enroll |
Rozpocznij rejestrację anonsowanej metody uwierzytelniania. |
activate |
Zweryfikuj kod zarejestrowanej metody. |
update |
Prześlij hasło zastępcze. |
poll |
Sprawdź aktualizację asynchroniczną. |
continue |
Wznów autoryzację OAuth. |
Ta akcja jest odpowiednia dla wyboru konta Bring Your Own UX (BYO UX). Wbudowane integracje uwierzytelniania natywnego nie korzystają z niej, a wybór konta na stronie własnego środowiska użytkownika BYO nie jest obecnie obsługiwany.
Jeśli integracja środowiska użytkownika BYO jest zgodna z zalecanym obejściem przez wysłanie login_hint lub prompt=login wysłanie żądania autoryzacji, wybranie konta nie spowoduje przerwania ani przerwania istniejącego środowiska użytkownika.
Ładunek akcji jest częścią istniejących przekazywania initialResponse przeglądarki BYO UX i obejmuje:
-
state: interactionRequired,action: disambiguatei dlacontinuationTokenoczekującego zaznaczenia. - Tablica
_embedded.userz informacjami o poszczególnych oferowanych kontach i obsługiwanych linkach. Aktywne konto ma adres URL specyficzny dla_links.resumekonta. - Adres URL na poziomie
_links.discoverodpowiedzi dla nieaktywnego konta lub Użyj innego konta.
Zasoby metody uwierzytelniania
Wybór istniejącej metody poświadczeń używa metody _embedded.methods. Usługa może również wybrać jedną metodę. Istniejące poświadczenie ma nieprzezroczysteidtype, takie jak password, emaillub sms, i linki do dozwolonych operacji. Maskowany hint identyfikuje miejsce docelowe bez ujawniania go w całości; isPreferred jest opcjonalnymi metadanymi preferencji. Opcje rejestracji mają oddzielną reprezentację i nie wymagają istniejącego identyfikatora poświadczeń.
{
"_embedded": {
"methods": [
{
"id": "{id}",
"type": "email",
"hint": "u***@contoso.com",
"isPreferred": true,
"_links": {
"challenge": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{id}/challenge"
},
"verify": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{id}/verify"
}
}
}
]
}
}
Ten fragment ilustruje metadane metody. Dostępność metody jest określana dla każdej transakcji. Aplikacja może prezentować dostępne metody lub wybrać jedną za pomocą logiki przepływu aplikacji. Wyzwanie i weryfikacja działają na wybranej metodzie; rejestracja metody ma oddzielny kontrakt.
Nie wymagaj opcjonalnych metadanych prezentacji, takich jak pages lub scenario. W przykładach opisano podstawowe interakcje dotyczące haseł i wiadomości e-mail/SMS, a nie wszystkich dodatkowych wymagań specyficznych dla metody.
Rozpocznij autoryzację
Wyślij aplikację, zakresy i opcjonalne oświadczenia w początkowym żądaniu. Wartości kodowania formularzy; poniższe podziały wierszy służą do czytelności.
POST https://{custom_domain}/{tenant}/oauth2/v2.0/authorize-challenge
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&
scope=openid%20profile%20offline_access&
response_type=code
| Parametr | Używanie |
|---|---|
client_id |
Wymagany identyfikator aplikacji (klienta). |
scope |
Określa zakresy żądań aplikacji. Uwzględnij zakresy openID Connect (OIDC) i zasoby wymagane dla wynikowych tokenów. |
response_type |
code w tym przykładzie. Punkt końcowy zwraca kod autoryzacji po uwierzytelnieniu. |
claims |
Opcjonalne żądanie oświadczeń openID Connect zakodowane w formacie JSON. |
Jeśli wymagane jest uwierzytelnianie, odpowiedź to 401 Unauthorized, z Content-Type: application/json:
{
"error": "InsufficientAuthorization",
"error_description": "AADSTS500127: No authenticated credentials found in request.",
"error_codes": [
500127
],
"timestamp": "2026-08-28T17:30:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
"continuation_token": "******",
"reset_password": "/{tenant}/api/v2.0/resetpassword/start",
"sign_in": "/{tenant}/api/v2.0/signin/start",
"sign_up": "/{tenant}/api/v2.0/signup/start"
}
Adresy URL logowania i rejestracji są warunkowe. Linki podróży to właściwości odpowiedzi OAuth najwyższego poziomu, a nie _links wpisy. Wybierz anonsowany podróż i wyślij jego token, tak jak continuationToken w żądaniu JSON. Obsługa wszelkich zasad lub odrzucenia specyficznego dla konta.
Wznawianie autoryzacji
Gdy bieżąca odpowiedź zwróci state: continuewartość , opublikuj najnowszy token na _links.continue.hrefadres . Nie wysyłaj ponownie początkowego client_idżądania , scopeani claims w tym żądaniu.
POST https://{custom_domain}/{tenant}/oauth2/v2.0/authorize-challenge
Content-Type: application/x-www-form-urlencoded
continuation_token={continuation_token}
Pomyślna odpowiedź to 200 OK i JSON:
{
"code": "{authorization_code}"
}
Kody autoryzacji są krótkotrwałe i jednorazowe. Exchange kodu zamiast traktować go jako token dostępu.
Exchange kodu autoryzacji
Opublikuj kod o tym samym identyfikatorze aplikacji:
POST https://{custom_domain}/{tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&
grant_type=authorization_code&
code={authorization_code}
Wszystkie trzy parametry są wymagane.
grant_type jest authorization_code. To żądanie klienta publicznego nie zawiera wpisu tajnego klienta.
Pomyślna odpowiedź to 200 OK i JSON:
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "******",
"id_token": "******",
"refresh_token": "******"
}
Pola tokenu zależą od początkowo ustanowionych zakresów i oświadczeń. Token odświeżania jest zwracany tylko wtedy, gdy początkowe żądanie zawiera offline_accesswartość . Przykładowa wartość wygaśnięcia nie jest gwarancją stałego okresu istnienia. Nie żądaj offline_access , jeśli aplikacja nie potrzebuje tokenu odświeżania.
Wyzwanie lub ponowne wysłanie
Postępuj zgodnie z linkiem wybranej metody challenge lub bieżącym resend linkiem, gdy klient zażąda innego kodu dostępu:
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/{methodType}/{id}/challenge
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******"
}
Zadanie e-mail może zwrócić:
{
"continuationToken": "******",
"state": "interactionRequired",
"action": "verify",
"id": "{email_method_id}",
"type": "email",
"hint": "u***@contoso.com",
"codeLength": 8,
"_links": {
"verify": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/verify"
},
"resend": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/challenge"
}
}
}
Sms używa tego samego kształtu wyzwania poświadczeń z , zamaskowaną wskazówką dla telefonu i zwracanymi linkami type: smsmetody. Wyzwania związane z hasłem nie wysyłają kodu dostępu i zwracają akcję hasła verify . Użyj zwróconej codeLengthwartości , a nie przykładowej długości. Postępuj zgodnie z kontrolowaną przez usługę próbą i limitami ponownego pisania.
Weryfikowanie poświadczeń
Opublikuj bieżący verify link. Dla metody hasła:
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{id}/verify
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******",
"password": "******"
}
W przypadku metody wiadomości e-mail lub wiadomości SMS:
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/{methodType}/{id}/verify
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******",
"otp": "{one_time_passcode}"
}
Weryfikacja może zwrócić inne wyzwanie, kolekcję atrybutów, aktualizację hasła lub kontynuację. Obsłuż zwróconą akcję. Weryfikacja nie jest idempotentna; nie ponawiaj próby automatycznie po niejednoznacznej awarii sieci.
Rejestracja metody uwierzytelniania
Rejestracja lub logowanie może wymagać rejestracji wbudowanej za pomocą metody action: enroll, a następnie .action: activate Rejestracja jest oddzielona od zbierania atrybutów profilu lub weryfikowania istniejącego poświadczenia.
Important
Rejestracja jest oddzielona od uwierzytelniania przy użyciu zarejestrowanej metody. Użyj tylko metod rejestracji anonsowanych dla bieżącej transakcji; Nie wywnioskuj operacji rejestracji z wyzwania poświadczeń.
Wybieranie i rejestrowanie metody
Wybierz obsługiwaną metodę z adresu URL i postępuj zgodnie z _embedded.methods jej _links.enroll adresem URL.
| Metoda | Ogłoszenie | Wymagane pola JSON |
|---|---|---|
| Wiadomość SMS na telefon |
type: phone, z sms in channels. |
continuationToken, phoneNumber w tym kod kraju i channel: sms. |
type: email. |
continuationToken i email. Nie wysyłaj pliku channel. |
Rejestracja na telefonie używa type: phonetypu , a nie typu używanego sms przez istniejące metody wyzwania SMS. Przykładowy adres URL rejestracji telefonu to /{tenant}/api/v2.0/auth/methods/phone; adres URL wiadomości e-mail to /{tenant}/api/v2.0/auth/methods/email. Użyj w POST formacie JSON i postępuj zgodnie z anonsowanym adresem URL, a nie konstruuj go.
W przypadku rejestracji wiadomości SMS na telefon treść to:
{
"continuationToken": "******",
"phoneNumber": "+1 2025550123",
"channel": "sms"
}
W przypadku rejestracji w wiadomości e-mail treść to:
{
"continuationToken": "******",
"email": "user@contoso.com"
}
Usługa wysyła kod dostępu i zwraca action: activate, nowy token kontynuacji i activate link. Wyświetl zwróconą maskę hint i codeLength gdy jest obecna. Wiadomości e-mail i wiadomości SMS mogą używać różnych długości kodu.
Odpowiedź na aktywację telefoniczną może być:
{
"continuationToken": "******",
"state": "interactionRequired",
"action": "activate",
"id": "{phone_method_id}",
"type": "phone",
"channel": "sms",
"hint": "***0123",
"codeLength": 6,
"_links": {
"activate": {
"href": "/{tenant}/api/v2.0/auth/methods/phone/{phone_method_id}/activate"
},
"resend": {
"href": "/{tenant}/api/v2.0/auth/methods/phone"
}
}
}
Użyj pól i linków z rzeczywistej odpowiedzi; Wiadomość e-mail używa własnego typu metody, długości kodu i linków.
Aktywowanie lub ponowne wysyłanie
Wyślij kod JSON POST do bieżącego activate linku przy użyciu najnowszego continuationToken i kodu użytkownika w pliku otp. Przykłady telefonów używają ; /{tenant}/api/v2.0/auth/methods/phone/{phone_method_id}/activatewiadomość e-mail używa własnego anonsowanego linku. Nie przesyłaj kodów aktywacji do linku verify poświadczeń.
{
"continuationToken": "******",
"otp": "{one_time_passcode}"
}
Jeśli odpowiedź na aktywację anonsuje resend, wyślij kod JSON POST zawierający tylko najnowszy continuationToken link. Link może wrócić do rejestracji. Nie przechowuj ani nie wyślij ponownie danych kontaktowych; token przenosi kontekst rejestracji.
{
"continuationToken": "******"
}
Zastąp aktywny token, linki, wskazówka i długość kodu po każdej odpowiedzi. Kontynuuj obsługę zwróconych akcji po aktywacji; zezwala tylko state: continue na wznowienie autoryzacji. Rejestracja może spełniać wymagania uwierzytelniania wieloskładnikowego, więc oddzielne wyzwanie poświadczeń nie zawsze jest wymagane.
W przypadku programu invalidGrantinnerError.code: invalidOneTimeCodezachowaj bieżący token aktywacji i anonsowane linki. Pozwól użytkownikowi poprawić kod lub zażądać ponownego wysłanie żądania. Nie odtwarzaj automatycznie rejestracji ani aktywacji po niejednoznacznym niepowodzeniu połączenia.
Errors
Błędy protokołu OAuth używają pól, takich jak error, error_description, trace_idi correlation_id. Błędy uwierzytelniania natywnego używają zagnieżdżonej koperty. Na przykład nieprawidłowy kod weryfikacyjny wiadomości e-mail może zwrócić http 400 z:
{
"error": {
"code": "invalidGrant",
"message": "AADSTS50181: Unable to validate the otp.",
"timestamp": "2026-08-28T17:30:00Z",
"traceId": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
"innerError": {
"code": "invalidOneTimeCode"
}
}
}
Używaj stabilnych kodów do obsługi, a nie zlokalizowanych komunikatów. Walidacja atrybutu może być zwracana error.innerError.code: attributeValidationError z details wpisami zawierającymi codewartości , messagei attributeIds, oraz opcjonalne suggestions lub recovery. Sprawdź stan HTTP i typ zawartości przed analizowaniem; Nie renderuj nieoczekiwanej treści błędu HTML w aplikacji.
| Warunek | Stan lub błąd | Obsługa |
|---|---|---|
| Nieprawidłowy parametr OAuth | 400 invalid_request |
Popraw żądanie; nie ponawiaj próby bez zmian. |
| Nieprawidłowy lub wygasły kod | 400 invalid_grant |
Uruchom ponownie autoryzację. |
| Nieprawidłowa aplikacja | 400 invalid_client |
Popraw konfigurację aplikacji. |
| Nieprawidłowy lub niegranowany zakres | 400 invalid_scope |
Sprawdź żądane zakresy i zgodę. |
| Wymagane uwierzytelnianie | 401 InsufficientAuthorization |
Postępuj zgodnie z włączonym linkiem podróży. |
| Nieprawidłowy token/stan kontynuacji | 400 invalidRequest |
Uruchom ponownie odpowiedni przepływ. |
| Wygasły token aktualizacji hasła |
400 expiredToken z innerError.code: expiredContinuationToken |
Uruchom ponownie autoryzację. |
| Brak kodu weryfikacyjnego | 400 invalidRequest |
Popraw brakujące dane wejściowe. |
| Nieprawidłowy kod weryfikacyjny wiadomości e-mail lub SMS |
400 invalidGrant z innerError.code: invalidOneTimeCode |
Pozwól użytkownikowi poprawić kod przy użyciu bieżącego stanu weryfikacji lub postępować zgodnie z anonsowanym linkiem do ponownego wyślij. Nie przesyłaj ponownie automatycznie. |
| Nieprawidłowy kod aktywacji |
400 invalidGrant z innerError.code: invalidOneTimeCode |
Zachowaj bieżący token aktywacji i anonsowane linki. Pozwól użytkownikowi poprawić kod lub użyć anonsowanej akcji ponownego wysłanie. Nie przesyłaj ponownie automatycznie. |
| Wymagana interakcja z przeglądarką |
invalid_grant z web_redirect_required |
Zatrzymaj żądania natywne i użyj skonfigurowanej interaktywnej ścieżki odzyskiwania. Nie przekazuj tokenu kontynuacji do dowolnego adresu URL. |
| Transakcja natywna nie może kontynuować | Treść natywna {"state":"redirect"} |
Zatrzymywanie żądań natywnych. Osobne logowanie w przeglądarce nie zachowuje natywnych postępów. |
| Ograniczanie przepustowości | 429 |
Wskazówki dotyczące honorowania Retry-After i serwera. |
Błędy sieci i usługi mogą używać innych formatów odpowiedzi. Traktuj nieoczekiwany typ zawartości jako jawny błąd. W tabeli opisano konkretne typowe przypadki, a nie wyczerpujący wykaz błędów dla każdej operacji.
Zabezpieczenia i diagnostyka
Użyj protokołu HTTPS dla każdego żądania nadrzędnego. Zachowaj hasła, kody dostępu, tokeny kontynuacji, kody i wystawione tokeny z adresów URL, dzienników, telemetrii, wyjątków, zrzutów ekranu i załączników pomocy technicznej. Nie buforuj odpowiedzi uwierzytelniania ani nie udostępniaj stanu transakcji między użytkownikami.
Odrzuć nieoczekiwane władze i przekierowania, a nie przekazywanie wpisów tajnych. Nie ponawiaj automatycznie weryfikacji poświadczeń, przesyłania kont ani aktualizacji haseł po niejednoznacznym niepowodzeniu.
Wyświetlaj tylko zamaskowane wskazówki dostarczone przez usługę. Używaj ogólnych niepowodzeń odnajdywania, aby komunikaty i prezentacja metody nie ujawniały niepotrzebnie istnienia konta.
Zachowaj bezpieczną diagnostykę: stan HTTP, kategoria operacji, client-request-id, identyfikatory śledzenia/korelacji usługi i znacznik czasu. Nazwy OAuth używają podkreśleń; Nazwy błędów uwierzytelniania natywnego używają przypadku camel. Wyodrębnij te pola diagnostyczne bez zachowywania pełnych treści żądania lub odpowiedzi.
Niestandardowe rozszerzenia uwierzytelniania
Konfiguracja zdarzeń i kontrakty są specyficzne dla każdego rozszerzenia i podróży. Aplikacja nadal wybiera dozwolone operacje z odpowiedzi usługi, gdy rozszerzenie uczestniczy w przepływie.
Pokrycie zdarzeń natywnych obejmuje OnOtpSend wiadomości e-mail i OnTokenIssuanceStart.
OnAttributeCollectionStart i OnAttributeCollectionSubmit nie są obsługiwane w przypadku uwierzytelniania natywnego osadzonego ani środowiska użytkownika Bring Your Own. Zobacz Niestandardowe rozszerzenia uwierzytelniania , aby uzyskać informacje o zachowaniu specyficznym dla zdarzenia. Ten zestaw zdarzeń nie ustanawia punktów zaczepienia migracji haseł, synchronizacji aktualizacji haseł ani dowolnych propagacji kontekstu.