Защищенный веб-API: конфигурация кода

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

Чтобы настроить код для защищенного веб-API, изучите следующие сведения.

  • Что определяет интерфейсы API как защищенные.
  • Как настроить токен носителя.
  • Как проверить токен

Принятая версия токена

Платформа удостоверений Microsoft может предоставлять токены версии 1.0 и 2.0. Дополнительные сведения об этих маркерах см. в разделе "Маркеры доступа".

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

  • Если значение поддерживаемых типов учетных записей — "Учетные записи" в любом каталоге организации и личных учетных записях Майкрософт (например, Skype, Xbox, Outlook.com), то допустимая версия токена должна быть версии 2.0.
  • В противном случае принятой версией маркера может быть версия 1.0.

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

  1. В Центре администрирования Microsoft Entra выберите приложение и выберите манифест.
  2. Найдите в манифесте свойство accessTokenAcceptedVersion.
  3. Значение указывает Microsoft Entra, какую версию токена принимает веб-API.
    • Если это значение равно 2, веб-API принимает маркеры версии 2.0.
    • Если это значение равно null, веб-API принимает маркеры версии 1.0.
  4. Если вы изменили версию маркера, то после изменения нажмите кнопку Сохранить.

Веб-API указывает, какая версия маркера принимается. Когда клиент запрашивает маркер для веб-API через платформу удостоверений Microsoft, клиенту предоставляется маркер, указывающий, какая версия маркера принимается веб-API.

Что определяет интерфейсы API ASP.NET и ASP.NET Core как защищенные?

Как и веб-приложения, ASP.NET и ASP.NET Основные веб-API защищаются, так как их действия контроллера префиксируются атрибутом [Авторизовать] . Действия контроллера могут вызываться только в том случае, если API вызывается с разрешенным удостоверением.

Оцените следующие вопросы.

  • Только приложение может вызывать веб-API. Как API узнает удостоверение приложения, которое его вызывает?
  • Если приложение вызывает API от имени пользователя, каково удостоверение пользователя?

Маркер носителя

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

Ниже приведен пример кода C#, в котором показан клиент, вызывающий API после получения маркера с помощью библиотеки проверки подлинности Майкрософт для .NET (MSAL.NET):

var scopes = new[] {$"api://.../access_as_user"};
var result = await app.AcquireToken(scopes)
                      .ExecuteAsync();

httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", result.AccessToken);

// Call the web API.
HttpResponseMessage response = await _httpClient.GetAsync(apiUri);

Внимание

Клиентское приложение запрашивает токен носителя на платформе идентификации Майкрософт для веб-API. API — это единственное приложение, которое должно проверить маркер и просмотреть утверждения, содержащиеся в нем. Клиентские приложения никогда не должны пытаться проверить утверждения в токенах.

В будущем для веб-API может потребоваться шифрование токена. Это требование помешает доступу к клиентским приложениям, которые могут просматривать токены доступа.

Конфигурация JwtBearer

В этом разделе описывается, как настроить токен носителя.

Файл конфигурации

Необходимо указать только в TenantId том случае, если вы хотите принять маркеры доступа из одного клиента (бизнес-приложение). В противном случае его можно оставить как common. Различные значения могут быть следующими:

  • GUID (идентификатор клиента = идентификатор каталога)
  • commonможет быть любой организацией и личная учетная запись
  • organizations может быть любой организацией
  • consumersявляются личная учетная запись Майкрософт
{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "Enter_the_Application_(client)_ID_here",
    "TenantId": "common"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

Использование пользовательского URI идентификатора приложения для веб-API

Если вы приняли URI идентификатора приложения по умолчанию, предлагаемый порталом Azure, вам не нужно указывать аудиторию. В противном случае следует добавить свойство Audience, значение которого является универсальным кодом ресурса (URI) идентификатора приложения для веб-API. Обычно это начинается с api://.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "Enter_the_Application_(client)_ID_here",
    "TenantId": "common",
    "Audience": "Enter_the_Application_ID_URI_here"
  },
}

Инициализация кода

При вызове приложения в действии контроллера, которое содержит атрибут [Authorization], ASP.NET и ASP.NET Core извлекают маркер доступа из токена носителя заголовка авторизации. Затем маркер доступа перенаправляется в по промежуточного слоя JwtBearer, который вызывает расширения Microsoft IdentityModel для .NET.

Веб-сайт Microsoft.Identity.Web

Корпорация Майкрософт рекомендует использовать пакет NuGet Microsoft.Identity.Web при разработке веб-API с ASP.NET Core.

Microsoft.Identity.Web обеспечивает для .NET связь между ASP.NET Core, промежуточным слоем для проверки подлинности и библиотекой проверки подлинности Майкрософт (MSAL). Это обеспечивает более четкий и надежный опыт разработки и использует всю мощь платформы идентификации Майкрософт и Azure AD B2C.

ASP.NET для .NET 6.0

Чтобы создать проект веб-API, использующий Microsoft.Identity.Web, используйте шаблон проекта в .NET 6.0 CLI или Visual Studio.

.NET Core CLI

# Create new web API that uses Microsoft.Identity.Web
dotnet new webapi --auth SingleOrg

Visual Studio. Чтобы создать проект веб-API в Visual Studio, выберите Файл>Создать>Проект>ASP.NET Core Web API.

Шаблоны проектов .NET CLI и Visual Studio создают файл Program.cs , похожий на фрагмент кода. Обратите внимание Microsoft.Identity.Web на директиву using и строки, содержащие проверку подлинности и авторизацию.

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();

app.Run();
  • Last updated on