Быстрое начало: Авторизация пользователей в веб-приложении ASP.NET Core

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

Если у вас нет клиента Microsoft Entra, создайте учетную запись free перед началом работы.

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

• пакет SDK .NET 9
• Клиент Microsoft Entra ID
• Регистрация приложения в клиенте Microsoft Entra. Если вам нужно создать его, см. статью "Регистрация приложения".

Создание проекта из шаблона

Самый быстрый способ приступить к работе — создать шаблон нового проекта с предварительно настроенной проверкой подлинности.

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

dotnet new webapp --auth SingleOrg --name MyWebApp
cd MyWebApp

Шаблон создает проект с уже настроенным Microsoft.Identity.Web. Вам нужно указать только сведения о регистрации приложения.

Откройте appsettings.json и замените значения заполнителей идентификатором приложения (клиента) и идентификатором каталога (клиента) из регистрации приложения:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "CallbackPath": "/signin-oidc"
  }
}

Запустите приложение, чтобы убедиться, что вход работает:

dotnet run

Перейдите к разделу https://localhost:5001 и выберите "Войти". Если появится запрос на вход Microsoft, конфигурация правильна.

Добавление проверки подлинности в существующее веб-приложение

Если у вас есть существующее приложение ASP.NET Core, выполните следующие действия, чтобы добавить функцию входа в Microsoft Entra.

Установка пакетов Nuget

Добавьте библиотеки Microsoft.Identity.Web. Пакет Microsoft.Identity.Web обрабатывает проверку подлинности и Microsoft.Identity.Web.UI предоставляет предварительно созданные компоненты пользовательского интерфейса входа и выхода:

dotnet add package Microsoft.Identity.Web
dotnet add package Microsoft.Identity.Web.UI

Настройка служб проверки подлинности

Откройте Program.cs и добавьте службы проверки подлинности. Следующий код регистрирует аутентификацию с помощью OpenID Connect в Microsoft Entra, включает получение токенов для вызовов целевого API и добавляет интерфейс входа/выхода.

using Microsoft.Identity.Web;
using Microsoft.Identity.Web.UI;

var builder = WebApplication.CreateBuilder(args);

// Add authentication
builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApp(builder.Configuration, "AzureAd")
                .EnableTokenAcquisitionToCallDownstreamApi() // Optional: if calling APIs
                .AddInMemoryTokenCaches(); // For production, use distributed cache

// Add Razor Pages or MVC
builder.Services.AddRazorPages()
    .AddMicrosoftIdentityUI(); // Adds sign-in/sign-out UI

var app = builder.Build();

// Configure middleware
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();

app.UseAuthentication(); //  Add authentication middleware
app.UseAuthorization();

app.MapRazorPages();
app.MapControllers();

app.Run();

Добавить конфигурацию Microsoft Entra

Откройте appsettings.json и добавьте AzureAd раздел. Замените значения заполнителей идентификатором приложения (клиента). Задайте TenantId целевую аудиторию для вашего приложения.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "common",
    "ClientId": "your-client-id-from-app-registration",
    "CallbackPath": "/signin-oidc"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.Identity.Web": "Information"
    }
  }
}

Значение TenantId определяет, какие учетные записи могут войти:

Значение	Принятые учетные записи
common	Рабочие и учебные и личные учетные записи Microsoft
organizations	Только рабочие и учебные учетные записи
consumers	Только личные учетные записи Майкрософт
<your-tenant-id>	Один клиент — только ваша организация

Защита страниц

[Authorize] Добавьте атрибут на страницы или контроллеры, для которых требуется вход.

Для Razor Pages [Authorize] атрибут перенаправляет пользователей без проверки подлинности на страницу входа. После входа пользовательские утверждения, такие как Name и preferred_username доступны через User объект:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc.RazorPages;

[Authorize] //  Require authentication
public class IndexModel : PageModel
{
    public void OnGet()
    {
        var userName = User.Identity?.Name;
        var userEmail = User.FindFirst("preferred_username")?.Value;
    }
}

Для контроллеров MVC тот же [Authorize] атрибут применяется на уровне контроллера или действия:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[Authorize] //  Require authentication
public class HomeController : Controller
{
    public IActionResult Index()
    {
        var userName = User.Identity?.Name;
        return View();
    }
}

Добавление ссылок для входа и выхода

Добавьте ссылки навигации в макет, чтобы пользователи могли войти и выйти. Маршруты MicrosoftIdentity области предоставляются пакетом Microsoft.Identity.Web.UI. Следующая разметка Razor условно отображает выход или вход на основе состояния проверки подлинности пользователя:

<ul class="navbar-nav">
    @if (User.Identity?.IsAuthenticated == true)
    {
        <li class="nav-item">
            <span class="nav-link">Hello @User.Identity.Name!</span>
        </li>
        <li class="nav-item">
            <a class="nav-link" asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignOut">Sign out</a>
        </li>
    }
    else
    {
        <li class="nav-item">
            <a class="nav-link" asp-area="MicrosoftIdentity" asp-controller="Account" asp-action="SignIn">Sign in</a>
        </li>
    }
</ul>

Запуск и тестирование

Запустите приложение, чтобы убедиться, что проверка подлинности работает:

dotnet run

Перейдите по адресу https://localhost:5001. Вы увидите ссылку для входа . Выберите его, чтобы подтвердить успешное завершение процесса входа Microsoft.

Зарегистрируйте ваше приложение

Если у вас еще нет регистрации приложения, выполните следующие действия, чтобы создать его на портале Azure.

1. Войдите на портал Azure.
2. Перейдите к идентификатору Microsoft Entra ID>регистрации приложений>Новая регистрация.
3. Введите отображаемое имя (например, "My Web App").
4. Выберите поддерживаемые типы учетных записей:
   • Один клиент — только пользователи в организации
   • Многопользовательский — пользователи из любой организации
   • Multi-tenant + personal — все учетные записи Microsoft
5. В разделе URI перенаправления задайте для платформы веб-сайт и введите https://localhost:5001/signin-oidc.
6. Выберите Зарегистрировать.
7. На странице обзора скопируйте идентификатор приложения (клиента) и идентификатор каталога (клиента). Эти значения требуются для полей ClientId и TenantId в appsettings.json.

Настройка необязательных параметров

В сценарии могут потребоваться эти дополнительные параметры.

Включение выдачи токена идентификатора — Некоторые сценарии гибридной аутентификации требуют непосредственной выдачи токенов идентификаторов из конечной точки авторизации. Поток кода авторизации (используется Microsoft. Identity.Web) — это рекомендуемый подход. Включите этот параметр только в том случае, если для вашего сценария требуется следующее:

1. В регистрации приложения перейдите к проверке подлинности.
2. В Неявное предоставление и гибридные потоки выберите ID токены.
3. Нажмите Сохранить.

Примечание

Поток неявного предоставления — это устаревший поток. Microsoft рекомендует использовать авторизационный кодовый поток с PKCE для всех новых приложений. Дополнительные сведения см. в документации платформа удостоверений Майкрософт.

Configure front-channel logout URL — гарантирует, что пользователи выходят из вашего приложения при выходе из системы Microsoft Entra.

1. В регистрации приложения перейдите к проверке подлинности.
2. В поле URL-адрес для выхода через front-channel введите https://localhost:5001/signout-oidc.
3. Нажмите Сохранить.

Устранение распространенных ошибок

Если во время входа возникают проблемы, проверьте наличие распространенных ошибок.

Error	Причина	Решение
AADSTS50011: адрес ответа не зарегистрирован	Несоответствие URI перенаправления между кодом и регистрацией приложения	Убедитесь, что URI перенаправления в вашей регистрации приложения совпадает с CallbackPath (/signin-oidc по умолчанию)
AADSTS700016: приложение не найдено	Неверно ClientId в конфигурации	Убедитесь, что идентификатор приложения (клиента) соответствует appsettings.json регистрации приложения
Ошибка конфигурации авторитета	Отсутствующие или недопустимые Instance или TenantId	Установите Instance на https://login.microsoftonline.com/ и подтвердите, что TenantId действительны

Связанный контент

• Вызов подчиненных API из веб-приложений
• Авторизация
• Общие сведения о кэше маркеров
• Краткое руководство: Веб-API