Веб-приложение, которое вызывает веб-API. Конфигурация кода

Как описано на странице Веб-приложение, которое выполняет вход пользователей в систему, веб-приложение использует для входа пользователей поток кода авторизации OAuth 2.0. Этот поток включает два этапа:

  1. Запрос кода авторизации. Эта часть делегирует частный диалог с пользователем на платформу удостоверений Майкрософт. Во время этого диалога пользователь входит в систему и предоставляет согласие на использование веб-API. После успешного завершения частного диалога веб-приложение получает код авторизации в URI перенаправления.
  2. Запрос маркера доступа для API с помощью активации кода авторизации.

На странице Веб-приложение, которое выполняет вход пользователей в систему описан лишь первый этап. На этой странице содержатся сведения об изменении веб-приложения, чтобы оно не только выполняло вход пользователей в систему, но и вызывало веб-API.

Библиотеки Майкрософт, поддерживающие веб-приложения

Ниже перечислены библиотеки Майкрософт, поддерживающие веб-приложения.

Язык или платформа Проект на сайте
GitHub
Пакет Получение
запущен
Выполнение входа пользователей Доступ к веб-API Общедоступная версия (GA) или
Общедоступная предварительная версия1
.NET MSAL.NET Microsoft.Identity.Client Библиотека не может запрашивать маркеры идентификаторов для входа пользователя. Библиотека может запросить маркеры доступа для защищенных веб-API. GA
.NET Microsoft.IdentityModel Microsoft.IdentityModel Library cannot request ID tokens for user sign-in.2 Library cannot request access tokens for protected web APIs.2 GA
ASP.NET Core ASP.NET Core Microsoft.AspNetCore.Authentication Краткое руководство Библиотека может запросить маркеры идентификатора для входа пользователя. Библиотека не может запрашивать маркеры доступа для защищенных веб-API. GA
ASP.NET Core Microsoft.Identity.Web Microsoft.Identity.Web Краткое руководство Библиотека может запросить маркеры идентификатора для входа пользователя. Библиотека может запросить маркеры доступа для защищенных веб-API. GA
Java MSAL4J msal4j Краткое руководство Библиотека может запросить маркеры идентификатора для входа пользователя. Библиотека может запросить маркеры доступа для защищенных веб-API. GA
Spring spring-cloud-azure-starter-active-directory spring-cloud-azure-starter-active-directory Руководство Библиотека может запросить маркеры идентификатора для входа пользователя. Библиотека может запросить маркеры доступа для защищенных веб-API. GA
Node.js MSAL Node msal-node Краткое руководство Библиотека может запросить маркеры идентификатора для входа пользователя. Библиотека может запросить маркеры доступа для защищенных веб-API. GA
Python MSAL Python msal Краткое руководство Библиотека может запросить маркеры идентификатора для входа пользователя. Библиотека может запросить маркеры доступа для защищенных веб-API. GA

1Дополнительные условия использования предварительных версий Microsoft Azure применяются к библиотекам в общедоступной предварительной версии.

2 Библиотека Microsoft.IdentityModel только проверяет маркеры и не может запрашивать идентификаторы или маркеры доступа.

Выберите нужную вкладку для платформы:

Секреты клиента или сертификаты клиента

Учитывая, что веб-приложение теперь вызывает нижестоящий веб-API, укажите секрет клиента или сертификат клиента в файле appsettings.json. Можно также добавить раздел, который указывает:

  • URL-адрес нижестоящего веб-API;
  • необходимые области для вызова API.

В следующем примере эти параметры задаются в разделе GraphBeta.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Client_id-of-web-app-eg-2ec40e65-ba09-4853-bcde-bcb60029e596]",
    "TenantId": "common",

   // To call an API
   "ClientSecret": "[Copy the client secret added to the app from the Azure portal]",
   "ClientCertificates": [
  ]
 },
 "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": "user.read"
    }
}

Вместо секрета клиента можно предоставить сертификат клиента. В приведенном ниже фрагменте кода показано использование сертификата, хранящегося в Azure Key Vault.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Client_id-of-web-app-eg-2ec40e65-ba09-4853-bcde-bcb60029e596]",
    "TenantId": "common",

   // To call an API
   "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
        "KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
      }
   ]
  },
  "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": "user.read"
  }
}

Microsoft.Identity.Web позволяет описывать сертификаты несколькими способами, как по конфигурации, так и по коду. Дополнительные сведения см. в статье на GitHub об использовании Microsoft.Identity.Web с сертификатами.

Startup.cs

Веб-приложению потребуется получить маркер для нижестоящего API. Его можно указать в строке .EnableTokenAcquisitionToCallDownstreamApi() после .AddMicrosoftIdentityWebApp(Configuration). Эта строка предоставляет службу ITokenAcquisition, которую можно использовать для действий контроллера и страницы. Но это можно сделать проще, как описано в двух вариантах далее. Также нужно выбрать реализацию кэша маркеров, например .AddInMemoryTokenCaches(), в Startup.cs:

using Microsoft.Identity.Web;

public class Startup
{
  // ...
  public void ConfigureServices(IServiceCollection services)
  {
  // ...
  services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
          .AddMicrosoftIdentityWebApp(Configuration, "AzureAd")
            .EnableTokenAcquisitionToCallDownstreamApi(new string[]{"user.read" })
            .AddInMemoryTokenCaches();
   // ...
  }
  // ...
}

Области, передаваемые в EnableTokenAcquisitionToCallDownstreamApi, являются необязательными и позволяют веб-приложению запрашивать области и согласие пользователя на эти области при входе в систему. Если не указать области, Microsoft.Identity.Web предоставит добавочную процедуру согласия.

Если вы не хотите получать маркер самостоятельно, Microsoft.Identity.Web предоставляет два механизма вызова веб-API из веб-приложения. Выбор зависит от того, что необходимо вызывать: Microsoft Graph или другой API.

Вариант 1. Вызов Microsoft Graph

Если необходимо вызвать Microsoft Graph, Microsoft.Identity.Web позволяет напрямую использовать GraphServiceClient (предоставляется пакетом SDK Microsoft Graph) в действиях API. Чтобы предоставить Microsoft Graph, выполните указанные ниже действия.

  1. Добавьте в проект пакет NuGet Microsoft.Identity.Web.MicrosoftGraph.

  2. Добавьте .AddMicrosoftGraph() после .EnableTokenAcquisitionToCallDownstreamApi() в файл Startup.cs. .AddMicrosoftGraph() имеет несколько переопределений. При использовании переопределения, которое принимает в качестве параметра раздел конфигурации, код принимает следующий вид:

    using Microsoft.Identity.Web;
    
    public class Startup
    {
      // ...
      public void ConfigureServices(IServiceCollection services)
      {
      // ...
      services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
              .AddMicrosoftIdentityWebApp(Configuration, "AzureAd")
                .EnableTokenAcquisitionToCallDownstreamApi(new string[]{"user.read" })
                   .AddMicrosoftGraph(Configuration.GetSection("GraphBeta"))
                .AddInMemoryTokenCaches();
       // ...
      }
      // ...
    }
    

Вариант 2. Вызов нижестоящего веб-API, отличающегося от Microsoft Graph

Для вызова веб-API, отличающегося от Microsoft Graph, Microsoft.Identity.Web предоставляет .AddDownstreamWebApi(), который запрашивает маркеры и вызывает нижестоящий веб-API.

using Microsoft.Identity.Web;

public class Startup
{
  // ...
  public void ConfigureServices(IServiceCollection services)
  {
  // ...
  services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
          .AddMicrosoftIdentityWebApp(Configuration, "AzureAd")
            .EnableTokenAcquisitionToCallDownstreamApi(new string[]{"user.read" })
               .AddDownstreamWebApi("MyApi", Configuration.GetSection("GraphBeta"))
            .AddInMemoryTokenCaches();
   // ...
  }
  // ...
}

Сводка

Как и в случае с веб-API, можно выбрать различные реализации кэша маркеров. Дополнительные сведения см. в статье на GitHub Microsoft.Identity.Web: сериализация кэша маркеров.

На следующем рисунке показаны разные варианты использования Microsoft.Identity.Web и их влияние на файл Startup.cs.

Блок-схема с вариантами настройки службы в Startup.cs для вызова веб-API и указания реализации кэша маркеров

Примечание

Чтобы полностью понять приведенные примеры кода, ознакомьтесь с базовыми понятиями ASP.NET, в частности, с внедрением зависимостей и параметрами.

Код, который активирует код авторизации

Microsoft.Identity.Web упрощает ваш код, устанавливая правильные параметры OpenID Connect, подписываясь на событие получения кода и его активации. Для активации кода авторизации дополнительный код не требуется. Ознакомьтесь с исходным кодом Microsoft.Identity.Web, чтобы понять, как это работает.

Вместо секрета клиента конфиденциальное клиентское приложение также может подтвердить свою подлинность с помощью сертификата клиента или утверждения клиента. Использование утверждений клиента является расширенным сценарием, подробно описанным на странице Конфиденциальные утверждения клиентов.

Кэш маркеров

Важно!

Реализация кэша маркеров для веб-приложений или веб-API отличается от реализации для классических приложений, которая часто основана на файлах. В целях повышения безопасности и производительности важно убедиться, что для веб-приложений и веб-API существует отдельный кэш маркеров в каждой учетной записи пользователя. Сериализацию кэша маркеров также следует выполнять отдельно для каждой учетной записи.

В руководстве по ASP.NET Core используется внедрение зависимостей, позволяющее выбрать реализацию кэша маркеров в файле Startup.cs для приложения. Microsoft.Identity.Web поставляется с предварительно созданными сериализаторами кэша маркеров, описанными в разделе о сериализации кэша маркеров. Интересной возможностью является выбор кэшей распределенной памяти ASP.NET Core:

// Use a distributed token cache by adding:
    services.AddMicrosoftIdentityWebAppAuthentication(Configuration, "AzureAd")
            .EnableTokenAcquisitionToCallDownstreamApi(
                initialScopes: new string[] { "user.read" })
            .AddDistributedTokenCaches();

// Then, choose your implementation.
// For instance, the distributed in-memory cache (not cleared when you stop the app):
services.AddDistributedMemoryCache();

// Or a Redis cache:
services.AddStackExchangeRedisCache(options =>
{
 options.Configuration = "localhost";
 options.InstanceName = "SampleInstance";
});

// Or even a SQL Server token cache:
services.AddDistributedSqlServerCache(options =>
{
 options.ConnectionString = _config["DistCache_ConnectionString"];
 options.SchemaName = "dbo";
 options.TableName = "TestCache";
});

Дополнительные сведения о поставщиках кэша маркеров см. в статье о сериализации кэша маркеров Microsoft.Identity.Web, а также на странице учебных материалов по кэшированию маркеров для веб-приложений ASP.NET Core.

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

На этом этапе при входе пользователя маркер сохраняется в кэше маркеров. Ознакомьтесь со сведениями об использовании кэша в других частях веб-приложения.

Удалить учетные записи из кэша после глобального выхода