Инициализация клиентских приложений

Завершено

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

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

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

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

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

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

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

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

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

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

• .WithAuthority модификатор: .WithAuthority модификатор задает центру по умолчанию приложения центру Microsoft Entra с возможностью выбора облака Azure, аудитории, клиента (идентификатора клиента или имени домена) или предоставления непосредственно URI центра.

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

• Модификатор .WithRedirectUri: модификатор .WithRedirectUri переопределяет универсальный код ресурса (URI) перенаправления по умолчанию.

  IPublicClientApplication app;
  app = PublicClientApplicationBuilder.Create(client_id)
      .WithAuthority(AzureCloudInstance.AzurePublic, tenant_id)
      .WithRedirectUri("http://localhost")
      .Build();
  

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

В таблице ниже перечислены некоторые модификаторы, которые можно задать на общедоступном или конфиденциальном клиенте.

Модификатор	Description
.WithAuthority()	Задает центру приложения по умолчанию центр Microsoft Entra с возможностью выбора облака Azure, аудитории, клиента (идентификатора клиента или доменного имени) или предоставления непосредственно URI центра.
.WithTenantId(string tenantId)	Переопределяет идентификатор или описание клиента.
.WithClientId(string)	Переопределяет идентификатор клиента.
.WithRedirectUri(string redirectUri)	Переопределяет по умолчанию универсальный код ресурса перенаправления. Это полезно для сценариев, требующих брокера.
.WithComponent(string)	Задает имя библиотеки с помощью MSAL.NET (по причинам телеметрии).
.WithDebugLoggingCallback()	При вызове приложение вызывает Debug.Write просто включение трассировки отладки.
.WithLogging()	При вызове приложение вызывает обратный вызов с трассировками отладки.
.WithTelemetry(TelemetryCallback telemetryCallback)	Задает делегата, используемого для отправки данных телеметрии.

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

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

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