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

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

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

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

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

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

Язык или платформа Проект на сайте
GitHub
Пакет Получение
запущен
Выполнение входа пользователей Доступ к веб-API Общедоступная версия (GA) или
Общедоступная предварительная версия1
.NET MSAL.NET Microsoft.Identity.Client Library cannot request ID tokens for user sign-in. Library can request access tokens for protected web APIs. 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 Microsoft.AspNetCore.Authentication Краткое руководство Library can request ID tokens for user sign-in. Library cannot request access tokens for protected web APIs. GA
ASP.NET Core Microsoft.Identity.Web Microsoft.Identity.Web Краткое руководство Library can request ID tokens for user sign-in. Library can request access tokens for protected web APIs. GA
Java MSAL4J msal4j Краткое руководство Library can request ID tokens for user sign-in. Library can request access tokens for protected web APIs. GA
Node.js MSAL Node msal-node Краткое руководство Library can request ID tokens for user sign-in. Library can request access tokens for protected web APIs. GA
Python MSAL Python msal Краткое руководство Library can request ID tokens for user sign-in. Library can request access tokens for protected web APIs. 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() после .AddMicrosoftIdentityWebApi(Configuration). Эта строка предоставляет службу ITokenAcquisition, которую можно использовать для действий контроллера и страницы. Но это можно сделать проще, как описано в двух вариантах далее. Также нужно выбрать реализацию кэша маркеров, например .AddInMemoryTokenCaches(), в .AddInMemoryTokenCaches():

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 позволяет напрямую использовать (предоставляется пакетом SDK Microsoft Graph) в действиях API. Чтобы предоставить Microsoft Graph, выполните указанные ниже действия.

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

  2. Добавьте .AddMicrosoftGraph() после .EnableTokenAcquisitionToCallDownstreamApi() в файл .AddMicrosoftGraph(). .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 предоставляет , который запрашивает маркеры и вызывает нижестоящий веб-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.

Block diagram showing service configuration options in startup dot C S for calling a web API and specifying a token cache implementation

Примечание

Чтобы полностью понять приведенные примеры кода, ознакомьтесь с базовыми понятиями 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.

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

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

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