Инициализация клиентских приложений с помощью MSAL.NET

В этой статье описывается инициализация общедоступных клиентских и конфиденциальных клиентских приложений с помощью Microsoft Authentication Library для .NET (MSAL.NET). Дополнительные сведения о типах клиентских приложений см. в разделе "Общедоступный клиент" и "Конфиденциальные клиентские приложения".

При использовании MSAL.NET 3.x рекомендуется создать экземпляр приложения с помощью построителей приложений: PublicClientApplicationBuilder и ConfidentialClientApplicationBuilder. Они предлагают мощный механизм настройки приложения из кода, файла конфигурации или даже путем сочетания обоих подходов.

Необходимые условия

Прежде чем инициализировать приложение, сначала необходимо зарегистрировать его, чтобы приложение можно было интегрировать с платформа удостоверений Майкрософт. Дополнительные сведения см. в статье Краткое руководство: регистрация приложения с помощью платформы Microsoft identity. После регистрации вам потребуются следующие сведения, которые можно найти на странице регистрации приложения в Центр администрирования Microsoft Entra.

  • Идентификатор приложения (клиента) — это строка, представляющая GUID.
  • Идентификатор каталога (тенанта) — предоставляет возможности управления идентификацией и доступом (IAM) для приложений и ресурсов, используемых вашей организацией. Это позволяет указать, создаёте ли вы бизнес-приложение исключительно для вашей организации (также называемое однотенантным приложением).
  • URL-адрес поставщика удостоверений (называемый instance) и аудитория входа для вашего приложения. Эти два параметра в совокупности называются авторитетной частью.
  • Учетные данные клиента , которые могут принимать форму секрета приложения (строка секрета клиента) или сертификата (типа X509Certificate2), если это конфиденциальное клиентское приложение.
  • Для веб-приложений, а иногда и для публичных клиентских приложений (в частности, если вашему приложению нужно использовать брокер), необходимо указать URI перенаправления, на который поставщик удостоверений будет перенаправлять обратно в ваше приложение маркеры безопасности.

Инициализация приложений

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

Инициализация общедоступного клиентского приложения из кода

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

IPublicClientApplication app = PublicClientApplicationBuilder.Create(clientId)
    .Build();

Инициализация конфиденциального клиентского приложения из кода

Таким же образом следующий код создаёт экземпляр конфиденциального приложения (веб-приложения, расположенного по адресу https://myapp.azurewebsites.net), которое обрабатывает токены пользователей в общедоступном облаке Microsoft Azure, использующих свои рабочие или учебные учётные записи либо личные учётные записи Microsoft. Приложение идентифицируется у поставщика удостоверений с помощью общего секрета клиента:

string redirectUri = "https://myapp.azurewebsites.net";
IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithClientSecret(clientSecret)
    .WithRedirectUri(redirectUri )
    .Build();

Однако в рабочей среде сертификаты рекомендуется использовать, так как они более безопасны, чем секреты клиента. Их можно создать и отправить в Центр администрирования Microsoft Entra. Затем код будет следующим:

IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithCertificate(certificate)
    .WithRedirectUri(redirectUri )
    .Build();

Инициализация общедоступного клиентского приложения из параметров конфигурации

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

PublicClientApplicationOptions options = GetOptions(); // your own method
IPublicClientApplication app = PublicClientApplicationBuilder.CreateWithApplicationOptions(options)
    .Build();

Инициализация конфиденциального клиентского приложения из параметров конфигурации

Такой же шаблон применяется к конфиденциальным клиентским приложениям. Можно также добавить другие параметры с помощью .WithXXX модификаторов. В этом примере используется .WithCertificate.

ConfidentialClientApplicationOptions options = GetOptions(); // your own method
IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.CreateWithApplicationOptions(options)
    .WithCertificate(certificate)
    .Build();

Модификаторы строителя

В фрагментах кода с помощью построителей приложений многие .With методы можно применять как модификаторы (например, .WithCertificate и .WithRedirectUri).

Модификаторы, распространенные для общедоступных и конфиденциальных клиентских приложений

Модификаторы, которые можно задать на общедоступном клиенте или в построителе конфиденциальных клиентских приложений, можно найти в AbstractApplicationBuilder<T> классе. Различные методы можно найти в документации по Azure SDK для .NET.

Модификаторы, относящиеся к приложениям Xamarin.iOS

Модификаторы, которые можно задать в построителе общедоступных клиентских приложений в Xamarin.iOS:

Модификатор Description
.WithIosKeychainSecurityGroup() Только Xamarin.iOS: задает группу безопасности связки ключей iOS (для сохранения кэша).

Модификаторы, относящиеся к конфиденциальным клиентским приложениям

Модификаторы, относящиеся к построителю конфиденциальных клиентских приложений, можно найти в ConfidentialClientApplicationBuilder классе. Различные методы можно найти в документации по Azure SDK для .NET.

Модификаторы, такие как .WithCertificate(X509Certificate2 certificate) и .WithClientSecret(string clientSecret) являются взаимоисключающими. Если вы предоставляете оба варианта, MSAL создает понятное исключение.

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

Предположим, что ваше приложение является бизнес-приложением, которое предназначено только для вашей организации. Затем можно написать следующее:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
        .Build();

Программирование для национальных облаков упрощено, поэтому, если вы хотите, чтобы приложение было мультитенантным приложением в национальном облаке, можно написать, например:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAuthority(AzureCloudInstance.AzureUsGovernment, AadAuthorityAudience.AzureAdMultipleOrgs)
        .Build();

Также предусмотрено переопределение для ADFS (MSAL.NET поддерживает только ADFS версии 2019 или более поздних):

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAdfsAuthority("https://consoso.com/adfs")
        .Build();

Наконец, если вы разработчик Azure AD B2C, вы можете указать свой арендатор следующим образом:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithB2CAuthority("https://fabrikamb2c.b2clogin.com/tfp/{tenant}/{PolicySignInSignUp}")
        .Build();

См. также

Справочная документация по API

Пакет в NuGet

Исходный код библиотеки

Примеры кода

Дальнейшие действия

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

Документация по сценарию приложения содержит рекомендации по входу пользователя и получению маркера доступа для доступа к API от имени этого пользователя:

  • Last updated on