Autoryzowanie dostępu do aplikacji internetowych usługi Azure Active Directory przy użyciu przepływu udzielania kodu OAuth 2.0

  • Artykuł

Ostrzeżenie

Ta zawartość dotyczy starszego punktu końcowego Azure AD w wersji 1.0. Użyj Platforma tożsamości Microsoft dla nowych projektów.

Uwaga

Jeśli nie poinformujesz serwera, jaki zasób ma być wywoływany, serwer nie wyzwoli zasad dostępu warunkowego dla tego zasobu. Aby mieć wyzwalacz uwierzytelniania wieloskładnikowego, musisz uwzględnić zasób w adresie URL.

Przy użyciu protokołu OAuth 2.0 usługa Azure Active Directory (Azure AD) umożliwia autoryzację dostępu do aplikacji internetowych i internetowych interfejsów API w dzierżawie usługi Azure AD. Ten przewodnik jest niezależny od języka i opisuje sposób wysyłania i odbierania komunikatów HTTP bez używania żadnej z naszych bibliotek typu open source.

Przepływ kodu autoryzacji OAuth 2.0 został opisany w sekcji 4.1 specyfikacji OAuth 2.0. Służy do przeprowadzania uwierzytelniania i autoryzacji w większości typów aplikacji, w tym aplikacji internetowych i natywnie zainstalowanych aplikacji.

Rejestrowanie aplikacji w dzierżawie usługi AD

Najpierw zarejestruj aplikację w dzierżawie usługi Azure Active Directory (Azure AD). Spowoduje to nadanie aplikacji identyfikatora oraz umożliwi jej otrzymywanie tokenów.

  1. Zaloguj się w witrynie Azure Portal.

  2. Wybierz dzierżawę Azure AD, wybierając konto w prawym górnym rogu strony, a następnie wybierając nawigację Przełącz katalog, a następnie wybierając odpowiednią dzierżawę.

    • Pomiń ten krok, jeśli masz tylko jedną dzierżawę Azure AD w ramach konta lub jeśli wybrano już odpowiednią dzierżawę Azure AD.

  3. W Azure Portal wyszukaj i wybierz pozycję Azure Active Directory.

  4. W menu po lewej stronie usługi Azure Active Directory wybierz pozycję Rejestracje aplikacji, a następnie wybierz pozycję Nowa rejestracja.

  5. Postępuj zgodnie z monitami i utwórz nową aplikację. Nie ma znaczenia, czy jest to aplikacja internetowa lub aplikacja publiczna (mobilna & klasyczna) na potrzeby tego samouczka, ale jeśli chcesz użyć konkretnych przykładów dla aplikacji internetowych lub publicznych aplikacji klienckich, zapoznaj się z naszymi przewodnikami Szybki start.

    • Nazwa to nazwa aplikacji; opisuje aplikację innym użytkownikom.
    • W obszarze Obsługiwane typy kont wybierz pozycję Konta w dowolnym katalogu organizacyjnym i konta osobiste Microsoft.
    • Podaj identyfikator URI przekierowania. W przypadku aplikacji internetowych jest to podstawowy adres URL aplikacji, pod którym użytkownicy mogą się logować. Na przykład http://localhost:12345. W przypadku klienta publicznego (mobilnego & desktop) Azure AD używa go do zwracania odpowiedzi tokenu. Wprowadź wartość specyficzną dla swojej aplikacji. Na przykład http://MyFirstAADApp.

  6. Po zakończeniu rejestracji Azure AD przypisze aplikacji unikatowy identyfikator klienta (identyfikator aplikacji). Ta wartość jest potrzebna w następnych sekcjach, więc skopiuj ją ze strony aplikacji.

  7. Aby znaleźć aplikację w Azure Portal, wybierz pozycję Rejestracje aplikacji, a następnie wybierz pozycję Wyświetl wszystkie aplikacje.

Przepływ autoryzacji OAuth 2.0

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

Przepływ kodu uwierzytelniania OAuth

Żądanie kodu autoryzacji

Przepływ kodu autoryzacji rozpoczyna się od klienta kierującego użytkownika do punktu końcowego /authorize . W tym żądaniu klient wskazuje uprawnienia, które musi uzyskać od użytkownika. Punkt końcowy autoryzacji OAuth 2.0 dla dzierżawy można uzyskać, wybierając pozycję Rejestracje aplikacji > Punkty końcowe w Azure Portal.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%3A12345
&response_mode=query
&resource=https%3A%2F%2Fservice.contoso.com%2F
&state=12345
Parametr Typ Opis
Dzierżawy wymagane Wartość {tenant} w ścieżce żądania może służyć do kontrolowania, kto może zalogować się do aplikacji. Dozwolone wartości to identyfikatory dzierżawy, na przykład 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 lub contoso.onmicrosoft.comcommon dla tokenów niezależnych od dzierżawy
client_id wymagane Identyfikator aplikacji przypisany do aplikacji po zarejestrowaniu jej w Azure AD. Można to znaleźć w Azure Portal. Kliknij pozycję Azure Active Directory na pasku bocznym usług, kliknij pozycję Rejestracje aplikacji i wybierz aplikację.
response_type wymagane Musi zawierać code przepływ kodu autoryzacji.
redirect_uri zalecane Redirect_uri aplikacji, w której można wysyłać i odbierać odpowiedzi uwierzytelniania przez aplikację. Musi dokładnie odpowiadać jednemu z redirect_uris, który został zarejestrowany w portalu, z wyjątkiem tego, że musi być zakodowany w adresie URL. W przypadku aplikacji natywnych & mobilnych należy użyć wartości domyślnej https://login.microsoftonline.com/common/oauth2/nativeclient.
response_mode optional Określa metodę, która powinna służyć do wysyłania wynikowego tokenu z powrotem do aplikacji. Może to być query, fragmentlub form_post. query Dostarcza kod jako parametr ciągu zapytania w identyfikatorze URI przekierowania. Jeśli żądasz tokenu identyfikatora przy użyciu przepływu niejawnego, nie możesz użyć query wartości określonej w specyfikacji OpenID. Jeśli żądasz tylko kodu, możesz użyć polecenia query, fragmentlub form_post. form_post wykonuje post zawierający kod do identyfikatora URI przekierowania. Wartość domyślna to query przepływ kodu.
stan zalecane Wartość uwzględniona w żądaniu, która jest również zwracana w odpowiedzi tokenu. Losowo wygenerowana unikatowa wartość jest zwykle używana do zapobiegania fałszerzowaniu żądań między witrynami. Stan jest również używany do kodowania informacji o stanie użytkownika w aplikacji przed wystąpieniem żądania uwierzytelnienia, na przykład strony lub widoku, na której się znajdował.
zasób zalecane Identyfikator URI identyfikatora aplikacji docelowego internetowego interfejsu API (zabezpieczony zasób). Aby znaleźć identyfikator URI identyfikatora aplikacji, w Azure Portal kliknij pozycję Azure Active Directory, kliknij pozycję Rejestracje aplikacji, otwórz stronę Ustawienia aplikacji, a następnie kliknij pozycję Właściwości. Może to być również zasób zewnętrzny, taki jak https://graph.microsoft.com. Jest to wymagane w jednym z żądań autoryzacji lub tokenu. Aby zapewnić mniej monitów o uwierzytelnienie, umieść je w żądaniu autoryzacji, aby upewnić się, że zgoda zostanie odebrana od użytkownika.
scope Ignorowane W przypadku aplikacji Azure AD w wersji 1 zakresy muszą być statycznie skonfigurowane w Azure Portal w obszarze Ustawienia aplikacji, Wymagane uprawnienia.
Wierszu optional Określ wymagany typ interakcji użytkownika.

Prawidłowe wartości:

logowanie: użytkownik powinien zostać poproszony o ponowne uwierzytelnienie.

select_account: użytkownik jest monitowany o wybranie konta, przerywając logowanie jednokrotne. Użytkownik może wybrać istniejące zalogowane konto, wprowadzić swoje poświadczenia dla zapamiętanego konta lub całkowicie użyć innego konta.

zgoda: udzielono zgody użytkownika, ale należy je zaktualizować. Użytkownik powinien zostać poproszony o wyrażenie zgody.

admin_consent: Administrator powinien zostać poproszony o zgodę w imieniu wszystkich użytkowników w swojej organizacji
login_hint optional Może służyć do wstępnego wypełniania pola nazwy użytkownika/adresu e-mail na stronie logowania użytkownika, jeśli znasz nazwę użytkownika z wyprzedzeniem. Często aplikacje używają tego parametru podczas ponownego uwierzytelniania, po wyodrębnieniu nazwy użytkownika z poprzedniego logowania przy użyciu preferred_username oświadczenia.
domain_hint optional Zawiera wskazówkę dotyczącą dzierżawy lub domeny, która powinna być używana przez użytkownika do logowania. Wartość domain_hint jest zarejestrowaną domeną dla dzierżawy. Jeśli dzierżawa jest sfederowana z katalogiem lokalnym, usługa AAD przekierowuje do określonego serwera federacyjnego dzierżawy.
code_challenge_method zalecane Metoda używana do kodowania code_verifier parametru code_challenge . Może być jednym z elementów plain lub S256. W przypadku wykluczenia przyjmuje się, że jest to zwykły tekst, code_challenge jeśli code_challenge jest dołączony. Usługa Azure AAD w wersji 1.0 obsługuje elementy i plainS256. Aby uzyskać więcej informacji, zobacz dokument RFC PKCE.
code_challenge zalecane Służy do zabezpieczania udzielania kodu autoryzacji za pośrednictwem klucza dowodowego dla wymiany kodu (PKCE) z natywnego lub publicznego klienta. Wymagane, jeśli code_challenge_method jest uwzględniona. Aby uzyskać więcej informacji, zobacz dokument RFC PKCE.

Uwaga

Jeśli użytkownik jest częścią organizacji, administrator organizacji może wyrazić zgodę lub odrzucić w imieniu użytkownika lub zezwolić użytkownikowi na wyrażanie zgody. Użytkownik ma możliwość wyrażenia zgody tylko wtedy, gdy administrator na to zezwoli.

Na tym etapie użytkownik jest proszony o wprowadzenie poświadczeń i zgodę na uprawnienia żądane przez aplikację w Azure Portal. Gdy użytkownik uwierzytelnia się i udziela zgody, Azure AD wysyła odpowiedź do aplikacji na redirect_uri adres w żądaniu przy użyciu kodu.

Pomyślna odpowiedź

Pomyślna odpowiedź może wyglądać następująco:

GET  HTTP/1.1 302 Found
Location: http://localhost:12345/?code= AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA&session_state=7B29111D-C220-4263-99AB-6F6E135D75EF&state=D79E5777-702E-4260-9A62-37F75FF22CCE
Parametr Opis
admin_consent Wartość ma wartość True, jeśli administrator wyraził zgodę na monit o zgodę.
kod Kod autoryzacji żądany przez aplikację. Aplikacja może użyć kodu autoryzacji, aby zażądać tokenu dostępu dla zasobu docelowego.
session_state Unikatowa wartość identyfikująca bieżącą sesję użytkownika. Ta wartość jest identyfikatorem GUID, ale powinna być traktowana jako nieprzezroczysta wartość, która jest przekazywana bez badania.
stan Jeśli parametr stanu jest uwzględniony w żądaniu, ta sama wartość powinna pojawić się w odpowiedzi. Dobrym rozwiązaniem jest sprawdzenie, czy wartości stanu w żądaniu i odpowiedzi są identyczne przed użyciem odpowiedzi. Pomaga to wykrywać ataki fałszera żądań między lokacjami (CSRF, Cross-Site Request Forgery) na klienta.

Odpowiedź na błąd

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

GET http://localhost:12345/?
error=access_denied
&error_description=the+user+canceled+the+authentication
Parametr Opis
error Wartość kodu błędu zdefiniowana w sekcji 5.2 struktury autoryzacji OAuth 2.0. W następnej tabeli opisano kody błędów, które Azure AD zwracane.
error_description Bardziej szczegółowy opis błędu. Ta wiadomość nie jest przeznaczona do obsługi użytkownika końcowego.
stan Wartość stanu to losowo wygenerowana wartość nienależący do ponownego użycia, która jest wysyłana w żądaniu i zwracana w odpowiedzi, aby zapobiec atakom polegającym na fałszowaniu żądań między witrynami (CSRF).

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. Jest to błąd programowania i zazwyczaj jest przechwytywane podczas testowania początkowego.
unauthorized_client Aplikacja kliencka nie może zażądać kodu autoryzacji. Zwykle dzieje się tak, gdy aplikacja kliencka nie jest zarejestrowana w Azure AD lub nie jest dodawana do Azure AD dzierżawy użytkownika. Aplikacja może monitować użytkownika z instrukcjami dotyczącymi instalowania aplikacji i dodawania jej do Azure AD.
Access_denied Odmowa zgody właściciela zasobu Aplikacja kliencka może powiadomić użytkownika, że nie może kontynuować, chyba że użytkownik wyrazi na to zgodę.
unsupported_response_type Serwer autoryzacji nie obsługuje typu odpowiedzi w żądaniu. Napraw i prześlij ponownie żądanie. Jest to błąd programowania i zazwyczaj jest przechwytywane podczas testowania początkowego.
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 z powodu tymczasowego błędu.
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 tymczasowego stanu.
invalid_resource Zasób docelowy jest nieprawidłowy, ponieważ nie istnieje, Azure AD nie można go odnaleźć 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 z instrukcjami dotyczącymi instalowania aplikacji i dodawania jej do Azure AD.

Używanie kodu autoryzacji do żądania tokenu dostępu

Po uzyskaniu kodu autoryzacji i udzieleniu przez użytkownika uprawnień możesz zrealizować kod tokenu dostępu do żądanego zasobu, wysyłając żądanie POST do punktu końcowego /token :

// Line breaks for legibility only

POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA
&redirect_uri=https%3A%2F%2Flocalhost%3A12345
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=p@ssw0rd

//NOTE: client_secret only required for web apps
Parametr Typ Opis
Dzierżawy wymagane Wartość {tenant} w ścieżce żądania może służyć do kontrolowania, kto może zalogować się do aplikacji. Dozwolone wartości to identyfikatory dzierżawy, na przykład 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 lub contoso.onmicrosoft.comcommon dla tokenów niezależnych od dzierżawy
client_id wymagane Identyfikator aplikacji przypisany do aplikacji po zarejestrowaniu jej w Azure AD. Można to znaleźć w Azure Portal. Identyfikator aplikacji jest wyświetlany w ustawieniach rejestracji aplikacji.
grant_type wymagane Musi być authorization_code przeznaczony dla przepływu kodu autoryzacji.
kod wymagane Element authorization_code uzyskany w poprzedniej sekcji
redirect_uri wymagane Zarejestrowana redirect_uriw aplikacji klienckiej.
client_secret wymagane w przypadku aplikacji internetowych, niedozwolone dla klientów publicznych Wpis tajny aplikacji utworzony w Azure Portal dla aplikacji w obszarze Klucze. Nie można jej używać w aplikacji natywnej (kliencie publicznym), ponieważ client_secrets nie może być niezawodnie przechowywana na urządzeniach. Jest to wymagane w przypadku aplikacji internetowych i internetowych interfejsów API (wszystkich poufnych klientów), które mają możliwość bezpiecznego przechowywania client_secret danych po stronie serwera. Przed wysłaniem client_secret należy kodować adresy URL.
zasób zalecane Identyfikator URI identyfikatora aplikacji docelowego internetowego interfejsu API (zabezpieczony zasób). Aby znaleźć identyfikator URI identyfikatora aplikacji, w Azure Portal kliknij pozycję Azure Active Directory, kliknij pozycję Rejestracje aplikacji, otwórz stronę Ustawienia aplikacji, a następnie kliknij pozycję Właściwości. Może to być również zasób zewnętrzny, taki jak https://graph.microsoft.com. Jest to wymagane w jednym z żądań autoryzacji lub tokenu. Aby zapewnić mniej monitów o uwierzytelnienie, umieść je w żądaniu autoryzacji, aby upewnić się, że zgoda zostanie odebrana od użytkownika. Jeśli w żądaniu autoryzacji i żądaniu tokenu parametry zasobu muszą być zgodne.
code_verifier optional Ten sam code_verifier, który został użyty do uzyskania authorization_code. Wymagane, jeśli klucz PKCE został użyty w żądaniu udzielenia kodu autoryzacji. Aby uzyskać więcej informacji, zobacz dokument RFC PKCE

Aby znaleźć identyfikator URI identyfikatora aplikacji, w Azure Portal kliknij pozycję Azure Active Directory, kliknij pozycję Rejestracje aplikacji, otwórz stronę Ustawienia aplikacji, a następnie kliknij pozycję Właściwości.

Pomyślna odpowiedź

Azure AD zwraca token dostępu po pomyślnej odpowiedzi. Aby zminimalizować wywołania sieciowe z aplikacji klienckiej i skojarzone z nimi opóźnienie, aplikacja kliencka powinna buforować tokeny dostępu dla okresu istnienia tokenu określonego w odpowiedzi OAuth 2.0. Aby określić okres istnienia tokenu, użyj wartości parametrów expires_in lub expires_on .

Jeśli zasób internetowego interfejsu API zwraca invalid_token kod błędu, może to oznaczać, że zasób ustalił, że token wygasł. Jeśli czas zegara klienta i zasobu są różne (nazywane "niesymetrycznością czasu"), zasób może rozważyć wygaśnięcie tokenu, zanim token zostanie wyczyszczone z pamięci podręcznej klienta. W takim przypadku wyczyść token z pamięci podręcznej, nawet jeśli nadal mieści się w obliczonym okresie istnienia.

Pomyślna odpowiedź może wyglądać następująco:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
  "token_type": "Bearer",
  "expires_in": "3600",
  "expires_on": "1388444763",
  "resource": "https://service.contoso.com/",
  "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA",
  "scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83ZmU4MTQ0Ny1kYTU3LTQzODUtYmVjYi02ZGU1N2YyMTQ3N2UvIiwiaWF0IjoxMzg4NDQwODYzLCJuYmYiOjEzODg0NDA4NjMsImV4cCI6MTM4ODQ0NDc2MywidmVyIjoiMS4wIiwidGlkIjoiN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlIiwib2lkIjoiNjgzODlhZTItNjJmYS00YjE4LTkxZmUtNTNkZDEwOWQ3NGY1IiwidXBuIjoiZnJhbmttQGNvbnRvc28uY29tIiwidW5pcXVlX25hbWUiOiJmcmFua21AY29udG9zby5jb20iLCJzdWIiOiJKV3ZZZENXUGhobHBTMVpzZjd5WVV4U2hVd3RVbTV5elBtd18talgzZkhZIiwiZmFtaWx5X25hbWUiOiJNaWxsZXIiLCJnaXZlbl9uYW1lIjoiRnJhbmsifQ."
}
Parametr Opis
access_token Żądany token dostępu. Jest to nieprzezroczysny ciąg — zależy od tego, czego oczekuje zasób, i nie jest przeznaczony do przyjrzenia się klientowi. 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 Azure AD jest Bearer. Aby uzyskać więcej informacji na temat tokenów elementu nośnego, zobacz OAuth2.0 Authorization Framework: Bearer Token Usage (RFC 6750)
expires_in Jak długo token dostępu jest prawidłowy (w sekundach).
expires_on Czas wygaśnięcia tokenu dostępu. Data jest reprezentowana jako liczba sekund od 1970-01-01T0:0:0Z UTC do czasu wygaśnięcia. Ta wartość służy do określania okresu istnienia buforowanych tokenów.
zasób Identyfikator URI identyfikatora aplikacji internetowego interfejsu API (zabezpieczony zasób).
scope Uprawnienia personifikacji przyznane aplikacji klienckiej. Domyślne uprawnienie to user_impersonation. Właściciel zabezpieczonego zasobu może zarejestrować dodatkowe wartości w Azure AD.
refresh_token Token odświeżania OAuth 2.0. Aplikacja może użyć tego tokenu do uzyskania dodatkowych tokenów dostępu po wygaśnięciu bieżącego tokenu dostępu. Tokeny odświeżania są długotrwałe i mogą służyć do zachowania dostępu do zasobów przez dłuższy czas.
id_token Niepodpisany token internetowy JSON (JWT) reprezentujący token identyfikatora. Aplikacja może zdekodować segmenty tego tokenu w formacie base64Url, 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 na żadnych granicach autoryzacji ani zabezpieczeń.

Aby uzyskać więcej informacji na temat tokenów internetowych JSON, zobacz specyfikację wersji roboczej JWT IETF. Aby dowiedzieć się więcej o id_tokenssystemie, zobacz przepływ OpenID Connect w wersji 1.0.

Odpowiedź na błąd

Błędy punktu końcowego wystawiania tokenu to kody błędów HTTP, ponieważ klient wywołuje punkt końcowy wystawiania tokenu bezpośrednio. Oprócz kodu stanu HTTP punkt końcowy wystawiania tokenu Azure AD zwraca również dokument JSON z obiektami, które opisują błąd.

Przykładowa odpowiedź o błędzie może wyglądać następująco:

{
  "error": "invalid_grant",
  "error_description": "AADSTS70002: Error validating credentials. AADSTS70008: The provided authorization code or refresh token is expired. Send a new interactive authorization request for this user and resource.\r\nTrace ID: 3939d04c-d7ba-42bf-9cb7-1e5854cdce9e\r\nCorrelation ID: a8125194-2dc8-4078-90ba-7b6592a7f231\r\nTimestamp: 2016-04-11 18:00:12Z",
  "error_codes": [
    70002,
    70008
  ],
  "timestamp": "2016-04-11 18:00:12Z",
  "trace_id": "3939d04c-d7ba-42bf-9cb7-1e5854cdce9e",
  "correlation_id": "a8125194-2dc8-4078-90ba-7b6592a7f231"
}
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 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.
sygnatura czasowa 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 stanu HTTP

W poniższej tabeli wymieniono kody stanu HTTP zwracane przez punkt końcowy wystawiania tokenu. W niektórych przypadkach kod błędu jest wystarczający do opisania odpowiedzi, ale jeśli występują błędy, należy przeanalizować towarzyszący dokument JSON i sprawdzić jego kod błędu.

Kod HTTP Opis
400 Domyślny kod HTTP. Używany w większości przypadków i jest zwykle spowodowany źle sformułowanym żądaniem. Napraw i prześlij ponownie żądanie.
401 Nie można przeprowadzić uwierzytelniania. Na przykład w żądaniu brakuje parametru client_secret.
403 Autoryzacja nie powiodła się. Na przykład użytkownik nie ma uprawnień dostępu do zasobu.
500 Wystąpił błąd wewnętrzny w usłudze. Ponów próbę żądania.

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. Naprawianie i ponowne przesłanie żądania
invalid_grant Kod autoryzacji jest nieprawidłowy lub wygasł. Wypróbuj nowe żądanie do punktu końcowego /authorize
unauthorized_client Uwierzytelniony klient nie ma autoryzacji do korzystania z tego typu udzielania autoryzacji. Zwykle dzieje się tak, gdy aplikacja kliencka nie jest zarejestrowana w Azure AD lub nie jest dodawana do dzierżawy Azure AD użytkownika. Aplikacja może monitować użytkownika o instrukcje dotyczące instalowania aplikacji i dodawania jej do 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 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, Azure AD nie może go odnaleźć lub nie został 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 Azure AD.
interaction_required Żądanie wymaga interakcji z użytkownikiem. Na przykład wymagany jest dodatkowy krok uwierzytelniania. Zamiast żądania nieinterakcyjnego spróbuj ponownie za pomocą interakcyjnego żądania autoryzacji dla tego samego zasobu.
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 tymczasowego warunku.

Uzyskiwanie dostępu do zasobu przy użyciu tokenu dostępu

Po pomyślnym uzyskaniu access_tokentokenu można użyć tokenu w żądaniach do internetowych interfejsów API, dołączając go do nagłówka Authorization . Specyfikacja RFC 6750 wyjaśnia, jak używać tokenów elementu nośnego w żądaniach HTTP w celu uzyskania dostępu do chronionych zasobów.

Przykładowe żądanie

GET /data HTTP/1.1
Host: service.contoso.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ

Odpowiedź na błąd

Zabezpieczone zasoby, które implementują kod stanu HTTP RFC 6750. Jeśli żądanie nie zawiera poświadczeń uwierzytelniania lub brakuje tokenu, odpowiedź zawiera WWW-Authenticate nagłówek. Gdy żądanie zakończy się niepowodzeniem, serwer zasobów odpowie kodem stanu HTTP i kodem błędu.

Poniżej przedstawiono przykład nieudanej odpowiedzi, gdy żądanie klienta nie zawiera tokenu elementu nośnego:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer authorization_uri="https://login.microsoftonline.com/contoso.com/oauth2/authorize",  error="invalid_token",  error_description="The access token is missing.",

Parametry błędu

Parametr Opis
authorization_uri Identyfikator URI (fizyczny punkt końcowy) serwera autoryzacji. Ta wartość jest również używana jako klucz odnośnika, aby uzyskać więcej informacji o serwerze z punktu końcowego odnajdywania.

Klient musi sprawdzić, czy serwer autoryzacji jest zaufany. Gdy zasób jest chroniony przez Azure AD, wystarczy sprawdzić, czy adres URL zaczyna się od https://login.microsoftonline.com lub innej nazwy hosta obsługiwanej przez Azure AD. Zasób specyficzny dla dzierżawy powinien zawsze zwracać identyfikator URI autoryzacji specyficzny dla dzierżawy.
error Wartość kodu błędu zdefiniowana w sekcji 5.2 struktury autoryzacji OAuth 2.0.
error_description Bardziej szczegółowy opis błędu. Ta wiadomość nie jest przeznaczona do przyjaznego dla użytkownika końcowego.
resource_id Zwraca unikatowy identyfikator zasobu. Aplikacja kliencka może użyć tego identyfikatora jako wartości parametru resource , gdy żąda tokenu dla zasobu.

Ważne jest, aby aplikacja kliencka zweryfikowała tę wartość. W przeciwnym razie złośliwa usługa może być w stanie wywołać atak z podniesieniem uprawnień

Zalecaną strategią zapobiegania atakowi jest sprawdzenie, czy resource_id jest zgodna z bazą internetowego adresu URL interfejsu API, do którego uzyskuje się dostęp. Jeśli na przykład https://service.contoso.com/data jest uzyskiwany dostęp, resource_id może to być https://service.contoso.com/. Aplikacja kliencka musi odrzucić element resource_id , który nie zaczyna się od podstawowego adresu URL, chyba że istnieje niezawodny alternatywny sposób weryfikacji identyfikatora.

Kody błędów schematu elementu nośnego

Specyfikacja RFC 6750 definiuje następujące błędy dla zasobów, które używają schematu nagłówka WWW-Authenticate i elementu nośnego w odpowiedzi.

Kod stanu HTTP Kod błędu Opis Akcja klienta
400 invalid_request Żądanie nie jest dobrze sformułowane. Na przykład może brakować parametru lub dwa razy używać tego samego parametru. Napraw błąd i ponów próbę żądania. Ten typ błędu powinien wystąpić tylko podczas programowania i być wykrywany podczas testowania początkowego.
401 invalid_token Brak tokenu dostępu, nieprawidłowy lub został odwołany. Wartość parametru error_description zawiera dodatkowe szczegóły. Zażądaj nowego tokenu z serwera autoryzacji. Jeśli nowy token zakończy się niepowodzeniem, wystąpił nieoczekiwany błąd. Wyślij komunikat o błędzie do użytkownika i ponów próbę po losowych opóźnieniach.
403 insufficient_scope Token dostępu nie zawiera uprawnień personifikacji wymaganych do uzyskania dostępu do zasobu. Wyślij nowe żądanie autoryzacji do punktu końcowego autoryzacji. Jeśli odpowiedź zawiera parametr zakresu, użyj wartości zakresu w żądaniu do zasobu.
403 insufficient_access Podmiot tokenu nie ma uprawnień wymaganych do uzyskania dostępu do zasobu. Monituj użytkownika o użycie innego konta lub zażądanie uprawnień do określonego zasobu.

Odświeżanie tokenów dostępu

Tokeny dostępu są krótkotrwałe i muszą zostać odświeżone po wygaśnięciu, aby nadal uzyskiwać dostęp do zasobów. Możesz odświeżyć polecenie access_token , przesyłając kolejne POST żądanie do punktu końcowego /token , ale tym razem podaj wartość refresh_token zamiast code. Tokeny odświeżania są prawidłowe dla wszystkich zasobów, do których klient udzielił już zgody na dostęp — w związku z tym token odświeżania wystawiony na żądanie resource=https://graph.microsoft.com może służyć do żądania nowego tokenu dostępu dla resource=https://contoso.com/apiprogramu .

Tokeny odświeżania 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łane lub nie mają wystarczających uprawnień dla żądanej akcji. Aplikacja musi oczekiwać błędów zwróconych przez punkt końcowy wystawiania tokenu i obsługiwać je prawidłowo.

Po otrzymaniu odpowiedzi z błędem tokenu odświeżania odrzuć bieżący token odświeżania i zażądaj nowego kodu autoryzacji lub tokenu dostępu. W szczególności w przypadku korzystania z tokenu odświeżania w przepływie udzielania kodu autoryzacji, jeśli otrzymasz odpowiedź z kodami interaction_required błędów lub invalid_grant , odrzuć token odświeżania i zażądaj nowego kodu autoryzacji.

Przykładowe żądanie punktu końcowego specyficznego dla dzierżawy (można również użyć wspólnego punktu końcowego), aby uzyskać nowy token dostępu przy użyciu tokenu odświeżania, wygląda następująco:

// Line breaks for legibility only

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

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps

Pomyślna odpowiedź

Pomyślna odpowiedź tokenu będzie wyglądać następująco:

{
  "token_type": "Bearer",
  "expires_in": "3600",
  "expires_on": "1460404526",
  "resource": "https://service.contoso.com/",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
  "refresh_token": "AwABAAAAv YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl PM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfmVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA"
}
Parametr Opis
token_type Typ tokenu. Jedyną obsługiwaną wartością jest element nośny.
expires_in Pozostały okres istnienia tokenu w sekundach. Typowa wartość to 3600 (jedna godzina).
expires_on Data i godzina wygaśnięcia tokenu. Data jest reprezentowana jako liczba sekund od 1970-01-01T0:0:0Z UTC do czasu wygaśnięcia.
zasób Identyfikuje zabezpieczony zasób, za pomocą którego można uzyskać dostęp do tokenu dostępu.
scope Uprawnienia personifikacji przyznane natywnej aplikacji klienckiej. Domyślne uprawnienie to user_impersonation. Właściciel zasobu docelowego może zarejestrować alternatywne wartości w Azure AD.
access_token Nowy token dostępu, którego zażądano.
refresh_token Nowa refresh_token protokołu OAuth 2.0, która może służyć do żądania nowych tokenów dostępu po wygaśnięciu tej odpowiedzi.

Odpowiedź na błąd

Przykładowa odpowiedź o błędzie może wyglądać następująco:

{
  "error": "invalid_resource",
  "error_description": "AADSTS50001: The application named https://foo.microsoft.com/mail.read was not found in the tenant named 295e01fc-0c56-4ac3-ac57-5d0ed568f872. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You might have sent your authentication request to the wrong tenant.\r\nTrace ID: ef1f89f6-a14f-49de-9868-61bd4072f0a9\r\nCorrelation ID: b6908274-2c58-4e91-aea9-1f6b9c99347c\r\nTimestamp: 2016-04-11 18:59:01Z",
  "error_codes": [
    50001
  ],
  "timestamp": "2016-04-11 18:59:01Z",
  "trace_id": "ef1f89f6-a14f-49de-9868-61bd4072f0a9",
  "correlation_id": "b6908274-2c58-4e91-aea9-1f6b9c99347c"
}
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 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.
sygnatura czasowa 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.

Aby uzyskać opis kodów błędów i zalecanej akcji klienta, zobacz Kody błędów dla błędów punktu końcowego tokenu.

Następne kroki

Aby dowiedzieć się więcej o punkcie końcowym Azure AD w wersji 1.0 i sposobie dodawania uwierzytelniania i autoryzacji do aplikacji internetowych i internetowych interfejsów API, zobacz przykładowe aplikacje.