Przepływ kodu autoryzacji Microsoft Identity platform i OAuth 2,0Microsoft identity platform and OAuth 2.0 authorization code flow

Dotyczy:Applies to:
  • Punkt końcowy platforma tożsamości firmy MicrosoftMicrosoft identity platform endpoint

Przyznanie kodu autoryzacji OAuth 2,0 może być stosowane w aplikacjach zainstalowanych na urządzeniu w celu uzyskania dostępu do chronionych zasobów, takich jak interfejsy API sieci Web.The OAuth 2.0 authorization code grant can be used in apps that are installed on a device to gain access to protected resources, such as web APIs. Korzystając z implementacji Microsoft Identity platform w ramach uwierzytelniania OAuth 2,0, można dodać funkcję logowania i dostęp do interfejsu API do aplikacji mobilnych i klasycznych.Using the Microsoft identity platform implementation of OAuth 2.0, you can add sign in and API access to your mobile and desktop apps. Ten przewodnik jest niezależny od języka i zawiera opis sposobu wysyłania i odbierania komunikatów HTTP bez użycia żadnych bibliotek uwierzytelniania typu open-source platformy Azure.This guide is language-independent, and describes how to send and receive HTTP messages without using any of the Azure open-source authentication libraries.

W tym artykule opisano, jak programować bezpośrednio w odniesieniu do protokołu w aplikacji.This article describes how to program directly against the protocol in your application. Jeśli to możliwe, zalecamy korzystanie z obsługiwanych bibliotek uwierzytelniania firmy Microsoft (MSAL) zamiast uzyskiwać tokeny i wywoływać zabezpieczone interfejsy API sieci Web.When possible, we recommend you use the supported Microsoft Authentication Libraries (MSAL) instead to acquire tokens and call secured web APIs. Zapoznaj się również z przykładowymi aplikacjami korzystającymi z MSAL.Also take a look at the sample apps that use MSAL.

Uwaga

Nie wszystkie scenariusze Azure Active Directory & funkcje są obsługiwane przez punkt końcowy platformy tożsamości firmy Microsoft.Not all Azure Active Directory scenarios & features are supported by the Microsoft identity platform endpoint. Aby określić, czy należy używać punktu końcowego platformy tożsamości firmy Microsoft, przeczytaj artykuł ograniczenia dotyczące platformy tożsamości firmy Microsoft.To determine if you should use the Microsoft identity platform endpoint, read about Microsoft identity platform limitations.

Przepływ kodu autoryzacji OAuth 2,0 został opisany w sekcji 4,1 specyfikacji oauth 2,0.The OAuth 2.0 authorization code flow is described in section 4.1 of the OAuth 2.0 specification. Służy do uwierzytelniania i autoryzacji w większości typów aplikacji, w tym aplikacji sieci Web i natywnie zainstalowanych aplikacji.It's used to perform authentication and authorization in the majority of app types, including web apps and natively installed apps. Przepływ umożliwia aplikacjom bezpieczne pozyskiwanie access_tokens, których można użyć w celu uzyskania dostępu do zasobów zabezpieczonych przez punkt końcowy platformy tożsamości firmy Microsoft.The flow enables apps to securely acquire access_tokens that can be used to access resources secured by the Microsoft identity platform endpoint.

Diagram protokołuProtocol diagram

Na wysokim poziomie cały przepływ uwierzytelniania dla aplikacji natywnej/mobilnej wygląda następująco:At a high level, the entire authentication flow for a native/mobile application looks a bit like this:

Przepływ kodu uwierzytelniania OAuth

Żądanie kodu autoryzacjiRequest an authorization code

Przepływ kodu autoryzacji zaczyna się od klienta kierującego użytkownika do punktu końcowego /authorize.The authorization code flow begins with the client directing the user to the /authorize endpoint. W tym żądaniu klient wskazuje uprawnienia wymagane do uzyskania przez użytkownika:In this request, the client indicates the permissions it needs to acquire from the user:

// 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=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345

Porada

Kliknij link poniżej, aby wykonać to żądanie.Click the link below to execute this request! Po zalogowaniu przeglądarka powinna zostać przekierowana do https://localhost/myapp/ przy użyciu code na pasku adresu.After signing in, your browser should be redirected to https://localhost/myapp/ with a code in the address bar. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

ParametrParameter Wymagane/opcjonalneRequired/optional OpisDescription
tenant {1>wymagane<1}required Wartość {tenant} w ścieżce żądania może służyć do kontrolowania, kto może zalogować się do aplikacji.The {tenant} value in the path of the request can be used to control who can sign into the application. Dozwolone wartości to common, organizations, consumersi identyfikator dzierżawy.The allowed values are common, organizations, consumers, and tenant identifiers. Aby uzyskać więcej informacji, zobacz temat podstawowe informacje o protokole.For more detail, see protocol basics.
client_id {1>wymagane<1}required Identyfikator aplikacji (klienta) , który Azure Portal — rejestracje aplikacji środowisko przypisane do aplikacji.The Application (client) ID that the Azure portal – App registrations experience assigned to your app.
response_type {1>wymagane<1}required Musi zawierać code dla przepływu kodu autoryzacji.Must include code for the authorization code flow.
redirect_uri {1>wymagane<1}required Redirect_uri aplikacji, w której odpowiedzi uwierzytelniania mogą być wysyłane i odbierane przez aplikację.The redirect_uri of your app, where authentication responses can be sent and received by your app. Musi dokładnie pasować do jednego z redirect_uris zarejestrowanego w portalu, z wyjątkiem tego, że musi on być zakodowany w adresie URL.It must exactly match one of the redirect_uris you registered in the portal, except it must be url encoded. W przypadku natywnych aplikacji mobilnych & należy użyć wartości domyślnej https://login.microsoftonline.com/common/oauth2/nativeclient.For native & mobile apps, you should use the default value of https://login.microsoftonline.com/common/oauth2/nativeclient.
scope {1>wymagane<1}required Rozdzielana spacjami lista zakresów , do których użytkownik ma wyrazić zgodę.A space-separated list of scopes that you want the user to consent to. W przypadku /authorize rozgałęzienia żądania może to obejmować wiele zasobów, co pozwala aplikacji na uzyskanie zgody na wiele interfejsów API sieci Web, które mają być wywoływane.For the /authorize leg of the request, this can cover multiple resources, allowing your app to get consent for multiple web APIs you want to call.
response_mode zalecanerecommended Określa metodę, która ma zostać użyta do wysłania zwróconego tokenu z powrotem do aplikacji.Specifies the method that should be used to send the resulting token back to your app. Może to być jeden z następujących elementów:Can be one of the following:

- query
- fragment
- form_post

query udostępnia kod jako parametr ciągu zapytania w identyfikatorze URI przekierowania.query provides the code as a query string parameter on your redirect URI. Jeśli żądasz tokenu identyfikatora przy użyciu niejawnego przepływu, nie możesz używać query jak określono w specyfikacji OpenID Connect. Jeśli żądasz tylko kodu, możesz użyć query, fragmentlub form_post.If you're requesting an ID token using the implicit flow, you can't use query as specified in the OpenID spec. If you're requesting just the code, you can use query, fragment, or form_post. form_post wykonuje wpis zawierający kod dla identyfikatora URI przekierowania.form_post executes a POST containing the code to your redirect URI. Aby uzyskać więcej informacji, zobacz OpenID Connect Connect Protocol.For more info, see OpenID Connect protocol.
state zalecanerecommended Wartość uwzględniona w żądaniu, która również zostanie zwrócona w odpowiedzi tokenu.A value included in the request that will also be returned in the token response. Może to być ciąg dowolnej zawartości.It can be a string of any content that you wish. Losowo wygenerowana unikatowa wartość jest zwykle używana w celu zapobiegania atakom na fałszerstwo żądań między witrynami.A randomly generated unique value is typically used for preventing cross-site request forgery attacks. Ta wartość może również kodować informacje o stanie użytkownika w aplikacji przed wystąpieniem żądania uwierzytelniania, takie jak strona lub widok.The value can also encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
prompt opcjonalnieoptional Wskazuje typ interakcji użytkownika, która jest wymagana.Indicates the type of user interaction that is required. Jedyne prawidłowe wartości w tym momencie to login, nonei consent.The only valid values at this time are login, none, and consent.

- prompt=login wymusi, aby użytkownik wprowadził swoje poświadczenia na tym żądaniu, negację logowania jednokrotnego.- prompt=login will force the user to enter their credentials on that request, negating single-sign on.
- prompt=none jest przeciwieństwem-zapewnia, że użytkownik nie będzie wyświetlany z żadnym interaktywnym monitem.- prompt=none is the opposite - it will ensure that the user isn't presented with any interactive prompt whatsoever. Jeśli żądanie nie może zostać zakończone dyskretnie przy użyciu logowania jednokrotnego, punkt końcowy platformy tożsamości firmy Microsoft zwróci błąd interaction_required.If the request can't be completed silently via single-sign on, the Microsoft identity platform endpoint will return an interaction_required error.
- prompt=consent będzie wyzwalać okno dialogowe zgody OAuth po zalogowaniu się użytkownika, z prośbą o udzielenie uprawnień do aplikacji.- prompt=consent will trigger the OAuth consent dialog after the user signs in, asking the user to grant permissions to the app.
login_hint opcjonalnieoptional Może służyć do wstępnego wypełniania pola Nazwa użytkownika/adres e-mail strony logowania dla użytkownika, jeśli znana jest jego nazwa użytkownika przed czasem.Can be used to pre-fill the username/email address field of the sign-in page for the user, if you know their username ahead of time. Często aplikacje będą używać tego parametru podczas ponownego uwierzytelniania, ponieważ już wyodrębnili nazwę użytkownika z poprzedniego logowania przy użyciu preferred_username.Often apps will use this parameter during re-authentication, having already extracted the username from a previous sign-in using the preferred_username claim.
domain_hint opcjonalnieoptional Może to być jeden z consumers lub organizations.Can be one of consumers or organizations.

W przypadku pominięcia zostanie pominięty proces odnajdywania na podstawie poczty e-mail, który użytkownik przejdzie na stronie logowania, co prowadzi do nieco bardziej usprawnionego środowiska użytkownika.If included, it will skip the email-based discovery process that user goes through on the sign-in page, leading to a slightly more streamlined user experience. Często aplikacje będą używać tego parametru podczas ponownego uwierzytelniania przez wyodrębnienie tid z poprzedniego logowania.Often apps will use this parameter during re-authentication, by extracting the tid from a previous sign-in. Jeśli tid wartość żądania jest 9188040d-6c67-4c5b-b112-36a304b66dad, należy użyć domain_hint=consumers.If the tid claim value is 9188040d-6c67-4c5b-b112-36a304b66dad, you should use domain_hint=consumers. W przeciwnym razie użyj domain_hint=organizations.Otherwise, use domain_hint=organizations.
code_challenge_method opcjonalnieoptional Metoda używana do kodowania code_verifier dla parametru code_challenge.The method used to encode the code_verifier for the code_challenge parameter. Może być jedną z następujących wartości:Can be one of the following values:

- plain
- S256

W przypadku wykluczenia code_challenge przyjmuje się, że jest to zwykły tekst, jeśli code_challenge jest uwzględniony.If excluded, code_challenge is assumed to be plaintext if code_challenge is included. Platforma tożsamości firmy Microsoft obsługuje zarówno plain, jak i S256.Microsoft identity platform supports both plain and S256. Aby uzyskać więcej informacji, zobacz dokument RFC PKCE.For more information, see the PKCE RFC.
code_challenge opcjonalnieoptional Używane do zabezpieczania kodu autoryzacji za pośrednictwem klucza testowego dla wymiany kodu (PKCE) z klienta natywnego.Used to secure authorization code grants via Proof Key for Code Exchange (PKCE) from a native client. Wymagane, jeśli code_challenge_method jest uwzględniony.Required if code_challenge_method is included. Aby uzyskać więcej informacji, zobacz dokument RFC PKCE.For more information, see the PKCE RFC.

W tym momencie użytkownik zostanie poproszony o wprowadzenie poświadczeń i zakończenie uwierzytelniania.At this point, the user will be asked to enter their credentials and complete the authentication. Punkt końcowy platformy tożsamości firmy Microsoft sprawdzi również, czy użytkownik wyraził zgodę na uprawnienia wskazane w scope parametr zapytania.The Microsoft identity platform endpoint will also ensure that the user has consented to the permissions indicated in the scope query parameter. Jeśli użytkownik nie wyraził zgody na żadne z tych uprawnień, poprosił użytkownika o zgodę na wymagane uprawnienia.If the user has not consented to any of those permissions, it will ask the user to consent to the required permissions. Szczegółowe informacje o uprawnieniach, zgodzie i aplikacjach wielodostępnych są dostępne tutaj.Details of permissions, consent, and multi-tenant apps are provided here.

Gdy użytkownik uwierzytelni się i udzieli zgody, punkt końcowy platformy tożsamości firmy Microsoft zwróci odpowiedź do aplikacji we wskazanym redirect_uriprzy użyciu metody określonej w parametrze response_mode.Once the user authenticates and grants consent, the Microsoft identity platform endpoint will return a response to your app at the indicated redirect_uri, using the method specified in the response_mode parameter.

Pomyślna odpowiedźSuccessful response

Pomyślna odpowiedź przy użyciu response_mode=query wygląda następująco:A successful response using response_mode=query looks like:

GET https://login.microsoftonline.com/common/oauth2/nativeclient?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
ParametrParameter OpisDescription
code Authorization_code żądana przez aplikację.The authorization_code that the app requested. Aplikacja może użyć kodu autoryzacji, aby zażądać tokenu dostępu dla zasobu docelowego.The app can use the authorization code to request an access token for the target resource. Authorization_codes są krótkotrwałe, zazwyczaj wygasają po około 10 minutach.Authorization_codes are short lived, typically they expire after about 10 minutes.
state Jeśli w żądaniu zostanie uwzględniony parametr stanu, ta sama wartość powinna pojawić się w odpowiedzi.If a state parameter is included in the request, the same value should appear in the response. Aplikacja powinna sprawdzić, czy wartości stanu w żądaniu i odpowiedzi są identyczne.The app should verify that the state values in the request and response are identical.

Odpowiedź na błądError response

Odpowiedzi na błędy mogą być również wysyłane do redirect_uri, aby aplikacja mogła je odpowiednio obsłużyć:Error responses may also be sent to the redirect_uri so the app can handle them appropriately:

GET https://login.microsoftonline.com/common/oauth2/nativeclient?
error=access_denied
&error_description=the+user+canceled+the+authentication
ParametrParameter OpisDescription
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 mogą być używane do reagowania na błędy.An error code string that can be used to classify types of errors that occur, and can be used to react to errors.
error_description Konkretny komunikat o błędzie, który może ułatwić deweloperom zidentyfikowanie głównej przyczyny błędu uwierzytelniania.A specific error message that can help a developer identify the root cause of an authentication error.

Kody błędów dla błędów punktu końcowego autoryzacjiError codes for authorization endpoint errors

W poniższej tabeli opisano różne kody błędów, które mogą być zwracane w error parametru odpowiedzi na błąd.The following table describes the various error codes that can be returned in the error parameter of the error response.

Kod błęduError Code OpisDescription Akcja klientaClient Action
invalid_request Błąd protokołu, taki jak brak wymaganego parametru.Protocol error, such as a missing required parameter. Napraw i ponownie prześlij żądanie.Fix and resubmit the request. Jest to błąd programistyczny zwykle przechwycony podczas wstępnego testowania.This is a development error typically caught during initial testing.
unauthorized_client Aplikacja kliencka nie może zażądać kodu autoryzacji.The client application isn't permitted to request an authorization code. Ten błąd występuje zazwyczaj, gdy aplikacja kliencka nie jest zarejestrowana w usłudze Azure AD lub nie została dodana do dzierżawy usługi Azure AD użytkownika.This error usually occurs when the client application isn't registered in Azure AD or isn't added to the user's Azure AD tenant. Aplikacja może monitować użytkownika z instrukcją dotyczącą instalowania aplikacji i dodawania jej do usługi Azure AD.The application can prompt the user with instruction for installing the application and adding it to Azure AD.
access_denied Niedozwolona zgoda właściciela zasobuResource owner denied consent Aplikacja kliencka może powiadomić użytkownika, że nie może wykonać tej czynności, chyba że użytkownik wyraził zgodę.The client application can notify the user that it can't proceed unless the user consents.
unsupported_response_type Serwer autoryzacji nie obsługuje typu odpowiedzi w żądaniu.The authorization server does not support the response type in the request. Napraw i ponownie prześlij żądanie.Fix and resubmit the request. Jest to błąd programistyczny zwykle przechwycony podczas wstępnego testowania.This is a development error typically caught during initial testing.
server_error Serwer napotkał nieoczekiwany błąd.The server encountered an unexpected error. Ponów żądanie.Retry the request. Te błędy mogą wynikać z warunków tymczasowych.These errors can result from temporary conditions. Aplikacja kliencka może wyjaśnić użytkownikowi, że odpowiedź jest opóźniona z błędem tymczasowym.The client application might explain to the user that its response is delayed to a temporary error.
temporarily_unavailable Serwer jest tymczasowo zbyt zajęty, aby obsłużyć żądanie.The server is temporarily too busy to handle the request. Ponów żądanie.Retry the request. Aplikacja kliencka może wyjaśnić użytkownikowi, że jego odpowiedź jest opóźniona ze względu na tymczasowy warunek.The client application might explain to the user that its response is delayed because of a temporary condition.
invalid_resource Zasób docelowy jest nieprawidłowy, ponieważ nie istnieje, usługa Azure AD nie może go odnaleźć lub nie jest poprawnie skonfigurowana.The target resource is invalid because it does not exist, Azure AD can't find it, or it's not correctly configured. Ten błąd wskazuje, że zasób (jeśli istnieje) nie został skonfigurowany w dzierżawie.This error indicates the resource, if it exists, has not been configured in the tenant. Aplikacja może monitować użytkownika z instrukcją dotyczącą instalowania aplikacji i dodawania jej do usługi Azure AD.The application can prompt the user with instruction for installing the application and adding it to Azure AD.
login_required Zbyt wiele lub nie znaleziono użytkownikówToo many or no users found Klient zażądał uwierzytelniania dyskretnego (prompt=none), ale nie można odnaleźć pojedynczego użytkownika.The client requested silent authentication (prompt=none), but a single user could not found. Może to oznaczać, że wielu użytkowników jest aktywnych w sesji lub nie ma żadnych użytkowników.This may mean there are multiple users active in the session, or no users. Uwzględnia to wybraną dzierżawę (na przykład jeśli istnieją dwa aktywne konta usługi Azure AD i jeden konto Microsoft, a wybrano consumers, zostanie wykonane uwierzytelnianie dyskretne).This takes into account the tenant chosen (for example, if there are two Azure AD accounts active and one Microsoft account, and consumers is chosen, silent authentication will work).
interaction_required Żądanie wymaga interakcji z użytkownikiem.The request requires user interaction. Wymagany jest dodatkowy krok uwierzytelniania lub zgoda.An additional authentication step or consent is required. Ponów żądanie bez prompt=none.Retry the request without prompt=none.

Żądanie tokenu dostępuRequest an access token

Po uzyskaniu authorization_code i uzyskaniu przez niego uprawnień użytkownik można zrealizować code access_token do żądanego zasobu.Now that you've acquired an authorization_code and have been granted permission by the user, you can redeem the code for an access_token to the desired resource. W tym celu należy wysłać żądanie POST do punktu końcowego /token:Do this by sending a POST request to the /token endpoint:

// 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%2Fuser.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps

Porada

Spróbuj wykonać to żądanie w programie Poster!Try executing this request in Postman! (Nie zapomnij zastąpić code) spróbuj uruchomić to żądanie w programie Poster(Don't forget to replace the code) Try running this request in Postman

ParametrParameter Wymagane/opcjonalneRequired/optional OpisDescription
tenant {1>wymagane<1}required Wartość {tenant} w ścieżce żądania może służyć do kontrolowania, kto może zalogować się do aplikacji.The {tenant} value in the path of the request can be used to control who can sign into the application. Dozwolone wartości to common, organizations, consumersi identyfikator dzierżawy.The allowed values are common, organizations, consumers, and tenant identifiers. Aby uzyskać więcej informacji, zobacz temat podstawowe informacje o protokole.For more detail, see protocol basics.
client_id {1>wymagane<1}required Identyfikator aplikacji (klienta), którą strona Rejestracje aplikacji Azure Portala — jest przypisana do aplikacji.The Application (client) ID that the Azure portal – App registrations page assigned to your app.
grant_type {1>wymagane<1}required Należy authorization_code dla przepływu kodu autoryzacji.Must be authorization_code for the authorization code flow.
scope {1>wymagane<1}required Rozdzielana spacjami lista zakresów.A space-separated list of scopes. Zakresy żądane w tym etapie muszą być równoważne lub podzbiorem zakresów żądanych w pierwszym etapie.The scopes requested in this leg must be equivalent to or a subset of the scopes requested in the first leg. Wszystkie zakresy muszą pochodzić z pojedynczego zasobu, a także zakresy OIDC (profile, openid, email).The scopes must all be from a single resource, along with OIDC scopes (profile, openid, email). Aby uzyskać bardziej szczegółowy opis zakresów, zapoznaj się z uprawnieniami, zgodą i zakresami.For a more detailed explanation of scopes, refer to permissions, consent, and scopes.
code {1>wymagane<1}required Authorization_code, które zostały nabyte w pierwszym etapie przepływu.The authorization_code that you acquired in the first leg of the flow.
redirect_uri {1>wymagane<1}required Ta sama redirect_uri wartość, która została użyta w celu uzyskania authorization_code.The same redirect_uri value that was used to acquire the authorization_code.
client_secret wymagane dla aplikacji sieci Webrequired for web apps Wpis tajny aplikacji utworzony w portalu rejestracji aplikacji dla aplikacji.The application secret that you created in the app registration portal for your app. Nie należy używać wpisu tajnego aplikacji w aplikacji natywnej, ponieważ client_secrets nie może być niezawodnie przechowywana na urządzeniach.You shouldn't use the application secret in a native app because client_secrets can't be reliably stored on devices. Jest to wymagane w przypadku aplikacji sieci Web i interfejsów API sieci Web, które umożliwiają bezpieczne przechowywanie client_secret po stronie serwera.It's required for web apps and web APIs, which have the ability to store the client_secret securely on the server side. Wpis tajny klienta musi być zakodowany przy użyciu adresu URL przed wysłaniem.The client secret must be URL-encoded before being sent.
code_verifier opcjonalnieoptional Ten sam code_verifier, który został użyty w celu uzyskania authorization_code.The same code_verifier that was used to obtain the authorization_code. Wymagane, jeśli w żądaniu udzielenia uprawnienia do kodu autoryzacji użyto PKCE.Required if PKCE was used in the authorization code grant request. Aby uzyskać więcej informacji, zobacz dokument RFC PKCE.For more information, see the PKCE RFC.

Pomyślna odpowiedźSuccessful response

Pomyślna odpowiedź dotycząca tokenu będzie wyglądać następująco:A successful token response will look like:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "https%3A%2F%2Fgraph.microsoft.com%2Fuser.read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
ParametrParameter OpisDescription
access_token Żądany token dostępu.The requested access token. Aplikacja może używać tego tokenu do uwierzytelniania w zabezpieczonym zasobie, takim jak internetowy interfejs API.The app can use this token to authenticate to the secured resource, such as a web API.
token_type Wskazuje wartość typu tokenu.Indicates the token type value. Jedynym typem obsługiwanym przez usługę Azure AD jest znakThe only type that Azure AD supports is Bearer
expires_in Jak długo token dostępu jest prawidłowy (w sekundach).How long the access token is valid (in seconds).
scope Zakresy, dla których access_token jest prawidłowa.The scopes that the access_token is valid for.
refresh_token Token odświeżania OAuth 2,0.An OAuth 2.0 refresh token. Aplikacja może używać tego tokenu, uzyskując dodatkowe tokeny dostępu po wygaśnięciu bieżącego tokenu dostępu.The app can use this token acquire additional access tokens after the current access token expires. Refresh_tokens są długotrwałe i mogą być używane do przechowywania zasobów przez dłuższy czas.Refresh_tokens are long-lived, and can be used to retain access to resources for extended periods of time. Aby uzyskać więcej informacji na temat odświeżania tokenu dostępu, zapoznaj się z sekcją poniżej.For more detail on refreshing an access token, refer to the section below.
Uwaga: Dostępne tylko wtedy, gdy zażądano zakresu offline_access.Note: Only provided if offline_access scope was requested.
id_token Token sieci Web JSON (JWT).A JSON Web Token (JWT). Aplikacja może zdekodować segmenty tego tokenu, aby zażądać informacji o użytkowniku, który się zalogował.The app can decode the segments of this token to request information about the user who signed in. Aplikacja może buforować wartości i wyświetlać je, ale nie należy polegać na nich w przypadku jakichkolwiek ograniczeń autoryzacji lub zabezpieczeń.The app can cache the values and display them, but it should not rely on them for any authorization or security boundaries. Aby uzyskać więcej informacji na temat id_tokens, zobacz id_token reference.For more information about id_tokens, see the id_token reference.
Uwaga: Dostępne tylko wtedy, gdy zażądano zakresu openid.Note: Only provided if openid scope was requested.

Odpowiedź na błądError response

Odpowiedzi na błędy będą wyglądać następująco:Error responses will look like:

{
  "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"
}
ParametrParameter OpisDescription
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 mogą być używane do reagowania na błędy.An error code string that can be used to classify types of errors that occur, and can be used to react to errors.
error_description Konkretny komunikat o błędzie, który może ułatwić deweloperom zidentyfikowanie głównej przyczyny błędu uwierzytelniania.A specific error message that can help a developer identify the root cause of an authentication error.
error_codes Lista kodów błędów specyficznych dla usługi STS, które mogą pomóc w diagnostyce.A list of STS-specific error codes that can help in diagnostics.
timestamp Godzina wystąpienia błędu.The time at which the error occurred.
trace_id Unikatowy identyfikator żądania, które może pomóc w diagnostyce.A unique identifier for the request that can help in diagnostics.
correlation_id Unikatowy identyfikator żądania, które może pomóc w diagnostyce między składnikami.A unique identifier for the request that can help in diagnostics across components.

Kody błędów dla błędów punktu końcowego tokenuError codes for token endpoint errors

Kod błęduError Code OpisDescription Akcja klientaClient Action
invalid_request Błąd protokołu, taki jak brak wymaganego parametru.Protocol error, such as a missing required parameter. Napraw i ponownie prześlij żądanieFix and resubmit the request
invalid_grant Kod autoryzacji lub weryfikator kodu PKCE jest nieprawidłowy lub wygasł.The authorization code or PKCE code verifier is invalid or has expired. Wypróbuj nowe żądanie do punktu końcowego /authorize i sprawdź, czy parametr code_verifier był poprawny.Try a new request to the /authorize endpoint and verify that the code_verifier parameter was correct.
unauthorized_client Uwierzytelniony klient nie ma autoryzacji do korzystania z tego typu udzielania autoryzacji.The authenticated client isn't authorized to use this authorization grant type. Zwykle dzieje się tak, gdy aplikacja kliencka nie jest zarejestrowana w usłudze Azure AD lub nie została dodana do dzierżawy usługi Azure AD użytkownika.This usually occurs when the client application isn't registered in Azure AD or isn't added to the user's Azure AD tenant. Aplikacja może monitować użytkownika z instrukcją dotyczącą instalowania aplikacji i dodawania jej do usługi Azure AD.The application can prompt the user with instruction for installing the application and adding it to Azure AD.
invalid_client Uwierzytelnianie klienta nie powiodło się.Client authentication failed. Poświadczenia klienta są nieprawidłowe.The client credentials aren't valid. Aby rozwiązać ten problem, administrator aplikacji aktualizuje poświadczenia.To fix, the application administrator updates the credentials.
unsupported_grant_type Serwer autoryzacji nie obsługuje typu przydzielenia autoryzacji.The authorization server does not support the authorization grant type. Zmień typ dotacji w żądaniu.Change the grant type in the request. Ten typ błędu powinien wystąpić tylko podczas opracowywania i być wykrywany podczas wstępnego testowania.This type of error should occur only during development and be detected during initial testing.
invalid_resource Zasób docelowy jest nieprawidłowy, ponieważ nie istnieje, usługa Azure AD nie może go odnaleźć lub nie jest poprawnie skonfigurowana.The target resource is invalid because it does not exist, Azure AD can't find it, or it's not correctly configured. Wskazuje to, że zasób, jeśli istnieje, nie został skonfigurowany w dzierżawie.This indicates the resource, if it exists, has not been configured in the tenant. Aplikacja może monitować użytkownika z instrukcją dotyczącą instalowania aplikacji i dodawania jej do usługi Azure AD.The application can prompt the user with instruction for installing the application and adding it to Azure AD.
interaction_required Żądanie wymaga interakcji z użytkownikiem.The request requires user interaction. Na przykład wymagany jest dodatkowy krok uwierzytelniania.For example, an additional authentication step is required. Spróbuj ponownie wykonać żądanie przy użyciu tego samego zasobu.Retry the request with the same resource.
temporarily_unavailable Serwer jest tymczasowo zbyt zajęty, aby obsłużyć żądanie.The server is temporarily too busy to handle the request. Ponów żądanie.Retry the request. Aplikacja kliencka może wyjaśnić użytkownikowi, że jego odpowiedź jest opóźniona ze względu na tymczasowy warunek.The client application might explain to the user that its response is delayed because of a temporary condition.

Korzystanie z tokenu dostępuUse the access token

Po pomyślnym pobraniu access_tokenmożna użyć tokenu w żądaniach do interfejsów API sieci Web, dołączając go do nagłówka Authorization:Now that you've successfully acquired an access_token, you can use the token in requests to Web APIs by including it in the Authorization header:

Porada

Wykonaj to żądanie w programie Poster!Execute this request in Postman! (Najpierw Zastąp nagłówek Authorization) spróbuj uruchomić to żądanie w programie Poster(Replace the Authorization header first) Try running this request in Postman

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

Odświeżanie tokenu dostępuRefresh the access token

Access_tokens są krótkotrwałe i należy je odświeżyć po wygaśnięciu, aby nadal uzyskiwać dostęp do zasobów.Access_tokens are short lived, and you must refresh them after they expire to continue accessing resources. Można to zrobić przez przesłanie kolejnego żądania POST do punktu końcowego /token, a tym razem refresh_token zamiast code.You can do so by submitting another POST request to the /token endpoint, this time providing the refresh_token instead of the code. Tokeny odświeżania są prawidłowe dla wszystkich uprawnień, do których klient otrzymał już zgodę — w tym celu token odświeżania wystawiony na żądanie scope=mail.read może służyć do żądania nowego tokenu dostępu dla scope=api://contoso.com/api/UseResource.Refresh tokens are valid for all permissions that your client has already received consent for - thus, a refresh token issued on a request for scope=mail.read can be used to request a new access token for scope=api://contoso.com/api/UseResource.

Tokeny odświeżania nie mają określonych okresów istnienia.Refresh tokens do not have specified lifetimes. Zwykle okresy istnienia tokenów odświeżania są stosunkowo długie.Typically, the lifetimes of refresh tokens are relatively long. Jednak w niektórych przypadkach tokeny odświeżania wygasną, są odwoływane lub nie ma wystarczających uprawnień do żądanej akcji.However, in some cases, refresh tokens expire, are revoked, or lack sufficient privileges for the desired action. Aplikacja musi oczekiwać i obsłużyć błędy zwrócone przez punkt końcowy wystawiania tokenów .Your application needs to expect and handle errors returned by the token issuance endpoint correctly.

Chociaż tokeny odświeżania nie są odwoływane, gdy są używane do uzyskiwania nowych tokenów dostępu, oczekuje się, że stary token odświeżania zostanie odrzucony.Although refresh tokens aren't revoked when used to acquire new access tokens, you are expected to discard the old refresh token. Specyfikacja OAuth 2,0 brzmi: "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.The OAuth 2.0 spec says: "The authorization server MAY issue a new refresh token, in which case the client MUST discard the old refresh token and replace it with the new refresh token. Serwer autoryzacji może odwołać stary token odświeżania po wydaniu nowego tokenu odświeżania do klienta ".The authorization server MAY revoke the old refresh token after issuing a new refresh token to the client."

// 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%2Fuser.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh      // NOTE: Only required for web apps

Porada

Spróbuj wykonać to żądanie w programie Poster!Try executing this request in Postman! (Nie zapomnij zastąpić refresh_token) spróbuj uruchomić to żądanie w programie Poster(Don't forget to replace the refresh_token) Try running this request in Postman

ParametrParameter OpisDescription
tenant {1>wymagane<1}required Wartość {tenant} w ścieżce żądania może służyć do kontrolowania, kto może zalogować się do aplikacji.The {tenant} value in the path of the request can be used to control who can sign into the application. Dozwolone wartości to common, organizations, consumersi identyfikator dzierżawy.The allowed values are common, organizations, consumers, and tenant identifiers. Aby uzyskać więcej informacji, zobacz temat podstawowe informacje o protokole.For more detail, see protocol basics.
client_id {1>wymagane<1}required Identyfikator aplikacji (klienta) , który Azure Portal — rejestracje aplikacji środowisko przypisane do aplikacji.The Application (client) ID that the Azure portal – App registrations experience assigned to your app.
grant_type {1>wymagane<1}required Musi być refresh_token dla tego odcinka przepływu kodu autoryzacji.Must be refresh_token for this leg of the authorization code flow.
scope {1>wymagane<1}required Rozdzielana spacjami lista zakresów.A space-separated list of scopes. Zakresy żądane w tym etapie muszą być równoważne lub podzbiorem zakresów żądanych w pierwotnym etapie żądania authorization_code.The scopes requested in this leg must be equivalent to or a subset of the scopes requested in the original authorization_code request leg. Jeśli zakresy określone w tym żądaniu obejmują wiele serwerów zasobów, punkt końcowy platformy tożsamości firmy Microsoft zwróci token dla zasobu określonego w pierwszym zakresie.If the scopes specified in this request span multiple resource server, then the Microsoft identity platform endpoint will return a token for the resource specified in the first scope. Aby uzyskać bardziej szczegółowy opis zakresów, zapoznaj się z uprawnieniami, zgodą i zakresami.For a more detailed explanation of scopes, refer to permissions, consent, and scopes.
refresh_token {1>wymagane<1}required Refresh_token, które zostały nabyte w drugim etapie przepływu.The refresh_token that you acquired in the second leg of the flow.
client_secret wymagane dla aplikacji sieci Webrequired for web apps Wpis tajny aplikacji utworzony w portalu rejestracji aplikacji dla aplikacji.The application secret that you created in the app registration portal for your app. Nie powinna być używana w aplikacji natywnej, ponieważ client_secrets nie może być niezawodnie przechowywana na urządzeniach.It should not be used in a native app, because client_secrets can't be reliably stored on devices. Jest to wymagane w przypadku aplikacji sieci Web i interfejsów API sieci Web, które umożliwiają bezpieczne przechowywanie client_secret po stronie serwera.It's required for web apps and web APIs, which have the ability to store the client_secret securely on the server side.

Pomyślna odpowiedźSuccessful response

Pomyślna odpowiedź dotycząca tokenu będzie wyglądać następująco:A successful token response will look like:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "https%3A%2F%2Fgraph.microsoft.com%2Fuser.read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
ParametrParameter OpisDescription
access_token Żądany token dostępu.The requested access token. Aplikacja może używać tego tokenu do uwierzytelniania w zabezpieczonym zasobie, takim jak internetowy interfejs API.The app can use this token to authenticate to the secured resource, such as a web API.
token_type Wskazuje wartość typu tokenu.Indicates the token type value. Jedynym typem obsługiwanym przez usługę Azure AD jest znakThe only type that Azure AD supports is Bearer
expires_in Jak długo token dostępu jest prawidłowy (w sekundach).How long the access token is valid (in seconds).
scope Zakresy, dla których access_token jest prawidłowa.The scopes that the access_token is valid for.
refresh_token Nowy token odświeżania protokołu OAuth 2,0.A new OAuth 2.0 refresh token. Należy zastąpić stary token odświeżania nowym, pobranym tokenem odświeżania, aby upewnić się, że tokeny odświeżania pozostają prawidłowe, tak długo, jak to możliwe.You should replace the old refresh token with this newly acquired refresh token to ensure your refresh tokens remain valid for as long as possible.
Uwaga: Dostępne tylko wtedy, gdy zażądano zakresu offline_access.Note: Only provided if offline_access scope was requested.
id_token Niepodpisany token sieci Web JSON (JWT).An unsigned JSON Web Token (JWT). Aplikacja może zdekodować segmenty tego tokenu, aby zażądać informacji o użytkowniku, który się zalogował.The app can decode the segments of this token to request information about the user who signed in. Aplikacja może buforować wartości i wyświetlać je, ale nie należy polegać na nich w przypadku jakichkolwiek ograniczeń autoryzacji lub zabezpieczeń.The app can cache the values and display them, but it should not rely on them for any authorization or security boundaries. Aby uzyskać więcej informacji na temat id_tokens, zobacz id_token reference.For more information about id_tokens, see the id_token reference.
Uwaga: Dostępne tylko wtedy, gdy zażądano zakresu openid.Note: Only provided if openid scope was requested.

Odpowiedź na błądError response

{
  "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"
}
ParametrParameter OpisDescription
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 mogą być używane do reagowania na błędy.An error code string that can be used to classify types of errors that occur, and can be used to react to errors.
error_description Konkretny komunikat o błędzie, który może ułatwić deweloperom zidentyfikowanie głównej przyczyny błędu uwierzytelniania.A specific error message that can help a developer identify the root cause of an authentication error.
error_codes Lista kodów błędów specyficznych dla usługi STS, które mogą pomóc w diagnostyce.A list of STS-specific error codes that can help in diagnostics.
timestamp Godzina wystąpienia błędu.The time at which the error occurred.
trace_id Unikatowy identyfikator żądania, które może pomóc w diagnostyce.A unique identifier for the request that can help in diagnostics.
correlation_id Unikatowy identyfikator żądania, które może pomóc w diagnostyce między składnikami.A unique identifier for the request that can help in diagnostics across components.

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.For a description of the error codes and the recommended client action, see Error codes for token endpoint errors.