Dokumentacja interfejsu API uwierzytelniania natywnego w wersji 2

Dotyczy: Zielony okrąg z białym symbolem znacznika wyboru, który wskazuje następującą zawartość ma zastosowanie do dzierżaw zewnętrznych. 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-Origin wartość dla tego dokładnego dozwolonego źródła, a nie *.
  • Umożliwia wymaganą POST operację lub PUT metodę 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.

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 dla continuationToken oczekującego zaznaczenia.
  • Tablica _embedded.user z informacjami o poszczególnych oferowanych kontach i obsługiwanych linkach. Aktywne konto ma adres URL specyficzny dla _links.resume konta.
  • Adres URL na poziomie _links.discover odpowiedzi 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.
E-mail 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.