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 wysyłania nieprzetworzonych żądań HTTP do wykonania procesu, co jest jednak niezalecane. 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 do uwzględnienia element w żądaniach wysyłanych do zasobów chronionych przez platformę 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 SPA (aplikacji jednostronicowych) korzystających z "auth code flow" wymagają specjalnej konfiguracji.
- Dodaj identyfikator URI przekierowania, który obsługuje przepływ kodu uwierzytelniania za pomocą PKCE i współdzielenia zasobów między źródłami (CORS): postępuj zgodnie z krokami w dokumentacji Identyfikator URI przekierowania: MSAL.js 2.0 z przepływem kodu uwierzytelniania.
-
Aktualizowanie identyfikatora URI przekierowania: Ustaw identyfikator URI przekierowania na
spaprzy użyciu edytora manifestu aplikacji w centrum administracyjnym Microsoft Entra.
spa Typ przekierowania jest wstecznie zgodny z jej wcześniejszymi wersjami z niejawnym przepływem. Aplikacje, które obecnie korzystają z niejawnego przepływu do pobierania tokenów, mogą bez problemu przejść do typu przekierowania URI spa i nadal używać niejawnego przepływu. Pomimo zachowania zgodności z poprzednimi wersjami zalecamy użycie procesu przekazywania kodu uwierzytelniania z mechanizmem PKCE dla SPA.
Jeśli spróbujesz użyć procesu autoryzacji z użyciem kodu bez skonfigurowania mechanizmu CORS dla adresu URI przekierowania, pojawi się błąd w konsoli.
access to XMLHttpRequest at 'https://login.microsoftonline.com/common/oauth2/v2.0/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 z typu spa.
Aplikacje nie mogą używać URI przekierowania z przepływami spoza SPA, na przykład aplikacji natywnych 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 nagłówka Origin, aby upewnić się, że tajemnice 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 uprawnień openid, offline_access i 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, consumers i identyfikatory najemcy. W przypadku scenariuszy gościa, w których zalogujesz użytkownika z jednej dzierżawy do innej, 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 Twojej aplikacji przez Microsoft Entra admin center – App registrations. |
response_type |
wymagane | Musi zawierać code dla przepływu kodu autoryzacji. Może również zawierać id_token lub token, jeśli używany jest przepływ hybrydowy. |
redirect_uri |
wymagane | Miejsce redirect_uri Twojej aplikacji, w którym można wysyłać i odbierać odpowiedzi uwierzytelniania. Musi dokładnie odpowiadać jednemu z identyfikatorów URI przekierowania, które zarejestrowałeś w centrum administracyjnym Microsoft Entra, z zastrzeżeniem, że musi być zakodowany w formacie 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 ID przy użyciu flowu niejawnego. - fragment: Wartość domyślna podczas żądania tokenu identyfikacji przy użyciu przepływu typu implicit. 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óra jest również zwracana w odpowiedzi na token. Może to być ciąg dowolnej zawartości. Losowo wygenerowana unikatowa wartość jest zwykle używana do zapobiegania atakom fałszowania żądań między stronami. 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 |
opcjonalny | Wskazuje wymagany typ interakcji użytkownika. Prawidłowe wartości to login, , noneconsenti 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 przedstawiany z żadnym interaktywnym 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, umożliwiając wybór konta z listy wszystkich kont wchodzących w sesję, dowolnego zapamiętanego konta lub opcji wyboru innego konta. |
login_hint |
opcjonalny | 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 |
opcjonalny | Jeśli jest to uwzględnione, aplikacja pomija proces wykrywania opartego na e-mailu, który użytkownik przechodzi na stronie logowania, co prowadzi do nieco bardziej usprawnionego doświadczenia użytkownika. Na przykład, wysłanie ich do federacyjnego dostawcy tożsamości. 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ędnione. 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 jest wymagany przez platformę tożsamości Microsoft dla aplikacji jednostronicowych wykorzystujących przepływ kodu autoryzacji. |
code_challenge_method |
zalecane/wymagane | Metoda używana do kodowania code_verifier dla parametru code_challenge. To POWINNO być S256, ale specyfikacja zezwala na użycie plain, jeśli klient nie może obsługiwać SHA256. Jeśli code_challenge zostanie wykluczony, przyjmuje się, ż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 używających przepływu z kodem 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 Platformie 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 |
authorization_code żądane przez aplikację. 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, aby aplikacja 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 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 Microsoft Entra ID lub nie jest dodana do dzierżawy 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 nadawania uprawnień dla tokenu identyfikatora w rejestracji aplikacji klienckiej. |
server_error |
Serwer napotkał nieoczekiwany błąd. | Spróbuj ponownie wysłać żądanie. 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 żądanie. 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 u dzierżawcy. 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 wybranego najemcę. 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 lub 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 zażądania tokenu identyfikatora: nowych zakresów, nowego typu odpowiedzi (response_type) i nowego parametru zapytania nonce.
// 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 | W odpowiedzi z punktu końcowego /authorize, dodanie id_token wskazuje serwerowi, że aplikacja chciałaby otrzymać token identyfikacyjny. |
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ść, wygenerowana przez aplikację i uwzględniona w żądaniu, która jest zawarta w wynikowym id_token jako roszczenie. 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 to query tylko kodu autoryzacji, ale fragment jeśli żądanie zawiera id_tokenresponse_type zgodnie z określeniem w specyfikacji OpenID. Zalecamy, aby aplikacje korzystały z form_post, zwłaszcza gdy jako identyfikator URI przekierowania używa się http://localhost. |
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 roszczenie, 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. |
Zrealizuj kod na token dostępu
Wszyscy klienci poufni mogą korzystać z tajnych danych klienta lub poświadczeń certyfikatu. Symetryczne wspólne tajemnice są generowane przez platformę tożsamości Microsoft. Poświadczenia certyfikatu to klucze asymetryczne przekazywane przez dewelopera. Aby uzyskać więcej informacji, zobacz poświadczenia certyfikatów uwierzytelniania aplikacji w platformie tożsamości Microsoft.
Aby uzyskać najlepsze zabezpieczenia, zalecamy używanie poświadczeń certyfikatowych. Klienci publiczni, którzy obejmują aplikacje natywne i aplikacje jednostronicowe, nie mogą używać sekretów 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 i uzyskaniu zgody od użytkownika, możesz zrealizować code na 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 strona Microsoft Entra admin center – App registrations przypisała do Twojej aplikacji. |
scope |
opcjonalny | 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 na platformie 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 pierwszej części procesu. |
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 dla przepływu kodu autoryzacji. |
code_verifier |
zalecane | To samo code_verifier, które zostało użyte do uzyskania kodu autoryzacji. 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 | Sekret aplikacji utworzony w portalu rejestracji aplikacji. Nie używaj sekretu aplikacji w aplikacji natywnej ani w aplikacji jednostronicowej, ponieważ client_secret nie można niezawodnie przechowywać na urządzeniach ani stronach internetowych. Jest to wymagane w przypadku aplikacji internetowych i internetowych interfejsów API, które mogą przechowywać client_secret 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, polegający na podawaniu poświadczeń bezpośrednio w nagłówku autoryzacji, zgodnie ze standardem RFC 6749, jest również obsługiwany. |
Żądanie tokenu dostępu z poświadczeniem 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, consumers i identyfikatory dzierżawy. Aby uzyskać więcej informacji, zobacz Punkty końcowe. |
client_id |
wymagane | Identyfikator aplikacji (klienta), który strona centrum administracyjnego Microsoft Entra – Rejestracje aplikacji przypisała do Twojej aplikacji. |
scope |
opcjonalny | 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 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_assertion_type |
wymagane w przypadku poufnych aplikacji internetowych | Wartość musi być ustawiona na urn:ietf:params:oauth:client-assertion-type:jwt-bearer, aby użyć poświadczeń certyfikatu. |
client_assertion |
wymagane w przypadku poufnych aplikacji internetowych | Asercja, czyli token internetowy JSON (JWT), który musisz utworzyć i podpisać przy użyciu certyfikatu zarejestrowanego jako poświadczenia dla aplikacji. Przeczytaj o poświadczeniach certyfikatu , aby dowiedzieć się, jak zarejestrować certyfikat i format potwierdzenia. |
Parametry są takie same jak w żądaniu przy użyciu wspólnego sekretu, z tą różnicą, że parametr client_secret jest zastępowany przez dwa parametry: 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 access_token jest prawidłowy. 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 zakres został zażądany. |
id_token |
Token sieciowy 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: Dostarczone tylko wtedy, gdy poproszono o zakres openid. |
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 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ź, czy parametr code_verifier był 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 Microsoft Entra ID lub nie została dodana do dzierżawy 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, ż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. |
interaction_required |
Non-standard, ponieważ zgodnie ze specyfikacją OIDC ten kod jest używany tylko na punkcie końcowym /authorize. Żą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 żądanie po krótkim 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 na punkcie końcowym /authorize zgodnie ze specyfikacjami OIDC. Zwracany, gdy parametr scope został użyty w procesie realizacji kodu, którego aplikacja kliencka nie ma uprawnień do żądania. |
Klient powinien wysłać użytkownika z powrotem do punktu końcowego /authorize z odpowiednim zakresem, aby uzyskać 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ć błąd invalid_request wskazujący, że wymiana tokenu między źródłami jest dozwolona tylko dla klienta typu "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ą ważne dla wszystkich uprawnień, na które klient już wyraził zgodę. Na przykład token odświeżania wydany w odpowiedzi na żądanie scope=mail.read, może być użyty do zażądania nowego tokenu dostępu dla 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ą, są unieważniane lub nie mają wystarczających uprawnień do wykonania akcji. Aplikacja musi być przygotowana na błędy zwracane przez punkt końcowy wystawiania tokenu oraz je obsługiwać. 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 w najwyższym poziomie, w pełnej nawigacji strony lub w oknie podręcznym, w przeglądarkach niewspierających plików cookie innych firm, takich jak Safari.
Tokeny odświeżania nie są odwoływane, gdy są używane do uzyskania 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 spa, token odświeżania wygasa po 24 godzinach. Dodatkowe tokeny odświeżania uzyskane przy użyciu tokenu odświeżania początkowego zachowują ten sam czas wygaśnięcia, dlatego aplikacje muszą być przygotowane do ponownego uruchomienia przepływu kodu autoryzacji, korzystając z uwierzytelniania interakcyjnego, aby uzyskać nowy token odświeżania co 24 godziny. Użytkownicy nie muszą wprowadzać swoich danych logowania i zwykle nawet nie widzą żadnego interfejsu 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 | Typ | 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, consumers i identyfikatory dzierżawy. Aby uzyskać więcej informacji, zobacz Punkty końcowe. |
client_id |
wymagane | Identyfikator aplikacji (klienta), który został przypisany do Twojej aplikacji przez centrum administracyjne Microsoft Entra – Rejestracje aplikacji. |
grant_type |
wymagane | Musi być refresh_token dla tej części przepływu kodu autoryzacji. |
scope |
opcjonalny | Rozdzielona spacjami lista zakresów. Zakresy wymagane w tym etapie muszą być równoważne lub podzbiorem zakresów wymaganych w pierwotnym authorization_code etapie żą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 platformie tożsamości Microsoft. |
refresh_token |
wymagane | Element refresh_token uzyskany w drugim etapie procesu. |
client_secret |
wymagane dla aplikacji internetowych | Tajny klucz aplikacji utworzony w portalu rejestracji aplikacji. Nie należy używać w aplikacji natywnej, ponieważ client_secret nie można niezawodnie przechowywać na urządzeniach. Jest to wymagane w przypadku aplikacji internetowych oraz interfejsów API, które mogą bezpiecznie przechowywać je 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 access_token jest prawidłowy. |
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_token, zobacz tokeny identyfikatorów platformy tożsamości Microsoft. Uwaga: Podano tylko wtedy, gdy openid zakres został zażądany. |
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). Odczytywanie tokenów jest przydatnym narzędziem do debugowania i nauki, jednak nie należy uzależniać od tego swojego kodu ani zakładać szczegółów dotyczących tokenów, które nie są przypisane do API pozostającego pod twoją kontrolą.
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
- Zapoznaj się z przykładami MSAL JS, aby rozpocząć kodowanie.
- Dowiedz się więcej o scenariuszach wymiany tokenów.