Использование MSAL.NET с диспетчером веб-учетных записей (WAM)

MSAL может обращаться к диспетчеру веб-учетных записей (WAM), компоненту Windows, входящему в состав ОС. Этот компонент выступает в качестве брокера аутентификации, позволяя пользователям вашего приложения использовать интеграцию с учетными записями, известными системе Windows, например с учетной записью, под которой вы вошли в сеанс Windows.

Что такое брокер

Брокер аутентификации — это приложение, работающее на компьютере пользователя и управляющее процессами аутентификации и токенами для подключённых учётных записей. Операционная система Windows использует диспетчер веб-учетных записей (WAM) в качестве брокера проверки подлинности. Он имеет множество преимуществ для разработчиков и клиентов, включая:

• Улучшенная безопасность. Многие улучшения безопасности будут доставлены брокером без необходимости обновлять логику приложения.
• Поддержка функций. С помощью брокера разработчики могут получить доступ к широким возможностям ОС и сервисов, таким как Windows Hello, политики условного доступа и ключи FIDO, без написания дополнительного вспомогательного кода.
• Интеграция системы. Приложения, использующие подключаемый модуль брокера с встроенным средство выбора учетных записей, позволяют пользователю быстро выбрать существующую учетную запись вместо повторного ввода одинаковых учетных данных.
• Защита токенов. WAM гарантирует, что маркеры обновления привязаны к устройству и позволяют приложениям получать маркеры доступа, привязанные к устройству. См. раздел "Защита маркеров".

Включение WAM

Поддержка WAM разделена между двумя пакетами:

• Microsoft.Identity.Client (то есть MSAL) — основная библиотека для получения токенов.
• Microsoft. Identity.Client.Broker — добавляет поддержку проверки подлинности с помощью брокера.

После подключения соответствующих пакетов вызовите WithBroker(BrokerOptions), указав параметры конфигурации брокера и дескриптор окна, к которому будет привязан брокер.

var scopes = new[] { "User.Read" };

BrokerOptions options = new BrokerOptions(BrokerOptions.OperatingSystems.Windows);
options.Title = "My Awesome Application";

IPublicClientApplication app =
    PublicClientApplicationBuilder.Create("YOUR_CLIENT_ID")
    .WithDefaultRedirectUri()
    .WithParentActivityOrWindow(GetConsoleOrTerminalWindow)
    .WithBroker(options)
    .Build();

AuthenticationResult result = null;

// Try to use the previously signed-in account from the cache
IEnumerable<IAccount> accounts = await app.GetAccountsAsync();
IAccount existingAccount = accounts.FirstOrDefault();

try
{    
    if (existingAccount != null)
    {
        result = await app.AcquireTokenSilent(scopes, existingAccount).ExecuteAsync();
    }
    // Next, try to sign in silently with the account that the user is signed into Windows
    else
    {    
        result = await app.AcquireTokenSilent(scopes, PublicClientApplication.OperatingSystemAccount)
                            .ExecuteAsync();
    }
}
// Can't get a token silently, go interactive
catch (MsalUiRequiredException ex)
{
    result = await app.AcquireTokenInteractive(scopes).ExecuteAsync();
}

При использовании брокера, если используемый authority предназначен как для Microsoft Entra ID, так и для личных учетных записей Microsoft, пользователю сначала будет предложено выбрать учетную запись с помощью встроенного системного средства выбора учетной записи.

Если конфигурация задается для каждого арендатора отдельно с помощью WithTenantId или если параметр authority задан для аудитории, которая не включает личные учетные записи Microsoft, встроенное средство выбора учетной записи Windows не будет отображаться, и вместо этого пользователю будет показан стандартный запрос аутентификации Microsoft.

После добавления или выбора учетной записи пользователю будет предложено предоставить дополнительное согласие, если они никогда не использовали приложение раньше или приложение требует дополнительных разрешений.

Маркеры родительского окна

Чтобы использовать брокер, теперь необходимо указать дескриптор окна, которое будет родительским для модального диалогового окна WAM, с помощью API WithParentActivityOrWindow. Дескриптор окна должен быть предоставлен разработчиком, поскольку MSAL не может самостоятельно определить родительское окно, а в прошлом это приводило к неудобству для пользователей, когда окно аутентификации оказывалось скрыто за окном приложения.

Сведения о приложениях пользовательского интерфейса, таких как Windows Forms, Windows Presentation Foundation (WPF) или WinUI3, см. в разделе "Получение дескриптора окна( HWND)".

Для консольных приложений можно использовать код, например приведенный ниже фрагмент.

enum GetAncestorFlags
{   
    GetParent = 1,
    GetRoot = 2,
    /// <summary>
    /// Retrieves the owned root window by walking the chain of parent and owner windows returned by GetParent.
    /// </summary>
    GetRootOwner = 3
}

/// <summary>
/// Retrieves the handle to the ancestor of the specified window.
/// </summary>
/// <param name="hwnd">A handle to the window whose ancestor is to be retrieved.
/// If this parameter is the desktop window, the function returns NULL. </param>
/// <param name="flags">The ancestor to be retrieved.</param>
/// <returns>The return value is the handle to the ancestor window.</returns>
[DllImport("user32.dll", ExactSpelling = true)]
static extern IntPtr GetAncestor(IntPtr hwnd, GetAncestorFlags flags);

[DllImport("kernel32.dll")]
static extern IntPtr GetConsoleWindow();

// This is your window handle!
public IntPtr GetConsoleOrTerminalWindow()
{
    IntPtr consoleHandle = GetConsoleWindow();
    IntPtr handle = GetAncestor(consoleHandle, GetAncestorFlags.GetRootOwner );
    
    return handle;
}

Токены доступа с подтверждением владения

Брокер WAM позволяет получать маркеры PoP для общедоступных потоков клиентов. Дополнительные сведения см. в разделе «Токены подтверждения владения».

Перенаправляющий URI

URI перенаправления WAM не нужно настраивать в MSAL, но их необходимо настроить в регистрации приложения. Они должны соответствовать следующему шаблону:

ms-appx-web://microsoft.aad.brokerplugin/{client_id}

Поток имени пользователя и пароля

Этот поток, также известный как учетные данные пароля владельца ресурса (ROPC), не рекомендуется, кроме сценариев тестирования или сценариев, в которых доступ субъекта-службы к ресурсу дает слишком широкие права доступа и ограничить их можно только с помощью пользовательских потоков. При использовании WAM AcquireTokenByUsernamePassword позволит WAM управлять протоколом и получать токены.

Ограничения WAM

• Авторитеты Azure B2C и службы федерации Active Directory (AD FS) (ADFS) не поддерживаются. MSAL вернется к использованию браузера для проверки подлинности пользователей.
• В macOS, Linux и версиях Windows до 10, а также в Windows Server 2019, MSAL будет использовать браузер как запасной вариант.

Доступность пакета

Чтобы использовать брокер, разработчикам потребуется вызвать WithBroker(PublicClientApplicationBuilder, BrokerOptions) из пакета Microsoft.Identity.Client.Broker. Большинству вариантов платформы .NET, поддерживаемых MSAL.NET, потребуется только этот пакет с несколькими исключениями. Подробное сопоставление см. в таблице ниже.

†Microsoft.Identity.Client версии 4.61.0 и выше больше не включают net6.0-windows7.0 двоичный файл. Существующие классические приложения, предназначенные для net6.0-windows, должны ссылаться на Microsoft.Identity.Client.Broker при использовании интерактивной аутентификации с брокером Windows и вызывать WithBroker(PublicClientApplicationBuilder, BrokerOptions); либо ссылаться на Microsoft.Identity.Client.Desktop при аутентификации через браузер и вызывать WithWindowsEmbeddedBrowserSupport(PublicClientApplicationBuilder).

Рекомендации по интеграции

Чтобы убедиться, что у ваших клиентов есть отличный опыт работы с WAM, мы настоятельно советуем придерживаться следующих принципов:

1. Предоставьте контекст пользователя перед проверкой подлинности. Нарисуйте пользовательский интерфейс или окно, которое сообщит пользователю о необходимости проверки подлинности, а также причины проверки подлинности. Объясните преимущества приложения, если это фоновая служба.
2. Вызов проверки подлинности на основе действия пользователя. Пользователь должен знать, что он активировал процесс проверки подлинности в определенном приложении, щелкнув ссылку или кнопку, или выполнив другой жест. Пользователи не должны вводить учетные данные в окнах, которые всплывают в операционной системе без присоединенного контекста или действий.
3. Сначала попытайтесь получить токен без вывода запроса и, если это не удастся, используйте интерактивный запрос. Клиенты должны запрашивать только интерактивную проверку подлинности, если необходимо повторно ввести учетные данные или выполнить требование политики.

Troubleshooting

"MsalClientException (ErrCode 5376): по крайней мере одна область должна быть запрошена для этого потока проверки подлинности". Сообщение об ошибке

Это сообщение указывает, что необходимо запросить по крайней мере одну область приложения (напримерuser.read, ) вместе с другими областями OIDC (profileemailилиoffline_access).

var authResult = await pca.AcquireTokenInteractive(new[] { "user.read" })
                 .ExecuteAsync();

Средство выбора учетных записей не отображается

Иногда обновление Windows может непреднамеренно повлиять на компонент средства выбора учетных записей, который отображает список учетных записей в Windows и параметр добавления новых учетных записей. Проблема заключается в том, что окно выбора не появляется у небольшого числа пользователей.

Возможное решение заключается в повторной регистрации компонента. Запустите этот сценарий из терминала с разрешениями администратора:

if (-not (Get-AppxPackage Microsoft.AccountsControl))
{ 
    Add-AppxPackage -Register "$env:windir\SystemApps\Microsoft.AccountsControl_cw5n1h2txyewy\AppxManifest.xml" -DisableDevelopmentMode -ForceApplicationShutdown 
}

Get-AppxPackage Microsoft.AccountsControl

Проблемы с подключением

Пользователь приложения видит сообщение об ошибке, аналогичное Please check your connection and try again. Если эта проблема возникает регулярно, ознакомьтесь с руководством по устранению неполадок в Office, которое также использует WAM.

Коды ошибок WAM

Дополнительные сведения об ошибках WAM см. в статье Ошибки, связанные с диспетчером веб-учетных записей (WAM).

Так как WAM является относительно новым компонентом, при возникновении ошибок рекомендуется регистрирование данных из AdditionalExceptionData. Это может помочь определить конкретные проблемы с конфигурацией или компонентом WAM. При возникновении проблем WAM , запишите ошибку . Это поможет нам своевременно решить проблему.