Параметры конфигурации приложений

Статья
10/24/2023

Для проверки подлинности и получения маркеров в коде инициализируется новое общедоступное или конфиденциальное клиентское приложение. При инициализации клиентского приложения в библиотеке проверки подлинности Майкрософт (MSAL) можно задать ряд параметров конфигурации. Эти параметры делятся на две группы:

Параметры регистрации, в том числе:
- центр (состоящий из экземпляра поставщика удостоверений, аудитории для входа в приложение и, возможно, идентификатора клиента);
- Идентификатор клиента
- URI перенаправления
- секрет клиента (для конфиденциальных клиентских приложений);
параметры ведения журнала, в том числе уровень ведения журнала, управление персональными данными и имя компонента, использующего библиотеку.

Центр

Центр — это URL-адрес, указывающий на каталог, из которого MSAL может запрашивать маркеры.

Ниже перечислены некоторые часто используемые центры.

URL-адреса часто используемых центров	Когда использовать
`https://login.microsoftonline.com/<tenant>/`	Вход пользователей только из определенной организации. В `<tenant>` URL-адресе указан идентификатор клиента Microsoft Entra (GUID) или его домена клиента.
`https://login.microsoftonline.com/common/`	Вход пользователей с рабочими и учебными учетными записями или личными учетными записями Майкрософт.
`https://login.microsoftonline.com/organizations/`	Вход пользователей с рабочими и учебными учетными записями.
`https://login.microsoftonline.com/consumers/`	Вход пользователей только с личными учетными записями Майкрософт (MSA).

Центр, указанный в коде, должен соответствовать поддерживаемым типам учетных записей, указанным вами для приложения в разделе Регистрация приложений на портале Azure.

Центр может принимать следующие формы:

Центр облака Microsoft Entra.
Центр Azure AD B2C. См. статью "Особенности B2C в AAD".
Центр служб федерации Active Directory (AD FS). См. статью "Поддержка ADFS".

В облачных центрах Microsoft Entra есть две части:

экземпляр поставщика удостоверений;
аудитория входа для приложения.

Экземпляр и аудиторию можно соединить и предоставить в качестве URL-адреса центра. На этой схеме показано, из чего состоит URL-адрес центра:

Из чего состоит URL-адрес центра

Облачный экземпляр

Экземпляр указывает, откуда входят пользователи в приложение: из общедоступного облака Azure или из национальных облаков. Используя MSAL в своем коде, вы можете установить облачный экземпляр Azure, применив перечисление или передав URL-адрес национальному облачному экземпляру в качестве члена Instance.

MSAL.NET выдаст явное исключение, если указаны и Instance, и AzureCloudInstance.

Если не указать экземпляр, приложение будет ориентироваться на экземпляр общедоступного облака Azure (экземпляр с URL-адресом https://login.onmicrosoftonline.com).

Аудитория приложения

Аудитория входа зависит от бизнес-потребностей вашего приложения.

Если вы разрабатываете бизнес-приложения (LOB), то, вероятно, вы создадите приложение с одним клиентом, которое будет использоваться только в вашей организации. В этом случае укажите организацию идентификатором клиента (идентификатором экземпляра Microsoft Entra) или доменным именем, связанным с экземпляром Microsoft Entra.
Если вы являетесь независимым поставщиком программного обеспечения, вам может понадобиться, чтобы пользователи входили с использованием рабочих и учебных учетных записей любой организации или некоторых организаций (многоклиентское приложение). Но, возможно, вам также потребуется, чтобы пользователи входили с использованием личных учетных записей Майкрософт.

Как указать аудиторию в коде или конфигурации

Используя в коде MSAL, вы можете указать аудиторию, задав одно из следующих значений:

Перечисление аудитории центра записи Майкрософт
Идентификатор клиента, который может быть:
- GUID (идентификатор экземпляра Microsoft Entra) для однотенантных приложений
- Доменное имя, связанное с экземпляром Microsoft Entra (также для однотенантных приложений)
Один из этих заполнителей в качестве идентификатора клиента вместо перечисления аудитории центра Microsoft Entra:
- organizations — для многоклиентского приложения;
- consumers — для входа пользователей только с использованием личных учетных записей;
- common — для входа пользователей с использованием рабочих и учебных учетных записей или личных учетных записей Майкрософт.

MSAL вызовет понятное исключение, если указать аудиторию центра Microsoft Entra и идентификатор клиента.

Рекомендуется указать аудиторию, так как многие клиенты и приложения, развернутые в них, будут иметь гостевых пользователей. Если у вашего приложения будут внешние пользователи common , то конечные точки и organization лучше всего избежать. Если вы не указываете аудиторию, ваше приложение будет нацелено на идентификатор Microsoft Entra ID и личные учетные записи Майкрософт в качестве аудитории и будет вести себя так, как было common указано.

Действующая аудитория

Действующей аудиторией вашего приложения будет наименьшее (если есть пересечение) подмножество аудитории, заданной в приложении, и аудитории, указанной в регистрационных данных приложения. По сути, вы можете задать аудиторию(поддерживаемые типы учетных записей) для приложения в разделе Регистрация приложений. Дополнительные сведения см. в Быстрый старт: зарегистрируйте приложение на платформе идентификации Microsoft.

В настоящее время, чтобы входить в приложение могли только пользователи с личными учетными записями Майкрософт, достаточно настроить оба этих параметра:

задайте для аудитории значение Work and school accounts and personal accounts в регистрационных данных приложения;
задайте для аудитории в коде или конфигурации значение AadAuthorityAudience.PersonalMicrosoftAccount (или TenantID = "consumers").

Client ID

Идентификатор клиента — это уникальный идентификатор приложения (клиента), назначенный приложению идентификатором Microsoft Entra ID при регистрации приложения. Идентификатор приложения (клиента) можно найти на странице обзора приложения в приложениях Identity>Applications>Enterprise.

URI-адрес перенаправления

URI перенаправления — это URI, по которому поставщик удостоверений возвращает маркеры безопасности.

URI перенаправления для общедоступных клиентских приложений

Если вы разработчик общедоступных клиентских приложений и используете MSAL:

Вы хотели бы использовать .WithDefaultRedirectUri() в приложениях рабочего стола или приложениях универсальной платформы Windows (UWP) (MSAL.NET 4.1+). Метод .WithDefaultRedirectUri() устанавливает для свойства URI перенаправления общедоступного клиентского приложения рекомендуемый по умолчанию URI перенаправления для общедоступных клиентских приложений.

Платформа	URI-адрес перенаправления
Классическое приложение (платформа .NET Framework)	`https://login.microsoftonline.com/common/oauth2/nativeclient`
UWP	Значение параметра `WebAuthenticationBroker.GetCurrentApplicationCallbackUri()`. Это включает единый вход (SSO) с помощью браузера с установлением значение для результата WebAuthenticationBroker.GetCurrentApplicationCallbackUri(), который необходимо зарегистрировать
.NET	`https://localhost` позволяет пользователю использовать системный браузер для интерактивной проверки подлинности, так как .NET в данный момент не имеет пользовательского интерфейса для внедренного веб-представления.

Если вы создаете приложение Xamarin Android и iOS, которое не поддерживает URI перенаправления брокера, то вам не нужно добавлять URI перенаправления. Для Xamarin Android и iOS автоматически устанавливается значение msal{ClientId}://auth.
Настройте URI перенаправления в разделе Регистрация приложений:

URI перенаправления можно переопределить, задав свойство RedirectUri (например, при использовании брокеров). Вот некоторые примеры URI перенаправления для этого сценария:

RedirectUriOnAndroid = "msauth-5a434691-ccb2-4fd1-b97b-b64bcfbc03fc://com.microsoft.identity.client.sample";
RedirectUriOnIos = $"msauth.{Bundle.ID}://auth".

Дополнительные сведения об iOS см. в статьях Перенос приложений iOS, использующих Microsoft Authenticator, с ADAL.NET на MSAL.NET и Использование брокера на iOS. Дополнительные сведения об Android см. в разделе Аутентификация через брокера в Android.

URI перенаправления для конфиденциальных клиентских приложений

Для веб-приложений URI перенаправления (или URL-адрес ответа) — это универсальный код ресурса (URI), который идентификатор Microsoft Entra будет использовать для отправки маркера обратно в приложение. URI может быть URL-адресом веб-приложения или веб-API, если конфиденциальное приложение является одним из них. URI перенаправления должен быть указан в регистрационных данных приложения. Регистрация особенно важна при развертывании приложения, которое вы изначально тестировали локально. Затем необходимо добавить URL-адрес ответа развернутого приложения на портале регистрации приложений.

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

Секрет клиента

Этот параметр задает секрет клиента для конфиденциального клиентского приложения. Секрет клиента (пароль приложения) предоставляется порталом регистрации приложения или предоставляется идентификатору Microsoft Entra во время регистрации приложения с помощью идентификатора Microsoft Entra ID, PowerShell AzureRM или Azure CLI.

Ведение журнала

Для упрощения отладки и устранения неполадок с проверкой подлинности MSAL предоставляет встроенную поддержку ведения журнала. Ведение журнала в каждой библиотеке описано в следующих статьях:

Следующие шаги

Сведения о создании экземпляров клиентских приложений с помощью MSAL.NET и с помощью MSAL.js.