Использование MSAL.NET с встроенной проверкой подлинности Windows (IWA)

К документации по IWA следует обращаться только для сопровождения существующих продуктивных развертываний. Если вы планируете перейти на WAM для единого входа (SSO) с использованием учетной записи ОС, ознакомьтесь с приведенным ниже примером реализации в качестве руководства, а дополнительные сведения см. в статье WAM.

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
{    
    result = await app.AcquireTokenSilent(scopes, PublicClientApplication.OperatingSystemAccount)
                          .ExecuteAsync(); // this will try to SSO silently with Windows OS logged in account. 
}
// Can't get a token silently, go interactive
catch (MsalUiRequiredException ex)
{
    result = app.AcquireTokenInteractive(scopes)
                         .WithAccount(PublicClientApplication.OperatingSystemAccount)
                         .ExecuteAsync();
}

Если ваше настольное или мобильное приложение работает в Windows и выполняется на компьютере, подключённом к домену Windows (присоединённом к Active Directory или Microsoft Entra), можно использовать интегрированную проверку подлинности Windows (IWA) для получения токена без участия пользователя. При использовании приложения не нужен пользовательский интерфейс.

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

• Только федеративные пользователи, то есть те, которые созданы в Active Directory и связаны с Microsoft Entra ID. Пользователи, созданные непосредственно в Microsoft Entra ID, без поддержки AD — управляемых пользователей — не могут использовать этот поток проверки подлинности. Это ограничение не влияет на поток имени пользователя и пароля.

• Не работает для пользователей MSA. Для сценариев использования MSA попробуйте WAM

• IWA предназначен для приложений, написанных для .NET и .NET Framework.

• IWA не обходит MFA (многофакторная проверка подлинности). Если многофакторная аутентификация (MFA) настроена, аутентификация на основе интегрированной Windows (IWA) может завершиться ошибкой, если требуется многофакторный вызов, так как это требует взаимодействия с пользователем.

  Это сложно. IWA является неинтерактивным, но 2FA требует взаимодействия пользователей. Вы не контролируете, когда поставщик удостоверений запрашивает выполнение 2FA — это контролирует администратор арендатора. Из наших наблюдений, 2FA требуется при входе из другой страны, если вы не подключены через VPN к корпоративной сети, а иногда даже при подключении через VPN. Не ожидайте детерминированного набора правил, Microsoft Entra ID использует ИИ для непрерывного изучения необходимости 2FA. Если IWA не сработает, следует использовать подсказку для пользователя как запасной вариант.

• Полномочие, переданное в PublicClientApplicationBuilder, должно быть:

  • с указанием клиента (в формате https://login.microsoftonline.com/{tenant}/, где tenant — это либо GUID, представляющий идентификатор клиента, либо домен, связанный с клиентом.
  • для любых рабочих и учебных учетных записей (https://login.microsoftonline.com/organizations/)

  Microsoft личные учетные записи не поддерживаются (вы не можете использовать /common или /consumers tenants)

• Поскольку встроенная проверка подлинности Windows является неинтерактивным процессом:

  • Пользователь приложения должен ранее предоставить согласие на использование приложения.
  • или администратор клиента должен ранее предоставить всем пользователям в клиенте согласие на использование приложения.
  • Это означает, что:
    • либо вы в качестве разработчика нажали кнопку Grant на портале Azure для себя,
    • или администратор клиента нажал кнопку «Предоставить/отозвать согласие администратора для {tenant domain}» на вкладке Разрешения API в регистрации приложения (см. Добавление разрешений для доступа к веб-API)
    • или вы предоставили пользователям способ предоставления согласия на приложение (см. запрос отдельного согласия пользователя)
    • или вы предоставили способ предоставления администратору клиента согласия для приложения (см. согласие администратора)

• Этот сценарий доступен для классических приложений .NET, .NET Core и универсальных приложений Windows.

Дополнительные сведения о согласии см. в разделе разрешения и согласие версии 2.0

Как его использовать?

Регистрация приложения

Во время регистрации приложения в разделе проверки подлинности приложения:

• Вам не нужно указывать URI ответа

• Вам нужно выбрать ответ «Да» на вопрос «Рассматривать приложение как общедоступный клиент» (в абзаце «Тип клиента по умолчанию»)

  

Code

IPublicClientApplication содержит метод, называемый AcquireTokenByIntegratedWindowsAuth

AcquireTokenByIntegratedWindowsAuth(IEnumerable<string> scopes)

Обычно следует использовать только один параметр (scopes). Однако в зависимости от того, как администратор Windows настроил политики, возможно, что приложения на компьютере windows не разрешены для поиска пользователя, вошедшего в систему. В этом случае используйте второй метод .WithUsername() и передайте имя вошедшего в систему пользователя в формате UPN — joe@contoso.com.

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

static async Task GetATokenForGraph()
{
 string authority = "https://login.microsoftonline.com/contoso.com";
 string[] scopes = new string[] { "user.read" };
 IPublicClientApplication app = PublicClientApplicationBuilder
      .Create(clientId)
      .WithAuthority(authority)
      .Build();

 var accounts = await app.GetAccountsAsync();

 AuthenticationResult result = null;
 if (accounts.Any())
 {
  result = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault())
      .ExecuteAsync();
 }
 else
 {
  try
  {
   result = await app.AcquireTokenByIntegratedWindowsAuth(scopes)
      .ExecuteAsync(CancellationToken.None);
  }
  catch (MsalUiRequiredException ex)
  {
   // MsalUiRequiredException: AADSTS65001: The user or administrator has not consented to use the application 
   // with ID '{appId}' named '{appName}'.Send an interactive authorization request for this user and resource.

   // you need to get user consent first. This can be done, if you are not using .NET Core (which does not have any Web UI)
   // by doing (once only) an AcquireToken interactive.

   // If you are using .NET core or don't want to do an AcquireTokenInteractive, you might want to suggest the user to navigate
   // to a URL to consent: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={clientId}&response_type=code&scope=user.read

   // AADSTS50079: The user is required to use multi-factor authentication.
   // There is no mitigation - if MFA is configured for your tenant and Azure AD decides to enforce it, 
   // you need to fallback to an interactive flows such as AcquireTokenInteractive or AcquireTokenByDeviceCode
   }
   catch (MsalServiceException ex)
   {
    // Kind of errors you could have (in ex.Message)

    // MsalServiceException: AADSTS90010: The grant type is not supported over the /common or /consumers endpoints. Please use the /organizations or tenant-specific endpoint.
    // you used common.
    // Mitigation: as explained in the message from Azure AD, the authoriy needs to be tenanted or otherwise organizations

    // MsalServiceException: AADSTS70002: The request body must contain the following parameter: 'client_secret or client_assertion'.
    // Explanation: this can happen if your application was not registered as a public client application in Azure AD 
    // Mitigation: in the Azure portal, edit the manifest for your application and set the `allowPublicClient` to `true` 
   }
   catch (MsalClientException ex)
   {
      // Error Code: unknown_user Message: Could not identify logged in user
      // Explanation: the library was unable to query the current Windows logged-in user or this user is not AD or Azure AD
      // joined (work-place joined users are not supported). 

      // Mitigation: Implement your own logic to fetch the username (e.g. john@contoso.com) and use the 
      // AcquireTokenByIntegratedWindowsAuth form that takes in the username

      // Error Code: integrated_windows_auth_not_supported_managed_user
      // Explanation: This method relies on an a protocol exposed by Active Directory (AD). If a user was created in Azure 
      // Active Directory without AD backing ("managed" user), this method will fail. Users created in AD and backed by 
      // Azure AD ("federated" users) can benefit from this non-interactive method of authentication.
      // Mitigation: Use interactive authentication
   }
 }


 Console.WriteLine(result.Account.Username);
}

Примечание. При возникновении следующей ошибки:

"Microsoft. Identity.Client.MsalClientException: не удалось получить имя пользователя ---> System.ComponentModel.Win32Exception: не было выполнено сопоставление имен учетных записей и идентификаторов безопасности".

Это означает, что вы можете войти на устройство с помощью локальной учетной записи компьютера, а не с учетной записью Active Directory (AD). Убедитесь, что устройство присоединено к домену и что текущий вошедший в систему пользователь является пользователем Active Directory (AD). Недостаточно лишь присоединить компьютер к домену, поскольку локальные учетные записи на устройстве не смогут получить доступ к учетным данным Active Directory.

Пример, иллюстрирующий получение токенов через интегрированную проверку подлинности Windows с помощью MSAL.NET

Sample	Platform	Description
active-directory-dotnet-iwa-v2	Консоль (.NET)	Консольное приложение .NET Core, позволяющее пользователю, вошедшему в Windows, получить с помощью конечной точки Azure AD v2.0 токен для Microsoft Graph

Дополнительные сведения

Если вы хотите узнать больше об интегрированной проверке подлинности Windows:

• Как это было сделано с конечной точкой V1: AcquireTokenSilent с использованием интегрированной аутентификации в Windows (Kerberos) в ADAL.NET

Troubleshooting

Если вы столкнулись с кодом ошибки "parsing_wstrust_response_failed", это может быть связано с рядом проблем конфигурации в среде ADFS.

К некоторым из этих проблем относятся:

• Учетная запись недоступна для использования IWA
• Политика IWA предотвращает автоматическую проверку подлинности IWA
• Проблемы с прокси-сервером или конфигурацией мешают работе протокола NTLM (обычно это относится к запросу проверки подлинности 401 Negotiate/NTLM, который конечная точка возвращает для аутентификации Windows. Чтобы обойти эту проблему, можно попробовать использовать собственный HttpClient или изменить текущую версию .NET).
• Если сообщение об ошибке — "Ссылка на объект не задана для экземпляра объекта". включите ведение журнала MSAL на уровне предупреждения, чтобы просмотреть дополнительные сведения.

Дополнительные сведения см. в статье Устранение неполадок AD FS — интегрированная проверка подлинности Windows