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

Przyznawanie kodu autoryzacji OAuth 2.0 może być używane w aplikacjach zainstalowanych na urządzeniu w celu uzyskania dostępu do chronionych zasobów, takich jak internetowe interfejsy API. Korzystając z implementacji protokołu OAuth 2.0 na platformie tożsamości firmy Microsoft, możesz dodać dostęp do logowania i interfejsu API do aplikacji mobilnych i klasycznych.

W tym artykule opisano sposób programowania bezpośrednio przy użyciu protokołu w aplikacji przy użyciu dowolnego języka. Jeśli to możliwe, zalecamy użycie obsługiwanych bibliotek uwierzytelniania firmy Microsoft (MSAL) w celu uzyskania tokenów i wywołania zabezpieczonych internetowych interfejsów API. Przyjrzyj się również przykładowym aplikacjom, które korzystają z pakietu MSAL.

Przepływ kodu autoryzacji OAuth 2.0 opisano w sekcji 4.1 specyfikacji OAuth 2.0. Służy do uwierzytelniania i autoryzacji w większości typów aplikacji, w tym aplikacji jednostronicowych, aplikacji internetowych i aplikacji zainstalowanych natywnie. Przepływ umożliwia aplikacjom bezpieczne uzyskiwanie access_tokens, które mogą służyć do uzyskiwania dostępu do zasobów zabezpieczonych przez platformę tożsamości firmy Microsoft, a także odświeżanie tokenów w celu uzyskania dodatkowych tokenów access_tokens i tokenów identyfikatorów dla zalogowanego użytkownika.

Diagram protokołu

Na wysokim poziomie cały przepływ uwierzytelniania dla aplikacji wygląda nieco następująco:

Przepływ kodu uwierzytelniania OAuth

Konfiguracja przekierowania URI jest wymagana dla aplikacji jednostronicowych

Przepływ kodu autoryzacji dla aplikacji jednostronicowych wymaga dodatkowej konfiguracji. Postępuj zgodnie z instrukcjami dotyczącymi tworzenia aplikacji jednostronicowej, aby poprawnie oznaczyć twój adres URI przekierowania jako włączony dla cors. Aby zaktualizować istniejący adres URI przekierowania w celu włączenia funkcji CORS, otwórz edytor manifestu i ustaw pole dla swojego przekierowania type URI spa na wartość w replyUrlsWithType sekcji . Możesz również kliknąć adres URI przekierowania w sekcji "Internet" na karcie Uwierzytelnianie i wybrać URI, do których chcesz przeprowadzić migrację przy użyciu przepływu kodu autoryzacji.

Typ spa przekierowania jest wstecznie zgodny z niejawnym przepływem. Aplikacje korzystające obecnie z niejawnego przepływu w celu uzyskania tokenów mogą bez problemów przechodzić do typu przekierowania URI i spa nadal korzystać z niejawnego przepływu.

Jeśli spróbujemy użyć przepływu kodu autoryzacji i zobaczymy ten błąd:

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.

Następnie odwiedź stronę rejestracji aplikacji i zaktualizuj jej adres URI przekierowania, aby wpisać spa .

Aplikacje nie mogą używać przekierowania URI z przepływów innych niż SPA, na przykład natywnych spa aplikacji lub przepływów poświadczeń klienta. W celu zapewnienia bezpieczeństwa usługa Azure AD zwróci błąd, jeśli spróbujemy użyć w tych scenariuszach adresu URI przekierowania, np. z aplikacji natywnej, która nie wysyła spa Origin nagłówka.

Żądanie kodu autoryzacji

Przepływ kodu autoryzacji rozpoczyna się od skierowania użytkownika do punktu /authorize końcowego. W tym żądaniu klient żąda od użytkownika openid offline_access uprawnień , i https://graph.microsoft.com/mail.read . Niektóre uprawnienia są ograniczone przez administratora, na przykład zapisywanie danych w katalogu organizacji przy użyciu usługi Directory.ReadWrite.All . Jeśli aplikacja zażąda dostępu do jednego z tych uprawnień od użytkownika organizacyjnego, zostanie wyświetlony 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, przeczytaj uprawnienia ograniczone przez administratora.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read%20api%3A%2F%2F
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Porada

Kliknij poniższy link, aby wykonać to żądanie. Po zalogowaniu przeglądarka powinna zostać przekierowana do adresu przy użyciu http://localhost/myapp/ code adresu na pasku adresu. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

Parametr Wymagane/opcjonalne Opis
tenant wymagane Wartość w ścieżce żądania może służyć do kontrolowania, kto {tenant} może zalogować się do aplikacji. Dozwolone wartości to common , organizations , i consumers identyfikatory dzierżawy. Aby uzyskać więcej informacji, zobacz podstawowe informacje o protokole.
client_id wymagane Identyfikator aplikacji (klienta), który Azure Portal — Rejestracje aplikacji środowisko przypisane do aplikacji.
response_type wymagane Musi zawierać code dla przepływu kodu autoryzacji. Może również obejmować id_token lub w przypadku korzystania z token przepływu hybrydowego.
redirect_uri wymagane Adres redirect_uri aplikacji, w którym aplikacja może wysyłać i odbierać odpowiedzi uwierzytelniania. Musi on dokładnie odpowiadać jednej z redirect_uris zarejestrowanej w portalu, z tą różnicą, że musi być zakodowany w adresie URL. W przypadku & aplikacji mobilnych należy użyć jednej z zalecanych wartości — (w przypadku aplikacji korzystających z przeglądarek osadzonych) lub (w przypadku aplikacji korzystających z https://login.microsoftonline.com/common/oauth2/nativeclient http://localhost przeglądarek systemowych).
scope wymagane Rozdzielana spacjami lista zakresów, na które użytkownik ma wyrazić zgodę. W przypadku części żądania może to obejmować wiele zasobów, umożliwiając aplikacji wyrażenie zgody na wiele internetowych interfejsów /authorize API, które chcesz wywołać.
response_mode zalecane Określa metodę, która ma być używana do wysyłania wynikowego tokenu z powrotem do aplikacji. Może być jedną z następujących czynności:

- query
- fragment
- form_post

query Dostarcza kod jako parametr ciągu zapytania w twoim przekierowaniu URI. Jeśli żądasz tokenu identyfikatora przy użyciu niejawnego przepływu, nie możesz użyć wartości określonej w specyfikacji query OpenID. Jeśli żądasz tylko kodu, możesz użyć , query fragment lub form_post . form_post polecenie wykonuje polecenie POST zawierające kod do twojego przekierowania URI.
state zalecane Wartość uwzględniona w żądaniu, która również zostanie zwrócona w odpowiedzi tokenu. Może to być ciąg dowolnej zawartości. Losowo wygenerowana unikatowa wartość jest zwykle używana do zapobiegania atakom fałszerczym żądań między witrynami. Wartość może również zakodować informacje o stanie użytkownika w aplikacji przed zażądaniem uwierzytelnienia, takie jak strona lub widok, na którym się znajduje.
prompt optional Wskazuje wymagany typ interakcji z użytkownikiem. Jedyne prawidłowe wartości w tej chwili to login , none , i consent select_account .

- prompt=login Spowoduje to wymuś na użytkowniku wprowadzenie poświadczeń dla tego żądania, negując logowanie pojedynczej.
- prompt=none jest przeciwieństwem — zapewni to, że użytkownik nie będzie w ogóle wyświetlać żadnego interaktywnego monitu. Jeśli nie można ukończyć żądania w trybie dyskretnym za pośrednictwem logowania pojedynczego, platforma tożsamości firmy Microsoft zwróci interaction_required błąd.
- prompt=consent Spowoduje to wyzwolenie okna dialogowego zgody OAuth po tym, jak użytkownik się logowania, prosząc użytkownika o udzielenie uprawnień do aplikacji.
- prompt=select_account spowoduje przerwanie logowania się za pomocą logowania, zapewniając możliwość wyboru konta i wyświetlanie listy wszystkich kont w sesji lub dowolnym zapamiętanych kontach albo wybranie opcji użycia całkowicie innego konta.
login_hint optional Może służyć do wstępnego wypełnienia pola nazwy użytkownika/adresu e-mail na stronie logowania użytkownika, jeśli wcześniej znasz jego nazwę użytkownika. Często aplikacje będą używać tego parametru podczas ponownego uwierzytelniania, po wyodrębnieniu nazwy użytkownika z poprzedniego logowania przy użyciu preferred_username oświadczenia.
domain_hint optional Jeśli ta funkcja zostanie uwzględniona, pominie proces odnajdywania opartego na wiadomościach e-mail, który użytkownik przechodzi na stronie logowania, co spowoduje nieco usprawnione środowisko użytkownika — na przykład wysłanie go do dostawcy tożsamości federacji. Często aplikacje będą używać tego parametru podczas ponownego uwierzytelniania, wyodrębniając parametr tid z poprzedniego logowania. Jeśli wartość tid oświadczenia to , należy użyć 9188040d-6c67-4c5b-b112-36a304b66dad . domain_hint=consumers W przeciwnym razie domain_hint=organizations użyj .
code_challenge zalecane/wymagane Służy do zabezpieczania uprawnień kodu autoryzacji za pośrednictwem klucza weryfikacji dla wymiany kodu (PKCE). Wymagane, code_challenge_method jeśli jest dołączony. Aby uzyskać więcej informacji, zobacz PKCE RFC. Jest to teraz zalecane dla wszystkich typów aplikacji — zarówno klientów publicznych, jak i poufnych — i wymagane przez platformę tożsamości firmy Microsoft dla aplikacji jednostronicowych korzystających z przepływu kodu autoryzacji.
code_challenge_method zalecane/wymagane Metoda używana do kodowania code_verifier code_challenge parametru . Powinno to być , ale specyfikacja zezwala na użycie jeśli S256 z plain jakiegoś powodu klient nie obsługuje SHA256.

W przypadku wykluczenia code_challenge przyjmuje się, że jest to zwykły tekst, jeśli code_challenge został uwzględniony. Platforma tożsamości firmy Microsoft obsługuje zarówno system plain , jak i S256 . Aby uzyskać więcej informacji, zobacz PKCE RFC. Jest to wymagane w przypadku aplikacji jednostronicowych korzystających z przepływu kodu autoryzacji.

W tym momencie użytkownik zostanie poproszony o wprowadzenie poświadczeń i ukończenie uwierzytelniania. Platforma tożsamości firmy Microsoft gwarantuje również, że użytkownik wyraził zgodę na uprawnienia wskazane w scope parametrze zapytania. Jeśli użytkownik nie wyraził zgody na dowolne z tych uprawnień, poprosi go o zgodę na wymagane uprawnienia. Szczegółowe informacje o uprawnieniach, zgody i aplikacjach wielodostępnych znajdują się tutaj.

Gdy użytkownik uwierzytelni się i udziela zgody, platforma tożsamości firmy Microsoft zwróci odpowiedź do aplikacji we wskazanym miejscu , używając metody określonej redirect_uri w response_mode parametrze .

Pomyślna odpowiedź

Odpowiedź pomyślna przy użyciu response_mode=query funkcji wygląda następująco:

GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
Parametr Opis
code Aplikacja authorization_code żądana przez aplikację. Aplikacja może użyć kodu autoryzacji, aby zażądać tokenu dostępu dla zasobu docelowego. Authorization_codes są krótkotrwałe, zazwyczaj wygasają po około 10 minutach.
state Jeśli parametr stanu 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.

Możesz również otrzymać token identyfikatora, jeśli zażądasz tokenu i włączono niejawne udzielenie w rejestracji aplikacji. Jest to czasami nazywane "przepływem hybrydowym"i jest używane przez struktury, takie jak ASP.NET.

Odpowiedź z błędem

Odpowiedzi na błędy mogą być również wysyłane do usługi redirect_uri , aby aplikacja może 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, które występują, i może służyć do reagowania na błędy.
error_description Określony komunikat o błędzie, który może pomóc deweloperowi w zidentyfikowaniu głównej przyczyny błędu uwierzytelniania.

Kody błędów błędów punktów końcowych autoryzacji

W poniższej tabeli opisano różne kody błędów, które mogą być zwracane w error parametrze odpowiedzi na błąd.

Kod błędu Opis Akcja klienta
invalid_request Błąd protokołu, taki jak brak wymaganego parametru. Napraw i prześlij ponownie żądanie. Jest to błąd programistyki zwykle przechwycony podczas testowania początkowego.
unauthorized_client Aplikacja kliency nie może żądać kodu autoryzacji. Ten błąd występuje zwykle, gdy aplikacja klienca nie jest zarejestrowana w usłudze Azure AD lub nie została dodana do dzierżawy usługi Azure AD użytkownika. Aplikacja może monitować użytkownika o instrukcje dotyczące instalowania aplikacji i dodawania jej do usługi Azure AD.
access_denied Odmowa zgody właściciela zasobu Aplikacja kliency może powiadomić użytkownika, że nie może kontynuować pracy, chyba że użytkownik na to zgotuje.
unsupported_response_type Serwer autoryzacji nie obsługuje typu odpowiedzi w żądaniu. Napraw i prześlij ponownie żądanie. Jest to błąd programistyki zwykle przechwycony podczas testowania początkowego. W przypadku korzystania z przepływu hybrydowegoprogram sygnalizuje, że należy włączyć ustawienie przyznawania niejawnego 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 kliency może wyjaśnić użytkownikowi, że jej 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 kliency może wyjaśnić użytkownikowi, że jej odpowiedź jest opóźniona z powodu tymczasowego warunku.
invalid_resource Zasób docelowy jest nieprawidłowy, ponieważ nie istnieje, usługa Azure AD 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 o instrukcje dotyczące instalowania aplikacji i dodawania jej do usługi Azure AD.
login_required Znaleziono zbyt wielu użytkowników lub nie znaleziono ich Klient zażądał uwierzytelniania dyskretnego ( ), ale nie można prompt=none odnaleźć jednego użytkownika. Może to oznaczać, że w sesji jest aktywnych wielu użytkowników lub nie ma żadnych użytkowników. Uwzględnia to wybraną dzierżawę (na przykład jeśli są aktywne dwa konta usługi Azure AD i jedno konto konto Microsoft i zostanie wybrane, będzie działać uwierzytelnianie consumers dyskretne).
interaction_required Żądanie wymaga interakcji z użytkownikiem. Wymagany jest dodatkowy krok uwierzytelniania lub zgoda. Ponów próbę żądania bez prompt=none .

Żądanie tokenu identyfikatora również (przepływ hybrydowy)

Aby dowiedzieć się, kim jest użytkownik przed zrealizowaniem kodu autoryzacji, aplikacje często żądają tokenu identyfikatora podczas żądania kodu autoryzacji. Jest to nazywane przepływem hybrydowym, ponieważ łączy niejawne udzielenie z przepływem kodu autoryzacji. Przepływ hybrydowy jest często używany w aplikacjach internetowych, które chcą renderować stronę 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, z których wszystkie są wymagane do żądania tokenu identyfikatora: nowe zakresy, nowy response_type i nowy parametr nonce zapytania.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&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 parametru wskazuje serwerowi, że aplikacja chce mieć id_token token identyfikatora w odpowiedzi z punktu /authorize końcowego.
scope Wymagane W przypadku tokenów identyfikatorów należy zaktualizować w celu dołączyć zakresy tokenów identyfikatorów — openid , i opcjonalnie profile oraz email .
nonce Wymagane Wartość uwzględniona w żądaniu wygenerowana przez aplikację, która zostanie uwzględniona w wynikowej id_token jako oświadczenie. Następnie aplikacja może zweryfikować tę wartość, aby ograniczyć ataki związane z powtarzania tokenem. 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 ma być używana do wysyłania wynikowego tokenu z powrotem do aplikacji. Wartość domyślna query to tylko dla kodu autoryzacji, ale jeśli żądanie zawiera id_token fragment response_type . Zaleca się jednak używanie przez aplikacje funkcji form_post , szczególnie w przypadku używania jako http:/localhost przekierowania URI.

Użycie funkcji jako trybu odpowiedzi powoduje problemy w przypadku aplikacji internetowych, które odczytają kod z przekierowania, ponieważ przeglądarki nie przekażą fragment fragmentu do serwera internetowego. W takich sytuacjach aplikacje powinny używać trybu odpowiedzi, aby upewnić się, że wszystkie form_post dane są wysyłane do serwera.

Pomyślna odpowiedź

Pomyślna odpowiedź przy response_mode=fragment użyciu funkcji wygląda następująco:

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 i zazwyczaj wygasają po około 10 minutach.
id_token Token identyfikatora dla użytkownika wystawiony za pośrednictwem niejawnego udzielenia. Zawiera specjalne c_hash oświadczenie, które jest skrótem code w tym samym żądaniu.
state Jeśli parametr stanu 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 mogą korzystać z wpisów tajnych klienta (symetrycznie udostępnionych wpisów tajnych generowanych przez platformę tożsamości firmy Microsoft) i poświadczeń certyfikatów (kluczyasymetrycznych przekazanych przez dewelopera). Aby uzyskać najlepsze zabezpieczenia, zalecamy użycie poświadczeń certyfikatu. Klienci publiczni (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 prawidłowo wskazują typ aplikacji i są unikatowe.

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

Teraz, gdy użytkownik nabył authorization_code uprawnienie, możesz zrealizować element dla code access_token żądanego zasobu. W tym celu należy POST wysłać żądanie do punktu /token końcowego:

// 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=6731de76-14a6-49ae-97bc-6eba6914391e
&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=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps. This secret needs to be URL-Encoded.

Porada

Spróbuj wykonać to żądanie w programie Postman! (Nie zapomnij zastąpić ) code  Spróbuj uruchomić to żądanie w programie Postman

Parametr Wymagane/opcjonalne Opis
tenant wymagane Wartość w ścieżce żądania może służyć do kontrolowania, kto {tenant} może zalogować się do aplikacji. Dozwolone wartości to common , organizations , i consumers identyfikatory dzierżawy. Aby uzyskać więcej informacji, zobacz podstawowe informacje o protokole.
client_id wymagane Identyfikator aplikacji (klienta), który Azure Portal — Rejestracje aplikacji stronie przypisanej do aplikacji.
scope optional Rozdzielana spacjami lista zakresów. Wszystkie zakresy muszą pochodzić z jednego zasobu wraz z zakresami OIDC profile (, openid , email ). Aby uzyskać bardziej szczegółowy opis zakresów, zapoznaj się z uprawnieniami, zgodami i zakresami. Jest to rozszerzenie firmy Microsoft do przepływu kodu autoryzacji, które ma umożliwić aplikacjom deklarowanie zasobu, dla którego chcą uzyskać token podczas realizacji tokenu.
code wymagane Ten authorization_code uzyskany w pierwszym odgałędzie przepływu.
redirect_uri wymagane Ta sama redirect_uri, która została użyta do uzyskania authorization_code.
grant_type wymagane Musi być authorization_code dla przepływu kodu autoryzacji.
code_verifier zalecane Ta sama code_verifier, która została użyta do uzyskania authorization_code. Wymagane, jeśli w żądaniu udzielenia kodu autoryzacji był używany kod PKCE. Aby uzyskać więcej informacji, zobacz PKCE RFC.
client_secret wymagane dla poufnych aplikacji internetowych Klucz tajny aplikacji utworzony w portalu rejestracji aplikacji dla aplikacji. Nie należy używać tego tajnego dokumentu aplikacji w aplikacji natywnej ani aplikacji jednostronicowej, ponieważ nie można niezawodnie przechowywać client_secrets na urządzeniach ani na stronach internetowych. Jest to wymagane w przypadku aplikacji internetowych i internetowych interfejsów API, które mają możliwość bezpiecznego przechowywania client_secret po stronie serwera. Podobnie jak wszystkie parametry omówione w tym miejscu, klucz tajny klienta musi być zakodowany w adresie URL przed jego wysłaniem. Krok zazwyczaj jest wykonywany przez zestaw SDK. Aby uzyskać więcej informacji na temat kodowania URI, zobacz URI Generic Syntax specification (Specyfikacja składni ogólnej URI).

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

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

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&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ść w ścieżce żądania może służyć do kontrolowania, kto {tenant} może zalogować się do aplikacji. Dozwolone wartości to common , organizations , i consumers identyfikatory dzierżawy. Aby uzyskać więcej informacji, zobacz podstawowe informacje o protokole.
client_id wymagane Identyfikator aplikacji (klienta), który Azure Portal Rejestracje aplikacji stronie przypisanej do aplikacji.
scope optional Rozdzielana spacjami lista zakresów. Wszystkie zakresy muszą pochodzić z jednego zasobu wraz z zakresami OIDC profile (, openid , email ). Aby uzyskać bardziej szczegółowy opis zakresów, zapoznaj się z uprawnieniami, zgodami i zakresami. Jest to rozszerzenie firmy Microsoft do przepływu kodu autoryzacji, które ma umożliwić aplikacjom deklarowanie zasobu, dla którego chcą uzyskać token podczas realizacji tokenu.
code wymagane Ten authorization_code uzyskany w pierwszym odgałędzie przepływu.
redirect_uri wymagane Ta sama redirect_uri, która została użyta do uzyskania authorization_code.
grant_type wymagane Musi być authorization_code dla przepływu kodu autoryzacji.
code_verifier zalecane Ta sama code_verifier, która została użyta do uzyskania authorization_code. Wymagane, jeśli w żądaniu udzielenia kodu autoryzacji był używany kod PKCE. Aby uzyskać więcej informacji, zobacz PKCE RFC.
client_assertion_type wymagane dla poufnych aplikacji internetowych Wartość musi być ustawiona na urn:ietf:params:oauth:client-assertion-type:jwt-bearer , aby można było używać poświadczeń certyfikatu.
client_assertion wymagane dla poufnych aplikacji internetowych Potwierdzenie (token internetowy JSON), które należy 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.

Zwróć uwagę, że parametry są takie same jak w przypadku żądania przez wspólny klucz tajny, z tą różnicą, że parametr jest zastępowany przez client_secret dwa parametry: a client_assertion_type i client_assertion .

Pomyślna odpowiedź

Pomyślna odpowiedź tokenu będzie wyglądać tak:

{
    "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 usługa Azure AD, jest Bearer
expires_in Czas ważności tokenu dostępu (w sekundach).
scope Zakresy, dla których access_token jest prawidłowy. Opcjonalne — jest to wartość standardowa, a w przypadku pominięcia token będzie dotyczył zakresów żądanych na początkowym etapie przepływu.
refresh_token Token odświeżania protokołu OAuth 2.0. Aplikacja może użyć tego tokenu, aby uzyskać dodatkowe tokeny dostępu po wygaśnięciu bieżącego tokenu dostępu. Refresh_tokens są długotrwałe i mogą służyć do zachowania dostępu do zasobów przez dłuższy czas. Aby uzyskać więcej informacji na temat odświeżania tokenu dostępu, zapoznaj się z sekcją poniżej.
Uwaga: Podano tylko offline_access wtedy, gdy zażądano zakresu.
id_token A JSON Web Token (JWT). Aplikacja może zdekodować segmenty tego tokenu, aby zażądać informacji o zalogowanym użytkowniku. Aplikacja może buforować wartości i wyświetlać je, a klienci poufni mogą używać ich do autoryzacji. Aby uzyskać więcej informacji na id_tokens, zobacz id_token reference .
Uwaga: Podano tylko openid wtedy, gdy zażądano zakresu.

Odpowiedź z błędem

Odpowiedzi na błędy będą wyglądać tak:

{
  "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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
Parametr Opis
error Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów, które występują, i może służyć do reagowania na błędy.
error_description Określony komunikat o błędzie, który może pomóc deweloperowi w zidentyfikowaniu głównej przyczyny błędu uwierzytelniania.
error_codes Lista kodów błędów specyficznych dla 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 składników.

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 je ponownie
invalid_grant Kod autoryzacji lub weryfikator kodu PKCE jest nieprawidłowy lub wygasł. Spróbuj wykonać nowe żądanie do punktu /authorize końcowego i sprawdź, czy code_verifier jest poprawny.
unauthorized_client Uwierzytelniony klient nie ma autoryzacji do używania tego typu autoryzacji. Dzieje się tak zwykle, gdy aplikacja kliencyjna nie jest zarejestrowana w usłudze Azure AD lub nie została dodana do dzierżawy usługi Azure AD użytkownika. Aplikacja może monitować użytkownika o instrukcje dotyczące instalowania aplikacji i dodawania jej do usługi Azure AD.
invalid_client Uwierzytelnianie klienta nie powiodło się. Poświadczenia klienta są nieprawidłowe. Aby rozwiązać ten problem, administrator aplikacji aktualizuje poświadczenia.
unsupported_grant_type Serwer autoryzacji nie obsługuje typu autoryzacji. Zmień typ udzielenia w żądaniu. Ten typ błędu powinien wystąpić tylko podczas opracowywania i być wykrywany podczas wstępnego testowania.
invalid_resource Zasób docelowy jest nieprawidłowy, ponieważ nie istnieje, usługa Azure AD nie może go znaleźć lub nie jest poprawnie skonfigurowany. Oznacza to, że zasób, jeśli istnieje, nie został skonfigurowany w dzierżawie. Aplikacja może monitować użytkownika o instrukcje dotyczące instalowania aplikacji i dodawania jej do usługi Azure AD.
interaction_required Nieujemne, ponieważ specyfikacja OIDC wymaga tego tylko w punkcie /authorize końcowym. Żądanie wymaga interakcji z użytkownikiem. Na przykład wymagany jest dodatkowy krok uwierzytelniania. Ponów /authorize próbę żądania z tym samym zakresem.
temporarily_unavailable Serwer jest tymczasowo zbyt zajęty, aby obsłużyć żądanie. Ponów żądanie po niewielkim opóźnieniu. Aplikacja kliency może wyjaśnić użytkownikowi, że jej odpowiedź jest opóźniona z powodu tymczasowego warunku.
consent_required Żądanie wymaga zgody użytkownika. Ten błąd jest niestandardowych, ponieważ zwykle jest zwracany tylko w punkcie /authorize końcowym zgodnie ze specyfikacją OIDC. Zwracany, gdy w przepływie realizacji kodu został użyty parametr, który aplikacja klienca nie scope ma uprawnień do żądania. Klient powinien wysłać użytkownika z powrotem do punktu końcowego z /authorize prawidłowym zakresem, aby wyzwolić zgodę.
invalid_scope Zakres żądany przez aplikację jest nieprawidłowy. Zaktualizuj wartość parametru zakresu w żądaniu uwierzytelniania na prawidłową wartość.

Uwaga

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

Korzystanie z tokenu dostępu

Teraz, gdy pomyślnie uzyskasz token , możesz użyć tokenu w żądaniach do internetowych interfejsów API, uwzględniając access_token go w Authorization nagłówku:

Porada

Wykonaj to żądanie w programie Postman! (Najpierw zastąp Authorization nagłówek)  Spróbuj uruchomić to żądanie w programie Postman

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

Odświeżanie tokenu dostępu

Access_tokens są krótkotrwałe i należy je odświeżyć po wygaśnięciu, aby nadal uzyskać dostęp do zasobów. Możesz to zrobić, przesyłając kolejne żądanie do punktu POST końcowego, tym razem podając /token refresh_token zamiast code . Tokeny odświeżania są prawidłowe dla wszystkich uprawnień, na które klient otrzymał już zgodę — w związku z tym token odświeżania wystawiony dla żądania może służyć do żądania scope=mail.read nowego tokenu dostępu dla scope=api://contoso.com/api/UseResource usługi .

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ą odwoływowane lub nie mają wystarczających uprawnień dla żądanej akcji. Aplikacja musi prawidłowo oczekiwać błędów zwracanych przez punkt końcowy wystawiania tokenów i obsługiwać je. Jednak aplikacje jednostronicowe uzyskają token z 24-godzinnym okresem istnienia, co wymaga nowego uwierzytelniania każdego dnia. Można to zrobić w trybie dyskretnym w ramce iframe, gdy pliki cookie innych firm są włączone, ale należy to zrobić w ramce najwyższego poziomu (na całej stronie lub w okienku podręcznym) w przeglądarkach bez plików cookie innych firm, takich jak Safari.

Mimo że tokeny odświeżania nie są odwoływowane w przypadku uzyskiwania nowych tokenów dostępu, oczekuje się odrzucenia starego tokenu odświeżania. Specyfikacja protokołu OAuth 2.0 mówi: "Serwer autoryzacji MOŻE wydać nowy token odświeżania. W takim 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 klientowi nowego tokenu odświeżania".

Ważne

W przypadku tokenów odświeżania wysyłanych do przekierowania URI zarejestrowanego jako spa token odświeżania wygaśnie po 24 godzinach. Dodatkowe tokeny odświeżania uzyskane przy użyciu tokenu odświeżania początkowego przeniosą ten czas wygaśnięcia, dlatego aplikacje muszą być przygotowane do ponownego uruchomienia przepływu kodu autoryzacji przy użyciu interaktywnego uwierzytelniania w celu uzyskania nowego tokenu odświeżania co 24 godziny. Użytkownicy nie muszą wprowadzać swoich poświadczeń i zazwyczaj nie będą nawet widzieć żadnego środowiska użytkownika, tylko ponownego załadowania aplikacji — ale przeglądarka musi odwiedzić stronę logowania w ramce najwyższego poziomu, aby zobaczyć sesję logowania. Jest to spowodowane funkcjami prywatności w przeglądarkach, które blokują plikicookie 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=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh      // NOTE: Only required for web apps. This secret needs to be URL-Encoded

Porada

Spróbuj wykonać to żądanie w programie Postman! (Nie zapomnij zastąpić ) refresh_token  Spróbuj uruchomić to żądanie w programie Postman

Parametr Typ Opis
tenant wymagane Wartość w ścieżce żądania może służyć do kontrolowania, kto {tenant} może zalogować się do aplikacji. Dozwolone wartości to common , organizations , i consumers identyfikatory dzierżawy. Aby uzyskać więcej informacji, zobacz podstawowe informacje o protokole.
client_id wymagane Identyfikator aplikacji (klienta), który Azure Portal — Rejestracje aplikacji środowisko przypisane do aplikacji.
grant_type wymagane Musi być refresh_token dla tej części przepływu kodu autoryzacji.
scope optional Rozdzielana spacjami lista zakresów. Zakresy żądane w tej części muszą być równoważne lub podzbioru zakresów żądanych w oryginalnej części authorization_code żądania. Jeśli zakresy określone w tym żądaniu obejmują wiele serwerów zasobów, platforma tożsamości firmy Microsoft zwróci token dla zasobu określonego w pierwszym zakresie. Aby uzyskać bardziej szczegółowy opis zakresów, zapoznaj się z uprawnieniami, zgodą i zakresami.
refresh_token wymagane Ten refresh_token uzyskany 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_secrets nie można niezawodnie przechowywać na urządzeniach. Jest to wymagane w przypadku aplikacji internetowych i internetowych interfejsów API, które mają możliwość bezpiecznego przechowywania client_secret po stronie serwera. Ten klucz tajny musi być zakodowany w adresie URL. Aby uzyskać więcej informacji, zobacz specyfikację składni ogólnej URI.

Pomyślna odpowiedź

Pomyślna odpowiedź tokenu będzie wyglądać tak:

{
    "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 usługa Azure AD, jest Bearer
expires_in Czas ważności tokenu dostępu (w sekundach).
scope Zakresy, dla których access_token jest prawidłowy.
refresh_token Nowy token odświeżania protokołu OAuth 2.0. Należy zastąpić stary token odświeżania nowo uzyskany tokenem odświeżania, aby zapewnić, że tokeny odświeżania pozostaną ważne tak długo, jak to możliwe.
Uwaga: Podano tylko offline_access wtedy, gdy zażądano zakresu.
id_token Niepodpisane JSON Web Token (JWT). Aplikacja może zdekodować segmenty tego tokenu, aby zażądać informacji o zalogowanym użytkowniku. Aplikacja może buforować wartości i wyświetlać je, ale nie powinna polegać na nich w przypadku jakichkolwiek granic autoryzacji ani zabezpieczeń. Aby uzyskać więcej informacji na id_tokens, zobacz id_token reference .
Uwaga: Podano tylko openid wtedy, gdy zażądano zakresu.

Odpowiedź o błędzie

{
  "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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
Parametr Opis
error Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów, które występują, i może służyć do reagowania na błędy.
error_description Określony komunikat o błędzie, który może pomóc deweloperowi w zidentyfikowaniu głównej przyczyny błędu uwierzytelniania.
error_codes Lista kodów błędów specyficznych dla 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 składników.

Opis kodów błędów i zalecanej akcji klienta zawiera temat Kody błędów dla błędów punktu końcowego tokenu.