应用程序配置选项Application configuration options

在代码中,可以初始化新的公共或机密客户端应用程序(或 MSAL.js 的用户代理)以进行身份验证并获取令牌。In your code, you initialize a new public or confidential client application (or user-agent for MSAL.js) to authenticate and acquire tokens. 初始化 Microsoft 身份验证库 (MSAL) 中的客户端应用程序时,可以设置许多的配置选项。You can set a number of configuration options when you initialize the client app in Microsoft Authentication Library (MSAL). 这些选项划分为两组:These options fall into two groups:

颁发机构Authority

颁发机构是一个 URL,表示 MSAL 可从中请求令牌的目录。The authority is a URL that indicates a directory that MSAL can request tokens from. 常见的颁发机构包括:Common authorities are:

  • https://login.partner.microsoftonline.cn/<tenant>/,其中,<tenant> 是 Azure Active Directory (Azure AD) 租户的租户 ID,或者与此 Azure AD 租户关联的域。https://login.partner.microsoftonline.cn/<tenant>/, where <tenant> is the tenant ID of the Azure Active Directory (Azure AD) tenant or a domain associated with this Azure AD tenant. 仅用于将特定组织的用户登录。Used only to sign in users of a specific organization.
  • https://login.partner.microsoftonline.cn/common/。https://login.partner.microsoftonline.cn/common/. 用于通过工作和学校帐户将用户登录。Used to sign in users with work and school accounts.
  • https://login.partner.microsoftonline.cn/organizations/。https://login.partner.microsoftonline.cn/organizations/. 用于通过工作和学校帐户将用户登录。Used to sign in users with work and school accounts.

颁发机构设置需要与在门户中声明的设置一致。The authority setting needs to be consistent with what's declared in the portal.

颁发机构 URL 由实例和受众构成。The authority URL is composed of the instance and the audience.

颁发机构可以是:The authority can be:

  • Azure AD 云颁发机构。An Azure AD cloud authority.
  • Azure AD B2C 颁发机构。An Azure AD B2C authority. 请参阅 B2C 细节See B2C specifics.
  • Active Directory 联合身份验证服务 (AD FS) 颁发机构。An Active Directory Federation Services (AD FS) authority. 请参阅 AD FS support(AD FS 支持)。See AD FS support.

Azure AD 云颁发机构有两个组成部分:Azure AD cloud authorities have two parts:

  • 标识提供者实例 The identity provider instance
  • 应用的登录受众 The sign-in audience for the app

可将实例和受众连接到一起,以颁发机构 URL 的形式提供。The instance and audience can be concatenated and provided as the authority URL. 在 MSAL 3.x 以前的 MSAL.NET 版本中,必须根据想要面向的云和登录受众自行构成颁发机构。In versions of MSAL.NET earlier than MSAL 3.x, you had to compose the authority yourself, based on the cloud you wanted to target and the sign-in audience. 下图显示了颁发机构 URL 的构成方式:This diagram shows how the authority URL is composed:

如何构成颁发机构 URL

云实例Cloud instance

实例用于指定应用是要从 Azure 公有云还是国家/地区云将用户登录。 The instance is used to specify if your app is signing users from the Azure public cloud or from national clouds. 在代码中使用 MSAL 可以通过枚举或者将 URL 作为 Instance 成员(如果知道该成员)传递给国家/地区云实例,来设置 Azure 云实例。Using MSAL in your code, you can set the Azure cloud instance by using an enumeration or by passing the URL to the national cloud instance as the Instance member (if you know it).

如果同时指定 InstanceAzureCloudInstance,MSAL.NET 将引发显式异常。MSAL.NET will throw an explicit exception if both Instance and AzureCloudInstance are specified.

如果未指定实例,应用将面向 Azure 公有云实例If you don't specify an instance, your app will target the Azure public cloud instance

应用程序受众Application audience

登录受众取决于应用的业务需求:The sign-in audience depends on the business needs for your app:

  • 业务线应用程序 (LOB) 开发人员也许会生成一个只在其组织中使用的单租户应用程序。If you're a line of business (LOB) developer, you'll probably produce a single-tenant application that will be used only in your organization. 在这种情况下,需要按租户 ID(Azure AD 实例的 ID)或者与 Azure AD 实例关联的域名指定组织。In that case, you need to specify the organization, either by its tenant ID (the ID of your Azure AD instance) or by a domain name associated with the Azure AD instance.
  • ISV 可能想要使用任一组织或某些组织(多租户应用)中的用户工作帐户和学校帐户将用户登录。If you're an ISV, you might want to sign in users with their work and school accounts in any organization or in some organizations (multitenant app).

如何在代码/配置中指定受众How to specify the audience in your code/configuration

在代码中使用 MSAL 时,可以使用以下值之一指定受众:Using MSAL in your code, you specify the audience by using one of the following values:

  • Azure AD 颁发机构受众枚举The Azure AD authority audience enumeration
  • 租户 ID,可以是:The tenant ID, which can be:
    • 单租户应用程序的 GUID(Azure AD 实例的 ID)A GUID (the ID of your Azure AD instance), for single-tenant applications
    • 与 Azure AD 实例关联的域名(也适用于单租户应用程序)A domain name associated with your Azure AD instance (also for single-tenant applications)
  • 以下租户 ID 占位符之一代表 Azure AD 颁发机构受众枚举:One of these placeholders as a tenant ID in place of the Azure AD authority audience enumeration:
    • 多租户应用程序的 organizationsorganizations for a multitenant application
    • 用于通过工作和学校帐户将用户登录的 commoncommon to sign in users with their work and school accounts

如果你同时指定 Azure AD 颁发机构受众和租户 ID,MSAL 将引发有含义的异常。MSAL will throw a meaningful exception if you specify both the Azure AD authority audience and the tenant ID.

如果你未指定受众,应用将面向充当受众的 Azure AD。If you don't specify an audience, your app will target Azure AD as an audience. (也就是说,它的行为与指定了 common 时一样。)(That is, it will behave as though common were specified.)

有效的受众Effective audience

应用程序的有效受众是在应用中设置的受众与在应用注册中指定的受众之间的最小值(如果存在交集)。The effective audience for your application will be the minimum (if there's an intersection) of the audience you set in your app and the audience that's specified in the app registration. 实际上,可以在应用注册体验中指定应用的受众(支持的帐户类型)。In fact, the App registrations experience lets you specify the audience (the supported account types) for the app. 有关详细信息,请参阅快速入门:将应用程序注册到 Microsoft 标识平台For more information, see Quickstart: Register an application with the Microsoft identity platform.

客户端 IDClient ID

客户端 ID 是注册应用时由 Azure AD 分配给应用的唯一应用程序(客户端)ID。The client ID is the unique application (client) ID assigned to your app by Azure AD when the app was registered.

重定向 URIRedirect URI

重定向 URI 是标识提供者将安全令牌发回到的 URI。The redirect URI is the URI the identity provider will send the security tokens back to.

公共客户端应用的重定向 URIRedirect URI for public client apps

如果你是使用 MSAL 的公共客户端应用开发人员:If you're a public client app developer who's using MSAL:

  • 可能需要在桌面或 UWP 应用程序 (MSAL.NET 4.1+) 中使用 .WithDefaultRedirectUri()You'd want to use .WithDefaultRedirectUri() in desktop or UWP applications (MSAL.NET 4.1+). 此方法会将公共客户端应用程序的重定向 URI 属性设置为建议用于公共客户端应用程序的默认重定向 URI。This method will set the public client application's redirect uri property to the default recommended redirect uri for public client applications.

    平台Platform 重定向 URIRedirect URI
    桌面应用 (.NET FW)Desktop app (.NET FW) https://login.partner.microsoftonline.cn/common/oauth2/nativeclient
    UWPUWP WebAuthenticationBroker.GetCurrentApplicationCallbackUri() 的值。value of WebAuthenticationBroker.GetCurrentApplicationCallbackUri(). 这可以通过浏览器启用 SSO,方法是:将值设置为需注册的 WebAuthenticationBroker.GetCurrentApplicationCallbackUri() 的结果This enables SSO with the browser by setting the value to the result of WebAuthenticationBroker.GetCurrentApplicationCallbackUri() which you need to register
    .NET Core.NET Core https://localhosthttps://localhost. 这样用户就可以将系统浏览器用于交互式身份验证,因为 .NET Core 目前没有 UI 用于嵌入式 Web 视图。This enables the user to use the system browser for interactive authentication since .NET Core doesn't have a UI for the embedded web view at the moment.
  • 若要构建不支持代理的 Xamarin Android 和 iOS 应用程序,则不需添加重定向 URI(对于 Xamarin Android 和 iOS,重定向 URI 会自动设置为 msal{ClientId}://authYou don't need to add a redirect URI if you're building a Xamarin Android and iOS application that doesn't support broker (the redirect URI is automatically set to msal{ClientId}://auth for Xamarin Android and iOS

  • 需要在应用注册中配置重定向 URI:You need to configure the redirect URI in App registrations:

    应用注册中的重定向 URI

可以使用 RedirectUri 属性替代重定向 URI(例如,如果使用代理)。You can override the redirect URI by using the RedirectUri property (for example, if you use brokers). 下面是该方案的重定向 URI 的一些示例:Here are some examples of redirect URIs for that scenario:

  • RedirectUriOnAndroid = "msauth-5a434691-ccb2-4fd1-b97b-b64bcfbc03fc://com.microsoft.identity.client.sample";RedirectUriOnAndroid = "msauth-5a434691-ccb2-4fd1-b97b-b64bcfbc03fc://com.microsoft.identity.client.sample";
  • RedirectUriOnIos = $"msauth.{Bundle.ID}://auth";RedirectUriOnIos = $"msauth.{Bundle.ID}://auth";

有关更多 iOS 详细信息,请参阅将使用 Microsoft Authenticator 的 iOS 应用程序从 ADAL.NET 迁移到 MSAL.NET在 iOS 上利用中转站For additional iOS details, see Migrate iOS applications that use Microsoft Authenticator from ADAL.NET to MSAL.NET and Leveraging the broker on iOS.

机密客户端应用的重定向 URIRedirect URI for confidential client apps

对于 Web 应用,重定向 URI(或回复 URI)是 Azure AD 用来向应用程序发回令牌的 URI。For web apps, the redirect URI (or reply URI) is the URI that Azure AD will use to send the token back to the application. 如果机密应用是 Web 应用/Web API,则此 URI 可以是其 URL。This URI can be the URL of the web app/web API if the confidential app is one of these. 重定向 URI 需在应用注册中注册。The redirect URI needs to be registered in app registration. 部署一个最初已在本地测试的应用时,这种注册尤其重要。This registration is especially important when you deploy an app that you've initially tested locally. 然后,需要在门户中添加已部署的应用的回复 URL。You then need to add the reply URL of the deployed app in the portal.

对于守护程序应用,不需要指定重定向 URI。For daemon apps, you don't need to specify a redirect URI.

客户端机密Client secret

此选项指定机密客户端应用的客户端机密。This option specifies the client secret for the confidential client app. 在使用 PowerShell AzureAD、PowerShell AzureRM 或 Azure CLI 注册应用期间,此机密(应用密码)将提供给 Azure AD。This secret (app password) is provided to Azure AD during app registration with PowerShell AzureAD, PowerShell AzureRM, or Azure CLI.

日志记录Logging

其他配置选项可用于日志记录和故障排除。The other configuration options enable logging and troubleshooting. 有关其用法的详细信息,请参阅日志记录一文。See the Logging article for details on how to use them.

后续步骤Next steps

了解如何使用 MSAL.NET 实例化客户端应用程序Learn about instantiating client applications by using MSAL.NET. 了解如何使用 MSAL.js 实例化客户端应用程序Learn about instantiating client applications by using MSAL.js.