你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 .NET 的 Azure 标识中转身份验证客户端库 - 版本 1.0.0

项目
11/08/2023

该库扩展 Azure.Identity 库以提供身份验证代理支持。它包含必要的依赖项，并提供 InteractiveBrowserCredentialBrokerOptions 类。此选项类可用于创建能够 InteractiveBrowserCredential 使用系统身份验证代理代替系统浏览器（如果可用）的。

源代码 | 包 (nuget) | API 参考文档 | Microsoft Entra ID 文档

入门

安装包

使用 NuGet 安装适用于 .NET 的 Azure 标识客户端库：

dotnet add package Azure.Identity.Broker

先决条件

Azure.Identity 库是 Azure.Identity.Broker 的依赖项。

验证客户端

关键概念

此包与包中的 Azure.Identity 结合使用InteractiveBrowserCredential，通过 InteractiveBrowserCredentialBrokerOptions启用身份验证代理支持。

父窗口句柄

使用构造InteractiveBrowserCredentialBrokerOptions的以InteractiveBrowserCredential交互方式进行身份验证时，需要一个父窗口句柄，以确保身份验证对话框在请求窗口上正确显示。在设备上的图形用户界面上下文中，窗口句柄是操作系统分配给每个窗口的唯一标识符。对于 Windows 操作系统，此句柄是一个整数值，用作对特定窗口的引用。

Microsoft 帐户 (MSA) 直通

MICROSOFT 帐户 (MSA) 是用户创建的个人帐户，用于访问 Microsoft 服务。 MSA 直通是一种旧配置，使用户能够获取通常不接受 MSA 登录的资源的令牌。此功能仅适用于第一方应用程序。使用配置为使用 MSA 传递的应用程序进行身份验证的用户可以将属性true设置为 InteractiveBrowserCredentialBrokerOptions.IsLegacyMsaPassthroughEnabled 以允许 WAM 列出这些个人帐户。

重定向 URI

Microsoft Entra应用程序依赖于重定向 URI 来确定在用户登录后将身份验证响应发送到何处。若要通过 WAM 启用中转身份验证，应将匹配以下模式的重定向 URI 注册到应用程序：

ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}

示例

将配置为 `InteractiveBrowserCredential` 使用系统身份验证代理

此示例演示如何使用专用选项类型InteractiveBrowserCredentialBrokerOptions配置 InteractiveBrowserCredential 以启用中转身份验证。

IntPtr parentWindowHandle = GetForegroundWindow();

// Create an interactive browser credential which will use the system authentication broker
var credential = new InteractiveBrowserCredential(new InteractiveBrowserCredentialBrokerOptions(parentWindowHandle));

// Use the credential to authenticate a secret client
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);

故障排除

有关如何诊断各种故障场景的详细信息，请参阅故障排除指南。

错误处理

在向服务发出请求的任何服务客户端方法上，都可能会引发身份验证引起的错误。这是因为第一次从凭据请求令牌是在对服务的第一次调用时，并且任何后续调用都可能需要刷新令牌。为了将这些故障与服务客户端中的故障区分开来，Azure 标识类会向异常消息中的错误源以及错误消息中提供 AuthenticationFailedException 详细信息。根据应用程序，这些错误可能是可恢复的，也可能是无法恢复的。

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

// Create a secret client using the DefaultAzureCredential
var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), new DefaultAzureCredential());

try
{
    KeyVaultSecret secret = await client.GetSecretAsync("secret1");
}
catch (AuthenticationFailedException e)
{
    Console.WriteLine($"Authentication Failed. {e.Message}");
}

有关处理Microsoft Entra ID 或托管标识终结点请求失败导致的错误的更多详细信息，请参阅授权错误代码Microsoft Entra ID 文档。

日志记录

Azure 标识库提供的日志记录功能与 Azure SDK 的其余部分相同。

查看帮助调试身份验证问题的日志的最简单方法是启用控制台日志记录。

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

可以使用诊断选项配置所有凭据，其方式与 SDK 中的其他客户端相同。

DefaultAzureCredentialOptions options = new DefaultAzureCredentialOptions()
{
    Diagnostics =
    {
        LoggedHeaderNames = { "x-ms-request-id" },
        LoggedQueryParameters = { "api-version" },
        IsLoggingContentEnabled = true
    }
};

警告：Azure 标识库中的请求和响应包含敏感信息。在自定义输出时，必须采取预防措施来保护日志，以避免损害帐户安全性。

线程安全

我们保证所有凭据实例方法都是线程安全的，并且相互独立， (准则) 。这可确保重用凭据实例的建议始终是安全的，即使跨线程也是如此。

其他概念

客户端选项 | 访问响应 | 诊断 | 嘲笑 | 客户端生存期

后续步骤

支持使用 Azure 标识进行身份验证的客户端库

此处列出的许多客户端库都支持使用 TokenCredential 和 Azure 标识库进行身份验证。在这里，你还可以找到一些链接，你可以在其中了解有关其使用的详细信息，包括其他文档和示例。

已知问题

此库当前不支持与 AAD B2C 服务相关的方案。

可在此处找到 Azure.Identity 库当前未解决的问题。

贡献

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请访问 https://cla.microsoft.com 。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。直接按机器人提供的说明操作。只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。

曝光数

通过