Web APIWeb API

Web API 应用是需要通过 Web API 获取资源的 Web 应用。Web API apps are web applications that need to get resources from a web API. 在此方案中,Web 应用可以使用两种标识类型进行身份验证并调用 Web API:In this scenario, there are two identity types that the web application can use to authenticate and call the web API:

  • 应用程序标识 - 此方案使用 OAuth 2.0 客户端凭据授予作为应用程序进行身份验证并访问 Web API。Application identity - This scenario uses OAuth 2.0 client credentials grant to authenticate as the application and access the web API. 使用应用程序标识时,Web API 只能检测到 Web 应用程序在调用它,因为 Web API 不会收到关于用户的任何信息。When using an application identity, the web API can only detect that the web application is calling it, as the web API does not receive any information about the user. 如果应用程序收到关于用户的信息,该信息会通过应用程序协议发送,并且 Azure AD 不会对其签名。If the application receives information about the user, it will be sent via the application protocol, and it is not signed by Azure AD. Web API 相信 Web 应用程序已对用户进行了身份验证。The web API trusts that the web application authenticated the user. 因此,此模式称为受信任的子系统。For this reason, this pattern is called a trusted subsystem.
  • 委托用户标识 - 此方案可以通过两种方式完成:OpenID Connect 和 OAuth 2.0 授权代码使用机密客户端进行授权。Delegated user identity - This scenario can be accomplished in two ways: OpenID Connect, and OAuth 2.0 authorization code grant with a confidential client. Web 应用程序获取用户的访问令牌,该令牌将向 Web API 证明用户已成功通过了 Web 应用程序的身份验证并且 Web 应用程序能够获取委托用户标识来调用 Web API。The web application obtains an access token for the user, which proves to the web API that the user successfully authenticated to the web application and that the web application was able to obtain a delegated user identity to call the web API. 然后会在请求中将此访问令牌发送到 Web API,后者对用户进行授权并返回所需的资源。This access token is sent in the request to the web API, which authorizes the user and returns the desired resource.

下面的流对应用程序标识类型和委托用户标识类型都进行了讨论。Both the application identity and delegated user identity types are discussed in the flow below. 它们之间的主要区别是,委托用户标识必须先获取一个授权代码,用户才能登录并访问 Web API。The key difference between them is that the delegated user identity must first acquire an authorization code before the user can sign in and gain access to the web API.

图示Diagram

Web 应用程序到 Web API 图示

协议流Protocol flow

带有 OAuth 2.0 客户端凭据授权的应用程序标识Application identity with OAuth 2.0 client credentials grant

  1. 用户在 Web 应用中登录到 Azure AD(有关详细信息,请参阅 Web 应用部分)。A user is signed in to Azure AD in the web application (see the Web apps section for more info).
  2. Web 应用程序需要获取访问令牌,以便通过 Web API 进行身份验证并检索所需的资源。The web application needs to acquire an access token so that it can authenticate to the web API and retrieve the desired resource. 它向 Azure AD 的令牌终结点发出一个请求,在其中提供凭据、应用程序 ID 以及 Web API 的应用程序 ID URI。It makes a request to Azure AD’s token endpoint, providing the credential, application ID, and web API’s application ID URI.
  3. Azure AD 对应用程序进行身份验证并返回用来调用 Web API 的 JWT 访问令牌。Azure AD authenticates the application and returns a JWT access token that is used to call the web API.
  4. 通过 HTTPS,Web 应用程序使用返回的 JWT 访问令牌在发往 Web API 的请求的 Authorization 标头中添加一个具有“Bearer”限定符的 JWT 字符串。Over HTTPS, the web application uses the returned JWT access token to add the JWT string with a “Bearer” designation in the Authorization header of the request to the web API. 然后,Web API 对 JWT 令牌进行验证,如果验证成功,则返回所需的资源。The web API then validates the JWT token, and if validation is successful, returns the desired resource.

采用 OpenID Connect 的委托用户标识Delegated user identity with OpenID Connect

  1. 用户使用 Azure AD 登录到 Web 应用程序(请参阅前面的“Web 浏览器到 Web 应用程序”部分)。A user is signed in to a web application using Azure AD (see the Web Browser to Web Application section above). 如果 Web 应用程序的用户尚未许可允许 Web 应用程序代表自己调用 Web API,则需要用户许可。If the user of the web application has not yet consented to allowing the web application to call the web API on its behalf, the user will need to consent. 应用程序将显示它要求的权限,如果这些权限中有任何一个是管理员级权限,目录中的普通用户无法许可。The application will display the permissions it requires, and if any of these are administrator-level permissions, a normal user in the directory will not be able to consent. 此许可过程仅适用于多租户应用程序,不适用于单租户应用程序,因为单租户应用程序那时已经具有了必需的权限。This consent process only applies to multi-tenant applications, not single tenant applications, as the application will already have the necessary permissions. 用户登录后,Web 应用程序将收到一个 ID 令牌,其中包含关于用户的信息以及授权代码。When the user signed in, the web application received an ID token with information about the user, as well as an authorization code.
  2. 使用由 Azure AD 颁发的授权代码,Web 应用程序向 Azure AD 的令牌终结点发送请求,请求中包括授权代码、关于客户端应用程序的详细信息(应用程序 ID 和重定向 URI)以及所需的资源(Web API 的应用程序 ID URI)。Using the authorization code issued by Azure AD, the web application sends a request to Azure AD’s token endpoint that includes the authorization code, details about the client application (Application ID and redirect URI), and the desired resource (application ID URI for the web API).
  3. Azure AD 对授权代码和关于 Web 应用程序和 Web API 的信息进行验证。The authorization code and information about the web application and web API are validated by Azure AD. 验证成功时,Azure AD 返回两个令牌:一个 JWT 访问令牌和一个 JWT 刷新令牌。Upon successful validation, Azure AD returns two tokens: a JWT access token and a JWT refresh token.
  4. 通过 HTTPS,Web 应用程序使用返回的 JWT 访问令牌在发往 Web API 的请求的 Authorization 标头中添加一个具有“Bearer”限定符的 JWT 字符串。Over HTTPS, the web application uses the returned JWT access token to add the JWT string with a “Bearer” designation in the Authorization header of the request to the web API. 然后,Web API 对 JWT 令牌进行验证,如果验证成功,则返回所需的资源。The web API then validates the JWT token, and if validation is successful, returns the desired resource.

采用 OAuth 2.0 授权代码授权的委托用户标识Delegated user identity with OAuth 2.0 authorization code grant

  1. 用户已登录到 Web 应用程序,该应用程序的身份验证机制独立于 Azure AD。A user is already signed in to a web application, whose authentication mechanism is independent of Azure AD.
  2. Web 应用程序需要一个授权代码来获取访问令牌,因此,在成功进行身份验证后,它通过浏览器向 Azure AD 的授权终结点发出一个请求,其中提供了应用程序 ID 和 Web 应用程序的重定向 URI。The web application requires an authorization code to acquire an access token, so it issues a request through the browser to Azure AD’s authorization endpoint, providing the Application ID and redirect URI for the web application after successful authentication. 用户登录到 Azure AD。The user signs in to Azure AD.
  3. 如果 Web 应用程序的用户尚未许可允许 Web 应用程序代表自己调用 Web API,则需要用户许可。If the user of the web application has not yet consented to allowing the web application to call the web API on its behalf, the user will need to consent. 应用程序将显示它要求的权限,如果这些权限中有任何一个是管理员级权限,目录中的普通用户无法许可。The application will display the permissions it requires, and if any of these are administrator-level permissions, a normal user in the directory will not be able to consent. 此许可适用于单租户和多租户应用程序。This consent applies to both single and multi-tenant application. 在单租户情况下,管理员可以代表其用户对许可执行管理员同意。In the single tenant case, an admin can perform admin consent to consent on behalf of their users. 可使用 Azure 门户中的 Grant Permissions 按钮完成此操作。This can be done using the Grant Permissions button in the Azure portal.
  4. 用户许可后,Web 应用程序将收到它获取访问令牌所需的授权代码。After the user has consented, the web application receives the authorization code that it needs to acquire an access token.
  5. 使用由 Azure AD 颁发的授权代码,Web 应用程序向 Azure AD 的令牌终结点发送请求,请求中包括授权代码、关于客户端应用程序的详细信息(应用程序 ID 和重定向 URI)以及所需的资源(Web API 的应用程序 ID URI)。Using the authorization code issued by Azure AD, the web application sends a request to Azure AD’s token endpoint that includes the authorization code, details about the client application (Application ID and redirect URI), and the desired resource (application ID URI for the web API).
  6. Azure AD 对授权代码和关于 Web 应用程序和 Web API 的信息进行验证。The authorization code and information about the web application and web API are validated by Azure AD. 验证成功时,Azure AD 返回两个令牌:一个 JWT 访问令牌和一个 JWT 刷新令牌。Upon successful validation, Azure AD returns two tokens: a JWT access token and a JWT refresh token.
  7. 通过 HTTPS,Web 应用程序使用返回的 JWT 访问令牌在发往 Web API 的请求的 Authorization 标头中添加一个具有“Bearer”限定符的 JWT 字符串。Over HTTPS, the web application uses the returned JWT access token to add the JWT string with a “Bearer” designation in the Authorization header of the request to the web API. 然后,Web API 对 JWT 令牌进行验证,如果验证成功,则返回所需的资源。The web API then validates the JWT token, and if validation is successful, returns the desired resource.

代码示例Code samples

请参阅 Web 应用程序到 Web API 方案的代码示例。See the code samples for Web Application to Web API scenarios. 另外,请经常回来查看 - 我们会经常添加新示例。And, check back frequently -- new samples are added frequently. Web 应用程序到 Web APIWeb Application to Web API.

应用注册App registration

若要向 Azure AD v1.0 终结点注册应用程序,请参阅注册应用To register an application with the Azure AD v1.0 endpoint, see Register an app.

  • 单租户 - 对于应用程序标识和委托用户标识这两种情况,Web 应用和 Web API 都必须在 Azure AD 的同一个目录中进行注册。Single tenant - For both the application identity and delegated user identity cases, the web application and the web API must be registered in the same directory in Azure AD. 可以对 Web API 进行配置以公开一组权限,并使用这些权限来限制 Web 应用程序对其资源的访问。The web API can be configured to expose a set of permissions, which are used to limit the web application’s access to its resources. 如果使用的是委托用户标识类型,则 Web 应用需要从 Azure 门户的“对其他应用程序的权限” 下拉菜单中选择所需的权限。If a delegated user identity type is being used, the web application needs to select the desired permissions from the Permissions to other applications drop-down menu in the Azure portal. 如果使用的是应用程序标识类型,则不需要此步骤。This step is not required if the application identity type is being used.
  • 多租户 - 首先,Web 应用在配置后会指示它在正常运行时所需的权限。Multi-tenant - First, the web application is configured to indicate the permissions it requires to be functional. 目标目录中的用户或管理员许可应用程序的要求,使应用程序可供其组织使用时,此必需权限列表会显示在一个对话框中。This list of required permissions is shown in a dialog when a user or administrator in the destination directory gives consent to the application, which makes it available to their organization. 某些应用程序只需要用户级权限,组织中的任何用户都可以表示许可。Some applications only require user-level permissions, which any user in the organization can consent to. 另外一些应用程序需要管理员级权限,组织中的用户无法许可。Other applications require administrator-level permissions, which a user in the organization cannot consent to. 只有目录管理员可以对需要此级别的权限的应用程序表示许可。Only a directory administrator can give consent to applications that require this level of permissions. 用户或管理员许可后,在其目录中注册 Web 应用程序和 Web API。When the user or administrator consents, the web application and the web API are both registered in their directory.

令牌过期Token expiration

Web 应用程序使用其授权代码来获取 JWT 访问令牌时,它还会收到一个 JWT 刷新令牌。When the web application uses its authorization code to get a JWT access token, it also receives a JWT refresh token. 当访问令牌过期时,可以使用刷新令牌来重新对用户进行身份验证,而不需要他们重新登录。When the access token expires, the refresh token can be used to reauthenticate the user without requiring them to sign in again. 然后将使用此刷新令牌对用户进行身份验证,生成新的访问令牌和刷新令牌。This refresh token is then used to authenticate the user, which results in a new access token and refresh token.

后续步骤Next steps