Autoryzowanie dostępu do aplikacji internetowych usługi Azure Active Directory przy użyciu przepływu udzielania kodu OAuth 2.0Authorize access to Azure Active Directory web applications using the OAuth 2.0 code grant flow

Ostrzeżenie

Ta zawartość jest dla starszego punktu końcowego usługi Azure AD v 1.0.This content is for the older Azure AD v1.0 endpoint. Użyj platformy tożsamości firmy Microsoft dla nowych projektów.Use the Microsoft identity platform for new projects.

Uwaga

Jeśli nie poinformujesz serwera o zasobach, które zamierzasz wywołać, serwer nie wyzwoli zasad dostępu warunkowego dla tego zasobu.If you don't tell the server what resource you plan to call, then the server will not trigger the Conditional Access policies for that resource. Aby móc korzystać z wyzwalacza usługi MFA, należy uwzględnić zasób w adresie URL.So in order to have MFA trigger, you will need to include a resource in your 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.Azure Active Directory (Azure AD) uses OAuth 2.0 to enable you to authorize access to web applications and web APIs in your Azure AD tenant. Ten przewodnik jest niezależny od języka i opisuje, jak wysyłać i odbierać komunikaty HTTP bez używania bibliotek typu open-source.This guide is language independent, and describes how to send and receive HTTP messages without using any of our open-source libraries.

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 przypadku większości typów aplikacji, w tym aplikacji sieci Web i natywnie zainstalowanych aplikacji.It is used to perform authentication and authorization in most application types, including web apps and natively installed apps.

Rejestrowanie aplikacji w dzierżawie usługi ADRegister your application with your AD tenant

Najpierw Zarejestruj swoją aplikację za pomocą dzierżawy usługi Azure Active Directory (Azure AD).First, register your application with your Azure Active Directory (Azure AD) tenant. Spowoduje to nadanie aplikacji identyfikatora oraz umożliwi jej otrzymywanie tokenów.This will give you an Application ID for your application, as well as enable it to receive tokens.

  1. Zaloguj się w witrynie Azure Portal.Sign in to the Azure portal.

  2. Wybierz dzierżawę usługi Azure AD, wybierając swoje konto w prawym górnym rogu strony, a następnie wybierając pozycję Przełącz katalog nawigacji, a następnie wybierając odpowiednią dzierżawę.Choose your Azure AD tenant by selecting your account in the top right corner of the page, followed by selecting the Switch Directory navigation and then selecting the appropriate tenant.

    • Pomiń ten krok, jeśli masz tylko jedną dzierżawę usługi Azure AD w ramach Twojego konta lub wybrano już odpowiednią dzierżawę usługi Azure AD.Skip this step if you only have one Azure AD tenant under your account, or if you've already selected the appropriate Azure AD tenant.
  3. W Azure Portal Wyszukaj i wybierz pozycję Azure Active Directory.In the Azure portal, search for and select Azure Active Directory.

  4. W menu Azure Active Directory po lewej stronie wybierz pozycję rejestracje aplikacji, a następnie wybierz pozycję Nowa rejestracja.In the Azure Active Directory left menu, select App Registrations, and then select New registration.

  5. Postępuj zgodnie z monitami i utwórz nową aplikację.Follow the prompts and create a new application. Nie ma znaczenia, czy jest to aplikacja sieci Web lub aplikacja klienta publicznego (Mobile & Desktop) dla tego samouczka, ale jeśli chcesz znaleźć konkretne przykłady dla aplikacji sieci Web lub publicznych aplikacji klienckich, zapoznaj się z przewodnikami szybki start.It doesn't matter if it is a web application or a public client (mobile & desktop) application for this tutorial, but if you'd like specific examples for web applications or public client applications, check out our quickstarts.

    • Nazwa to nazwa aplikacji; opisuje aplikację innym użytkownikom.Name is the application name and describes your application to end users.
    • W obszarze Obsługiwane typy kont wybierz pozycję Konta w dowolnym katalogu organizacyjnym i konta osobiste Microsoft.Under Supported account types, select Accounts in any organizational directory and personal Microsoft accounts.
    • Podaj Identyfikator URI przekierowania.Provide the Redirect URI. W przypadku aplikacji sieci Web jest to podstawowy adres URL aplikacji, w której użytkownicy mogą się logować.For web applications, this is the base URL of your app where users can sign in. Na przykład http://localhost:12345.For example, http://localhost:12345. W przypadku klienta publicznego (Mobile & Desktop) usługa Azure AD używa go do zwracania odpowiedzi tokenów.For public client (mobile & desktop), Azure AD uses it to return token responses. Wprowadź wartość specyficzną dla swojej aplikacji.Enter a value specific to your application. Na przykład http://MyFirstAADApp.For example, http://MyFirstAADApp.
  6. Po zakończeniu rejestracji usługa Azure AD przypisze aplikację unikatowy identyfikator klienta ( Identyfikator aplikacji).Once you've completed registration, Azure AD will assign your application a unique client identifier (the Application ID). Ta wartość będzie potrzebna w następnych sekcjach, więc Skopiuj ją ze strony aplikacji.You need this value in the next sections, so copy it from the application page.

  7. Aby znaleźć aplikację w Azure Portal, wybierz pozycję rejestracje aplikacji, a następnie wybierz pozycję Wyświetl wszystkie aplikacje.To find your application in the Azure portal, select App registrations, and then select View all applications.

Przepływ autoryzacji OAuth 2,0OAuth 2.0 authorization flow

Na wysokim poziomie cały przepływ autoryzacji dla aplikacji wygląda następująco:At a high level, the entire authorization flow for an 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 /authorize punktu końcowego.The authorization code flow begins with the client directing the user to the /authorize endpoint. W tym żądaniu klient wskazuje uprawnienia wymagane do uzyskania od użytkownika.In this request, the client indicates the permissions it needs to acquire from the user. Punkt końcowy autoryzacji OAuth 2,0 dla dzierżawy można uzyskać, wybierając pozycję Rejestracje aplikacji > punktów końcowych w Azure Portal.You can get the OAuth 2.0 authorization endpoint for your tenant by selecting App registrations > Endpoints in the 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
ParametrParameter TypType OpisDescription
dzierżawtenant wymaganerequired {tenant}Wartość 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 identyfikatory dzierżawców, na przykład 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 lub contoso.onmicrosoft.com lub common dla tokenów niezależnych od dzierżawyThe allowed values are tenant identifiers, for example, 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 or contoso.onmicrosoft.com or common for tenant-independent tokens
client_idclient_id wymaganerequired Identyfikator aplikacji przypisany do aplikacji po jej zarejestrowaniu w usłudze Azure AD.The Application ID assigned to your app when you registered it with Azure AD. Ten temat można znaleźć w witrynie Azure Portal.You can find this in the Azure Portal. Kliknij przycisk Azure Active Directory na pasku bocznym usługi, kliknij pozycję rejestracje aplikacji, a następnie wybierz aplikację.Click Azure Active Directory in the services sidebar, click App registrations, and choose the application.
response_typeresponse_type wymaganerequired Musi zawierać code do przepływu kodu autoryzacji.Must include code for the authorization code flow.
redirect_uriredirect_uri zalecanerecommended 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.
response_moderesponse_mode optionaloptional 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 być query , fragment lub form_post .Can be query, fragment, or 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żyć query określonego w specyfikacji OpenID Connect. Jeśli żądasz tylko kodu, możesz użyć query , fragment , lub form_post .If you're requesting an ID token using the implicit flow, you cannot 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. Wartość domyślna to query dla przepływu kodu.The default is query for a code flow.
stanstate zalecanerecommended Wartość zawarta w żądaniu, która jest również zwracana w odpowiedzi tokenu.A value included in the request that is also returned in the token response. 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. Ten stan jest również używany do kodowania informacji o stanie użytkownika w aplikacji przed wystąpieniem żądania uwierzytelnienia, takiego jak strona lub widok.The state is also used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.
zasóbresource zalecanerecommended Identyfikator URI aplikacji docelowego internetowego interfejsu API (zabezpieczony zasób).The App ID URI of the target web API (secured resource). Aby znaleźć identyfikator URI aplikacji, w witrynie Azure Portal kliknij pozycję Azure Active Directory, kliknij pozycję rejestracje aplikacji, Otwórz stronę Ustawienia aplikacji, a następnie kliknij przycisk Właściwości.To find the App ID URI, in the Azure Portal, click Azure Active Directory, click Application registrations, open the application's Settings page, then click Properties. Może to być również zasób zewnętrzny, taki jak https://graph.microsoft.com .It may also be an external resource like https://graph.microsoft.com. Jest to wymagane w jednym z żądań autoryzacji lub tokenu.This is required in one of either the authorization or token requests. Aby zapewnić mniejszą liczbę wierszy uwierzytelniania, umieść ją w żądaniu autoryzacji, aby upewnić się, że od użytkownika otrzymano zgodę.To ensure fewer authentication prompts place it in the authorization request to ensure consent is received from the user.
scopescope Ignorujignored W przypadku aplikacji usługi Azure AD w wersji 1 zakresy muszą być konfigurowane statycznie w witrynie Azure Portal w obszarze Ustawieniaaplikacji, wymagane uprawnienia.For v1 Azure AD apps, scopes must be statically configured in the Azure Portal under the applications Settings, Required Permissions.
pytaćprompt optionaloptional Wskaż typ interakcji z użytkownikiem, która jest wymagana.Indicate the type of user interaction that is required.

Prawidłowe wartości:Valid values are:

Logowanie: użytkownik powinien mieć monit o ponowne uwierzytelnienie.login: The user should be prompted to reauthenticate.

select_account: użytkownik jest monitowany o wybranie konta, przerwanie logowania jednokrotnego.select_account: The user is prompted to select an account, interrupting single sign on. Użytkownik może wybrać istniejące zalogowane konto, wprowadzić poświadczenia dla konta zapamiętanego lub użyć innego konta.The user may select an existing signed-in account, enter their credentials for a remembered account, or choose to use a different account altogether.

zgoda: przyznano zgodę użytkownika, ale należy ją zaktualizować.consent: User consent has been granted, but needs to be updated. Użytkownik powinien zostać poproszony o zgodę.The user should be prompted to consent.

admin_consent: Administrator powinien otrzymywać monit o zgodę w imieniu wszystkich użytkowników w organizacji.admin_consent: An administrator should be prompted to consent on behalf of all users in their organization

login_hintlogin_hint optionaloptional 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 używają tego parametru podczas ponownego uwierzytelniania, ponieważ już wyodrębnili nazwę użytkownika z poprzedniego logowania przy użyciu tego preferred_username żądania.Often apps use this parameter during reauthentication, having already extracted the username from a previous sign-in using the preferred_username claim.
domain_hintdomain_hint optionaloptional Zawiera wskazówkę dotyczącą dzierżawy lub domeny, której użytkownik powinien używać do logowania.Provides a hint about the tenant or domain that the user should use to sign in. Wartość domain_hint jest zarejestrowaną domeną dla dzierżawcy.The value of the domain_hint is a registered domain for the tenant. Jeśli dzierżawca jest federacyjny do katalogu lokalnego, w usłudze AAD przekierowania do określonego serwera federacyjnego dzierżawcy.If the tenant is federated to an on-premises directory, AAD redirects to the specified tenant federation server.
code_challenge_methodcode_challenge_method zalecanerecommended Metoda używana do kodowania code_verifier code_challenge parametru.The method used to encode the code_verifier for the code_challenge parameter. Może być jedną z plain lub S256 .Can be one of plain or S256. Jeśli jest wykluczony, przyjmuje się, że jest to code_challenge zwykły tekst, jeśli code_challenge jest uwzględniony.If excluded, code_challenge is assumed to be plaintext if code_challenge is included. Usługa Azure AAD v 1.0 obsługuje zarówno program plain , jak i S256 .Azure AAD v1.0 supports both plain and S256. Aby uzyskać więcej informacji, zobacz dokument RFC PKCE.For more information, see the PKCE RFC.
code_challengecode_challenge zalecanerecommended Służy do zabezpieczania kodu autoryzacji za pośrednictwem klucza testowego dla wymiany kodu (PKCE) z klienta natywnego lub publicznego.Used to secure authorization code grants via Proof Key for Code Exchange (PKCE) from a native or public client. Wymagane, jeśli code_challenge_method jest dołączony.Required if code_challenge_method is included. Aby uzyskać więcej informacji, zobacz dokument RFC PKCE.For more information, see the PKCE RFC.

Uwaga

Jeśli użytkownik jest częścią organizacji, administrator organizacji może wyrazić zgodę na jego imienie lub zrezygnować z niego albo zezwolić użytkownikowi na wyrażanie zgody.If the user is part of an organization, an administrator of the organization can consent or decline on the user's behalf, or permit the user to consent. Użytkownik otrzymuje opcję zgody tylko wtedy, gdy administrator zezwoli na to.The user is given the option to consent only when the administrator permits it.

W tym momencie użytkownik zostanie poproszony o wprowadzenie poświadczeń i zgodę na uprawnienia wymagane przez aplikację w witrynie Azure Portal.At this point, the user is asked to enter their credentials and consent to the permissions requested by the app in the Azure Portal. Po uwierzytelnieniu i udzieleniu zgody użytkownik usługi Azure AD wyśle odpowiedź do aplikacji pod redirect_uri adresem w żądaniu przy użyciu kodu.Once the user authenticates and grants consent, Azure AD sends a response to your app at the redirect_uri address in your request with the code.

Pomyślna odpowiedźSuccessful response

Pomyślna odpowiedź może wyglądać następująco:A successful response could look like this:

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
ParametrParameter OpisDescription
admin_consentadmin_consent Wartość jest równa true, jeśli administrator wyraził zgodę na monit o żądanie zgody.The value is True if an administrator consented to a consent request prompt.
kodcode Kod autoryzacji żądany przez aplikację.The authorization code that the application requested. Aplikacja może użyć kodu autoryzacji do żądania tokenu dostępu dla zasobu docelowego.The application can use the authorization code to request an access token for the target resource.
session_statesession_state Unikatowa wartość, która identyfikuje bieżącą sesję użytkownika.A unique value that identifies the current user session. Ta wartość jest identyfikatorem GUID, ale powinien być traktowany jako nieprzezroczysta wartość, która jest przenoszona bez badania.This value is a GUID, but should be treated as an opaque value that is passed without examination.
stanstate 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. Dobrym sposobem, aby aplikacja mogła sprawdzić, czy wartości stanu w żądaniu i odpowiedzi są identyczne przed użyciem odpowiedzi.It's a good practice for the application to verify that the state values in the request and response are identical before using the response. Pomaga to wykrywać ataki między lokacjami (CSRF) na klientach.This helps to detect Cross-Site Request Forgery (CSRF) attacks against the client.

Odpowiedź na błądError response

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

GET http://localhost:12345/?
error=access_denied
&error_description=the+user+canceled+the+authentication
ParametrParameter OpisDescription
errorerror Wartość kodu błędu zdefiniowana w sekcji 5,2 struktury autoryzacji OAuth 2,0.An error code value defined in Section 5.2 of the OAuth 2.0 Authorization Framework. W następnej tabeli opisano kody błędów zwracanych przez usługę Azure AD.The next table describes the error codes that Azure AD returns.
error_descriptionerror_description Bardziej szczegółowy opis błędu.A more detailed description of the error. Ten komunikat nie powinien być przyjazny dla użytkownika końcowego.This message is not intended to be end-user friendly.
stanstate Wartość stanu jest generowaną losowo wartością, która nie jest ponownie używana, która jest wysyłana w żądaniu i zwracana w odpowiedzi, aby zapobiec atakom na żądania między lokacjami (CSRF).The state value is a randomly generated non-reused value that is sent in the request and returned in the response to prevent cross-site request forgery (CSRF) attacks.

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 parametrze 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_requestinvalid_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, który jest zazwyczaj przechwytywany podczas wstępnego testowania.This is a development error, and is typically caught during initial testing.
unauthorized_clientunauthorized_client Aplikacja kliencka nie może zażądać kodu autoryzacji.The client application is not permitted to request an authorization code. 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 is not registered in Azure AD or is not 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_deniedaccess_denied Niedozwolona zgoda właściciela zasobuResource owner denied consent Aplikacja kliencka może powiadomić użytkownika o tym, że nie może wykonać tej czynności, chyba że użytkownik wyraził zgodę.The client application can notify the user that it cannot proceed unless the user consents.
unsupported_response_typeunsupported_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, który jest zazwyczaj przechwytywany podczas wstępnego testowania.This is a development error, and is typically caught during initial testing.
server_errorserver_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 jego odpowiedź jest opóźniona z powodu tymczasowego błędu.The client application might explain to the user that its response is delayed due to a temporary error.
temporarily_unavailabletemporarily_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 due to a temporary condition.
invalid_resourceinvalid_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 cannot find it, or it is 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.

Używanie kodu autoryzacji do żądania tokenu dostępuUse the authorization code to request an access token

Po pobraniu kodu autoryzacji i przyznaniu użytkownikowi uprawnienia do tego celu można zrealizować kod tokenu dostępu do żądanego zasobu, wysyłając żądanie POST do /token punktu końcowego: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, by sending a POST request to the /token endpoint:

// 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
ParametrParameter TypType OpisDescription
dzierżawtenant wymaganerequired {tenant}Wartość 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 identyfikatory dzierżawców, na przykład 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 lub contoso.onmicrosoft.com lub common dla tokenów niezależnych od dzierżawyThe allowed values are tenant identifiers, for example, 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 or contoso.onmicrosoft.com or common for tenant-independent tokens
client_idclient_id wymaganerequired Identyfikator aplikacji przypisany do aplikacji po jej zarejestrowaniu w usłudze Azure AD.The Application Id assigned to your app when you registered it with Azure AD. Można to znaleźć w Azure Portal.You can find this in the Azure portal. Identyfikator aplikacji jest wyświetlany w ustawieniach rejestracji aplikacji.The Application Id is displayed in the settings of the app registration.
grant_typegrant_type wymaganerequired Musi być authorization_code dla przepływu kodu autoryzacji.Must be authorization_code for the authorization code flow.
kodcode wymaganerequired authorization_codePobrano w poprzedniej sekcjiThe authorization_code that you acquired in the previous section
redirect_uriredirect_uri wymaganerequired redirect_uriZarejestrowane w aplikacji klienckiej.A redirect_uriregistered on the client application.
client_secretclient_secret wymagane dla aplikacji sieci Web, niedozwolone dla klientów publicznychrequired for web apps, not allowed for public clients Wpis tajny aplikacji utworzony w witrynie Azure Portal dla aplikacji w obszarze klucze.The application secret that you created in the Azure Portal for your app under Keys. Nie może być używana w aplikacji natywnej (klient publiczny), ponieważ client_secrets nie może być niezawodnie przechowywana na urządzeniach.It cannot be used in a native app (public client), because client_secrets cannot be reliably stored on devices. Jest to wymagane w przypadku aplikacji sieci Web i interfejsów API sieci Web (wszystkich klientów poufnych), które umożliwiają bezpieczne przechowywanie danych po client_secret stronie serwera.It is required for web apps and web APIs (all confidential clients), which have the ability to store the client_secret securely on the server side. Client_secret powinna być zakodowana przy użyciu adresu URL przed wysłaniem.The client_secret should be URL-encoded before being sent.
zasóbresource zalecanerecommended Identyfikator URI aplikacji docelowego internetowego interfejsu API (zabezpieczony zasób).The App ID URI of the target web API (secured resource). Aby znaleźć identyfikator URI aplikacji, w witrynie Azure Portal kliknij pozycję Azure Active Directory, kliknij pozycję rejestracje aplikacji, Otwórz stronę Ustawienia aplikacji, a następnie kliknij przycisk Właściwości.To find the App ID URI, in the Azure Portal, click Azure Active Directory, click Application registrations, open the application's Settings page, then click Properties. Może to być również zasób zewnętrzny, taki jak https://graph.microsoft.com .It may also be an external resource like https://graph.microsoft.com. Jest to wymagane w jednym z żądań autoryzacji lub tokenu.This is required in one of either the authorization or token requests. Aby zapewnić mniejszą liczbę wierszy uwierzytelniania, umieść ją w żądaniu autoryzacji, aby upewnić się, że od użytkownika otrzymano zgodę.To ensure fewer authentication prompts place it in the authorization request to ensure consent is received from the user. Jeśli zarówno w żądaniu autoryzacji, jak i w żądaniu tokenu, parametry zasobu muszą być zgodne.If in both the authorization request and the token request, the resource` parameters must match.
code_verifiercode_verifier optionaloptional 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 PKCEFor more information, see the PKCE RFC

Aby znaleźć identyfikator URI aplikacji, w witrynie Azure Portal kliknij pozycję Azure Active Directory, kliknij pozycję rejestracje aplikacji, Otwórz stronę Ustawienia aplikacji, a następnie kliknij przycisk Właściwości.To find the App ID URI, in the Azure Portal, click Azure Active Directory, click Application registrations, open the application's Settings page, then click Properties.

Pomyślna odpowiedźSuccessful response

Usługa Azure AD zwraca token dostępu po pomyślnej odpowiedzi.Azure AD returns an access token upon a successful response. Aby zminimalizować wywołania sieci z aplikacji klienckiej i skojarzonych z nimi opóźnień, aplikacja kliencka powinna buforować tokeny dostępu dla okresu istnienia tokenu określonego w odpowiedzi OAuth 2,0.To minimize network calls from the client application and their associated latency, the client application should cache access tokens for the token lifetime that is specified in the OAuth 2.0 response. Aby określić okres istnienia tokenu, użyj expires_in expires_on wartości parametrów lub.To determine the token lifetime, use either the expires_in or expires_on parameter values.

Jeśli zasób interfejsu API sieci Web zwróci invalid_token Kod błędu, może to oznaczać, że zasób ustalił, że token wygasł.If a web API resource returns an invalid_token error code, this might indicate that the resource has determined that the token is expired. Jeśli czas zegara klienta i zasobu jest różny (nazywany "przesunięciem czasowym"), zasób może uznać, że token wygasł przed wyczyszczeniem tokenu z pamięci podręcznej klienta.If the client and resource clock times are different (known as a "time skew"), the resource might consider the token to be expired before the token is cleared from the client cache. W takim przypadku należy wyczyścić token z pamięci podręcznej, nawet jeśli nadal jest on obliczany okres istnienia.If this occurs, clear the token from the cache, even if it is still within its calculated lifetime.

Pomyślna odpowiedź może wyglądać następująco:A successful response could look like this:

{
  "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."
}

ParametrParameter OpisDescription
access_tokenaccess_token Żądany token dostępu.The requested access token. Jest to ciąg nieprzezroczysty — zależy od tego, co zasób oczekuje na otrzymanie, i nie jest przeznaczony do przeglądania przez klienta.This is an opaque string - it depends on what the resource expects to receive, and is not intended for the client to look at. 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_typetoken_type Wskazuje wartość typu tokenu.Indicates the token type value. Jedynym typem obsługiwanym przez usługę Azure AD jest znak.The only type that Azure AD supports is Bearer. Aby uzyskać więcej informacji na temat tokenów okaziciela, zobacz Struktura autoryzacji OAuth 2.0: użycie tokenu okaziciela (RFC 6750)For more information about Bearer tokens, see OAuth2.0 Authorization Framework: Bearer Token Usage (RFC 6750)
expires_inexpires_in Jak długo token dostępu jest prawidłowy (w sekundach).How long the access token is valid (in seconds).
expires_onexpires_on Czas wygaśnięcia tokenu dostępu.The time when the access token expires. Data jest reprezentowana jako liczba sekund od 1970-01-01T0:0: 0Z UTC do czasu wygaśnięcia.The date is represented as the number of seconds from 1970-01-01T0:0:0Z UTC until the expiration time. Ta wartość służy do określenia okresu istnienia buforowanych tokenów.This value is used to determine the lifetime of cached tokens.
zasóbresource Identyfikator URI aplikacji internetowego interfejsu API (zabezpieczony zasób).The App ID URI of the web API (secured resource).
scopescope Uprawnienia personifikacji przyznane aplikacji klienckiej.Impersonation permissions granted to the client application. Uprawnienie domyślne to user_impersonation .The default permission is user_impersonation. Właściciel zabezpieczonego zasobu może rejestrować dodatkowe wartości w usłudze Azure AD.The owner of the secured resource can register additional values in Azure AD.
refresh_tokenrefresh_token Token odświeżania OAuth 2,0.An OAuth 2.0 refresh token. Aplikacja może użyć tego tokenu, aby uzyskać dodatkowe tokeny dostępu po wygaśnięciu bieżącego tokenu dostępu.The app can use this token to acquire additional access tokens after the current access token expires. Tokeny odświeżania 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.
id_tokenid_token Niepodpisany token sieci Web JSON (JWT) reprezentujący token ID.An unsigned JSON Web Token (JWT) representing an ID token. Aplikacja może base64Url dekodowanie segmentów tego tokenu, aby zażądać informacji o użytkowniku, który się zalogował.The app can base64Url 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 tokenów sieci Web JSON, zobacz specyfikację wersji roboczej JWT IETF.For more information about JSON web tokens, see the JWT IETF draft specification. Aby dowiedzieć się więcej na temat id_tokens , zobacz przepływ połączenia OpenID Connect w wersji 1.0.To learn more about id_tokens, see the v1.0 OpenID Connect flow.

Odpowiedź na błądError response

Błędy punktu końcowego wystawiania tokenów to kody błędów HTTP, ponieważ klient wywołuje punkt końcowy wystawiania tokenów bezpośrednio.The token issuance endpoint errors are HTTP error codes, because the client calls the token issuance endpoint directly. Oprócz kodu stanu HTTP punkt końcowy wystawiania tokenów usługi Azure AD zwraca również dokument JSON z obiektami, które opisują błąd.In addition to the HTTP status code, the Azure AD token issuance endpoint also returns a JSON document with objects that describe the error.

Przykładowa odpowiedź na błąd może wyglądać następująco:A sample error response could look like this:

{
  "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"
}
ParametrParameter OpisDescription
errorerror 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_descriptionerror_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_codeserror_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.
sygnatura czasowatimestamp Godzina wystąpienia błędu.The time at which the error occurred.
trace_idtrace_id Unikatowy identyfikator żądania, które może pomóc w diagnostyce.A unique identifier for the request that can help in diagnostics.
correlation_idcorrelation_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 stanu HTTPHTTP status codes

Poniższa tabela zawiera listę kodów stanu HTTP zwracanych przez punkt końcowy wystawiania tokenu.The following table lists the HTTP status codes that the token issuance endpoint returns. W niektórych przypadkach kod błędu jest wystarczający do opisania odpowiedzi, ale w przypadku wystąpienia błędów należy przeanalizować towarzyszący dokument JSON i zbadać jego kod błędu.In some cases, the error code is sufficient to describe the response, but if there are errors, you need to parse the accompanying JSON document and examine its error code.

Kod HTTPHTTP Code OpisDescription
400400 Domyślny kod HTTP.Default HTTP code. Używane w większości przypadków i jest zazwyczaj spowodowane nieprawidłowo sformułowanym żądaniem.Used in most cases and is typically due to a malformed request. Napraw i ponownie prześlij żądanie.Fix and resubmit the request.
401401 Nie można przeprowadzić uwierzytelniania.Authentication failed. Na przykład w żądaniu brakuje parametru client_secret.For example, the request is missing the client_secret parameter.
403403 Autoryzacja nie powiodła się.Authorization failed. Na przykład użytkownik nie ma uprawnień dostępu do zasobu.For example, the user does not have permission to access the resource.
500500 Wystąpił błąd wewnętrzny w usłudze.An internal error has occurred at the service. Ponów żądanie.Retry the request.

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_requestinvalid_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_grantinvalid_grant Kod autoryzacji jest nieprawidłowy lub wygasł.The authorization code is invalid or has expired. Wypróbuj nowe żądanie do /authorize punktu końcowegoTry a new request to the /authorize endpoint
unauthorized_clientunauthorized_client Uwierzytelniony klient nie ma autoryzacji do korzystania z tego typu udzielania autoryzacji.The authenticated client is not 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 is not registered in Azure AD or is not 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_clientinvalid_client Uwierzytelnianie klienta nie powiodło się.Client authentication failed. Poświadczenia klienta są nieprawidłowe.The client credentials are not valid. Aby rozwiązać ten problem, administrator aplikacji aktualizuje poświadczenia.To fix, the application administrator updates the credentials.
unsupported_grant_typeunsupported_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_resourceinvalid_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 cannot find it, or it is 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_requiredinteraction_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. Zamiast żądania nieinterakcyjnego spróbuj ponownie, używając interakcyjnego żądania autoryzacji dla tego samego zasobu.Instead of a non-interactive request, retry with an interactive authorization request for the same resource.
temporarily_unavailabletemporarily_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 due to a temporary condition.

Korzystanie z tokenu dostępu w celu uzyskania dostępu do zasobuUse the access token to access the resource

Teraz, po pomyślnym pobraniu access_token , można użyć tokenu w żądaniach do interfejsów API sieci Web, dołączając je do Authorization nagłówka.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. Specyfikacja RFC 6750 wyjaśnia, jak używać tokenów okaziciela w żądaniach HTTP w celu uzyskania dostępu do chronionych zasobów.The RFC 6750 specification explains how to use bearer tokens in HTTP requests to access protected resources.

Przykładowe żądanieSample request

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łądError Response

Zabezpieczone zasoby, które implementują kody stanu HTTP 6750.Secured resources that implement RFC 6750 issue HTTP status codes. Jeśli żądanie nie zawiera poświadczeń uwierzytelniania lub brakuje tokenu, odpowiedź zawiera WWW-Authenticate nagłówek.If the request does not include authentication credentials or is missing the token, the response includes an WWW-Authenticate header. Gdy żądanie nie powiedzie się, serwer zasobów odpowiada za pomocą kodu stanu HTTP i kodu błędu.When a request fails, the resource server responds with the HTTP status code and an error code.

Poniżej przedstawiono przykład niepomyślnej odpowiedzi, gdy żądanie klienta nie zawiera tokenu okaziciela:The following is an example of an unsuccessful response when the client request does not include the bearer token:

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łęduError parameters

ParametrParameter OpisDescription
authorization_uriauthorization_uri Identyfikator URI (fizyczny punkt końcowy) serwera autoryzacji.The URI (physical endpoint) of the authorization server. Ta wartość jest również używana jako klucz wyszukiwania, aby uzyskać więcej informacji na temat serwera z punktu końcowego odnajdywania.This value is also used as a lookup key to get more information about the server from a discovery endpoint.

Klient musi sprawdzić, czy serwer autoryzacji jest zaufany.The client must validate that the authorization server is trusted. Gdy zasób jest chroniony przez usługę Azure AD, wystarczy sprawdzić, czy adres URL zaczyna się od https://login.microsoftonline.com lub od innej nazwy hosta obsługiwanej przez usługę Azure AD.When the resource is protected by Azure AD, it is sufficient to verify that the URL begins with https://login.microsoftonline.com or another hostname that Azure AD supports. Zasób specyficzny dla dzierżawy powinien zawsze zwracać identyfikator URI autoryzacji specyficznej dla dzierżawy.A tenant-specific resource should always return a tenant-specific authorization URI.

errorerror Wartość kodu błędu zdefiniowana w sekcji 5,2 struktury autoryzacji OAuth 2,0.An error code value defined in Section 5.2 of the OAuth 2.0 Authorization Framework.
error_descriptionerror_description Bardziej szczegółowy opis błędu.A more detailed description of the error. Ten komunikat nie powinien być przyjazny dla użytkownika końcowego.This message is not intended to be end-user friendly.
resource_idresource_id Zwraca unikatowy identyfikator zasobu.Returns the unique identifier of the resource. Aplikacja kliencka może używać tego identyfikatora jako wartości resource parametru, gdy żąda tokenu dla zasobu.The client application can use this identifier as the value of the resource parameter when it requests a token for the resource.

Ważne jest, aby aplikacja kliencka mogła sprawdzić tę wartość. w przeciwnym razie złośliwa usługa może być w stanie wywołać atak podniesienia uprawnieńIt is important for the client application to verify this value, otherwise a malicious service might be able to induce an elevation-of-privileges attack

Zalecana strategia zapobiegania atakom polega na sprawdzeniu, czy jest to resource_id zgodne z podstawą dostępu do adresu URL internetowego interfejsu API.The recommended strategy for preventing an attack is to verify that the resource_id matches the base of the web API URL that being accessed. Na przykład, jeśli https://service.contoso.com/data jest uzyskiwany dostęp, resource_id może to być https://service.contoso.com/ .For example, if https://service.contoso.com/data is being accessed, the resource_id can be https://service.contoso.com/. Aplikacja kliencka musi odrzucić obiekt resource_id , który nie zaczyna się od podstawowego adresu URL, chyba że istnieje niezawodny alternatywny sposób na zweryfikowanie identyfikatora.The client application must reject a resource_id that does not begin with the base URL unless there is a reliable alternate way to verify the id.

Kody błędów schematów okazicielaBearer scheme error codes

Specyfikacja RFC 6750 definiuje następujące błędy dla zasobów, które używają nagłówka WWW-Authenticate i schematu okaziciela w odpowiedzi.The RFC 6750 specification defines the following errors for resources that use the WWW-Authenticate header and Bearer scheme in the response.

Kod stanu HTTPHTTP Status Code Kod błęduError Code OpisDescription Akcja klientaClient Action
400400 invalid_requestinvalid_request Żądanie nie jest poprawnie sformułowane.The request is not well-formed. Na przykład może brakować parametru lub użyć tego samego parametru dwa razy.For example, it might be missing a parameter or using the same parameter twice. Usuń błąd i spróbuj ponownie wykonać żądanie.Fix the error and retry the request. Ten typ błędu powinien wystąpić tylko podczas tworzenia i zostanie wykryty podczas wstępnego testowania.This type of error should occur only during development and be detected in initial testing.
401401 invalid_tokeninvalid_token Brak tokenu dostępu, jest on nieprawidłowy lub został odwołany.The access token is missing, invalid, or is revoked. Wartość parametru error_description zawiera dodatkowe szczegóły.The value of the error_description parameter provides additional detail. Zażądaj nowego tokenu od serwera autoryzacji.Request a new token from the authorization server. W przypadku niepowodzenia nowego tokenu wystąpił nieoczekiwany błąd.If the new token fails, an unexpected error has occurred. Wyślij do użytkownika komunikat o błędzie i ponów próbę po opóźnieniu losowym.Send an error message to the user and retry after random delays.
403403 insufficient_scopeinsufficient_scope Token dostępu nie zawiera uprawnień personifikacji wymaganych do uzyskania dostępu do zasobu.The access token does not contain the impersonation permissions required to access the resource. Wyślij nowe żądanie autoryzacji do punktu końcowego autoryzacji.Send a new authorization request to the authorization endpoint. Jeśli odpowiedź zawiera parametr Scope, użyj wartości Scope w żądaniu do zasobu.If the response contains the scope parameter, use the scope value in the request to the resource.
403403 insufficient_accessinsufficient_access Podmiot tokenu nie ma uprawnień wymaganych do uzyskania dostępu do zasobu.The subject of the token does not have the permissions that are required to access the resource. Monituj użytkownika o użycie innego konta lub zażądanie uprawnień do określonego zasobu.Prompt the user to use a different account or to request permissions to the specified resource.

Odświeżanie tokenów dostępuRefreshing the access tokens

Tokeny dostępu są krótkotrwałe i muszą być odświeżane po wygaśnięciu, aby nadal uzyskiwać dostęp do zasobów.Access Tokens are short-lived and must be refreshed after they expire to continue accessing resources. Można odświeżyć access_token przez przesłanie kolejnego POST żądania do /token punktu końcowego, ale tym razem refresh_token zamiast code .You can refresh the access_token by submitting another POST request to the /token endpoint, but this time providing the refresh_token instead of the code. Tokeny odświeżania są prawidłowe dla wszystkich zasobów, do których klient wyraził zgodę na dostęp — w tym celu 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/api .Refresh tokens are valid for all resources that your client has already been given consent to access - thus, a refresh token issued on a request for resource=https://graph.microsoft.com can be used to request a new access token for resource=https://contoso.com/api.

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.

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.When you receive a response with a refresh token error, discard the current refresh token and request a new authorization code or access token. W szczególności w przypadku używania tokenu odświeżania w przepływie przydzielenia kodu autoryzacji, jeśli otrzymasz odpowiedź z interaction_required invalid_grant kodami błędów lub, Odrzuć token odświeżenia i zażądaj nowego kodu autoryzacji.In particular, when using a refresh token in the Authorization Code Grant flow, if you receive a response with the interaction_required or invalid_grant error codes, discard the refresh token and request a new authorization code.

Przykładowe żądanie do 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:A sample request to the tenant-specific endpoint (you can also use the common endpoint) to get a new access token using a refresh token looks like this:

// 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źSuccessful response

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

{
  "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"
}
ParametrParameter OpisDescription
token_typetoken_type Typ tokenu.The token type. Jedyna obsługiwana wartość to Bearer.The only supported value is bearer.
expires_inexpires_in Pozostały okres istnienia tokenu w sekundach.The remaining lifetime of the token in seconds. Typowa wartość to 3600 (jedna godzina).A typical value is 3600 (one hour).
expires_onexpires_on Data i godzina wygaśnięcia tokenu.The date and time on which the token expires. Data jest reprezentowana jako liczba sekund od 1970-01-01T0:0: 0Z UTC do czasu wygaśnięcia.The date is represented as the number of seconds from 1970-01-01T0:0:0Z UTC until the expiration time.
zasóbresource Identyfikuje zabezpieczony zasób, do którego można uzyskać dostęp za pomocą tokenu dostępu.Identifies the secured resource that the access token can be used to access.
scopescope Uprawnienia personifikacji przyznane natywnej aplikacji klienckiej.Impersonation permissions granted to the native client application. Uprawnienie domyślne jest user_impersonation.The default permission is user_impersonation. Właściciel zasobu docelowego może zarejestrować alternatywne wartości w usłudze Azure AD.The owner of the target resource can register alternate values in Azure AD.
access_tokenaccess_token Zażądano nowego tokenu dostępu.The new access token that was requested.
refresh_tokenrefresh_token Nowe refresh_token OAuth 2,0, których można użyć do żądania nowych tokenów dostępu, gdy ta odpowiedź wygaśnie.A new OAuth 2.0 refresh_token that can be used to request new access tokens when the one in this response expires.

Odpowiedź na błądError response

Przykładowa odpowiedź na błąd może wyglądać następująco:A sample error response could look like this:

{
  "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"
}
ParametrParameter OpisDescription
errorerror 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_descriptionerror_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_codeserror_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.
sygnatura czasowatimestamp Godzina wystąpienia błędu.The time at which the error occurred.
trace_idtrace_id Unikatowy identyfikator żądania, które może pomóc w diagnostyce.A unique identifier for the request that can help in diagnostics.
correlation_idcorrelation_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.

Następne krokiNext steps

Aby dowiedzieć się więcej o punkcie końcowym usługi Azure AD v 1.0 i sposobach dodawania uwierzytelniania i autoryzacji do aplikacji sieci Web i interfejsów API sieci Web, zobacz przykładowe aplikacje.To learn more about the Azure AD v1.0 endpoint and how to add authentication and authorization to your web applications and web APIs, see sample applications.