Azure App Service 中的驗證與授權Authentication and authorization in Azure App Service

注意

在這個階段,AAD V2 (包括 MSAL) 不支援 Azure App Service 和 Azure Functions。At this time, AAD V2 (including MSAL) is not supported for Azure App Services and Azure Functions. 請稍後回來查看更新。Please check back for updates.

Azure App Service 提供內建的驗證和授權支援,因此您在 Web 應用程式、RESTful API 和行動裝置後端以及 Azure Functions 中幾乎不需要寫入或完全無需寫入程式碼,即可登入使用者及存取資料。Azure App Service provides built-in authentication and authorization support, so you can sign in users and access data by writing minimal or no code in your web app, RESTful API, and mobile back end, and also Azure Functions. 本文說明 App Service 如何協助您簡化應用程式的驗證和授權。This article describes how App Service helps simplify authentication and authorization for your app.

若要有安全的驗證和授權,必須對安全性有深入了解,包括同盟、加密、JSON Web 權杖 (JWT) 管理、授與類型等等。Secure authentication and authorization require deep understanding of security, including federation, encryption, JSON web tokens (JWT) management, grant types, and so on. App Service 會提供這些公用程式,以便您可以將更多的時間和精力花在為客戶提供商務價值上。App Service provides these utilities so that you can spend more time and energy on providing business value to your customer.

注意

您不需要使用 App Service 來進行驗證和授權。You're not required to use App Service for authentication and authorization. 許多 Web 架構都會搭載安全性功能,您可以視需要加以使用。Many web frameworks are bundled with security features, and you can use them if you like. 如果您需要的彈性高於 App Service 所提供的彈性,也可以撰寫您自己的公用程式。If you need more flexibility than App Service provides, you can also write your own utilities.

如需原生行動應用程式的專屬資訊,請參閱 Azure App Service 的行動應用程式使用者驗證和授權For information specific to native mobile apps, see User authentication and authorization for mobile apps with Azure App Service.

運作方式How it works

驗證和授權模組會在與應用程式程式碼相同的沙箱中執行。The authentication and authorization module runs in the same sandbox as your application code. 此模組啟用時,每個連入的 HTTP 要求會先通過此模組,再由應用程式程式碼處理。When it's enabled, every incoming HTTP request passes through it before being handled by your application code.

此模組會處理應用程式的幾件事:This module handles several things for your app:

  • 向指定提供者驗證使用者Authenticates users with the specified provider
  • 驗證、儲存及重新整理權杖Validates, stores, and refreshes tokens
  • 管理已驗證的工作階段Manages the authenticated session
  • 將身分識別資訊插入要求標頭中Injects identity information into request headers

此模組會與應用程式程式碼分開執行,並且會使用應用程式設定加以設定。The module runs separately from your application code and is configured using app settings. 不需要任何 SDK、特定語言或對應用程式程式碼進行任何變更。No SDKs, specific languages, or changes to your application code are required.

使用者宣告User claims

在所有語言架構中,App Service 都會將使用者的宣告插入要求標頭內以供程式碼使用。For all language frameworks, App Service makes the user's claims available to your code by injecting them into the request headers. 在 ASP.NET 4.6 應用程式中,App Service 會使用已驗證的使用者宣告填入 ClaimsPrincipal.Current,因此您可以遵循標準的 .NET 程式碼模式,包括 [Authorize] 屬性。For ASP.NET 4.6 apps, App Service populates ClaimsPrincipal.Current with the authenticated user's claims, so you can follow the standard .NET code pattern, including the [Authorize] attribute. 同樣地,在 PHP 應用程式中,App Service 會填入 _SERVER['REMOTE_USER'] 變數。Similarly, for PHP apps, App Service populates the _SERVER['REMOTE_USER'] variable. 針對 Java 應用程式,會宣告可以從 Tomcat servlet 存取For Java apps, the claims are accessible from the Tomcat servlet.

Azure Functions 中,系統不會針對 .NET 程式碼將 ClaimsPrincipal.Current 序列化,不過您仍可以在要求標頭中找到使用者宣告。For Azure Functions, ClaimsPrincipal.Current is not hydrated for .NET code, but you can still find the user claims in the request headers.

如需詳細資訊,請參閱存取使用者宣告For more information, see Access user claims.

權杖存放區Token store

App Service 會提供內建的權杖存放區,也就是與 Web 應用程式、API 或原生行動應用程式相關聯的權杖存放庫。App Service provides a built-in token store, which is a repository of tokens that are associated with the users of your web apps, APIs, or native mobile apps. 當您使用任何提供者啟用驗證時,此權杖存放區就會立即供應用程式使用。When you enable authentication with any provider, this token store is immediately available to your app. 如果應用程式程式碼需要代表使用者存取這些提供者的資料,例如:If your application code needs to access data from these providers on the user's behalf, such as:

  • 張貼至已驗證使用者的 Facebook 時間軸post to the authenticated user's Facebook timeline
  • 從 Azure Active Directory 圖形 API 或甚至 Microsoft Graph 讀取使用者的公司資料read the user's corporate data from the Azure Active Directory Graph API or even the Microsoft Graph

您通常必須撰寫程式碼,才能在應用程式中收集、儲存及重新整理這些權杖。You typically must write code to collect, store, and refresh these tokens in your application. 使用權杖存放區時,您只有在需要權杖時才會取出權杖,並在權杖失效時才會告知 App Service 加以重新整理With the token store, you just retrieve the tokens when you need them and tell App Service to refresh them when they become invalid.

系統會針對已驗證的工作階段快取識別碼權杖、存取權杖和重新整理權杖,且只有相關聯的使用者能存取這些權杖。The id tokens, access tokens, and refresh tokens cached for the authenticated session, and they're accessible only by the associated user.

如果您不需要在應用程式中使用權杖,可以將權杖存放區停用。If you don't need to work with tokens in your app, you can disable the token store.

記錄和追蹤Logging and tracing

如果您啟用應用程式記錄,則會直接在記錄檔中看到驗證和授權追蹤。If you enable application logging, you will see authentication and authorization traces directly in your log files. 如果您看到非預期的驗證錯誤,可以在現有的應用程式記錄中查看,輕鬆地找到所有詳細資料。If you see an authentication error that you didn’t expect, you can conveniently find all the details by looking in your existing application logs. 如果您啟用失敗要求追蹤,就可以看到驗證和授權模組可能在失敗要求中所扮演的確切角色。If you enable failed request tracing, you can see exactly what role the authentication and authorization module may have played in a failed request. 在追蹤記錄中,尋找名為 EasyAuthModule_32/64 的模組參考。In the trace logs, look for references to a module named EasyAuthModule_32/64.

識別提供者Identity providers

App Service 使用同盟身分識別,由第三方識別提供者為您管理使用者身分識別和驗證流程。App Service uses federated identity, in which a third-party identity provider manages the user identities and authentication flow for you. 預設可用的識別提供者有五個:Five identity providers are available by default:

提供者Provider 登入端點Sign-in endpoint
Azure Active DirectoryAzure Active Directory /.auth/login/aad
Microsoft 帳戶Microsoft Account /.auth/login/microsoftaccount
FacebookFacebook /.auth/login/facebook
GoogleGoogle /.auth/login/google
TwitterTwitter /.auth/login/twitter

當您利用上述其中一個提供者啟用驗證和授權時,其登入端點即可用來驗證使用者,以及用來驗證提供者的驗證權杖。When you enable authentication and authorization with one of these providers, its sign-in endpoint is available for user authentication and for validation of authentication tokens from the provider. 您可以輕鬆地為使用者提供任何數目的上述登入選項。You can provide your users with any number of these sign-in options with ease. 您也可以整合其他識別提供者或自己的自訂身分識別解決方案You can also integrate another identity provider or your own custom identity solution.

驗證流程Authentication flow

所有提供者的驗證流程皆相同,但會根據您是否要使用提供者的 SDK 登入而有所不同:The authentication flow is the same for all providers, but differs depending on whether you want to sign in with the provider's SDK:

  • 不使用提供者 SDK:應用程式會將同盟登入委派給 App Service。Without provider SDK: The application delegates federated sign-in to App Service. 瀏覽器應用程式通常是這種情況,可以向使用者顯示提供者的登入頁面。This is typically the case with browser apps, which can present the provider's login page to the user. 伺服器程式碼會管理登入程序,因此也稱為「伺服器導向流程」 或「伺服器流程」 。The server code manages the sign-in process, so it is also called server-directed flow or server flow. 此案例適用於瀏覽器應用程式。This case applies to browser apps. 它也適用於使用 Mobile Apps 用戶端 SDK 將使用者登入的原生應用程式,因為 SDK 會開啟 Web 檢視,使用 App Service 驗證將使用者登入。It also applies to native apps that sign users in using the Mobile Apps client SDK because the SDK opens a web view to sign users in with App Service authentication.
  • 使用提供者 SDK:應用程式會以手動方式將使用者登入提供者,然後將驗證權杖提交給 App Service 進行驗證。With provider SDK: The application signs users in to the provider manually and then submits the authentication token to App Service for validation. 無瀏覽器應用程式通常是這種情況,無法向使用者顯示提供者的登入頁面。This is typically the case with browser-less apps, which can't present the provider's sign-in page to the user. 應用程式程式碼會管理登入程序,因此也稱為「用戶端導向流程」 或「用戶端流程」 。The application code manages the sign-in process, so it is also called client-directed flow or client flow. 此案例適用於 REST API、Azure Functions、JavaScript 瀏覽器用戶端,以及在登入程序中需要更多彈性的瀏覽器應用程式。This case applies to REST APIs, Azure Functions, and JavaScript browser clients, as well as browser apps that need more flexibility in the sign-in process. 它也適用於使用提供者 SDK 將使用者登入的原生行動應用程式。It also applies to native mobile apps that sign users in using the provider's SDK.

注意

您可以使用伺服器導向流程來驗證 App Service 中受信任瀏覽器應用程式的呼叫對 App Service 或 Azure Functions 中另一個 REST API 的呼叫。Calls from a trusted browser app in App Service calls another REST API in App Service or Azure Functions can be authenticated using the server-directed flow. 如需詳細資訊,請參閱自訂 App Service 中的驗證與授權For more information, see Customize authentication and authorization in App Service.

下表顯示驗證流程的步驟。The table below shows the steps of the authentication flow.

步驟Step 不使用提供者 SDKWithout provider SDK 使用提供者 SDKWith provider SDK
1.將使用者登入1. Sign user in 將用戶端重新導向至 /.auth/login/<provider>Redirects client to /.auth/login/<provider>. 用戶端程式碼會直接使用提供者的 SDK 將使用者登入,並接收驗證權杖。Client code signs user in directly with provider's SDK and receives an authentication token. 如需詳細資訊,請參閱提供者的文件。For information, see the provider's documentation.
2.後續驗證2. Post-authentication 提供者會將用戶端重新導向至 /.auth/login/<provider>/callbackProvider redirects client to /.auth/login/<provider>/callback. 用戶端程式碼會將提供者的權杖公佈至 /.auth/login/<provider> 以進行驗證。Client code posts token from provider to /.auth/login/<provider> for validation.
3.建立已驗證的工作階段3. Establish authenticated session App Service 會將已驗證的 Cookie 新增至回應。App Service adds authenticated cookie to response. App Service 會將自己的驗證權杖傳回至用戶端程式碼。App Service returns its own authentication token to client code.
4.提供已驗證的內容4. Serve authenticated content 用戶端會在後續要求中包含驗證 Cookie (瀏覽器會自動處理)。Client includes authentication cookie in subsequent requests (automatically handled by browser). 用戶端程式碼會在 X-ZUMO-AUTH 標頭中顯示驗證權杖 (Mobile Apps 用戶端 SDK 會自動處理)。Client code presents authentication token in X-ZUMO-AUTH header (automatically handled by Mobile Apps client SDKs).

對於用戶端瀏覽器,App Service 可以自動將所有未經驗證的使用者導向至 /.auth/login/<provider>For client browsers, App Service can automatically direct all unauthenticated users to /.auth/login/<provider>. 您也可以向使用者顯示一或多個 /.auth/login/<provider> 連結,讓其使用選擇的提供者登入您的應用程式。You can also present users with one or more /.auth/login/<provider> links to sign in to your app using their provider of choice.

授權行為Authorization behavior

Azure 入口網站中,您可以使用一些行為來設定 App Service 授權。In the Azure portal, you can configure App Service authorization with a number of behaviors.

下列標題會說明可用選項。The following headings describe the options.

允許所有要求 (預設值)Allow all requests (default)

驗證和授權未受 App Service 管理 (關閉)。Authentication and authorization are not managed by App Service (turned off).

如果您不需要驗證和授權,或如果您要撰寫自己的驗證和授權程式碼,請選擇此選項。Choose this option if you don't need authentication and authorization, or if you want to write your own authentication and authorization code.

僅允許已驗證的要求Allow only authenticated requests

選項為 [使用 <提供者> 登入] 。The option is Log in with <provider>. App Service 會將所有匿名要求重新導向至您所選提供者的 /.auth/login/<provider>App Service redirects all anonymous requests to /.auth/login/<provider> for the provider you choose. 如果匿名要求來自原生行動應用程式,則傳回的回應是 HTTP 401 UnauthorizedIf the anonymous request comes from a native mobile app, the returned response is an HTTP 401 Unauthorized.

使用此選項時,您不需要在應用程式中撰寫任何驗證程式碼。With this option, you don't need to write any authentication code in your app. 您可以藉由檢查使用者的宣告來處理更精細的授權 (例如特定角色授權,請參閱存取使用者宣告)。Finer authorization, such as role-specific authorization, can be handled by inspecting the user's claims (see Access user claims).

允許所有要求,但要驗證已驗證的要求Allow all requests, but validate authenticated requests

選項為 [允許匿名要求] 。The option is Allow Anonymous requests. 此選項會開啟 App Service 中的驗證和授權,但是會延遲對應用程式程式碼的授權決策。This option turns on authentication and authorization in App Service, but defers authorization decisions to your application code. 對於已驗證的要求,App Service 也會在 HTTP 標頭中一起傳送驗證資訊。For authenticated requests, App Service also passes along authentication information in the HTTP headers.

此選項會提供更大的彈性來處理匿名要求。This option provides more flexibility in handling anonymous requests. 例如,它可讓您向使用者顯示多個登入提供者For example, it lets you present multiple sign-in providers to your users. 不過,您必須撰寫程式碼。However, you must write code.

其他資源More resources

教學課程:在 Azure App Service 中對使用者進行端對端驗證和授權 (Windows)Tutorial: Authenticate and authorize users end-to-end in Azure App Service (Windows)
教學課程:在適用於 Linux 的 Azure App Service 中端對端驗證和授權使用者Tutorial: Authenticate and authorize users end-to-end in Azure App Service for Linux
自訂 App Service 中的驗證與授權Customize authentication and authorization in App Service

提供者專屬的使用說明指南:Provider-specific how-to guides: