快速入门:配置客户端应用程序以访问 Web APIQuickstart: Configure a client application to access web APIs

在本快速入门中,你将添加重定向 URI、凭据或权限,用于访问应用程序的 Web API。In this quickstart, you add redirect URIs, credentials, or permissions to access web APIs for your application. Web 或机密客户端应用程序需要建立安全凭据,才能参与需要身份验证的授权流。A web or confidential client application needs to establish secure credentials to participate in an authorization grant flow that requires authentication. Azure 门户支持的默认身份验证方法为“客户端 ID + 机密密钥”。The default authentication method supported by the Azure portal is client ID + secret key. 应用将在此过程中获取访问令牌。The app obtains an access token during this process.

在客户端可以访问资源应用程序公开的 Web API(例如 Microsoft Graph API)之前,许可框架可确保客户端获取所请求权限的授权。Before a client can access a web API exposed by a resource application, such as Microsoft Graph API, the consent framework ensures the client obtains the permission grant required for the permissions requested. 默认情况下,所有应用程序都可以从 Microsoft Graph API 请求权限。By default, all applications can request permissions from the Microsoft Graph API.

先决条件Prerequisites

登录到 Azure 门户,并选择应用Sign in to the Azure portal and select the app

  1. 使用工作或学校帐户登录到 Azure 门户Sign in to the Azure portal using a work or school account.
  2. 如果帐户有权访问多个租户,请在右上角选择该帐户。If your account gives you access to more than one tenant, select your account in the upper right corner. 将门户会话设置为所需的 Azure AD 租户。Set your portal session to the Azure AD tenant that you want.
  3. 搜索并选择“Azure Active Directory” 。Search for and select Azure Active Directory. 在“管理”下,选择“应用注册”。 Under Manage, select App registrations.
  4. 找到并选择要配置的应用程序。Find and select the application you want to configure. 选择应用后,会看到应用程序的“概述”页或主注册页。 After you select the app, you see the application's Overview or main registration page.

使用以下过程配置应用程序以访问 Web API。Use the following procedures to configure your application to access web APIs.

将重定向 URI 添加到应用程序Add redirect URIs to your application

可将自定义重定向 URI 和建议的重定向 URI 添加到应用程序。You can add custom redirect URIs and suggested redirect URIs to your application. 若要为 Web 和公共客户端应用程序添加自定义重定向 URI:To add a custom redirect URI for web and public client applications:

  1. 在应用的“概述”页中,选择“身份验证”。 From the app Overview page, select Authentication.

  2. 找到“重定向 URI”。 Locate Redirect URIs. 可能需要选择“切换到旧体验”。 You may need to select Switch to the old experience.

  3. 选择要生成的应用程序类型:“Web”或“公共客户端/本机(移动和桌面)”。 Select the type of application you're building: Web or Public client/native (mobile & desktop).

  4. 输入应用程序的重定向 URI。Enter the Redirect URI for your application.

    • 对于 Web 应用程序,请提供应用程序的基 URL。For web applications, provide the base URL of your application. 例如,http://localhost:31544 可以是本地计算机上运行的 Web 应用程序的 URL。For example, http://localhost:31544 might be the URL for a web application running on your local machine. 用户将使用此 URL 登录到 Web 客户端应用程序。Users would use this URL to sign into a web client application.
    • 对于公共应用程序,请提供 Azure AD 返回令牌响应时所用的 URI。For public applications, provide the URI used by Azure AD to return token responses. 输入特定于应用程序的值,例如 https://MyFirstAppEnter a value specific to your application, for example: https://MyFirstApp.
  5. 选择“保存”。 Select Save.

若要从建议用于公共客户端的重定向 URI 中进行选择,请执行以下步骤:To choose from suggested redirect URIs for public clients, follow these steps:

  1. 在应用的“概述”页中,选择“身份验证”。 From the app Overview page, select Authentication.
  2. 找到“建议用于公共客户端(移动、桌面)的重定向 URI”。 Locate Suggested Redirect URIs for public clients (mobile, desktop). 可能需要选择“切换到旧体验”。 You may need to select Switch to the old experience.
  3. 为应用程序选择一个或多个重定向 URI。Select one or more redirect URIs for your application. 还可以输入自定义重定向 URI。You can also enter a custom redirect URI. 如果不确定要使用哪个值,请参阅库文档。If you're not sure what to use, see the library documentation.
  4. 选择“保存”。 Select Save.

某些限制适用于重定向 URI。Certain restrictions apply to redirect URIs. 有关详细信息,请参阅重定向 URI/回复 URL 的限制和局限性For more information, see Redirect URI/reply URL restrictions and limitations.

备注

尝试新的“身份验证设置”体验,在其中可以根据要面向的平台或设备配置应用程序的设置。 Try out the new Authentication settings experience where you can configure settings for your application based on the platform or device that you want to target.

若要查看此视图,请在“身份验证”页中选择“试用新体验”。 To see this view, select Try out the new experience from the Authentication page.

单击“试用新体验”以查看平台配置视图

此时会转到新的“平台配置”页This takes you to the new Platform configurations page.

配置应用程序的高级设置Configure advanced settings for your application

根据要注册的应用程序,可能需要配置其他一些设置,例如:Depending on the application you're registering, there are some additional settings that you may need to configure, such as:

  • 注销 URLLogout URL.
  • 对于单页应用,可以启用“隐式授权”,并选择希望授权终结点颁发的令牌。 For single-page apps, you can enable Implicit grant and select the tokens that you'd like the authorization endpoint to issue.
  • 对于“默认客户端类型”部分中使用 Windows 集成身份验证、设备代码流或用户名/密码获取令牌的桌面应用,请将“将应用程序视为公共客户端”设置指定为“是”。 For desktop apps that acquire tokens by using Integrated Windows Authentication, device code flow, or username/password in the Default client type section, set the Treat application as public client setting to Yes.
  • 对于使用 Live SDK 来与 Microsoft 帐户服务集成的传统应用,请配置“Live SDK 支持”。 For legacy apps that were using the Live SDK to integrate with the Microsoft account service, configure Live SDK support. 新应用不需要此设置。New apps don't need this setting.
  • 默认客户端类型Default client type.
  • 支持的帐户类型Supported account types.

修改支持的帐户类型Modify supported account types

“支持的帐户类型”指定哪些用户可以使用该应用程序或访问 API。 The Supported account types specify who can use the application or access the API.

如果在注册应用程序时配置了支持的帐户类型,则只能在以下情况下使用应用程序清单编辑器更改此设置:If you configured the supported account types when you registered the application, you can only change this setting using the application manifest editor if:

  • 将帐户类型从 AzureADMyOrgAzureADMultipleOrgs 更改为 AzureADandPersonalMicrosoftAccount,或反之,或者You change account types from AzureADMyOrg or AzureADMultipleOrgs to AzureADandPersonalMicrosoftAccount, or the other way around, or
  • 将帐户类型从 AzureADMyOrg 更改为 AzureADMultipleOrgs,或反之。You change account types from AzureADMyOrg to AzureADMultipleOrgs, or the other way around.

若要更改现有应用注册支持的帐户类型,请更新 signInAudience 键。To change the supported account types for an existing app registration, update the signInAudience key. 有关详细信息,请参阅配置应用程序清单For more information, see Configure the application manifest.

配置应用程序的平台设置Configure platform settings for your application

根据平台或设备配置应用的设置

若要根据面向的平台或设备配置应用程序设置:To configure application settings based on the platform or device, you're targeting:

  1. 在“平台配置”页上选择“添加平台”,并从可用选项中进行选择。 In the Platform configurations page, select Add a platform and choose from the available options.

    显示“配置平台”页

  2. 根据所选的平台输入设置信息。Enter the settings info based on the platform you selected.

    平台Platform 配置设置Configuration settings
    WebWeb 输入应用程序的“重定向 URI”。 Enter the Redirect URI for your application.
    iOS/macOSiOS / macOS 输入应用的“捆绑 ID”(可在 XCode 中的 info.plist 内找到,或者在“生成设置”中找到)。 Enter the app Bundle ID, which you can find in XCode in Info.plist, or Build Settings. 添加捆绑 ID 可自动创建应用程序的重定向 URI。Adding the bundle ID automatically creates a redirect URI for the application.
    AndroidAndroid 提供应用的“包名称”(可在 AndroidManifest.xml 文件中找到)。 Provide the app Package name, which you can find in the AndroidManifest.xml file.
    生成并输入签名哈希Generate and enter the Signature hash. 添加签名哈希可自动创建应用程序的重定向 URI。Adding the signature hash automatically creates a redirect URI for the application.
    移动和桌面应用程序Mobile and desktop applications 可选。Optional. 为桌面和设备生成应用时,请选择建议的重定向 URI 之一。Select one of the recommended Suggested redirect URIs if you're building apps for desktop and devices.
    可选。Optional. 输入一个自定义重定向 URI,用作 Azure AD 在响应身份验证请求时将用户重定向到的位置。Enter a Custom redirect URI, which is used as the location where Azure AD will redirect users in response to authentication requests. 例如,对于要交互的 .NET Core 应用程序,请使用 http://localhostFor example, for .NET Core applications where you want interaction, use http://localhost.

    备注

    在 Active Directory 联合身份验证服务 (AD FS) 和 Azure AD B2C 上,还必须指定端口号。On Active Directory Federation Services (AD FS) and Azure AD B2C, you must also specify a port number. 例如:http://localhost:1234For example: http://localhost:1234.

    重要

    对于不使用最新 Microsoft 身份验证库 (MSAL) 或不使用中介的移动应用程序,必须在“桌面 + 设备”中为这些应用程序配置重定向 URI。 For mobile applications that aren't using the latest Microsoft Authentication Library (MSAL) or not using a broker, you must configure the redirect URIs for these applications in Desktop + devices.

根据所选的平台,可能还可以配置其他设置。Depending on the platform you chose, there may be additional settings that you can configure. 对于“Web”应用,可以: For Web apps, you can:

  • 添加更多重定向 URIAdd more redirect URIs

  • 配置“隐式授权”,以选择希望由授权终结点颁发的令牌: Configure Implicit grant to select the tokens you'd like to be issued by the authorization endpoint:

    • 对于单页应用,请同时选择“访问令牌”和“ID 令牌” For single-page apps, select both Access tokens and ID tokens
    • 对于 Web 应用,请选择“ID 令牌” For web apps, select ID tokens

将凭据添加到 Web 应用程序Add credentials to your web application

若要将凭据添加到 Web 应用程序,请添加证书或创建客户端机密。To add a credential to your web application, either add a certificate or create a client secret. 若要添加证书,请执行以下操作:To add a certificate:

  1. 在应用的“概述”页中,选择“证书和机密”部分。 From the app Overview page, select the Certificates & secrets section.
  2. 选择“上传证书”。 Select Upload certificate.
  3. 选择要上传的文件。Select the file you'd like to upload. 它必须是以下文件类型之一:.cer、.pem、.crt。It must be one of the following file types: .cer, .pem, .crt.
  4. 选择 添加Select Add.

若要添加客户端机密:To add a client secret:

  1. 在应用的“概述”页中,选择“证书和机密”部分。 From the app Overview page, select the Certificates & secrets section.
  2. 选择“新建客户端机密”。 Select New client secret.
  3. 添加客户端机密的说明。Add a description for your client secret.
  4. 选择持续时间。Select a duration.
  5. 选择 添加Select Add.

备注

保存配置更改后,最右边的列会包含客户端机密值。After you save the configuration changes, the right-most column will contain the client secret value. 请务必复制此值,以便在客户端应用程序代码中使用,因为退出此页后将无法访问此密钥。Be sure to copy the value for use in your client application code as it's not accessible once you leave this page.

添加用于访问 Web API 的权限Add permissions to access web APIs

默认已选择图形 API 登录和读取用户配置文件权限The Graph API sign-in and read user profile permission is selected by default. 对于每个 Web API,可以从两种类型的权限中进行选择:You can select from two types of permissions for each web API:

  • 应用程序权限Application permissions. 客户端应用程序需要自行直接访问 Web API,不使用用户上下文。Your client application needs to access the web API directly as itself, without user context. 此权限类型需要管理员许可。This type of permission requires administrator consent. 此权限不适用于桌面和移动客户端应用程序。This permission isn't available for desktop and mobile client applications.

  • 委托的权限Delegated permissions. 客户端应用程序需要以登录用户的身份访问 Web API,但访问权限受所选权限的限制。Your client application needs to access the web API as the signed-in user, but with access limited by the selected permission. 除非权限需要管理员许可,否则用户可以授予此类型的权限。This type of permission can be granted by a user unless the permission requires administrator consent.

    备注

    将委托权限添加到应用程序不会自动向租户中的用户授予许可。Adding a delegated permission to an application does not automatically grant consent to the users within the tenant. 除非管理员代表所有用户授予许可,否则用户仍必须在运行时手动同意添加的委托权限。Users must still manually consent for the added delegated permissions at runtime, unless the administrator grants consent on behalf of all users.

若要添加从客户端访问资源 API 的权限:To add permissions to access resource APIs from your client:

  1. 在应用的“概述”页中,选择“API 权限”。 From the app Overview page, select API permissions.

  2. 在“已配置权限” 下,选择“添加权限” 。Under Configured permissions, select Add a permission.

  3. 默认情况下,此视图允许从“Microsoft API”进行选择。 By default, the view allows you to select from Microsoft APIs. 选择感兴趣的 API 部分。Select the section of APIs that you're interested in:

    • Microsoft APIMicrosoft APIs. 用于选择 Microsoft API(例如 Microsoft Graph)的权限。Lets you select permissions for Microsoft APIs such as Microsoft Graph.
    • 我的组织使用的 APIAPIs my organization uses. 用于选择组织公开的 API 或者组织已集成的 API 的权限。Lets you select permissions for APIs that your organization exposes, or APIs that your organization has integrated with.
    • 我的 APIMy APIs. 用于选择你公开的 API 的权限。Lets you select permissions for APIs that you expose.
  4. 选择 API 后,会看到“请求 API 权限”页。 Once you've selected the APIs, you'll see the Request API Permissions page. 如果 API 公开委托的权限和应用程序权限,请选择应用程序需要哪种类型的权限。If the API exposes both delegated and application permissions, select which type of permission your application needs.

  5. 完成后,请选择“添加权限” 。When finished, select Add permissions.

随即会返回到“API 权限”页。 You return to the API permissions page. 权限已保存并已添加到表中。The permissions have been saved and added to the table.

已配置权限Configured permissions

本部分介绍已在应用程序对象中显式配置的权限。This section shows the permissions that have been explicitly configured on the application object. 这些权限是应用所需资源访问列表的一部分。These permissions are part of the app's required resource access list. 可以在此表中添加或删除权限。You may add or remove permissions from this table. 管理员还可为一组 API 权限或单个权限授予或撤销管理员许可。As an admin, you can also grant or revoke admin consent for a set of an API's permissions or individual permissions.

授予的其他权限Other permissions granted

如果你的应用程序已在租户中注册,则你可能会看到一个名为“为租户授予的其他权限”的附加部分 。If your application is registered in a tenant, you may see an additional section titled Other permissions granted for Tenant. 本部分介绍为租户授予的、未在应用程序对象中显式配置的权限。This section shows permissions granted for the tenant that haven't been explicitly configured on the application object. 这些权限是动态请求和许可的。These permissions were dynamically requested and consented. 仅当至少有一个应用的权限时,才会显示此部分。This section only appears if there is at least one permission that applies.

可以将此部分中显示的一组 API 权限或单个权限添加到“已配置权限”部分 。You may add a set of an API's permissions or individual permissions that appear in this section to the Configured permissions section. 作为管理员,你还可以撤销此部分中各个 API 或权限的管理员同意。As an admin, you can also revoke admin consent for individual APIs or permissions in this section.

如果你的应用程序已在租户中注册,你将看到“为租户授予管理员许可”按钮。 If your application is registered in a tenant, you see a Grant admin consent for Tenant button. 如果你不是管理员,或者没有为应用程序配置任何权限,则将禁用此按钮。It's disabled if you aren't an admin, or if no permissions have been configured for the application. 管理员可以通过此按钮向为应用程序配置的权限授予管理员许可。This button allows an admin to grant admin consent to the permissions configured for the application. 单击“管理员同意”按钮将启动一个新窗口,其中包含显示了所有已配置权限的同意提示。Clicking the admin consent button launches a new window with a consent prompt showing all the configured permissions.

备注

为应用程序配置的权限与在同意提示下显示的权限之间存在延迟。There is a delay between permissions being configured for the application and them appearing on the consent prompt. 如果在同意提示中看不到所有配置的权限,请将其关闭并重新启动。If you do not see all the configured permissions in the consent prompt, close it and launch it again.

如果为你授予了权限但尚未配置这些权限,则管理员许可按钮会提示你处理这些权限。If you have permissions that have been granted but not configured, the admin consent button prompts you to handle these permissions. 可以将它们添加到已配置的权限,也可以将其删除。You may add them to configured permissions or you may remove them.

同意提示提供“接受”或“取消”选项 。The consent prompt provides the option to Accept or Cancel. 选择“接受”以授予管理员许可。 Select Accept to grant admin consent. 如果选择“取消”,则不会授予管理员许可。 If you select Cancel, admin consent isn't granted. 将有一条错误消息指出已拒绝许可。An error message states that consent has been declined.

备注

在许可提示中选择“接受”授予管理员许可之后,在门户中反映管理员许可状态之前,会存在一段延迟。 There is a delay between granting admin consent by selecting Accept on the consent prompt and the status of admin consent being reflected in the portal.

后续步骤Next steps

继续学习下一篇文章了解如何公开 Web API。Advance to the next article to learn how to expose web APIs.