Azure 应用服务和 Azure Functions 中的身份验证和授权Authentication and authorization in Azure App Service and Azure Functions

Azure 应用服务提供内置的身份验证和授权支持。只需在 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. 本文介绍应用服务如何帮助简化应用的身份验证和授权。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 provides these utilities so that you can spend more time and energy on providing business value to your customer.


你并非必须使用此功能进行身份验证和授权。You're not required to use this feature for authentication and authorization. 可以在所选的 Web 框架中使用捆绑的安全功能,也可以编写自己的实用程序。You can use the bundled security features in your web framework of choice, or you can write your own utilities. 但请记住,Chrome 80 针对 Cookie 对其实现 SameSite 的方式进行了中断性变更(发布日期在 2020 年 3 月左右);自定义远程身份验证或依赖于跨站点 Cookie 发布的其他方案可能会在客户端 Chrome 浏览器更新时中断。However, keep in mind that Chrome 80 is making breaking changes to its implementation of SameSite for cookies (release date around March 2020), and custom remote authentication or other scenarios that rely on cross-site cookie posting may break when client Chrome browsers are updated. 解决方法很复杂,因为需要针对不同的浏览器支持不同的 SameSite 行为。The workaround is complex because it needs to support different SameSite behaviors for different browsers.

应用服务托管的 ASP.NET Core 2.1 及更高版本已针对此中断性变更进行了修补,并且会相应地处理 Chrome 80 和更低版本的浏览器。The ASP.NET Core 2.1 and above versions hosted by App Service are already patched for this breaking change and handle Chrome 80 and older browsers appropriately. 此外,我们还在整个 2020 年 1 月在应用服务实例上部署了 ASP.NET Framework 4.7.2 的同一修补程序。In addition, the same patch for ASP.NET Framework 4.7.2 has been deployed on the App Service instances throughout January 2020. 有关详细信息,请参阅 Azure 应用服务 SameSite Cookie 更新For more information, see Azure App Service SameSite cookie update.


“身份验证/授权”功能有时也称为“简单身份验证/授权”。The Authentication/Authorization feature is also sometimes referred to as "Easy Auth".


启用此功能会导致对应用程序的所有非安全 HTTP 请求自动重定向到 HTTPS,而不管强制实施 HTTPS 所需的应用服务配置设置如何。Enabling this feature will cause all non-secure HTTP requests to your application to be automatically redirected to HTTPS, regardless of the App Service configuration setting to enforce HTTPS. 如果需要,可以通过身份验证/授权设置配置文件中的 requireHttps 设置禁用此功能,但需注意确保不通过非安全 HTTP 连接传输安全令牌。If needed, you can disable this via the requireHttps setting in the auth settings configuration file, but you must then take care to ensure no security tokens ever get transmitted over non-secure HTTP connections.

有关特定于本机移动应用的信息,请参阅使用 Azure 应用服务对移动应用进行用户身份验证和授权For information specific to native mobile apps, see User authentication and authorization for mobile apps with Azure App Service.

工作原理How it works

在 Windows 上On Windows

身份验证和授权模块在应用程序代码所在的同一沙盒中运行。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/Application claims

对于所有语言框架,应用服务都通过将传入令牌(无论是来自经过身份验证的最终用户还是来自客户端应用程序)中的声明注入请求标头,使其可供代码使用。For all language frameworks, App Service makes the claims in the incoming token (whether that be from an authenticated end user or a client application) available to your code by injecting them into the request headers. 对于 ASP.NET 4.6 应用,应用服务会在 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 应用,应用服务会填充 _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,但你仍然可以在请求标头中找到用户声明,也可通过请求上下文甚至通过绑定参数来获取 ClaimsPrincipal 对象。For Azure Functions, ClaimsPrincipal.Current is not populated for .NET code, but you can still find the user claims in the request headers, or get the ClaimsPrincipal object from the request context or even through a binding parameter. 有关详细信息,请参阅使用客户端标识See working with client identities for more information.

有关详细信息,请参阅访问用户声明For more information, see Access user claims.


目前,ASP.NET Core 不支持为当前用户填充身份验证/授权功能。At this time, ASP.NET Core does not currently support populating the current user with the Authentication/Authorization feature. 但是,确实存在一些第三方开源中间件组件,可以帮助填补这一空白。However, some 3rd party, open source middleware components do exist to help fill this gap.

令牌存储Token store

应用服务提供内置的令牌存储,这是与 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:

  • 发布到经过身份验证用户的 MicrosoftAccount 时间线post to the authenticated user's MicrosoftAccount timeline
  • 使用 Microsoft Graph API 读取用户的公司数据read the user's corporate data using the Microsoft Graph API

通常,必须编写代码才能在应用程序中收集、存储和刷新这些令牌。You typically must write code to collect, store, and refresh these tokens in your application. 使用令牌存储,只需在需要令牌时才检索令牌;当令牌失效时,可以告知应用服务刷新令牌With the token store, you just retrieve the tokens when you need them and tell App Service to refresh them when they become invalid.

将为经身份验证的会话缓存 ID 令牌、访问令牌和刷新令牌,它们只能由关联的用户访问。The ID tokens, access tokens, and refresh tokens are 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 in your app's Authentication / Authorization page.

日志记录和跟踪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 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
任何 OpenID Connect 提供程序(预览版)Any OpenID Connect provider (preview) /.auth/login/<providerName>

对其中一个提供程序启用身份验证和授权时,其登录终结点可用于用户身份验证,以及验证来自提供程序的身份验证令牌。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.

存在旧版可扩展性路径,用于与其他标识提供者或自定义身份验证/授权解决方案集成,但是不建议使用,A legacy extensibility path exists for integrating with other identity providers or a custom auth solution, but this is not recommended. 而应考虑使用 OpenID Connect 支持。Instead, consider using the OpenID Connect support.

身份验证流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:应用程序向应用服务委托联合登录。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. 它也适用于使用移动应用客户端 SDK 登录用户的本机应用,因为 SDK 会打开 Web 视图,使用应用服务身份验证将用户登录。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:应用程序手动将用户登录到提供程序,然后将身份验证令牌提交给应用服务进行验证。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.


对于应用服务中受信任浏览器应用对应用服务或 Azure Functions 中另一 REST API 的调用,可以使用服务器导向流对其进行身份验证。Calls from a trusted browser app in App Service to another REST API in App Service or Azure Functions can be authenticated using the server-directed flow. 有关详细信息,请参阅在应用服务中自定义身份验证和授权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 应用服务将经过身份验证的 Cookie 添加到响应中。App Service adds authenticated cookie to response. 应用服务将自身的身份验证令牌返回给客户端代码。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 标头中提供身份验证令牌(由移动应用客户端 SDK 自动处理)。Client code presents authentication token in X-ZUMO-AUTH header (automatically handled by Mobile Apps client SDKs).

对于客户端浏览器,应用服务可自动将所有未经身份验证的用户定向到 /.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 门户中,当传入请求未经过身份验证时,可以使用多种行为配置应用服务授权。In the Azure portal, you can configure App Service authorization with a number of behaviors when incoming request is not authenticated.


以下标题介绍了选项。The following headings describe the options.

允许匿名请求(无操作)Allow Anonymous requests (no action)

此选项将对未经身份验证的流量的授权交给应用程序代码处理。This option defers authorization of unauthenticated traffic to your application code. 对于经过身份验证的请求,应用服务还会在 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.

仅允许经过身份验证的请求Allow only authenticated requests

选项是“使用 <provider> 登录”。The option is Log in with <provider>. 应用服务将所有匿名请求重定向到所选提供程序的 /.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).


以这种方式限制访问适用于对应用的所有调用,对于想要主页公开可用的应用程序来说,这可能是不可取的,就像在许多单页应用程序中一样。Restricting access in this way applies to all calls to your app, which may not be desirable for apps wanting a publicly available home page, as in many single-page applications.


默认情况下,Azure AD 租户中的任何用户都可以从 Azure AD 请求应用程序的令牌。By default, any user in your Azure AD tenant can request a token for your application from Azure AD. 若要仅允许一组定义的用户访问应用,可以在 Azure AD 中配置应用程序You can configure the application in Azure AD if you want to restrict access to your app to a defined set of users.

更多资源More resources

特定于提供程序的操作方法指南:Provider-specific how-to guides: