调用 Web API 的守护程序应用 - 代码配置Daemon app that calls web APIs - code configuration

了解如何为调用 Web API 的守护程序应用程序配置代码。Learn how to configure the code for your daemon application that calls web APIs.

支持守护程序应用的 MSAL 库MSAL Libraries supporting daemon apps

支持守护程序应用的 Microsoft 库包括:The Microsoft libraries supporting daemon apps are:

MSAL 库MSAL library 说明Description
MSAL.NET
MSAL.NETMSAL.NET
支持用于构建守护程序应用程序的平台为 .NET Framework 和 .NET Core 平台(不包括 UWP、Xamarin.iOS 和 Xamarin.Android,因为这些平台用于构建公共客户端应用程序)Supported platforms to build a daemon application are .NET Framework and .NET Core platforms (not UWP, Xamarin.iOS, and Xamarin.Android as those platforms are used to build public client applications)
Python
MSAL PythonMSAL Python
Python 对守护程序应用程序的支持Support for daemon applications in Python
Java
MSAL JavaMSAL Java
Java 对守护程序应用程序的支持Support for daemon applications in Java

配置颁发机构Configuration of the Authority

如果你是 ISV 并希望提供多租户工具,则可使用 organizationsIf you're an ISV and want to provide a multi-tenant tool, you can use organizations. 但请记住,你还需向客户说明如何授予管理员同意。But keep in mind that you'll also need to explain to your customers how to grant admin consent. 有关详细信息,请参阅请求整个租户的许可See Requesting consent for an entire tenant for details. 此外,目前 MSAL 中有一个限制:仅当客户端凭据是应用程序机密(而不是证书)时才允许使用 organizationsAlso there's currently a limitation in MSAL: organizations is only allowed when the client credentials are an application secret (not a certificate).

应用程序配置和实例化Application configuration and instantiation

在 MSAL 库中,客户端凭据(机密或证书)是作为机密客户端应用程序构造的参数传递的。In MSAL libraries, the client credentials (secret or certificate) are passed as a parameter of the confidential client application construction.

Important

即使应用程序是作为服务运行的控制台应用程序,如果它是守护程序应用程序,则也需要是机密客户端应用程序。Even if your application is a console application running as a service, if it's a daemon application it needs to be a confidential client application.

配置文件Configuration file

配置文件定义:The configuration file defines:

  • 颁发机构或者云实例和 tenantIdthe authority or the cloud instance and tenantId
  • 通过应用程序注册获得的 ClientIDthe ClientID that you got from the application registration
  • 客户端机密或证书either a client secret, or a certificate

appsettings.json,来自 .NET Core 控制台守护程序示例。appsettings.json from the .NET Core console daemon sample.

{
  "Instance": "https://login.partner.microsoftonline.cn/{0}",
  "Tenant": "[Enter here the tenantID or domain name for your Azure AD tenant]",
  "ClientId": "[Enter here the ClientId for your application]",
  "ClientSecret": "[Enter here a client secret for your application]",
  "CertificateName": "[Or instead of client secret: Enter here the name of a certificate (from the user cert store) as registered with your application]"
}

你提供一个 clientSecret 或 certificateName。Either you provide a clientSecret or a certificateName. 两项设置都是独占性的。Both settings are exclusive.

安装 MSAL 应用程序Instantiation of the MSAL application

若要实例化 MSAL 应用程序,需执行以下操作:To instantiate the MSAL application, you need to:

  • 添加、引用或导入 MSAL 包(具体取决于语言)add, reference, or import the MSAL package (depending on the language)
  • 然后,构造取决于你是使用客户端机密还是使用证书(或者是使用充当高级方案的已签名断言)Then the construction is different depending on if you're using client secrets or certificates (or, as an advanced scenario, signed assertions)

引用此包Reference the package

在应用程序代码中引用 MSAL 包。Reference the MSAL package in your application code.

向应用程序添加 Microsoft.IdentityClient NuGet 包。Add the Microsoft.IdentityClient NuGet package to your application. 在 MSAL.NET 中,机密客户端应用程序通过 IConfidentialClientApplication 接口表示。In MSAL.NET, the confidential client application is represented by the IConfidentialClientApplication interface. 在源代码中使用 MSAL.NET 命名空间Use MSAL.NET namespace in the source code

using Microsoft.Identity.Client;
IConfidentialClientApplication app;

通过客户端机密实例化机密客户端应用程序Instantiate the confidential client application with client secrets

下面是代码,用于通过客户端机密实例化机密客户端应用程序:Here is the code to instantiate the confidential client application with a client secret:

app = ConfidentialClientApplicationBuilder.Create(config.ClientId)
           .WithClientSecret(config.ClientSecret)
           .WithAuthority(new Uri(config.Authority))
           .Build();

通过客户端证书实例化机密客户端应用程序Instantiate the confidential client application With client certificate

下面的代码演示如何使用证书来生成应用程序:Here is the code to build an application with a certificate:

X509Certificate2 certificate = ReadCertificate(config.CertificateName);
app = ConfidentialClientApplicationBuilder.Create(config.ClientId)
    .WithCertificate(certificate)
    .WithAuthority(new Uri(config.Authority))
    .Build();

高级方案 - 通过客户端断言实例化机密客户端应用程序Advanced scenario - instantiate the confidential client application with client assertions

机密客户端应用程序还可以使用客户端断言(而不是客户端密码或证书)来证明其身份。Instead of a client secret or a certificate, the confidential client application can also prove its identity using client assertions.

MSAL.NET 可以通过两种方法将签名的断言提供给机密客户端应用:MSAL.NET has two methods to provide signed assertions to the confidential client app:

  • .WithClientAssertion()
  • .WithClientClaims()

使用 WithClientAssertion 时,需提供签名的 JWT。When you use WithClientAssertion, you need to provide a signed JWT. 客户端断言详细介绍了这一高级方案This advanced scenario is detailed in Client assertions

string signedClientAssertion = ComputeAssertion();
app = ConfidentialClientApplicationBuilder.Create(config.ClientId)
                                          .WithClientAssertion(signedClientAssertion)
                                          .Build();

使用 WithClientClaims 时,MSAL.NET 会自行计算一个签名断言,其中包含 Azure AD 预期的声明,以及你想要发送的其他客户端声明。When you use WithClientClaims, MSAL.NET will compute itself a signed assertion containing the claims expected by Azure AD plus additional client claims that you want to send. 下面是演示如何这样做的代码片段:Here is a code snippet on how to do that:

string ipAddress = "192.168.1.2";
var claims = new Dictionary<string, string> { { "client_ip", ipAddress } };
X509Certificate2 certificate = ReadCertificate(config.CertificateName);
app = ConfidentialClientApplicationBuilder.Create(config.ClientId)
                                          .WithAuthority(new Uri(config.Authority))
                                          .WithClientClaims(certificate, claims)
                                          .Build();```

同样,如需详细信息,请参阅客户端断言Again, for details, see Client assertions.

后续步骤Next steps