调用 Web API 的守护程序应用 - 代码配置

了解如何为调用 Web API 的守护程序应用程序配置代码。

支持守护程序应用的 Microsoft 库

以下 Microsoft 库支持守护程序应用:

语言/框架 项目
GitHub
获取
started
用户登录 访问 Web API 正式发布 (GA) 或
公共预览版1
.NET MSAL.NET Microsoft.Identity.Client 快速入门 库无法为用户登录请求 ID令牌。 库可以为受保护的 Web API 请求访问令牌。 GA
Java MSAL4J msal4j 库无法为用户登录请求 ID令牌。 库可以为受保护的 Web API 请求访问令牌。 GA
节点 MSAL Node msal-node 快速入门 库无法为用户登录请求 ID令牌。 库可以为受保护的 Web API 请求访问令牌。 GA
Python MSAL Python msal-python 快速入门 库无法为用户登录请求 ID令牌。 库可以为受保护的 Web API 请求访问令牌。 GA

1 Azure 预览版的补充使用条款适用于公共预览版中的库。

配置颁发机构

守护程序应用程序使用应用程序权限,而不是委托的权限。 因此,它们支持的帐户类型不能是任何组织目录中的帐户。 你需要选择“我的组织中的帐户” 或“任何组织中的帐户” 。

在应用程序配置中指定的颁发机构应该是租户的(指定租户 ID 或者与组织相关联的域名)。

即使在需要提供多租户工具的情况下,也应在此流中使用租户 ID 或域名,而 不是 commonorganizations,因为该服务无法可靠推断出应使用哪个租户。

配置并实例化应用程序

在 MSAL 库中,客户端凭据(机密或证书)是作为机密客户端应用程序构造的参数传递的。

重要

即使应用程序是作为服务运行的控制台应用程序,如果它是守护程序应用程序,则也需要是机密客户端应用程序。

配置文件

配置文件定义:

  • 云实例和租户 ID,它们共同构成了“机构”。
  • 通过应用程序注册获得的客户端 ID。
  • 客户端机密或证书。

下面是关于在 appsettings.json 文件中定义配置的示例。 此示例摘自 GitHub 上的 .NET Core 控制台守护程序代码示例。

{
  "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]"
}

请提供 ClientSecretCertificateName。 这些设置是互斥的。

实例化 MSAL 应用程序

若要实例化 MSAL 应用程序,请添加、引用或导入 MSAL 包(取决于语言)。

构造取决于你是使用客户端机密还是使用证书(还是使用已签名断言,这是一种高级方案)。

引用此包

在应用程序代码中引用 MSAL 包。

Microsoft.Identity.Client NuGet 包添加到应用程序,然后在代码中添加一个 using 指令以引用它。

在 MSAL.NET 中,机密客户端应用程序通过 IConfidentialClientApplication 接口表示。

using Microsoft.Identity.Client;
IConfidentialClientApplication app;

使用客户端机密实例化机密客户端应用程序

下面的代码用于使用客户端机密实例化机密客户端应用程序:

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

Authority 是云实例和租户 ID 的串联,例如 https://login.partner.microsoftonline.cn/contoso.partner.onmschina.cnhttps://login.partner.microsoftonline.cn/eb1ed152-0000-0000-0000-32401f3f9abd。 在配置文件部分显示的 appsettings.json 文件中,它们分别由 InstanceTenant 值表示。

在上一个代码片段的源代码示例中,AuthorityAuthenticationConfig 类的属性,其定义如下:

/// <summary>
/// URL of the authority
/// </summary>
public string Authority
{
    get
    {
        return String.Format(CultureInfo.InvariantCulture, Instance, Tenant);
    }
}

通过客户端证书实例化机密客户端应用程序

下面的代码用于使用证书来构建应用程序:

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

高级方案:使用客户端断言实例化机密客户端应用程序

机密客户端应用程序还可以使用客户端断言(而不是客户端密码或证书)来证明其身份。

MSAL.NET 可以通过两种方法将签名的断言提供给机密客户端应用:

  • .WithClientAssertion()
  • .WithClientClaims()

使用 WithClientAssertion 时,请提供签名的 JWT。 客户端断言详细介绍了这一高级方案。

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

使用 WithClientClaims 时,MSAL.NET 将生成一个已签名断言,其中包含 Azure AD 预期的声明,以及你想要发送的其他客户端声明。 此代码展示了如何执行该操作:

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();

同样,如需详细信息,请参阅客户端断言

后续步骤

转到此方案中的下一篇文章:获取应用的令牌