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

为使 Web/机密客户端应用程序能够参与要求身份验证的授权流程(以及获取访问令牌),必须建立安全凭据。For a web/confidential client application to be able to participate in an authorization grant flow that requires authentication (and obtain an access token), it must establish secure credentials. Azure 门户支持的默认身份验证方法为“客户端 ID + 机密密钥”。The default authentication method supported by the Azure portal is client ID + secret key.

此外,在客户端可以访问资源应用程序公开的 Web API(例如 Microsoft Graph API)之前,许可框架可确保客户端根据请求的权限获取所需的授权。Additionally, 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 based on the permissions requested. 默认情况下,所有应用程序都可以从 Microsoft Graph API 选择权限。By default, all applications can choose permissions from the Microsoft Graph API. 默认选择图形 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 desired web API:

  • 应用程序权限 - 客户端应用程序需要亲自直接访问 Web API(无用户上下文)。Application permissions - Your client application needs to access the web API directly as itself (no user context). 此类型的权限需要管理员同意,并且不可用于公共(桌面和移动)客户端应用程序。This type of permission requires administrator consent and is also not available for public (desktop and mobile) client applications.

  • 委托的权限 - 客户端应用程序需要以登录用户的身份访问 Web API,但访问权限受所选权限的限制。Delegated permissions - 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.

    Note

    将委托权限添加到应用程序不会自动向租户中的用户授予许可。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.

本快速入门介绍如何将应用配置为执行以下操作:In this quickstart, we'll show you how to configure your app to:

先决条件Prerequisites

若要开始,请确保满足下列先决条件:To get started, make sure you complete these prerequisites:

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

在配置应用之前,请执行以下步骤:Before you can configure the app, follow these steps:

  1. 使用工作或学校帐户登录到 Azure 门户Sign in to the Azure portal using a work or school account.
  2. 如果你的帐户有权访问多个租户,请在右上角选择该帐户,并将门户会话设置为所需的 Azure AD 租户。If your account gives you access to more than one tenant, select your account in the top-right corner, and set your portal session to the desired Azure AD tenant.
  3. 搜索并选择“Azure Active Directory” 。Search for and select Azure Active Directory.
  4. 在左侧窗格中,选择“应用注册” 。From the left pane, select App registrations.
  5. 找到并选择要配置的应用程序。Find and select the application you want to configure. 选择应用以后,会看到应用程序的“概览”页或主注册页。 Once you've selected the app, you'll see the application's Overview or main registration page.
  6. 按步骤将应用程序配置为访问 Web API:Follow the steps to configure your application to access web APIs:

将重定向 URL 添加到应用程序Add redirect URI(s) to your application

若要将重定向 URI 添加到应用程序,请执行以下步骤:To add a redirect URI to your application:

  1. 在应用的“概览”页中,选择“身份验证”部分。 From the app's Overview page, select the Authentication section.

  2. 若要为 Web 和公共客户端应用程序添加自定义重定向 URI,请执行以下步骤:To add a custom redirect URI for web and public client applications, follow these steps:

    1. 找到“重定向 URI” 部分。Locate the Redirect URI section.
    2. 选择要生成的应用程序的类型:“Web”或“公共客户端(移动和桌面)”。 Select the type of application you're building, Web or Public client (mobile & desktop).
    3. 输入应用程序的重定向 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.
  3. 若要从建议用于公共客户端(移动、桌面)的重定向 URI 中进行选择,请执行以下步骤:To choose from suggested Redirect URIs for public clients (mobile, desktop), follow these steps:

    1. 找到“建议用于公共客户端(移动、桌面)的重定向 URI”部分。 Locate the Suggested Redirect URIs for public clients (mobile, desktop) section.
    2. 通过复选框选择适用于应用程序的重定向 URI。Select the appropriate Redirect URI(s) for your application using the checkboxes. 还可以输入自定义重定向 URI。You can also enter a custom redirect URI. 如果不确定要使用什么,请查看库文档。If you're not sure what to use, check out the library documentation.

有一些限制适用于重定向 URI。There are certain restrictions that apply to redirect URIs. 详细了解重定向 URI 限制和限制Learn more about redirect URI restrictions and limitations.

Note

尝试新的“身份验证设置”体验,在其中可以根据要面向的平台或设备配置应用程序的设置。 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 default Authentication page view.

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

此时会转到新的“平台配置”页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 are acquiring tokens with Integrated Windows Authentication, device code flow, or username/password in the Default client type section, configure 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

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

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

在最初注册应用程序时配置支持的帐户类型后,只能在以下情况下使用应用程序清单编辑器更改此设置:Once you've configured the supported account types when you initially 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 vice versa.
  • 将帐户类型从 AzureADMyOrg 更改为 AzureADMultipleOrgs,或反之。You change account types from AzureADMyOrg to AzureADMultipleOrgs, or vice versa.

若要更改现有应用注册支持的帐户类型:To change the supported account types for an existing app registration:

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

根据平台或设备配置应用的设置Configure settings for your app based on the platform or device

若要根据面向的平台或设备配置应用程序设置: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 选项Choices 配置设置Configuration settings
    Web 应用程序Web applications WebWeb 输入应用程序的“重定向 URI”。 Enter the Redirect URI for your application.
    移动应用程序Mobile applications iOSiOS 输入应用的“捆绑 ID”(可在 XCode 中的 info.plist 内找到,或者在“生成设置”中找到)。 Enter the app's 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's 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.
    桌面 + 设备Desktop + devices 桌面 + 设备Desktop + devices * 可选。* 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 应用程序,请使用 https://localhostFor example, for .NET Core applications where you want interaction, use https://localhost.

    Important

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

  3. 根据所选的平台,可能还可以配置其他设置。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:

  1. 在应用的“概览”页中,选择“证书和机密”部分。 From the app's Overview page, select the Certificates & secrets section.

  2. 若要添加证书,请执行以下步骤:To add a certificate, follow these steps:

    1. 选择“上传证书”。 Select Upload certificate.
    2. 选择要上传的文件。Select the file you'd like to upload. 它必须是以下文件类型之一:.cer、.pem、.crt。It must be one of the following file types: .cer, .pem, .crt.
    3. 选择“添加” 。Select Add.
  3. 若要添加客户端机密,请执行以下步骤:To add a client secret, follow these steps:

    1. 选择“新建客户端机密”。 Select New client secret.
    2. 添加客户端机密的说明。Add a description for your client secret.
    3. 选择持续时间。Select a duration.
    4. 选择“添加” 。Select Add.

Note

保存配置更改后,最右边的列会包含客户端机密值。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 的权限,请执行以下操作:To add permission(s) to access resource APIs from your client:

  1. 在应用的“概览”页中,选择“API 权限”部分。 From the app's Overview page, select API permissions.
  2. 在“已配置权限”部分下,选择“添加权限”按钮。 Under the Configured permissions section, select the Add a permission button.
  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 API - 用于选择 Microsoft API(例如 Microsoft Graph)的权限。Microsoft APIs - Lets you select permissions for Microsoft APIs such as Microsoft Graph.
    • 组织使用的 API - 用于选择由组织公开的 API 或组织已与之集成的 API 的权限。APIs my organization uses - Lets you select permissions for APIs that have been exposed by your organization, or APIs that your organization has integrated with.
    • 我的 API - 用于选择你已经公开的 API 的权限。My APIs - Lets you select permissions for APIs that you have exposed.
  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 will return to the API permissions page, where 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 (\the permissions that 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/revoke admin consent for a set of an API's permissions or individual permissions in this section.

授予的其他权限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 that have been granted for the tenant but have not been explicitly configured on the application object (e.g. permissions that 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 will see a Grant admin consent for Tenant button. 如果你不是管理员,或者没有为应用程序配置任何权限,则将禁用此按钮。It will be disabled if you are not an admin, or if no permissions have been configured for the application. 通过此按钮,管理员可以轻松地向为应用程序配置的权限授予管理员同意。This button allows an admin to easily 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.

Note

为应用程序配置的权限与在同意提示下显示的权限之间存在延迟。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, when clicking the admin consent button you will be prompted to decide how 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. 如果选择“接受” ,则将授予管理员同意。If you select Accept, admin consent is granted. 如果选择“取消” ,则不授予管理员同意,你将看到一条错误,指出同意已被拒绝。If you select Cancel, admin consent is not granted, and you will see an error stating that consent has been declined.

Note

授予管理员同意(在同意提示中选择“接受” )与在 UI 中反映的管理员同意状态之间存在延迟。There is a delay between granting admin consent (selecting Accept on the consent prompt) and the status of admin consent being reflected in the UI.

后续步骤Next steps

了解下述其他相关的应用管理快速入门:Learn about these other related app management quickstarts for apps:

了解有关表示已注册应用程序的两个 Azure AD 对象及它们之间的关系的详细信息,请参阅应用程序对象和服务主体对象To learn more about the two Azure AD objects that represent a registered application and the relationship between them, see Application objects and service principal objects.

深入了解使用 Azure Active Directory 开发应用程序时应使用的品牌准则,请参阅应用程序的品牌准则To learn more about the branding guidelines you should use when developing applications with Azure Active Directory, see Branding guidelines for applications.