Platforma tożsamości Microsoft a przepływ kodu autoryzacji OAuth 2.0

Typ udzielania kodu autoryzacji OAuth 2.0 lub przepływ kodu uwierzytelniania umożliwia aplikacji klienckiej uzyskanie autoryzowanego dostępu do chronionych zasobów, takich jak internetowe interfejsy API. Przepływ kodu uwierzytelniania wymaga agenta użytkownika, który obsługuje przekierowywanie z serwera autoryzacji (Platforma tożsamości Microsoft) z powrotem do aplikacji. Na przykład przeglądarka internetowa, aplikacja klasyczna lub mobilna obsługiwana przez użytkownika w celu zalogowania się do aplikacji i uzyskania dostępu do ich danych.

W tym artykule opisano szczegóły protokołu niskiego poziomu wymagane tylko podczas ręcznego tworzenia i wydawania nieprzetworzonych żądań HTTP do wykonania przepływu, które nie są zalecane. Zamiast tego użyj utworzonej i obsługiwanej przez firmę Microsoft biblioteki uwierzytelniania, aby uzyskać tokeny zabezpieczające i wywołać chronione internetowe interfejsy API w aplikacjach.

Aplikacje obsługujące przepływ kodu uwierzytelniania

Użyj przepływu kodu uwierzytelniania sparowanego z kluczem weryfikacji dla programu Code Exchange (PKCE) i openID Połączenie (OIDC), aby uzyskać tokeny dostępu i tokeny identyfikatorów w następujących typach aplikacji:

• Jednostronicowa aplikacja internetowa (SPA)
• Standardowa (oparta na serwerze) aplikacja internetowa
• Aplikacje klasyczne i mobilne

Szczegóły protokołu

Przepływ kodu autoryzacji OAuth 2.0 został opisany w sekcji 4.1 specyfikacji OAuth 2.0. Aplikacje korzystające z przepływu kodu autoryzacji OAuth 2.0 uzyskują access_token element do uwzględnienia w żądaniach do zasobów chronionych przez Platforma tożsamości Microsoft (zazwyczaj interfejsy API). Aplikacje mogą również żądać nowych identyfikatorów i tokenów dostępu dla wcześniej uwierzytelnionych jednostek przy użyciu mechanizmu odświeżania.

Na tym diagramie przedstawiono ogólny widok przepływu uwierzytelniania:

Identyfikatory URI przekierowania dla aplikacji jednostronicowych (SPA)

Identyfikatory URI przekierowania dla dostawców usług korzystających z przepływu kodu uwierzytelniania wymagają specjalnej konfiguracji.

• Dodaj identyfikator URI przekierowania, który obsługuje przepływ kodu uwierzytelniania za pomocą protokołu PKCE i współużytkowania zasobów między źródłami (CORS): wykonaj kroki opisane w artykule Identyfikator URI przekierowania: MSAL.js 2.0 z przepływem kodu uwierzytelniania.
• Aktualizowanie identyfikatora URI przekierowania: ustaw identyfikator URItype przekierowania na spa przy użyciu edytora manifestu aplikacji w centrum administracyjnym firmy Microsoft Entra.

spa Typ przekierowania jest zgodny z poprzednimi wersjami z niejawnym przepływem. Aplikacje korzystające obecnie z niejawnego przepływu do pobierania tokenów mogą przejść do spa typu identyfikatora URI przekierowania bez problemów i nadal korzystać z niejawnego przepływu.

Jeśli spróbujesz użyć przepływu kodu autoryzacji bez skonfigurowania mechanizmu CORS dla identyfikatora URI przekierowania, ten błąd zostanie wyświetlony w konsoli programu :

access to XMLHttpRequest at 'https://login.microsoftonline.com/common/v2.0/oauth2/token' from origin 'yourApp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Jeśli tak, odwiedź rejestrację aplikacji i zaktualizuj identyfikator URI przekierowania, aby aplikacja korzystała spa z typu .

Aplikacje nie mogą używać identyfikatora spa URI przekierowania z przepływami spoza SPA, na przykład natywnych aplikacji lub przepływów poświadczeń klienta. Aby zapewnić bezpieczeństwo i najlepsze rozwiązania, Platforma tożsamości Microsoft zwraca błąd w przypadku próby użycia identyfikatora spa URI przekierowania bez nagłówkaOrigin. Podobnie Platforma tożsamości Microsoft zapobiega również używaniu poświadczeń klienta we wszystkich przepływach w obecności Origin nagłówka, aby upewnić się, że wpisy tajne nie są używane z poziomu przeglądarki.

Żądanie kodu autoryzacji

Przepływ kodu autoryzacji rozpoczyna się od klienta kierującego użytkownika do punktu końcowego /authorize . W tym żądaniu klient żąda openiduprawnień , offline_accessi https://graph.microsoft.com/mail.read od użytkownika.

Niektóre uprawnienia są ograniczone przez administratora, na przykład zapisywanie danych w katalogu organizacji przy użyciu polecenia Directory.ReadWrite.All. Jeśli aplikacja żąda dostępu do jednego z tych uprawnień od użytkownika organizacyjnego, użytkownik otrzymuje komunikat o błędzie informujący, że nie ma autoryzacji do wyrażania zgody na uprawnienia aplikacji. Aby zażądać dostępu do zakresów ograniczonych przez administratora, należy zażądać ich bezpośrednio z globalnego Administracja istratora. Aby uzyskać więcej informacji, zobacz uprawnienia z ograniczeniami Administracja.

Jeśli nie określono inaczej, nie ma wartości domyślnych parametrów opcjonalnych. Istnieje jednak domyślne zachowanie żądania pomijającego parametry opcjonalne. Domyślnym zachowaniem jest zalogowanie się tylko bieżącego użytkownika, wyświetlenie selektora konta, jeśli istnieje wielu użytkowników, lub wyświetlenie strony logowania, jeśli nie ma zalogowanych użytkowników.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Parametr	Wymagane/opcjonalne	opis
tenant	wymagane	Wartość {tenant} w ścieżce żądania może służyć do kontrolowania, kto może zalogować się do aplikacji. Prawidłowe wartości to common, organizations, consumersi identyfikatory dzierżawy. W przypadku scenariuszy gościa, w których logujesz użytkownika z jednej dzierżawy do innej dzierżawy, musisz podać identyfikator dzierżawy, aby zalogować się do dzierżawy zasobów. Aby uzyskać więcej informacji, zobacz Punkty końcowe.
client_id	wymagane	Identyfikator aplikacji (klienta) przypisany do aplikacji przez centrum administracyjne firmy Microsoft — Rejestracje aplikacji.
response_type	wymagane	Musi zawierać code przepływ kodu autoryzacji. Może również zawierać id_token lub token używać przepływu hybrydowego.
redirect_uri	wymagane	Aplikacja redirect_uri , w której można wysyłać i odbierać odpowiedzi uwierzytelniania przez aplikację. Musi być dokładnie zgodny z jednym z identyfikatorów URI przekierowania zarejestrowanych w centrum administracyjnym firmy Microsoft Entra, z wyjątkiem tego, że musi być zakodowany pod adresem URL. W przypadku aplikacji natywnych i mobilnych użyj jednej z zalecanych wartości: https://login.microsoftonline.com/common/oauth2/nativeclient w przypadku aplikacji korzystających z przeglądarek osadzonych lub http://localhost aplikacji korzystających z przeglądarek systemowych.
scope	wymagane	Rozdzielona spacjami lista zakresów , do których użytkownik ma wyrazić zgodę. /authorize W przypadku części żądania ten parametr może obejmować wiele zasobów. Ta wartość umożliwia aplikacji uzyskanie zgody dla wielu internetowych interfejsów API, które chcesz wywołać.
response_mode	zalecane	Określa sposób, w jaki platforma tożsamości powinna zwrócić żądany token do aplikacji. Obsługiwane wartości: - query: wartość domyślna podczas żądania tokenu dostępu. Udostępnia kod jako parametr ciągu zapytania w identyfikatorze URI przekierowania. Parametr query nie jest obsługiwany podczas żądania tokenu identyfikatora przy użyciu przepływu niejawnego. - fragment: wartość domyślna podczas żądania tokenu identyfikatora przy użyciu przepływu niejawnego. Obsługiwane również w przypadku żądania tylko kodu. - form_post: wykonuje post zawierający kod do identyfikatora URI przekierowania. Obsługiwane podczas żądania kodu.
state	zalecane	Wartość uwzględniona w żądaniu, który jest również zwracany w odpowiedzi tokenu. Może to być ciąg dowolnej zawartości. Losowo wygenerowana unikatowa wartość jest zwykle używana do zapobiegania atakom fałszerzowanym żądań między witrynami. Wartość może również zakodować informacje o stanie użytkownika w aplikacji przed wystąpieniem żądania uwierzytelnienia. Może na przykład zakodować stronę lub wyświetlić, na której się znajdowały.
prompt	optional	Wskazuje wymagany typ interakcji użytkownika. Prawidłowe wartości to login, , consentnonei select_account. - prompt=login wymusza, aby użytkownik wprowadzał swoje poświadczenia na tym żądaniu, negując logowanie jednokrotne. - prompt=none jest przeciwieństwem. Gwarantuje to, że użytkownik nie jest wyświetlany z żadnym interakcyjnym monitem. Jeśli nie można ukończyć żądania w trybie dyskretnym przy użyciu logowania jednokrotnego, Platforma tożsamości Microsoft zwróci interaction_required błąd. - prompt=consent Wyzwala okno dialogowe zgody OAuth po zalogowaniu się użytkownika z prośbą o udzielenie uprawnień do aplikacji. - prompt=select_account przerywa logowanie jednokrotne, zapewniając środowisko wyboru konta z listą wszystkich kont w sesji lub dowolnym zapamiętanym koncie lub opcję, aby całkowicie użyć innego konta.
login_hint	optional	Tego parametru można użyć do wstępnego wypełnienia pola nazwy użytkownika i adresu e-mail strony logowania użytkownika. Aplikacje mogą używać tego parametru podczas ponownego uwierzytelniania po wyodrębnieniu opcjonalnego login_hintoświadczenia z wcześniejszego logowania.
domain_hint	optional	Jeśli jest to uwzględnione, aplikacja pomija proces odnajdywania opartego na wiadomości e-mail, który użytkownik przechodzi na stronie logowania, co prowadzi do nieco bardziej usprawnionego środowiska użytkownika. Na przykład wysłanie ich do dostawcy tożsamości federacyjnej. Aplikacje mogą używać tego parametru podczas ponownego uwierzytelniania, wyodrębniając tid element z poprzedniego logowania.
code_challenge	zalecane/wymagane	Służy do zabezpieczania udzielania kodu autoryzacji przy użyciu klucza dowodowego dla programu Code Exchange (PKCE). Wymagane, jeśli code_challenge_method jest uwzględniona. Aby uzyskać więcej informacji, zobacz PKCE RFC. Ten parametr jest teraz zalecany dla wszystkich typów aplikacji, zarówno klientów publicznych, jak i poufnych oraz wymaganych przez Platforma tożsamości Microsoft dla aplikacji jednostronicowych przy użyciu przepływu kodu autoryzacji.
code_challenge_method	zalecane/wymagane	Metoda używana do kodowania parametru code_verifiercode_challenge . Powinna to być S256wartość , ale specyfikacja zezwala na użycieplain, jeśli klient nie może obsługiwać algorytmu SHA256. Jeśli zostanie wykluczony, przyjmuje się, code_challenge że jest to zwykły tekst, jeśli code_challenge jest uwzględniony. Platforma tożsamości Microsoft obsługuje zarówno elementy , jak plain i S256. Aby uzyskać więcej informacji, zobacz PKCE RFC. Ten parametr jest wymagany dla aplikacji jednostronicowych przy użyciu przepływu kodu autoryzacji.

Na tym etapie użytkownik zostanie poproszony o wprowadzenie poświadczeń i ukończenie uwierzytelniania. Platforma tożsamości Microsoft gwarantuje również, że użytkownik wyraził zgodę na uprawnienia wskazane w parametrze scope zapytania. Jeśli użytkownik nie wyraził zgody na jakiekolwiek z tych uprawnień, prosi użytkownika o wyrażenie zgody na wymagane uprawnienia. Aby uzyskać więcej informacji, zobacz Uprawnienia i zgoda w Platforma tożsamości Microsoft.

Gdy użytkownik uwierzytelnia się i udziela zgody, Platforma tożsamości Microsoft zwraca odpowiedź do aplikacji pod wskazanym redirect_uriadresem , używając metody określonej w parametrze response_mode .

Odpowiedź pomyślna

W tym przykładzie pokazano pomyślną odpowiedź przy użyciu polecenia response_mode=query:

GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345

Parametr	Opis
code	Żądana authorization_code aplikacja. Aplikacja może użyć kodu autoryzacji, aby zażądać tokenu dostępu dla zasobu docelowego. Kody autoryzacji są krótkotrwałe. Zazwyczaj wygasają po około 10 minutach.
state	state Jeśli parametr jest uwzględniony w żądaniu, ta sama wartość powinna pojawić się w odpowiedzi. Aplikacja powinna sprawdzić, czy wartości stanu w żądaniu i odpowiedzi są identyczne.

Jeśli zażądasz tokenu identyfikatora, możesz również uzyskać niejawne przyznanie włączone w rejestracji aplikacji. To zachowanie jest czasami określane jako przepływ hybrydowy. Jest on używany przez struktury, takie jak ASP.NET.

Odpowiedź błędna

Odpowiedzi na błędy mogą być również wysyłane do redirect_uri aplikacji, aby mogła je odpowiednio obsłużyć:

GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication

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. Ta część błędu jest dostarczana tak, aby aplikacja mogła odpowiednio reagować na błąd, ale nie wyjaśnia szczegółowo, dlaczego wystąpił błąd.
error_description	Określony komunikat o błędzie, który może pomóc deweloperowi zidentyfikować przyczynę błędu uwierzytelniania. Ta część błędu zawiera większość przydatnych informacji o przyczynie wystąpienia błędu.

Kody błędów dla błędów punktu końcowego autoryzacji

W poniższej tabeli opisano różne kody błędów, które można zwrócić w parametrze error odpowiedzi o błędzie.

Kod błędu	opis	Akcja klienta
invalid_request	Błąd protokołu, taki jak brak wymaganego parametru.	Napraw i prześlij ponownie żądanie. Ten błąd jest zazwyczaj błędem programistycznym przechwyconym podczas początkowego testowania.
unauthorized_client	Aplikacja kliencka nie może zażądać kodu autoryzacji.	Ten błąd występuje zwykle, gdy aplikacja kliencka nie jest zarejestrowana w identyfikatorze Entra firmy Microsoft lub nie jest dodawana do dzierżawy firmy Microsoft Entra użytkownika. Aplikacja może monitować użytkownika z instrukcjami dotyczącymi instalowania aplikacji i dodawania jej do identyfikatora Entra firmy Microsoft.
access_denied	Odmowa zgody właściciela zasobu	Aplikacja kliencka może powiadomić użytkownika o tym, że nie może kontynuować, chyba że użytkownik wyrazi zgodę.
unsupported_response_type	Serwer autoryzacji nie obsługuje typu odpowiedzi w żądaniu.	Napraw i prześlij ponownie żądanie. Ten błąd jest zazwyczaj błędem programistycznym przechwyconym podczas początkowego testowania. W przepływie hybrydowym ten błąd sygnalizuje, że należy włączyć ustawienie niejawnego przyznawania tokenu identyfikatora w rejestracji aplikacji klienckiej.
server_error	Serwer napotkał nieoczekiwany błąd.	Ponów próbę żądania. Te błędy mogą wynikać z warunków tymczasowych. Aplikacja kliencka może wyjaśnić użytkownikowi, że jego odpowiedź jest opóźniona na tymczasowy błąd.
temporarily_unavailable	Serwer jest tymczasowo zbyt zajęty, aby obsłużyć żądanie.	Ponów próbę żądania. Aplikacja kliencka może wyjaśnić użytkownikowi, że jego odpowiedź jest opóźniona z powodu stanu tymczasowego.
invalid_resource	Zasób docelowy jest nieprawidłowy, ponieważ nie istnieje, identyfikator Entra firmy Microsoft nie może go znaleźć lub nie jest poprawnie skonfigurowany.	Ten błąd wskazuje, że zasób, jeśli istnieje, nie został skonfigurowany w dzierżawie. Aplikacja może monitować użytkownika z instrukcjami dotyczącymi instalowania aplikacji i dodawania jej do identyfikatora Entra firmy Microsoft.
login_required	Zbyt wielu lub nie znaleziono żadnych użytkowników.	Klient zażądał uwierzytelnienia dyskretnego (prompt=none), ale nie można odnaleźć jednego użytkownika. Ten błąd może oznaczać, że w sesji jest aktywnych wielu użytkowników lub brak użytkowników. Ten błąd uwzględnia wybraną dzierżawę. Jeśli na przykład istnieją dwa aktywne konta Microsoft Entra i jedno konto Microsoft i consumers zostanie wybrane, uwierzytelnianie dyskretne działa.
interaction_required	Żądanie wymaga interakcji z użytkownikiem.	Wymagany jest inny krok uwierzytelniania lub zgoda. Ponów próbę żądania bez prompt=none.

Żądanie tokenu identyfikatora oraz przepływu hybrydowego

Aby dowiedzieć się, kim jest użytkownik przed zrealizowaniem kodu autoryzacji, często aplikacje żądają tokenu identyfikatora podczas żądania kodu autoryzacji. Takie podejście jest nazywane przepływem hybrydowym, ponieważ miesza OIDC z przepływem kodu autoryzacji OAuth2.

Przepływ hybrydowy jest często używany w aplikacjach internetowych do renderowania strony dla użytkownika bez blokowania realizacji kodu, zwłaszcza w ASP.NET. Zarówno aplikacje jednostronicowe, jak i tradycyjne aplikacje internetowe korzystają z mniejszego opóźnienia w tym modelu.

Przepływ hybrydowy jest taki sam jak opisany wcześniej przepływ kodu autoryzacji, ale z trzema dodatkami. Wszystkie te dodatki są wymagane do żądania tokenu identyfikatora: nowych zakresów, nowego response_type i nowego nonce parametru zapytania.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code%20id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=fragment
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345
&nonce=abcde
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Zaktualizowany parametr	Wymagane/opcjonalne	opis
response_type	wymagane	Dodanie id_token wskazuje serwerowi, że aplikacja chciałaby token identyfikatora w odpowiedzi z punktu końcowego /authorize .
scope	wymagane	W przypadku tokenów identyfikatorów ten parametr musi zostać zaktualizowany, aby uwzględnić zakresy tokenów identyfikatorów: openid i opcjonalnie profile i email.
nonce	wymagane	Wartość uwzględniona w żądaniu wygenerowana przez aplikację, która jest uwzględniona w wynikowym id_token oświadczeniu. Następnie aplikacja może zweryfikować tę wartość, aby wyeliminować ataki ponownego odtwarzania tokenu. Wartość jest zazwyczaj losowym, unikatowym ciągiem, który może służyć do identyfikowania źródła żądania.
response_mode	zalecane	Określa metodę, która powinna służyć do wysyłania wynikowego tokenu z powrotem do aplikacji. Wartość domyślna dotyczy query tylko kodu autoryzacji, ale fragment jeśli żądanie zawiera element id_tokenresponse_type określony w specyfikacji OpenID. Zalecamy używanie aplikacji form_post, szczególnie w przypadku używania jako http://localhost identyfikatora URI przekierowania.

Użycie fragment funkcji jako trybu odpowiedzi powoduje problemy z aplikacjami internetowymi, które odczytują kod z przekierowania. Przeglądarki nie przekazują fragmentu do serwera internetowego. W takich sytuacjach aplikacje powinny używać form_post trybu odpowiedzi, aby upewnić się, że wszystkie dane są wysyłane do serwera.

Odpowiedź pomyślna

W tym przykładzie pokazano pomyślną odpowiedź przy użyciu polecenia response_mode=fragment:

GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345

Parametr	Opis
code	Kod autoryzacji żądany przez aplikację. Aplikacja może użyć kodu autoryzacji, aby zażądać tokenu dostępu dla zasobu docelowego. Kody autoryzacji są krótkotrwałe, zwykle wygasają po około 10 minutach.
id_token	Token identyfikatora użytkownika wystawiony przy użyciu niejawnego udzielenia. Zawiera specjalne c_hash oświadczenie, które jest skrótem code w tym samym żądaniu.
state	state Jeśli parametr jest uwzględniony w żądaniu, ta sama wartość powinna pojawić się w odpowiedzi. Aplikacja powinna sprawdzić, czy wartości stanu w żądaniu i odpowiedzi są identyczne.

Realizowanie kodu dla tokenu dostępu

Wszyscy klienci poufni mają możliwość korzystania z wpisów tajnych klienta lub poświadczeń certyfikatu. Symetryczne wspólne wpisy tajne są generowane przez Platforma tożsamości Microsoft. Poświadczenia certyfikatu to klucze asymetryczne przekazywane przez dewelopera. Aby uzyskać więcej informacji, zobacz Platforma tożsamości Microsoft poświadczenia certyfikatu uwierzytelniania aplikacji.

Aby uzyskać najlepsze zabezpieczenia, zalecamy używanie poświadczeń certyfikatu. Klienci publiczni, którzy obejmują aplikacje natywne i aplikacje jednostronicowe, nie mogą używać wpisów tajnych ani certyfikatów podczas realizacji kodu autoryzacji. Zawsze upewnij się, że identyfikatory URI przekierowania zawierają typ aplikacji i są unikatowe.

Żądanie tokenu dostępu przy użyciu client_secret

Teraz, po uzyskaniu authorization_code uprawnień i udzielono mu przez użytkownika, możesz zrealizować code element dla access_token zasobu. Zrealizuj żądanie code , wysyłając POST żądanie do punktu końcowego /token :

// Line breaks for legibility only

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=11112222-bbbb-3333-cccc-4444dddd5555
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong 
&client_secret=sampleCredentia1s    // NOTE: Only required for web apps. This secret needs to be URL-Encoded.

Parametr	Wymagane/opcjonalne	opis
tenant	wymagane	Wartość {tenant} w ścieżce żądania może służyć do kontrolowania, kto może zalogować się do aplikacji. Prawidłowe wartości to common, organizations, consumersi identyfikatory dzierżawy. Aby uzyskać więcej informacji, zobacz Punkty końcowe.
client_id	wymagane	Identyfikator aplikacji (klienta), który jest przypisany do aplikacji przez centrum administracyjne firmy Microsoft — Rejestracje aplikacji.
scope	optional	Rozdzielona spacjami lista zakresów. Zakresy muszą pochodzić z jednego zasobu wraz z zakresami OIDC (profile, openid, email). Aby uzyskać więcej informacji, zobacz Uprawnienia i zgoda w Platforma tożsamości Microsoft. Ten parametr jest rozszerzeniem firmy Microsoft do przepływu kodu autoryzacji, które ma umożliwić aplikacjom deklarowanie zasobu, dla którego chcą tokenu podczas realizacji tokenu.
code	wymagane	Element authorization_code uzyskany w pierwszym etapie przepływu.
redirect_uri	wymagane	Ta sama redirect_uri wartość, która została użyta do uzyskania elementu authorization_code.
grant_type	wymagane	Musi być authorization_code przeznaczony dla przepływu kodu autoryzacji.
code_verifier	zalecane	To samo code_verifier , które zostało użyte do uzyskania authorization_code. Wymagane, jeśli klucz PKCE został użyty w żądaniu udzielenia kodu autoryzacji. Aby uzyskać więcej informacji, zobacz PKCE RFC.
client_secret	wymagane w przypadku poufnych aplikacji internetowych	Wpis tajny aplikacji utworzony w portalu rejestracji aplikacji dla aplikacji. Nie używaj wpisu tajnego aplikacji w aplikacji natywnej ani aplikacji jednostronicowej, ponieważ client_secret nie można niezawodnie przechowywać go na urządzeniach lub stronach internetowych. Jest to wymagane w przypadku aplikacji internetowych i internetowych interfejsów API, które mogą przechowywać client_secret je bezpiecznie po stronie serwera. Podobnie jak w przypadku wszystkich parametrów, klucz tajny klienta musi być zakodowany w adresie URL przed wysłaniem. Ten krok jest wykonywany przez zestaw SDK. Aby uzyskać więcej informacji na temat kodowania identyfikatora URI, zobacz specyfikację składni ogólnej identyfikatora URI. Wzorzec uwierzytelniania podstawowego zamiast podawania poświadczeń w nagłówku autoryzacji na RFC 6749 jest również obsługiwany.

Żądanie tokenu dostępu przy użyciu poświadczeń certyfikatu

// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg

Parametr	Wymagane/opcjonalne	opis
tenant	wymagane	Wartość {tenant} w ścieżce żądania może służyć do kontrolowania, kto może zalogować się do aplikacji. Prawidłowe wartości to common, organizations, consumersi identyfikatory dzierżawy. Aby uzyskać więcej informacji, zobacz Punkty końcowe.
client_id	wymagane	Identyfikator aplikacji (klienta), który jest przypisany do aplikacji przez centrum administracyjne firmy Microsoft — Rejestracje aplikacji.
scope	optional	Rozdzielona spacjami lista zakresów. Zakresy muszą pochodzić z jednego zasobu wraz z zakresami OIDC (profile, openid, email). Aby uzyskać więcej informacji, zobacz uprawnienia, zgoda i zakresy. Ten parametr jest rozszerzeniem firmy Microsoft do przepływu kodu autoryzacji. To rozszerzenie umożliwia aplikacjom deklarowanie zasobu, dla którego chcą tokenu podczas realizacji tokenu.
code	wymagane	Element authorization_code uzyskany w pierwszym etapie przepływu.
redirect_uri	wymagane	Ta sama redirect_uri wartość, która została użyta do uzyskania elementu authorization_code.
grant_type	wymagane	Musi być authorization_code przeznaczony dla przepływu kodu autoryzacji.
code_verifier	zalecane	To samocode_verifier, które zostało użyte do uzyskania .authorization_code Wymagane, jeśli klucz PKCE został użyty w żądaniu udzielenia kodu autoryzacji. Aby uzyskać więcej informacji, zobacz PKCE RFC.
client_assertion_type	wymagane w przypadku poufnych aplikacji internetowych	Wartość musi być ustawiona tak, aby urn:ietf:params:oauth:client-assertion-type:jwt-bearer korzystała z poświadczeń certyfikatu.
client_assertion	wymagane w przypadku poufnych aplikacji internetowych	Asercji, czyli tokenu internetowego JSON (JWT), który należy utworzyć i podpisać przy użyciu certyfikatu zarejestrowanego jako poświadczenia aplikacji. Przeczytaj o poświadczeniach certyfikatu , aby dowiedzieć się, jak zarejestrować certyfikat i format potwierdzenia.

Parametry są takie same jak żądanie udostępnionego wpisu tajnego, z tą różnicą, że client_secret parametr jest zastępowany przez dwa parametry: a client_assertion_type i client_assertion.

Odpowiedź pomyślna

W tym przykładzie przedstawiono pomyślną odpowiedź tokenu:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}

Parametr	Opis
access_token	Żądany token dostępu. Aplikacja może używać tego tokenu do uwierzytelniania w zabezpieczonym zasobie, takim jak internetowy interfejs API.
token_type	Wskazuje wartość typu tokenu. Jedynym typem, który obsługuje identyfikator Entra firmy Microsoft, jest Bearer.
expires_in	Jak długo token dostępu jest prawidłowy w sekundach.
scope	Zakresy, dla których wartość jest prawidłowa access_token . Opcjonalny. Ten parametr jest niestandardowy i, jeśli pominięty, token dotyczy zakresów żądanych w początkowej części przepływu.
refresh_token	Token odświeżania OAuth 2.0. Aplikacja może użyć tego tokenu do uzyskania innych tokenów dostępu po wygaśnięciu bieżącego tokenu dostępu. Tokeny odświeżania są długotrwałe. Mogą oni utrzymywać dostęp do zasobów przez dłuższy czas. Aby uzyskać więcej informacji na temat odświeżania tokenu dostępu, zobacz Odświeżanie tokenu dostępu w dalszej części tego artykułu. Uwaga: podano tylko wtedy, gdy offline_access zażądano zakresu.
id_token	Token internetowy JSON. Aplikacja może dekodować segmenty tego tokenu, 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 id_tokens, zobacz id_token reference. Uwaga: podano tylko wtedy, gdy openid zażądano zakresu.

Odpowiedź błędna

W tym przykładzie jest odpowiedzią na błąd:

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "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 deweloperowi zidentyfikować przyczynę błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla usługi STS, które mogą pomóc w diagnostyce.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.

Kody błędów dla błędów punktu końcowego tokenu

Kod błędu	opis	Akcja klienta
invalid_request	Błąd protokołu, taki jak brak wymaganego parametru.	Napraw żądanie lub rejestrację aplikacji i prześlij ponownie żądanie.
invalid_grant	Kod autoryzacji lub weryfikator kodu PKCE jest nieprawidłowy lub wygasł.	Spróbuj wykonać nowe żądanie do punktu końcowego /authorize i sprawdź, code_verifier czy parametr jest poprawny.
unauthorized_client	Uwierzytelniony klient nie ma autoryzacji do korzystania z tego typu udzielania autoryzacji.	Ten błąd występuje zwykle, gdy aplikacja kliencka nie jest zarejestrowana w identyfikatorze Entra firmy Microsoft lub nie jest dodawana do dzierżawy firmy Microsoft Entra użytkownika. Aplikacja może monitować użytkownika z instrukcjami dotyczącymi instalowania aplikacji i dodawania jej do identyfikatora Entra firmy Microsoft.
invalid_client	Uwierzytelnianie klienta nie powiodło się.	Poświadczenia klienta nie są prawidłowe. Aby rozwiązać ten problem, Administracja istrator aplikacji aktualizuje poświadczenia.
unsupported_grant_type	Serwer autoryzacji nie obsługuje typu udzielania autoryzacji.	Zmień typ udzielenia w żądaniu. Ten typ błędu powinien wystąpić tylko podczas programowania i być wykrywany podczas testowania początkowego.
invalid_resource	Zasób docelowy jest nieprawidłowy, ponieważ nie istnieje, identyfikator Entra firmy Microsoft nie może go znaleźć lub nie jest poprawnie skonfigurowany.	Ten kod wskazuje zasób, jeśli istnieje, nie został skonfigurowany w dzierżawie. Aplikacja może monitować użytkownika z instrukcjami dotyczącymi instalowania aplikacji i dodawania jej do identyfikatora Entra firmy Microsoft.
interaction_required	Non-standard, ponieważ specyfikacja OIDC wywołuje ten kod tylko w punkcie /authorize końcowym. Żądanie wymaga interakcji z użytkownikiem. Na przykład wymagany jest kolejny krok uwierzytelniania.	Ponów próbę /authorize żądania z tymi samymi zakresami.
temporarily_unavailable	Serwer jest tymczasowo zbyt zajęty, aby obsłużyć żądanie.	Ponów próbę żądania po małym opóźnieniu. Aplikacja kliencka może wyjaśnić użytkownikowi, że jego odpowiedź jest opóźniona z powodu stanu tymczasowego.
consent_required	Żądanie wymaga zgody użytkownika. Ten błąd jest niestandardowy. Zwykle jest zwracany tylko w punkcie końcowym zgodnie ze specyfikacjami /authorize OIDC. Zwracany, gdy scope parametr był używany w przepływie realizacji kodu, że aplikacja kliencka nie ma uprawnień do żądania.	Klient powinien wysłać użytkownika z powrotem do punktu końcowego /authorize z prawidłowym zakresem, aby wyzwolić zgodę.
invalid_scope	Zakres żądany przez aplikację jest nieprawidłowy.	Zaktualizuj wartość parametru scope w żądaniu uwierzytelniania na prawidłową wartość.

Uwaga

Aplikacje jednostronicowe mogą otrzymać invalid_request błąd wskazujący, że realizacja tokenu między źródłami jest dozwolona tylko dla typu klienta "Aplikacja jednostronicowa". Oznacza to, że identyfikator URI przekierowania używany do żądania tokenu nie został oznaczony jako spa identyfikator URI przekierowania. Przejrzyj kroki rejestracji aplikacji, aby dowiedzieć się, jak włączyć ten przepływ.

Korzystanie z tokenu dostępu

Teraz, po pomyślnym uzyskaniu tokenu access_token, możesz użyć tokenu w żądaniach do internetowych interfejsów API, dołączając go do nagłówka Authorization :

GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

Odświeżanie tokenu dostępu

Tokeny dostępu są krótkotrwałe. Odśwież je po wygaśnięciu, aby nadal uzyskiwać dostęp do zasobów. Możesz to zrobić, przesyłając kolejne POST żądanie do punktu końcowego /token . Podaj wartość refresh_token zamiast .code Tokeny odświeżania są prawidłowe dla wszystkich uprawnień, dla których klient otrzymał już zgodę. Na przykład token odświeżania wystawiony na żądanie scope=mail.read może służyć do żądania nowego tokenu dostępu dla programu scope=api://contoso.com/api/UseResource.

Tokeny odświeżania dla aplikacji internetowych i aplikacji natywnych nie mają określonych okresów istnienia. Zazwyczaj okresy istnienia tokenów odświeżania są stosunkowo długie. Jednak w niektórych przypadkach tokeny odświeżania wygasają lub nie mają wystarczających uprawnień dla akcji. Aplikacja musi oczekiwać błędów zwracanych przez punkt końcowy wystawiania tokenu i obsługiwać je. Aplikacje jednostronicowe otrzymują token z okresem istnienia 24-godzinnym, co wymaga nowego uwierzytelniania każdego dnia. Tę akcję można wykonać w trybie dyskretnym, gdy pliki cookie innych firm są włączone. Należy to zrobić w ramce najwyższego poziomu, nawigacji pełnej strony lub okna podręcznego, w przeglądarkach bez plików cookie innych firm, takich jak Safari.

Tokeny odświeżania nie są odwoływały się, gdy są używane do uzyskiwania nowych tokenów dostępu. Oczekuje się, że odrzucisz stary token odświeżania. Specyfikacja protokołu OAuth 2.0 mówi: "Serwer autoryzacji MOŻE wydać nowy token odświeżania, w tym przypadku klient MUSI odrzucić stary token odświeżania i zastąpić go nowym tokenem odświeżania. Serwer autoryzacji MOŻE odwołać stary token odświeżania po wystawieniu nowego tokenu odświeżania do klienta.

Ważne

W przypadku tokenów odświeżania wysyłanych do identyfikatora URI przekierowania zarejestrowanego jako spatoken odświeżania wygasa po 24 godzinach. Dodatkowe tokeny odświeżania uzyskane przy użyciu tokenu odświeżania początkowego są przenoszone przez ten czas wygaśnięcia, dlatego aplikacje muszą być przygotowane do ponownego uruchomienia przepływu kodu autoryzacji przy użyciu uwierzytelniania interakcyjnego, aby uzyskać nowy token odświeżania co 24 godziny. Użytkownicy nie muszą wprowadzać swoich poświadczeń i zwykle nawet nie widzą żadnego środowiska użytkownika— wystarczy ponownie załadować aplikację. Aby wyświetlić sesję logowania, przeglądarka musi odwiedzić stronę logowania w ramce najwyższego poziomu. Jest to spowodowane funkcjami prywatności w przeglądarkach, które blokują pliki cookie innych firm.

// Line breaks for legibility only

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=sampleCredentia1s    // NOTE: Only required for web apps. This secret needs to be URL-Encoded

Parametr	Type	Opis
tenant	wymagane	Wartość {tenant} w ścieżce żądania może służyć do kontrolowania, kto może zalogować się do aplikacji. Prawidłowe wartości to common, organizations, consumersi identyfikatory dzierżawy. Aby uzyskać więcej informacji, zobacz Punkty końcowe.
client_id	wymagane	Identyfikator aplikacji (klienta) przypisany do aplikacji przez centrum administracyjne firmy Microsoft — Rejestracje aplikacji.
grant_type	wymagane	Musi być refresh_token dla tej części przepływu kodu autoryzacji.
scope	optional	Rozdzielona spacjami lista zakresów. Zakresy żądane w tej nodze muszą być równoważne lub podzestaw zakresów żądanych w pierwotnej authorization_code nodze żądania. Jeśli zakresy określone w tym żądaniu obejmują wiele serwerów zasobów, Platforma tożsamości Microsoft zwraca token dla zasobu określonego w pierwszym zakresie. Aby uzyskać więcej informacji, zobacz Uprawnienia i zgoda w Platforma tożsamości Microsoft.
refresh_token	wymagane	Uzyskany refresh_token w drugim etapie przepływu.
client_secret	wymagane dla aplikacji internetowych	Wpis tajny aplikacji utworzony w portalu rejestracji aplikacji dla aplikacji. Nie należy jej używać w aplikacji natywnej, ponieważ client_secret nie można jej niezawodnie przechowywać na urządzeniach. Jest to wymagane w przypadku aplikacji internetowych i internetowych interfejsów API, które mogą przechowywać client_secret je bezpiecznie po stronie serwera. Ten klucz tajny musi być zakodowany w formacie URL. Aby uzyskać więcej informacji, zobacz specyfikację składni ogólnej identyfikatora URI.

Odpowiedź pomyślna

W tym przykładzie przedstawiono pomyślną odpowiedź tokenu:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}

Parametr	Opis
access_token	Żądany token dostępu. Aplikacja może używać tego tokenu do uwierzytelniania w zabezpieczonym zasobie, takim jak internetowy interfejs API.
token_type	Wskazuje wartość typu tokenu. Jedynym typem, który obsługuje identyfikator Entra firmy Microsoft, jest bearer.
expires_in	Jak długo token dostępu jest prawidłowy w sekundach.
scope	Zakresy, dla których wartość jest prawidłowa access_token .
refresh_token	Nowy token odświeżania OAuth 2.0. Zastąp stary token odświeżania tym nowo uzyskanym tokenem odświeżania, aby upewnić się, że tokeny odświeżania pozostają prawidłowe tak długo, jak to możliwe. Uwaga: podano tylko wtedy, gdy offline_access zażądano zakresu.
id_token	Niepodpisany token internetowy JSON. Aplikacja może dekodować segmenty tego tokenu, aby zażądać informacji o użytkowniku, który się zalogował. Aplikacja może buforować wartości i wyświetlać je, ale nie powinna polegać na nich dla żadnych granic autoryzacji ani zabezpieczeń. Aby uzyskać więcej informacji na temat id_tokenprogramu , zobacz tokeny identyfikatorów Platforma tożsamości Microsoft. Uwaga: podano tylko wtedy, gdy openid zażądano zakresu.

Ostrzeżenie

Nie próbuj weryfikować ani odczytywać tokenów dla żadnego interfejsu API, którego nie jesteś właścicielem, w tym tokenów w tym przykładzie, w kodzie. Tokeny dla usługi firmy Microsoft mogą używać specjalnego formatu, który nie będzie weryfikowany jako JWT, a także może być szyfrowany dla użytkowników klienta (konta Microsoft). Podczas odczytywania tokenów jest przydatnym narzędziem do debugowania i uczenia, nie należy brać zależności od tego w kodzie ani zakładać konkretnych informacji o tokenach, które nie są przeznaczone dla kontrolującego interfejsu API.

Odpowiedź błędna

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "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 deweloperowi zidentyfikować główną przyczynę błędu uwierzytelniania.
error_codes	Lista kodów błędów specyficznych dla usługi STS, które mogą pomóc w diagnostyce.
timestamp	Czas wystąpienia błędu.
trace_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce.
correlation_id	Unikatowy identyfikator żądania, który może pomóc w diagnostyce między składnikami.

Opis kodów błędów i zalecanej akcji klienta można znaleźć w temacie Kody błędów dla błędów punktu końcowego tokenu.

Następne kroki

• Przejdź do przykładów biblioteki MSAL JS, aby rozpocząć kodowanie.
• Dowiedz się więcej o scenariuszach wymiany tokenów.