Защита автономного приложения ASP.NET Core Blazor WebAssembly с помощью библиотеки проверки подлинности

В этой статье объясняется, как защитить автономное приложение ASP.NET Core Blazor WebAssembly с помощью библиотеки проверки подлинности Blazor WebAssembly.

Библиотека аутентификации Blazor WebAssembly (Authentication.js) поддерживает только поток авторизационного кода с подтверждением ключа (PKCE) через Microsoft Authentication Library (MSAL, msal.js). Чтобы реализовать другие потоки авторизации, обратитесь к руководству MSAL, чтобы реализовать MSAL напрямую, но мы не поддерживаем и не рекомендуем использование потоков авторизации, отличных от PKCE для Blazor приложений.

Для Microsoft Entra (ME-ID) рекомендаций не следуйте этому руководству. См. Защитите автономное приложение ASP.NET Core Blazor WebAssembly с помощью Microsoft Entra ID.

Дополнительные сведения о сценарии безопасности после чтения этой статьи см. в разделе ASP.NET Core Blazor WebAssembly дополнительные сценарии безопасности.

Walkthrough

В подразделах пошагового руководства объясняется, как:

• Регистрация приложения
• Blazor Создание приложения
• Выполнить приложение

Регистрация приложения

Зарегистрируйте приложение с помощью поставщика OpenID Connect (OIDC)Identity после указания, предоставленного хранителем IP-адреса.

Запишите следующие сведения:

• Орган (например, https://accounts.google.com/).
• Идентификатор приложения (клиента) (например, 2...7-e...q.apps.googleusercontent.com).
• Дополнительная конфигурация IP (см. документацию по IP).

Blazor Создание приложения

Чтобы создать приложение standalone Blazor WebAssembly, использующее библиотеку Майкрософт.AspNetCore.Components.WebAssembly.Authentication, следуйте инструкциям по выбору инструментов. Если добавлена поддержка проверки подлинности, ознакомьтесь с разделом "Части приложения " этой статьи, чтобы получить рекомендации по настройке и настройке приложения.

dotnet new blazorwasm -au Individual -o {PROJECT NAME}

Настройка приложения

Настройте приложение, выполнив инструкции по IP-адресу. Как минимум, приложению требуются Local:Authority параметры конфигурации и Local:ClientId параметры конфигурации в файле приложения wwwroot/appsettings.json :

{
  "Local": {
    "Authority": "{AUTHORITY}",
    "ClientId": "{CLIENT ID}"
  }
}

Пример OIDC Google OAuth 2.0 для приложения, работающего localhost по адресу через порт 5001:

{
  "Local": {
    "Authority": "https://accounts.google.com/",
    "ClientId": "2...7-e...q.apps.googleusercontent.com",
    "PostLogoutRedirectUri": "https://localhost:5001/authentication/logout-callback",
    "RedirectUri": "https://localhost:5001/authentication/login-callback",
    "ResponseType": "code"
  }
}

URI перенаправления (https://localhost:5001/authentication/login-callback) регистрируется в консоли API Google в разделе Учетные данные>{NAME}>Разрешенные URI перенаправления, где {NAME} — это имя клиента приложения в списке идентификаторов клиентов OAuth 2.0 приложения в консоли Google API.

Выполнить приложение

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

• Visual Studio
  • Нажмите кнопку Запустить.
  • В меню выберите Отладка>Начать отладку.
  • Нажмите клавишу F5.
• командная оболочка cli .NET: выполните команду dotnet watch (или dotnet run) из папки приложения.

Пути удаленной проверки подлинности

Пути удаленной проверки подлинности настраиваются с помощью RemoteAuthenticationApplicationPathsOptionsRemoteAuthenticationOptions<TRemoteAuthenticationProviderOptions>.AuthenticationPaths свойства в файле приложения Program . Значения путей по умолчанию для платформы см. в справочном источникеdotnet/aspnetcore.

Если приложение настраивает путь удаленной проверки подлинности, выполните любой из следующих подходов:

• Сопоставьте путь в жёстко закодированных строках в приложении.

• Вставить Майкрософт.AspNetCore.Components.WebAssembly.Authentication.RemoteAuthenticationOptions<TRemoteAuthenticationProviderOptions>, чтобы получить настроенное значение по всему приложению. В следующем примере демонстрируется подход к компонентуRedirectToLogin.

  Добавьте следующие Razor директивы в начало файла компонента Razor :

  @using Microsoft.Extensions.Options
  @inject IOptionsSnapshot<RemoteAuthenticationOptions<ApiAuthorizationProviderOptions>> RemoteOptions
  

  Измените перенаправление компонента в методе OnInitialized :

  - Navigation.NavigateToLogin("authentication/login");
  + Navigation.NavigateToLogin(RemoteOptions.Get(Options.DefaultName)
  +     .AuthenticationPaths.LogInPath);
  

  Note

  Если другие пути отличаются от путей шаблона проекта или путей по умолчанию платформы, управляйте ими таким же образом.

Части приложения

В этом разделе описываются части приложения, созданные на основе Blazor WebAssembly шаблона проекта, и способы настройки приложения. В этом разделе нет конкретных рекомендаций для базового рабочего приложения, если вы создали приложение с помощью руководства в разделе "Пошаговое руководство ". Руководство в этом разделе полезно для обновления приложения для проверки подлинности и авторизации пользователей. Однако альтернативный подход к обновлению приложения — создать новое приложение из руководства в разделе "Пошаговое руководство " и переместить компоненты, классы и ресурсы приложения в новое приложение.

Пакет проверки подлинности

При создании приложения для использования отдельных учетных записей приложение автоматически получает ссылку на пакет Майкрософт.AspNetCore.Components.WebAssembly.Authentication. В пакете содержится набор примитивов, которые помогают приложению проверять подлинность пользователей и получать маркеры для вызова защищенных API.

При добавлении проверки подлинности в приложение вручную добавьте пакет Майкрософт.AspNetCore.Components.WebAssembly.Authentication.

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

Поддержка проверки подлинности пользователей с помощью OpenID Connect (OIDC) регистрируется в контейнере службы с помощью метода расширения AddOidcAuthentication, предоставленного пакетом Майкрософт.AspNetCore.Components.WebAssembly.Authentication.

Метод AddOidcAuthentication принимает обратный вызов для настройки параметров, необходимых для проверки подлинности приложения с помощью OIDC. Значения, необходимые для настройки приложения, можно получить от поставщика удостоверений, совместимого с OIDC. Получите эти значения при регистрации приложения, которая обычно производится на веб-портале.

Для нового приложения укажите значения для заполнителей {AUTHORITY} и {CLIENT ID} в следующей конфигурации. Укажите другие значения конфигурации, необходимые для использования с IP-адресом приложения. В качестве примера используется Google, для чего требуются PostLogoutRedirectUri, RedirectUri и ResponseType. При добавлении проверки подлинности в приложение вручную добавьте следующий код и конфигурацию в приложение со значениями заполнителей и другими значениями конфигурации.

В файле Program:

builder.Services.AddOidcAuthentication(options =>
{
    builder.Configuration.Bind("Local", options.ProviderOptions);
});

wwwroot/appsettings.jsonКонфигурация

Конфигурация предоставлена в файле wwwroot/appsettings.json:

{
  "Local": {
    "Authority": "{AUTHORITY}",
    "ClientId": "{CLIENT ID}"
  }
}

Области действия токенов доступа

Шаблон Blazor WebAssembly автоматически настраивает области по умолчанию для openid и profile.

Шаблон Blazor WebAssembly не выполняет автоматическую настройку приложения для запроса токена доступа к защищённому API. Чтобы настроить токен доступа в рамках процесса входа, добавьте область к областям токена доступа по умолчанию OidcProviderOptions. При добавлении аутентификации в приложение добавьте вручную следующий код и настройте URI для области.

В файле Program:

builder.Services.AddOidcAuthentication(options =>
{
    ...
    options.ProviderOptions.DefaultScopes.Add("{SCOPE URI}");
});

Дополнительные сведения см. в следующих разделах статьи Дополнительные сценарии:

• Запросите дополнительные токены доступа
• Присоединение маркеров к исходящим запросам

Импорт файла

Пространство имен Майкрософт.AspNetCore.Components.Authorization доступно в приложении через файл _Imports.razor:

...
@using Microsoft.AspNetCore.Components.Authorization
...

Страница индекса

Страница индекса (wwwroot/index.html) содержит сценарий, определяющий AuthenticationService в JavaScript. AuthenticationService обрабатывает низкоуровневые сведения о протоколе OIDC. Приложение внутренне вызывает методы, определенные в сценарии для выполнения операций проверки подлинности.

<script src="_content/Microsoft.AspNetCore.Components.WebAssembly.Authentication/AuthenticationService.js"></script>

Компонент приложения

Компонент App (App.razor) аналогичен компоненту App, который находится в приложениях Blazor Server:

Из-за изменений платформы в разных выпусках ASP.NET Core разметка Razor для компонента App (App.razor) не отображается в этом разделе. Чтобы изучить разметку этого компонента для конкретного выпуска, используйте один из следующих подходов:

• Создайте приложение, подготовленное для проверки подлинности, из шаблона проекта по умолчанию Blazor WebAssembly для версии ASP.NET Core, которую вы планируете использовать. Изучите компонент App (App.razor) в созданном приложении;

• изучите компонент App (App.razor) в справочных материалах. Выберите версию из селектора ветви и найдите компонент в ProjectTemplates папке репозитория, так как он перемещен на протяжении многих лет.

  Note

  Ссылки на справочную документацию .NET обычно ведут на ветвь репозитория по умолчанию, которая представляет собой текущую разработку следующего релиза .NET. Чтобы выбрать тег для определенного выпуска, используйте выпадающий список «Переключение ветвей или тегов». Дополнительные сведения см. в разделе Как выбрать тег версии исходного кода ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Компонент RedirectToLogin

Компонент RedirectToLogin (RedirectToLogin.razor):

• управляет перенаправлением неавторизованных пользователей на страницу входа.
• Текущий URL-адрес, который пользователь пытается получить, сохраняется, чтобы в случае успешной аутентификации его можно было вернуть на ту же страницу.
  • Состояние истории навигации в ASP.NET Core в .NET 7 или более поздней версии.
  • Строка запроса в ASP.NET Core в .NET 6 или более ранних версий.

Изучите компонент RedirectToLogin в справочных материалах. Расположение компонента изменилось с течением времени, поэтому используйте средства поиска GitHub для поиска компонента.

Компонент LoginDisplay

Компонент LoginDisplay (LoginDisplay.razor) отображается в компоненте MainLayout (MainLayout.razor) и управляет следующими поведениями.

• Для прошедших проверку подлинности пользователей:
  • Отображает имя текущего пользователя.
  • Предоставляет ссылку на страницу профиля пользователя в ASP.NET Core Identity.
  • Предлагает кнопку для выхода из приложения.
• Для анонимных пользователей:
  • Предоставляет возможность регистрации.
  • Предоставляет возможность входа в систему.

Из-за изменений фреймворка в разных выпусках ASP.NET Core разметка Razor для компонента LoginDisplay не отображается в этом разделе. Чтобы изучить разметку этого компонента для конкретного выпуска, используйте один из следующих подходов:

• Создайте приложение, подготовленное для проверки подлинности, из шаблона проекта по умолчанию Blazor WebAssembly для версии ASP.NET Core, которую вы планируете использовать. Изучите компонент LoginDisplay в созданном приложении.

• Изучите компонент LoginDisplay в справочных материалах. Расположение компонента изменилось с течением времени, поэтому используйте средства поиска GitHub для поиска компонента. Шаблонное содержимое для Hosted, равное true, используется.

  Note

  Ссылки на справочную документацию .NET обычно ведут на ветвь репозитория по умолчанию, которая представляет собой текущую разработку следующего релиза .NET. Чтобы выбрать тег для определенного выпуска, используйте выпадающий список «Переключение ветвей или тегов». Дополнительные сведения см. в разделе Как выбрать тег версии исходного кода ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Компонент проверки подлинности

Страница, созданная компонентом Authentication (Pages/Authentication.razor), определяет маршруты, необходимые для обработки различных этапов проверки подлинности.

Компонент RemoteAuthenticatorView:

• Предоставляется пакетом Майкрософт.AspNetCore.Components.WebAssembly.Authentication.
• Управляет выполнением соответствующих действий на каждом этапе проверки подлинности.

@page "/authentication/{action}"
@using Microsoft.AspNetCore.Components.WebAssembly.Authentication

<RemoteAuthenticatorView Action="@Action" />

@code {
    [Parameter]
    public string? Action { get; set; }
}

Troubleshoot

Logging

Чтобы включить ведение журнала отладки или трассировки для аутентификации Blazor WebAssembly, см. раздел Ведение журнала аутентификации на стороне клиента в ASP.NET Core Blazor ведении журнала, установив селектор версий статьи на ASP.NET Core в .NET 7 или более поздней версии.

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

• Неправильная настройка приложения или поставщика Identity (IP)

  Наиболее частые ошибки вызваны неправильной настройкой. Ниже приводятся несколько примеров.

  • В зависимости от требований сценария, отсутствующие или неправильные элементы, такие как центр сертификации, экземпляр, идентификатор арендатора, домен арендатора, идентификатор клиента или URI перенаправления, не позволяют приложению осуществлять проверку подлинности клиентов.
  • Неверные области запросов не позволяют клиентам получать доступ к конечным точкам веб-API сервера.
  • Неправильные или отсутствующие разрешения API сервера не позволяют клиентам получить доступ к конечным точкам веб-API сервера.
  • Запуск приложения на порте, отличающемся от того, который настроен в URI перенаправления для регистрации приложения с IP-адресом. Обратите внимание, что порт не требуется для Microsoft Entra ID и приложения, работающего на адресе тестирования localhost разработки. Однако конфигурация порта приложения и порт, на котором выполняется приложение, должны соответствовать, если используются адреса, отличные от localhost.

  В разделах конфигурации этой статьи приведены примеры правильной настройки. Внимательно изучите каждый раздел статьи, проверяя настройки приложения и IP.

  Если конфигурация верна, выполните приведенные ниже действия.

  • Проанализируйте журналы приложений.

  • Изучите сетевой трафик между клиентским приложением и IP-адресом или серверным приложением с помощью инструментов разработчика браузера. Часто точное сообщение об ошибке или сообщение с подсказкой о том, что вызывает проблему, возвращается клиенту приложением сервера или IP после выполнения запроса. Рекомендации по инструментам разработчика приведены в следующих статьях:

    • Google Chrome (документация по Google)
    • Microsoft Edge
    • Mozilla Firefox (документация по Mozilla)

  • В выпусках Blazor, где используется веб-токен JSON (JWT), декодируйте содержимое маркера, используемого для аутентификации клиента или доступа к веб-API сервера, в зависимости от того, где возникает проблема. Дополнительные сведения о проверке содержимого JSON Web Token (JWT) см. в этом разделе.

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

  • Stack Overflow (тег: blazor)
  • Команда Slack по ASP.NET Core
  • Blazor Гитер

  Предыдущие форумы не принадлежат или управляются Майкрософт.

  Для воспроизводимых отчетов об ошибках платформы, которые не связаны с безопасностью и не считаются конфиденциальными, откройте проблему с единицей продукта ASP.NET Core. Не открывайте обращение в команду по продукту, пока вы тщательно не изучите причину проблемы и не попытаетесь решить её самостоятельно или с помощью сообщества на общедоступном форуме поддержки. Единица продукта не способна устранять неполадки отдельных приложений, которые не работают из-за неправильной конфигурации или вариантов использования с участием сторонних служб. Если отчет является конфиденциальным по своей природе или описывает потенциальный недостаток безопасности в продукте, который может использоваться злоумышленниками, см. Сообщение о проблемах безопасности и ошибках (dotnet/aspnetcore репозитории на GitHub).

• Несанкционированный клиент для ME-ID

  сведения: Майкрософт.AspNetCore.Authorization.DefaultAuthorizationService[2] Авторизация не удалась. Эти требования не выполнены: DenyAnonymousAuthorizationRequirement: требуется прошедший проверку подлинности пользователь.

  Ошибка обратного вызова при входе из ME-ID

  • Ошибка: unauthorized_client
  • Описание: AADB2C90058: The provided application is not configured to allow public clients.

  Чтобы устранить эту ошибку, сделайте следующее:

  1. На портале Azure перейдите к манифесту приложения.
  2. Задайте для атрибута allowPublicClient значение null или true.

Файлы cookie и данные сайта

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

• файлы cookie входа пользователей;
• Файлы cookie приложений
• кэшированные и сохраненные данные сайта.

Один из подходов, позволяющих предотвратить влияние устаревших файлов cookie и данных сайта на тестирование и устранение неполадок заключается в следующем:

• Настройка браузера
  • Для тестирования используйте браузер, в котором можно настроить удаление всех файлов cookie и данных сайта при каждом закрытии браузера.
  • Убедитесь, что при любых изменениях в приложении, в данных тестового пользователя или в конфигурации поставщика закрытие браузера выполняется вручную или интегрированной средой разработки.
• Используйте пользовательскую команду, чтобы открыть браузер в режиме InPrivate или Incognito в Visual Studio:
  • Откройте в Visual Studio диалоговое окно Browse With с кнопки Run.
  • Нажмите кнопку Добавить.
  • Укажите путь к браузеру в поле Программа. Следующие пути исполняемого файла являются типичными расположениями установки для Windows 10. Если браузер установлен в другом расположении или вы не используете Windows 10, укажите путь к исполняемому файлу браузера.
    • Microsoft Edge: C:\Program Files (x86)\Майкрософт\Edge\Application\msedge.exe
    • Google Chrome: C:\Program Files (x86)\Google\Chrome\Application\chrome.exe
    • Mozilla Firefox: C:\Program Files\Mozilla Firefox\firefox.exe
  • В поле "Аргументы" укажите параметр командной строки, который браузер использует для открытия в режиме InPrivate или Incognito. Для некоторых браузеров требуется URL-адрес приложения.
    • Microsoft Edge. Используйте -inprivate.
    • Google Chrome: используйте --incognito --new-window {URL}, где метка {URL} представляет собой URL-адрес для открытия (например, https://localhost:5001).
    • Mozilla Firefox: используйте -private -url {URL}, где {URL} подстановочный элемент является URL-адресом для открытия (например, https://localhost:5001).
  • Введите имя в поле Дружелюбное имя. Например, Firefox Auth Testing.
  • Выберите кнопку ОК.
  • Чтобы не выбирать профиль браузера для каждой операции тестирования с помощью приложения, задайте профиль по умолчанию с помощью кнопки По умолчанию.
  • Убедитесь, что при любых изменениях в приложении, в данных тестового пользователя или в конфигурации поставщика закрытие браузера выполняется интегрированной средой разработки.

Обновления приложений

Функционирующее приложение может перестать работать сразу после обновления .NET SDK на компьютере разработчика или изменения версий пакетов в приложении. В некоторых случаях несогласованные пакеты могут нарушить работу приложения при проведении важных обновлений. Большинство этих проблем можно исправить следующим образом:

1. Очистите кэши пакетов NuGet локальных систем, выполнив команду dotnet nuget locals all --clear из командной оболочки.
2. Удалите папки bin и obj проекта.
3. Восстановите и перестройте проект.
4. Удалите все файлы из папки развертывания на сервере, прежде чем повторно развернуть приложение.

Проверка пользователя

Следующий User компонент можно использовать непосредственно в приложениях или служить основой для дальнейшей настройки.

User.razor:

@page "/user"
@attribute [Authorize]
@using System.Text.Json
@using System.Security.Claims
@inject IAccessTokenProvider AuthorizationService

<h1>@AuthenticatedUser?.Identity?.Name</h1>

<h2>Claims</h2>

@foreach (var claim in AuthenticatedUser?.Claims ?? Array.Empty<Claim>())
{
    <p class="claim">@(claim.Type): @claim.Value</p>
}

<h2>Access token</h2>

<p id="access-token">@AccessToken?.Value</p>

<h2>Access token claims</h2>

@foreach (var claim in GetAccessTokenClaims())
{
    <p>@(claim.Key): @claim.Value.ToString()</p>
}

@if (AccessToken != null)
{
    <h2>Access token expires</h2>

    <p>Current time: <span id="current-time">@DateTimeOffset.Now</span></p>
    <p id="access-token-expires">@AccessToken.Expires</p>

    <h2>Access token granted scopes (as reported by the API)</h2>

    @foreach (var scope in AccessToken.GrantedScopes)
    {
        <p>Scope: @scope</p>
    }
}

@code {
    [CascadingParameter]
    private Task<AuthenticationState> AuthenticationState { get; set; }

    public ClaimsPrincipal AuthenticatedUser { get; set; }
    public AccessToken AccessToken { get; set; }

    protected override async Task OnInitializedAsync()
    {
        await base.OnInitializedAsync();
        var state = await AuthenticationState;
        var accessTokenResult = await AuthorizationService.RequestAccessToken();

        if (!accessTokenResult.TryGetToken(out var token))
        {
            throw new InvalidOperationException(
                "Failed to provision the access token.");
        }

        AccessToken = token;

        AuthenticatedUser = state.User;
    }

    protected IDictionary<string, object> GetAccessTokenClaims()
    {
        if (AccessToken == null)
        {
            return new Dictionary<string, object>();
        }

        // header.payload.signature
        var payload = AccessToken.Value.Split(".")[1];
        var base64Payload = payload.Replace('-', '+').Replace('_', '/')
            .PadRight(payload.Length + (4 - payload.Length % 4) % 4, '=');

        return JsonSerializer.Deserialize<IDictionary<string, object>>(
            Convert.FromBase64String(base64Payload));
    }
}

Проверка содержимого JSON Web Token (JWT)

Чтобы декодировать веб-токен JSON (JWT), используйте средство Майкрософт jwt.ms. Значения в пользовательском интерфейсе остаются в браузере.

Пример закодированного JWT (сокращено для отображения):

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ilg1ZVhrNHh5b2pORnVtMWtsMll0djhkbE5QNC1j ... bQdHBHGcQQRbW7Wmo6SWYG4V_bU55Ug_PW4pLPr20tTS8Ct7_uwy9DWrzCMzpD-EiwT5IjXwlGX3IXVjHIlX50IVIydBoPQtadvT7saKo1G5Jmutgq41o-dmz6-yBMKV2_nXA25Q

Пример JWT, декодированного средством для приложения, которое проходит проверку подлинности в Azure AAD B2C.

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1610059429,
  "nbf": 1610055829,
  "ver": "1.0",
  "iss": "https://mysiteb2c.b2clogin.com/11112222-bbbb-3333-cccc-4444dddd5555/v2.0/",
  "sub": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "aud": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "nonce": "bbbb0000-cccc-1111-dddd-2222eeee3333",
  "iat": 1610055829,
  "auth_time": 1610055822,
  "idp": "idp.com",
  "tfp": "B2C_1_signupsignin"
}.[Signature]

Дополнительные ресурсы

• ASP.NET Core Blazor WebAssembly дополнительные сценарии безопасности
• Запросы веб-API, не прошедшие проверку подлинности или неавторизованные, в приложении с защищенным клиентом по умолчанию
• Configure ASP.NET Core для работы с прокси-серверами и подсистемами балансировки нагрузки. Включает следующие рекомендации.
  • Использование промежуточного программного обеспечения для перенаправленных заголовков для сохранения сведений о схеме HTTPS на прокси-серверах и во внутренних сетях.
  • Дополнительные сценарии и варианты использования, включая ручную настройку схемы, изменение пути запроса для правильной маршрутизации запроса и перенаправление схемы запроса для обратных прокси-серверов Linux и обратных прокси-серверов, отличных от IIS.