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 dowodowym dla programu Code Exchange (PKCE) i OpenID Connect (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 URI
typeprzekierowania naspaprzy 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. Pomimo zgodności z poprzednimi wersjami zalecamy użycie przepływu kodu uwierzytelniania z kluczem PKCE dla spAs.
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 przykładowym żą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 od administratora globalnego. Aby uzyskać więcej informacji, zobacz Uprawnienia z ograniczeniami administratora.
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_hint oś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_verifier code_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
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, administrator 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.