本机应用Native apps

重要

Microsoft 标识平台 (v2.0) 由 Azure Active Directory (Azure AD) 开发人员平台 (v1.0) 演变而来。Microsoft identity platform (v2.0) is an evolution of the Azure Active Directory (Azure AD) developer platform (v1.0). 开发人员可以通过它来生成应用程序,从而可以采用所有 Microsoft 标识登录,以及获取令牌来调用 Microsoft Graph 等 Microsoft API 或开发人员生成的 API。It allows developers to build applications that sign in all Microsoft identities and get tokens to call Microsoft APIs such as Microsoft Graph or APIs that developers have built. 此内容适用于较旧的 Azure AD v1.0 终结点。This content is for the older, Azure AD v1.0 endpoint. 我们建议对新项目使用 v2.0 终结点。We recommend that you use the v2.0 endpoint for new projects. 有关详细信息,请阅读为什么更新到 Microsoft 标识平台 (v2.0)?For more info, read Why update to Microsoft identity platform (v2.0)? 以及 Microsoft 标识平台限制as well as Microsoft identity platform limitations.

本机应用是代表用户调用 Web API 的应用程序。Native apps are applications that call a web API on behalf of a user. 此方案是基于带有公共客户端的 OAuth 2.0 授权代码授予类型构建的,如 OAuth 2.0 规范的第 4.1 部分所述。This scenario is built on the OAuth 2.0 authorization code grant type with a public client, as described in section 4.1 of the OAuth 2.0 specification. 本机应用程序使用 OAuth 2.0 协议获取用户的访问令牌。The native application obtains an access token for the user by using the OAuth 2.0 protocol. 然后会在请求中将此访问令牌发送到 Web API,后者对用户进行授权并返回所需的资源。This access token is then sent in the request to the web API, which authorizes the user and returns the desired resource.

图示Diagram

本机应用程序到 Web API 图示

协议流Protocol flow

如果使用 AD 身份验证库,它会替你处理下面所述的大多数协议细节,例如浏览器弹出窗口、令牌缓存以及对刷新令牌的处理。If you are using the AD Authentication Libraries, most of the protocol details described below are handled for you, such as the browser pop-up, token caching, and handling of refresh tokens.

  1. 本机应用程序使用浏览器弹出窗口向 Azure AD 中的授权终结点发出请求。Using a browser pop-up, the native application makes a request to the authorization endpoint in Azure AD. 此请求包括本机应用程序的应用程序 ID 和重定向 URI(如 Azure 门户中所示),以及 Web API 的应用程序 ID URI。This request includes the Application ID and the redirect URI of the native application as shown in the Azure portal, and the application ID URI for the web API. 如果用户尚未登录,系统同样会提示他们登录If the user hasn’t already signed in, they are prompted to sign in again
  2. Azure AD 对用户进行身份验证。Azure AD authenticates the user. 如果它是一个多租户应用程序并且需要许可才能使用应用程序,用户需要表示许可(如果他们尚未如此做)。If it is a multi-tenant application and consent is required to use the application, the user will be required to consent if they haven’t already done so. 在用户授予许可并成功进行身份验证后,Azure AD 会将一个授权代码响应发回客户端应用程序的重定向 URI。After granting consent and upon successful authentication, Azure AD issues an authorization code response back to the client application’s redirect URI.
  3. Azure AD 将授权代码响应发回重定向 URI 时,客户端应用程序将停止浏览器交互并从响应中提取授权代码。When Azure AD issues an authorization code response back to the redirect URI, the client application stops browser interaction and extracts the authorization code from the response. 使用此授权代码,客户端应用程序向 Azure AD 的令牌终结点发送请求,请求中包括授权代码、关于客户端应用程序的详细信息(应用程序 ID 和重定向 URI)以及所需的资源(Web API 的应用程序 ID URI)。Using this authorization code, the client 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).
  4. Azure AD 对授权代码和关于客户端应用程序和 Web API 的信息进行验证。The authorization code and information about the client 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. 此外,Azure AD 还会返回关于用户的基本信息,例如其显示名称和租户 ID。In addition, Azure AD returns basic information about the user, such as their display name and tenant ID.
  5. 通过 HTTPS,客户端应用程序使用返回的 JWT 访问令牌在发往 Web API 的请求的 Authorization 标头中添加一个具有“Bearer”限定符的 JWT 字符串。Over HTTPS, the client 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.
  6. 访问令牌过期时,客户端应用程序会收到一个错误,指出用户需要重新进行身份验证。When the access token expires, the client application will receive an error that indicates the user needs to authenticate again. 如果应用程序具有有效的刷新令牌,可以使用它来获取新的访问令牌,系统不会提示用户重新登录。If the application has a valid refresh token, it can be used to acquire a new access token without prompting the user to sign in again. 如果刷新令牌过期,应用程序会再次需要以交互方式对用户进行身份验证。If the refresh token expires, the application will need to interactively authenticate the user once again.

备注

Azure AD 颁发的刷新令牌可以用来访问多个资源。The refresh token issued by Azure AD can be used to access multiple resources. 例如,如果某个客户端应用程序有权调用两个 Web API,则同样可以使用刷新令牌来获取其他 Web API 的访问令牌。For example, if you have a client application that has permission to call two web APIs, the refresh token can be used to get an access token to the other web API as well.

代码示例Code samples

请参阅本机应用程序到 Web API 方案的代码示例。See the code samples for Native Application to Web API scenarios. 另外,请经常回来查看 - 我们会经常添加新示例。And, check back frequently -- we add new samples frequently. 本机应用程序到 Web APINative 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 API 必须在 Azure AD 的同一个目录中进行注册。Single tenant - Both the native application and the web API must be registered in the same directory in Azure AD. 可以对 Web API 进行配置以公开一组权限,并使用这些权限来限制本机应用程序对其资源的访问。The web API can be configured to expose a set of permissions, which are used to limit the native application’s access to its resources. 然后,客户端应用程序从 Azure 门户的“对其他应用程序的权限”下拉菜单中选择所需的权限。The client application then selects the desired permissions from the “Permissions to Other Applications” drop-down menu in the Azure portal.
  • 多租户 - 首先,本机应用程序只在开发人员或发布者的目录中进行注册。Multi-tenant - First, the native application only ever registered in the developer or publisher’s directory. 其次,本机应用程序在配置后会指示它在正常运行时所需的权限。Second, the native 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 API。When the user or administrator consents, only the web API is registered in their directory.

令牌过期Token expiration

本机应用程序使用其授权代码来获取 JWT 访问令牌时,它还会收到一个 JWT 刷新令牌。When the native 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 re-authenticate 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