Защита ASP.NET Core Blazor Web App с помощью OpenID Connect (OIDC)

В этой статье описывается, как защитить Blazor Web Appприложение OpenID Connect (OIDC) с помощью примера приложения в dotnet/blazor-samples репозитории GitHub (.NET 8 или более поздней версии) (как скачать).

Эта версия статьи охватывает реализацию OIDC без использования шаблона Backend для Frontend (BFF) с приложением, которое использует глобальное интерактивное автоматическое рендеринг (для серверов и .Client проектов). Шаблон BFF полезен для выполнения аутентифицированных запросов к внешним службам. Измените селектор версии статьи на OIDC с шаблоном BFF, если спецификация приложения вызывает внедрение шаблона BFF.

Рассматривается следующая спецификация:

• Blazor Web App использует режим автоматической отрисовки с глобальной интерактивностью.
• Пользовательские службы, предоставляющие состояние аутентификации, используются сервером и клиентскими приложениями для фиксации состояния аутентификации пользователя и передачи между сервером и клиентом.
• Это приложение является отправной точкой для любого потока проверки подлинности OIDC. OIDC настраивается вручную в приложении и не зависит от Microsoft Entra ID или пакетов Microsoft Identity Web, также пример приложения не требует размещения в Microsoft Azure. Однако пример приложения можно использовать с Entra, Microsoft Identity Web и размещать в Azure.
• Автоматическое обновление неинтерактивного токена.
• Безопасно вызывает (веб-) API в серверном проекте для данных.

Для получения альтернативного опыта работы с библиотекой аутентификации Microsoft для .NET, Microsoft Web, и Microsoft Entra ID, см. статью "Защита ASP.NET Core с помощью Microsoft Entra ID".

Пример приложения

Пример приложения состоит из двух проектов:

• BlazorWebAppOidc: серверный проект объекта Blazor Web App, содержащий пример минимальной конечной точки API для данных погоды.
• BlazorWebAppOidc.Client: клиентский проект объекта Blazor Web App.

Перейдите к образцам приложений, используя папку с последней версией в корневом каталоге репозитория, по следующей ссылке. Проекты находятся в папке BlazorWebAppOidc для .NET 8 или более поздней версии.

Просмотреть или скачать образец кода (описание загрузки)

Серверный Blazor Web App проект (BlazorWebAppOidc)

Проект BlazorWebAppOidc является серверным проектом Blazor Web App.

Файл BlazorWebAppOidc.http можно использовать для тестирования запроса данных о погоде. Обратите внимание, что BlazorWebAppOidc проект должен выполняться для тестирования конечной точки, а конечная точка жестко закодирована в файл. Дополнительные сведения см. в статье "Использование HTTP-файлов в Visual Studio 2022".

Настройка

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

Примечание.

Для Microsoft Entra ID или Azure AD B2C вы можете использовать AddMicrosoftIdentityWebApp из Microsoft Identity Web (пакет Microsoft.Identity.Web NuGet, документация по API), которые добавляют как обработчики OIDC, так и Cookie проверку подлинности с соответствующими значениями по умолчанию. Пример приложения и руководство в этом разделе не используют Microsoft Identity Web. В руководстве показано, как настроить обработчик OIDC вручную для любого поставщика OIDC. Дополнительные сведения о реализации Microsoft Identity Web см. в связанных ресурсах.

Создайте секрет клиента

Предупреждение

Не сохраняйте секреты приложений, строка подключения, учетные данные, пароли, персональные идентификационные номера (ПИН-коды), частный код C#/.NET или закрытые ключи и токены в клиентском коде, который всегда небезопасн. В тестовых, промежуточных и рабочих средах код на стороне Blazor сервера и веб-API должен использовать безопасные методы аутентификации, которые избегают хранения учетных данных в коде проекта или конфигурационных файлах. Вне локального тестирования разработки рекомендуется избегать использования переменных среды для хранения конфиденциальных данных, так как переменные среды не являются наиболее безопасным подходом. Для локального тестирования разработки средство Secret Manager рекомендуется для защиты конфиденциальных данных. Дополнительные сведения см. в разделе "Безопасное обслуживание конфиденциальных данных и учетных данных".

Для локального тестирования разработки используйте средство Secret Manager для хранения секрета клиента серверного приложения под ключом Authentication:Schemes:MicrosoftOidc:ClientSecretконфигурации.

Примечание.

Если приложение использует идентификатор Microsoft Entra или Azure AD B2C, создайте секрет клиента в регистрации приложения в портале Entra или Azure (Управление>Сертификаты и секреты>Новый секрет клиента). Используйте значение нового секрета в следующем руководстве.

Образец приложения не был инициализирован для инструмента Secret Manager. Используйте командную оболочку, например командную оболочку PowerShell разработчика в Visual Studio, чтобы выполнить следующую команду. Перед выполнением команды с помощью команды cd измените каталог на директорию проекта сервера. Команда устанавливает идентификатор секретов пользователя (<UserSecretsId> в файле проекта приложения сервера):

dotnet user-secrets init

Выполните следующую команду, чтобы задать секрет клиента. Заполнитель {SECRET} — это секрет клиента, полученный из регистрации приложения:

dotnet user-secrets set "Authentication:Schemes:MicrosoftOidc:ClientSecret" "{SECRET}"

При использовании Visual Studio можно подтвердить, что секрет задан, щелкнув правой кнопкой мыши проект сервера в Обозреватель решений и выбрав "Управление секретами пользователей".

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

Следующая OpenIdConnectOptions конфигурация найдена в файле проекта Program при вызове AddOpenIdConnect:

• SignInScheme. Задает схему проверки подлинности, соответствующую ПО промежуточного слоя, ответственному за сохранение удостоверения пользователя после успешной проверки подлинности. Обработчик OIDC должен использовать схему входа, которая может сохранять учетные данные пользователя в запросах. Следующая строка представлена лишь для демонстрационных целей. Если опущено, DefaultSignInScheme используется в качестве резервного значения.

  oidcOptions.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
  

• Области для openid и profile (Scope) (необязательно): области openid и profile также настраиваются по умолчанию, так как они необходимы для работы обработчика OIDC, но их может потребоваться повторно добавить, если области включены в конфигурацию Authentication:Schemes:MicrosoftOidc:Scope. Общие рекомендации по настройке см. в разделе "Конфигурация" в ASP.NET Core и Blazor ASP.NET Core.

  oidcOptions.Scope.Add(OpenIdConnectScope.OpenIdProfile);
  

• SaveTokens: определяет, следует ли хранить маркеры доступа и обновления в AuthenticationProperties после успешной авторизации. Это свойство имеет значение true, поэтому токен обновления сохраняется для неинтерактивного обновления токенов.

  oidcOptions.SaveTokens = true;
  

• Область для офлайн-доступа (Scope): Область offline_access необходима для получения маркера обновления.

  oidcOptions.Scope.Add(OpenIdConnectScope.OfflineAccess);
  

• Authority и ClientId: задает уровень полномочий и идентификатор клиента для вызовов OIDC.

  oidcOptions.Authority = "{AUTHORITY}";
  oidcOptions.ClientId = "{CLIENT ID}";
  

  Пример:

  • Орган ({AUTHORITY}): https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/ (использует идентификатор клиента aaaabbbb-0000-cccc-1111-dddd2222eeee)
  • Идентификатор клиента ({CLIENT ID}): 00001111-aaaa-2222-bbbb-3333cccc4444

  oidcOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/";
  oidcOptions.ClientId = "00001111-aaaa-2222-bbbb-3333cccc4444";
  

  Пример для "common" домена Microsoft Azure:

  "Общий" полномочия должны использоваться для мультитенантных приложений. Вы также можете использовать полномочия "common" для однотенантных приложений, но требуется настраиваемый IssuerValidator, как показано далее в этом разделе.

  oidcOptions.Authority = "https://login.microsoftonline.com/common/v2.0/";
  

• ResponseType: настраивает обработчик OIDC только для выполнения потока кода авторизации. Неявные гранты и гибридные потоки являются ненужными в этом режиме. Обработчик OIDC автоматически запрашивает соответствующие маркеры с помощью кода, возвращаемого из конечной точки авторизации.

  oidcOptions.ResponseType = OpenIdConnectResponseType.Code;
  

  Примечание.

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

• MapInboundClaims и настройка NameClaimType и RoleClaimType: многие серверы name OIDC используют "name" и "ClaimTypes" вместо значений по умолчанию SOAP/WS-Fed. Если MapInboundClaims задано значение false, обработчик не выполняет сопоставления утверждений, а имена утверждений из JWT используются непосредственно приложением. В следующем примере тип требований к роли задан как "roles", что подходит для Microsoft Entra ID (ME-ID). Дополнительные сведения см. в документации поставщика удостоверений.

  Примечание.

  MapInboundClaims Необходимо задать значение false для большинства поставщиков OIDC, что предотвращает переименование утверждений.

  oidcOptions.MapInboundClaims = false;
  oidcOptions.TokenValidationParameters.NameClaimType = "name";
  oidcOptions.TokenValidationParameters.RoleClaimType = "roles";
  

• Конфигурация пути: Пути должны соответствовать URI перенаправления (путь обратного вызова для входа) и пути перенаправления после выхода (путь обратного вызова после выхода), которые были настроены при регистрации приложения у поставщика OIDC. В портале Azure пути настраиваются в области проверки подлинности регистрации приложения. Пути входа и выхода должны быть зарегистрированы как URI перенаправления. Значения по умолчанию: /signin-oidc и /signout-callback-oidc.

  • CallbackPath: Путь запроса в пределах базового пути приложения, где возвращается агент пользователя.

    Настройте путь обратного вызова для выхода из системы в настройках провайдера OIDC приложения. В следующем примере заполнитель {PORT} является портом приложения:

    https://localhost:{PORT}/signin-oidc

    Примечание.

    Порт не требуется для localhost адресов при использовании идентификатора Microsoft Entra. Большинству других поставщиков OIDC требуется правильный порт.

  • SignedOutCallbackPath (ключ конфигурации: "SignedOutCallbackPath"): путь запроса в рамках базового пути приложения, перехваченный обработчиком OIDC, куда агент пользователя сначала возвращается после выхода из поставщика удостоверений. Пример приложения не задает значение для пути, так как используется значение по умолчанию "/signout-callback-oidc". После перехвата запроса обработчик OIDC перенаправляется в SignedOutRedirectUri или RedirectUri, если указано.

    Настройте путь обратного вызова для выхода из системы в настройках провайдера OIDC приложения. В следующем примере заполнитель {PORT} является портом приложения:

    https://localhost:{PORT}/signout-callback-oidc

    Примечание.

    При использовании Microsoft Entra ID укажите путь в конфигурации платформы для записей URI перенаправления на портале Entra или Azure. Порт не требуется при использовании Entra для адресов "localhost". Большинству других поставщиков OIDC требуется правильный порт. Если вы не добавите URI пути обратного вызова после выхода из системы в регистрацию приложения в Entra, Entra откажется перенаправить пользователя обратно в приложение и просто попросит его закрыть окно браузера.

  • RemoteSignOutPath: запросы, полученные по этому пути, приводят к тому, что обработчик вызывает выход, используя схему выхода.

    В следующем примере заполнитель {PORT} является портом приложения:

    https://localhost/signout-oidc

    Примечание.

    При использовании идентификатора Microsoft Entra задайте URL-адрес выхода front-channel на портале Entra или Azure. Порт не требуется при использовании Entra для адресов "localhost". Большинству других поставщиков OIDC требуется правильный порт.

    oidcOptions.CallbackPath = new PathString("{PATH}");
    oidcOptions.SignedOutCallbackPath = new PathString("{PATH}");
    oidcOptions.RemoteSignOutPath = new PathString("{PATH}");
    

    Примеры (значения по умолчанию):

    oidcOptions.CallbackPath = new PathString("/signin-oidc");
    oidcOptions.SignedOutCallbackPath = new PathString("/signout-callback-oidc");
    oidcOptions.RemoteSignOutPath = new PathString("/signout-oidc");
    

• (Microsoft Azure только с "общей" конечной точкой) TokenValidationParameters.IssuerValidator: Многие поставщики OIDC работают с проверкой издателя по умолчанию, но нам нужно учитывать параметризованный идентификатор клиента ({TENANT ID}), который возвращает https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Дополнительные сведения см. в статье SecurityTokenInvalidIssuerException с OpenID Connect и «общей» конечной точкой Azure AD (AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet#1731).

  Только для приложений, использующих Microsoft Entra ID или Azure AD B2C с конечной точкой «common»:

  var microsoftIssuerValidator = AadIssuerValidator.GetAadIssuerValidator(oidcOptions.Authority);
  oidcOptions.TokenValidationParameters.IssuerValidator = microsoftIssuerValidator.Validate;
  

Пример кода приложения

Проверьте пример приложения для следующих функций:

• Автоматическое обновление токена без взаимодействия пользователя с помощью настраиваемого cookie средства обновления (CookieOidcRefresher.cs).
• Серверный проект вызывает AddAuthenticationStateSerialization, чтобы добавить поставщика состояния проверки подлинности на стороне сервера, который используется PersistentComponentState для передачи состояния проверки подлинности клиенту. Клиент вызывает AddAuthenticationStateDeserialization для десериализации и использования состояния аутентификации, переданного сервером. Состояние аутентификации зафиксировано на все время существования приложения WebAssembly.
• Пример запросов к Blazor Web App данным о погоде обрабатывается минимальной конечной точкой API (/weather-forecast) в Program файле (Program.cs). Для конечной точки требуется авторизация путем вызова RequireAuthorization. Для всех контроллеров, добавляющихся в проект, добавьте [Authorize] атрибут в контроллер или действие. Дополнительные сведения о требовании авторизации в приложении с помощью политики авторизации и отключении авторизации в подмножестве общедоступных конечных точек см. руководство Razor Pages OIDC.
• Приложение безопасно вызывает (веб-) API в проекте сервера для погодных данных:
  • При отрисовке компонента Weather на сервере, компонент использует ServerWeatherForecaster для получения данных о погоде напрямую (а не через вызов веб-API).
  • При отрисовке компонента на клиенте компонент использует ClientWeatherForecaster реализацию службы, которая использует предустановленный HttpClient (в файле клиентского проекта Program) для выполнения вызова веб-API в серверном проекте. Минимальная конечная точка API (/weather-forecast), определенная в файле проекта Program сервера, получает данные о погоде из ServerWeatherForecaster клиента и возвращает данные клиенту.

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

Клиентский Blazor Web App проект (BlazorWebAppOidc.Client)

Проект BlazorWebAppOidc.Client — это клиентский проект Blazor Web App.

Клиент вызывает AddAuthenticationStateDeserialization для десериализации и использования состояния аутентификации, переданного сервером. Состояние аутентификации зафиксировано на все время существования приложения WebAssembly.

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

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

Эта версия статьи охватывает реализацию OIDC без использования шаблона BFF (Backend for Frontend) с приложением, которое использует глобальное рендеринг интерактивного сервера (в рамках одного проекта). Шаблон BFF полезен для выполнения аутентифицированных запросов к внешним службам. Измените селектор версии статьи на OIDC с шаблоном BFF, если спецификация приложения предписывает внедрение шаблона BFF с глобальной интерактивной автоотрисовкой.

Рассматривается следующая спецификация:

• Blazor Web App использует режим отрисовки сервера с глобальной интерактивностью.
• Это приложение является отправной точкой для любого потока проверки подлинности OIDC. OIDC настраивается вручную в приложении и не зависит от Microsoft Entra ID или пакетов Microsoft Identity Web, также пример приложения не требует размещения в Microsoft Azure. Однако пример приложения можно использовать с Entra, Microsoft Identity Web и размещаться в Azure.
• Автоматическое обновление неинтерактивного токена.

Для получения альтернативного опыта работы с библиотекой аутентификации Microsoft для .NET, Microsoft Web, и Microsoft Entra ID, см. статью "Защита ASP.NET Core с помощью Microsoft Entra ID".

Пример приложения

Пример приложения состоит из одного серверного проекта Blazor Web App (BlazorWebAppOidcServer).

Перейдите к примеру приложения через последнюю папку версии из корневого каталога репозитория, используя следующую ссылку. Проект находится в папке BlazorWebAppOidcServer для .NET 8 или более поздней версии.

Просмотреть или скачать образец кода (описание загрузки)

Настройка

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

Примечание.

Для Microsoft Entra ID или Azure AD B2C вы можете использовать AddMicrosoftIdentityWebApp из Microsoft Identity Web (пакет Microsoft.Identity.Web NuGet, документация по API), которые добавляют как обработчики OIDC, так и Cookie проверку подлинности с соответствующими значениями по умолчанию. Пример приложения и руководство в этом разделе не используют Microsoft Identity Web. В руководстве показано, как настроить обработчик OIDC вручную для любого поставщика OIDC. Дополнительные сведения о реализации Microsoft Identity Web см. в связанных ресурсах.

Создайте секрет клиента

Предупреждение

Не сохраняйте секреты приложений, строка подключения, учетные данные, пароли, персональные идентификационные номера (ПИН-коды), частный код C#/.NET или закрытые ключи и токены в клиентском коде, который всегда небезопасн. В тестовых, промежуточных и рабочих средах код на стороне Blazor сервера и веб-API должен использовать безопасные методы аутентификации, которые избегают хранения учетных данных в коде проекта или конфигурационных файлах. Вне локального тестирования разработки рекомендуется избегать использования переменных среды для хранения конфиденциальных данных, так как переменные среды не являются наиболее безопасным подходом. Для локального тестирования разработки средство Secret Manager рекомендуется для защиты конфиденциальных данных. Дополнительные сведения см. в разделе "Безопасное обслуживание конфиденциальных данных и учетных данных".

Для локального тестирования разработки используйте инструмент Менеджера секретов для хранения секрета клиента приложения под ключом конфигурации Authentication:Schemes:MicrosoftOidc:ClientSecret.

Примечание.

Если приложение использует идентификатор Microsoft Entra или Azure AD B2C, создайте секрет клиента в регистрации приложения в портале Entra или Azure (Управление>Сертификаты и секреты>Новый секрет клиента). Используйте значение нового секрета в следующем руководстве.

Образец приложения не был инициализирован для инструмента Secret Manager. Используйте командную оболочку, например командную оболочку PowerShell разработчика в Visual Studio, чтобы выполнить следующую команду. Перед выполнением команды измените каталог с помощью команды cd на каталог проекта. Команда устанавливает идентификатор секретов пользователя (<UserSecretsId> в файле проекта приложения):

dotnet user-secrets init

Выполните следующую команду, чтобы задать секрет клиента. Заполнитель {SECRET} — это секрет клиента, полученный из регистрации приложения:

dotnet user-secrets set "Authentication:Schemes:MicrosoftOidc:ClientSecret" "{SECRET}"

При использовании Visual Studio можно подтвердить, что секрет задан, щелкнув правой кнопкой мыши проект в обозревателе решений и выбрав Управление секретами пользователей.

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

Следующая OpenIdConnectOptions конфигурация найдена в файле проекта Program при вызове AddOpenIdConnect:

• SignInScheme. Задает схему проверки подлинности, соответствующую ПО промежуточного слоя, ответственному за сохранение удостоверения пользователя после успешной проверки подлинности. Обработчик OIDC должен использовать схему входа, которая может сохранять учетные данные пользователя в запросах. Следующая строка представлена лишь для демонстрационных целей. Если опущено, DefaultSignInScheme используется в качестве резервного значения.

  oidcOptions.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
  

• Области для openid и profile (Scope) (необязательно): области openid и profile также настраиваются по умолчанию, так как они необходимы для работы обработчика OIDC, но их может потребоваться повторно добавить, если области включены в конфигурацию Authentication:Schemes:MicrosoftOidc:Scope. Общие рекомендации по настройке см. в разделе "Конфигурация" в ASP.NET Core и Blazor ASP.NET Core.

  oidcOptions.Scope.Add(OpenIdConnectScope.OpenIdProfile);
  

• SaveTokens: определяет, следует ли хранить маркеры доступа и обновления в AuthenticationProperties после успешной авторизации. Это свойство имеет значение true, поэтому токен обновления сохраняется для неинтерактивного обновления токенов.

  oidcOptions.SaveTokens = true;
  
  

• Область для офлайн-доступа (Scope): Область offline_access необходима для получения маркера обновления.

  oidcOptions.Scope.Add(OpenIdConnectScope.OfflineAccess);
  

• Authority и ClientId: задает уровень полномочий и идентификатор клиента для вызовов OIDC.

  oidcOptions.Authority = "{AUTHORITY}";
  oidcOptions.ClientId = "{CLIENT ID}";
  

  Пример:

  • Орган ({AUTHORITY}): https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/ (использует идентификатор клиента aaaabbbb-0000-cccc-1111-dddd2222eeee)
  • Идентификатор клиента ({CLIENT ID}): 00001111-aaaa-2222-bbbb-3333cccc4444

  oidcOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/";
  oidcOptions.ClientId = "00001111-aaaa-2222-bbbb-3333cccc4444";
  

  Пример для "common" домена Microsoft Azure:

  "Общий" полномочия должны использоваться для мультитенантных приложений. Вы также можете использовать полномочия "common" для однотенантных приложений, но требуется настраиваемый IssuerValidator, как показано далее в этом разделе.

  oidcOptions.Authority = "https://login.microsoftonline.com/common/v2.0/";
  

• ResponseType: настраивает обработчик OIDC только для выполнения потока кода авторизации. Неявные гранты и гибридные потоки являются ненужными в этом режиме. Обработчик OIDC автоматически запрашивает соответствующие маркеры с помощью кода, возвращаемого из конечной точки авторизации.

  oidcOptions.ResponseType = OpenIdConnectResponseType.Code;
  

  Примечание.

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

• MapInboundClaims и настройка NameClaimType и RoleClaimType: многие серверы name OIDC используют "name" и "ClaimTypes" вместо значений по умолчанию SOAP/WS-Fed. Если MapInboundClaims задано значение false, обработчик не выполняет сопоставления утверждений, а имена утверждений из JWT используются непосредственно приложением. В следующем примере тип требований к роли задан как "roles", что подходит для Microsoft Entra ID (ME-ID). Дополнительные сведения см. в документации поставщика удостоверений.

  Примечание.

  MapInboundClaims Необходимо задать значение false для большинства поставщиков OIDC, что предотвращает переименование утверждений.

  oidcOptions.MapInboundClaims = false;
  oidcOptions.TokenValidationParameters.NameClaimType = "name";
  oidcOptions.TokenValidationParameters.RoleClaimType = "roles";
  

• Конфигурация пути: Пути должны соответствовать URI перенаправления (путь обратного вызова для входа) и пути перенаправления после выхода (путь обратного вызова после выхода), которые были настроены при регистрации приложения у поставщика OIDC. В портале Azure пути настраиваются в области проверки подлинности регистрации приложения. Пути входа и выхода должны быть зарегистрированы как URI перенаправления. Значения по умолчанию: /signin-oidc и /signout-callback-oidc.

  • CallbackPath: Путь запроса в базовом пути приложения, в котором возвращается агент пользователя.

    Настройте путь обратного вызова для выхода из системы в настройках провайдера OIDC приложения. В следующем примере заполнитель {PORT} является портом приложения:

    https://localhost:{PORT}/signin-oidc

    Примечание.

    Порт не требуется для localhost адресов при использовании идентификатора Microsoft Entra. Большинству других поставщиков OIDC требуется правильный порт.

  • SignedOutCallbackPath (ключ конфигурации: "SignedOutCallbackPath"): путь запроса в рамках базового пути приложения, перехваченный обработчиком OIDC, куда агент пользователя сначала возвращается после выхода из поставщика удостоверений. Пример приложения не задает значение для пути, так как используется значение по умолчанию "/signout-callback-oidc". После перехвата запроса обработчик OIDC перенаправляет на SignedOutRedirectUri или RedirectUri, если указано.

    Настройте путь обратного вызова для выхода из системы в настройках провайдера OIDC приложения. В следующем примере заполнитель {PORT} является портом приложения:

    https://localhost:{PORT}/signout-callback-oidc

    Примечание.

    При использовании Microsoft Entra ID укажите путь в конфигурации платформы для записей URI перенаправления на портале Entra или Azure. Порт не требуется при использовании Entra для адресов "localhost". Большинству других поставщиков OIDC требуется правильный порт. Если вы не добавите URI пути обратного вызова после выхода из системы в регистрацию приложения в Entra, Entra откажется перенаправить пользователя обратно в приложение и просто попросит его закрыть окно браузера.

  • RemoteSignOutPath: запросы, полученные по этому пути, приводят к тому, что обработчик вызывает выход, используя схему выхода.

    В следующем примере заполнитель {PORT} является портом приложения:

    https://localhost/signout-oidc

    Примечание.

    При использовании идентификатора Microsoft Entra задайте URL-адрес выхода front-channel на портале Entra или Azure. Порт не требуется при использовании Entra для адресов "localhost". Большинству других поставщиков OIDC требуется правильный порт.

    oidcOptions.CallbackPath = new PathString("{PATH}");
    oidcOptions.SignedOutCallbackPath = new PathString("{PATH}");
    oidcOptions.RemoteSignOutPath = new PathString("{PATH}");
    

    Примеры (значения по умолчанию):

    oidcOptions.CallbackPath = new PathString("/signin-oidc");
    oidcOptions.SignedOutCallbackPath = new PathString("/signout-callback-oidc");
    oidcOptions.RemoteSignOutPath = new PathString("/signout-oidc");
    

• (Microsoft Azure только с "общей" конечной точкой) TokenValidationParameters.IssuerValidator: Многие поставщики OIDC работают с проверкой издателя по умолчанию, но нам нужно учитывать параметризованный идентификатор клиента ({TENANT ID}), который возвращает https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Дополнительные сведения см. в статье SecurityTokenInvalidIssuerException with OpenID Connect и конечная точка Azure AD common (AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet#1731).

  Только для приложений, использующих Microsoft Entra ID или Azure AD B2C с конечной точкой «common»:

  var microsoftIssuerValidator = AadIssuerValidator.GetAadIssuerValidator(oidcOptions.Authority);
  oidcOptions.TokenValidationParameters.IssuerValidator = microsoftIssuerValidator.Validate;
  

Пример кода приложения

Проверьте пример приложения для следующих функций:

• Автоматическое обновление токена без взаимодействия пользователя с помощью настраиваемого cookie средства обновления (CookieOidcRefresher.cs).
• Компонент Weather использует атрибут [Authorize] для предотвращения несанкционированного доступа. Дополнительные сведения о требовании авторизации в приложении с помощью политики авторизации и отключении авторизации в подмножестве общедоступных конечных точек см. руководство Razor Pages OIDC. Дополнительные сведения о том, как это приложение защищает данные о погоде, см. в разделе «Безопасность данных в Blazor Web Appс помощью интерактивного автоматического рендеринга».

Эта версия статьи рассматривает реализацию OIDC с шаблоном Backend для Frontend (BFF). Измените селектор версии статьи на OIDC без шаблона BFF, если спецификация приложения не требует внедрения шаблона BFF.

Рассматривается следующая спецификация:

• Blazor Web App использует режим автоматической отрисовки с глобальной интерактивностью.
• Пользовательские службы, предоставляющие состояние аутентификации, используются сервером и клиентскими приложениями для фиксации состояния аутентификации пользователя и передачи между сервером и клиентом.
• Это приложение является отправной точкой для любого потока проверки подлинности OIDC. OIDC настраивается вручную в приложении и не зависит от Microsoft Entra ID или пакетов Microsoft Identity Web, также пример приложения не требует размещения в Microsoft Azure. Однако пример приложения можно использовать с Entra, размещать на Microsoft Identity Web и в Azure.
• Автоматическое обновление неинтерактивного токена.
• Шаблон серверной части внешнего интерфейса (BFF) используется .NET Aspire для обнаружения служб и YARP для прокси-запросов к конечной точке прогноза погоды в серверном приложении.
  • Веб-API на стороне сервера использует аутентификацию с помощью JWT-бирера для валидирования JWT-токенов, сохраненных Blazor Web App в процедуре входа cookie.
  • Aspire улучшает возможности создания облачных приложений .NET. Он предоставляет согласованный набор средств и шаблонов для создания и запуска распределенных приложений.
  • YARP (еще один обратный прокси-сервер) — это библиотека, используемая для создания обратного прокси-сервера.

Для получения дополнительной информации о .NET Aspire, см. Генеральная доступность .NET Aspire: упрощение разработки .NET Cloud-Native (май 2024 г.).

Предварительные требования

.NET Aspire требуется Visual Studio версии 17.10 или более поздней.

Пример приложения

Пример приложения состоит из пяти проектов:

• .NET Aspire:
  • Aspire.AppHost: используется для управления аспектами оркестрации высокого уровня приложения.
  • Aspire.ServiceDefaults: содержит конфигурации приложений по умолчанию .NET Aspire , которые можно расширить и настроить по мере необходимости.
• MinimalApiJwt: серверный веб API, содержащий пример конечной точки минимального API для данных о погоде.
• BlazorWebAppOidc: серверный проект объекта Blazor Web App.
• BlazorWebAppOidc.Client: клиентский проект объекта Blazor Web App.

Перейдите к образцам приложений, используя папку с последней версией в корневом каталоге репозитория, по следующей ссылке. Проекты находятся в папке BlazorWebAppOidcBff для .NET 8 или более поздней версии.

Просмотреть или скачать образец кода (описание загрузки)

.NET Aspire проектов

Дополнительные сведения об использовании .NET Aspire и .AppHost.ServiceDefaults проектах примера приложения см. в .NET Aspire документации.

Убедитесь, что вы выполнили предварительные условия для .NET Aspire. Дополнительные сведения см. в разделе "Предварительные требования " краткого руководства. Создание первого .NET Aspire приложения.

Пример приложения настраивает только небезопасный профиль запуска HTTP (http) для использования во время тестирования разработки. Дополнительные сведения, включая пример небезопасных и безопасных профилей параметров запуска, см. в разделе «Разрешить небезопасный транспорт» (.NET Aspire.NET Aspire документация).

Серверный Blazor Web App проект (BlazorWebAppOidc)

Проект BlazorWebAppOidc является серверным проектом Blazor Web App. Проект использует YARP для маршрутизации запросов к конечной точке прогноза погоды в проекте внутреннего веб-API (MinimalApiJwt) с access_token, хранящимся в аутентификации cookie.

Файл BlazorWebAppOidc.http можно использовать для тестирования запроса данных о погоде. Обратите внимание, что BlazorWebAppOidc проект должен выполняться для тестирования конечной точки, а конечная точка жестко закодирована в файл. Дополнительные сведения см. в статье "Использование HTTP-файлов в Visual Studio 2022".

Настройка

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

Примечание.

Для Microsoft Entra ID или Azure AD B2C вы можете использовать AddMicrosoftIdentityWebApp из Microsoft Identity Web (пакет Microsoft.Identity.Web NuGet, документация по API), которые добавляют как обработчики OIDC, так и Cookie проверку подлинности с соответствующими значениями по умолчанию. Пример приложения и руководство в этом разделе не используют Microsoft Identity Web. В руководстве показано, как настроить обработчик OIDC вручную для любого поставщика OIDC. Дополнительные сведения о реализации Microsoft Identity Web см. в связанных ресурсах.

Создайте секрет клиента

Предупреждение

Не сохраняйте секреты приложений, строка подключения, учетные данные, пароли, персональные идентификационные номера (ПИН-коды), частный код C#/.NET или закрытые ключи и токены в клиентском коде, который всегда небезопасн. В тестовых, промежуточных и рабочих средах код на стороне Blazor сервера и веб-API должен использовать безопасные методы аутентификации, которые избегают хранения учетных данных в коде проекта или конфигурационных файлах. Вне локального тестирования разработки рекомендуется избегать использования переменных среды для хранения конфиденциальных данных, так как переменные среды не являются наиболее безопасным подходом. Для локального тестирования разработки средство Secret Manager рекомендуется для защиты конфиденциальных данных. Дополнительные сведения см. в разделе "Безопасное обслуживание конфиденциальных данных и учетных данных".

Для локального тестирования разработки используйте средство Secret Manager для хранения секрета клиента серверного приложения под ключом Authentication:Schemes:MicrosoftOidc:ClientSecretконфигурации.

Примечание.

Если приложение использует идентификатор Microsoft Entra или Azure AD B2C, создайте секрет клиента в регистрации приложения в портале Entra или Azure (Управление>Сертификаты и секреты>Новый секрет клиента). Используйте значение нового секрета в следующем руководстве.

Образец приложения не был инициализирован для инструмента Secret Manager. Используйте командную оболочку, например командную оболочку PowerShell разработчика в Visual Studio, чтобы выполнить следующую команду. Перед выполнением команды с помощью команды cd измените каталог на директорию проекта сервера. Команда устанавливает идентификатор секретов пользователя (<UserSecretsId> в файле проекта приложения сервера):

dotnet user-secrets init

Выполните следующую команду, чтобы задать секрет клиента. Заполнитель {SECRET} — это секрет клиента, полученный из регистрации приложения:

dotnet user-secrets set "Authentication:Schemes:MicrosoftOidc:ClientSecret" "{SECRET}"

При использовании Visual Studio можно подтвердить, что секрет задан, щелкнув правой кнопкой мыши проект сервера в Обозреватель решений и выбрав "Управление секретами пользователей".

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

Следующая OpenIdConnectOptions конфигурация найдена в файле проекта Program при вызове AddOpenIdConnect:

• SignInScheme. Задает схему проверки подлинности, соответствующую ПО промежуточного слоя, ответственному за сохранение удостоверения пользователя после успешной проверки подлинности. Обработчик OIDC должен использовать схему входа, которая может сохранять учетные данные пользователя в запросах. Следующая строка представлена лишь для демонстрационных целей. Если опущено, DefaultSignInScheme используется в качестве резервного значения.

  oidcOptions.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
  

• Области для openid и profile (Scope) (необязательно): области openid и profile также настраиваются по умолчанию, так как они необходимы для работы обработчика OIDC, но их может потребоваться повторно добавить, если области включены в конфигурацию Authentication:Schemes:MicrosoftOidc:Scope. Общие рекомендации по настройке см. в разделе "Конфигурация" в ASP.NET Core и Blazor ASP.NET Core.

  oidcOptions.Scope.Add(OpenIdConnectScope.OpenIdProfile);
  

• SaveTokens: определяет, следует ли хранить маркеры доступа и обновления в AuthenticationProperties после успешной авторизации. Для проверки подлинности запросов на данные о погоде из проекта веб-API серверной части установлено значение true, равное MinimalApiJwt.

  oidcOptions.SaveTokens = true;
  

• Область для офлайн-доступа (Scope): Область offline_access необходима для получения маркера обновления.

  oidcOptions.Scope.Add(OpenIdConnectScope.OfflineAccess);
  

• Области доступа для получения данных о погоде из веб-API (Scope): это необходимо для проекта веб-API серверной составляющей (MinimalApiJwt) для проверки токена доступа с помощью Bearer JWT.

  oidcOptions.Scope.Add("{APP ID URI}/{API NAME}");
  

  Примечание.

  При использовании идентификатора Microsoft Entra область Weather.Get настраивается в портале Azure или Entra в разделе Expose an API.

  Пример:

  • URI идентификатора приложения ({APP ID URI}): https://{DIRECTORY NAME}.onmicrosoft.com/{CLIENT ID}
    • Имя каталога ({DIRECTORY NAME}): contoso
    • Идентификатор приложения (клиента) ({CLIENT ID}): 00001111-aaaa-2222-bbbb-3333cccc4444
  • Область, настроенная для данных о погоде (MinimalApiJwt{API NAME}):Weather.Get

  oidcOptions.Scope.Add("https://contoso.onmicrosoft.com/00001111-aaaa-2222-bbbb-3333cccc4444/Weather.Get");
  

  Приведённый выше пример относится к приложению, зарегистрированному в клиенте с типом AAD B2C. Если приложение зарегистрировано в клиенте ME-ID, URI идентификатора приложения отличается, поэтому область отличается.

  Пример:

  • URI идентификатора приложения ({APP ID URI}): api://{CLIENT ID} с идентификатором приложения (идентификатор клиента) ({CLIENT ID}): 00001111-aaaa-2222-bbbb-3333cccc4444
  • Настроена область для данных о погоде из MinimalApiJwt ({API NAME}): Weather.Get

  oidcOptions.Scope.Add("api://00001111-aaaa-2222-bbbb-3333cccc4444/Weather.Get");
  

• Authority и ClientId: задает уровень полномочий и идентификатор клиента для вызовов OIDC.

  oidcOptions.Authority = "{AUTHORITY}";
  oidcOptions.ClientId = "{CLIENT ID}";
  

  Пример:

  • Орган ({AUTHORITY}): https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/ (использует идентификатор клиента aaaabbbb-0000-cccc-1111-dddd2222eeee)
  • Идентификатор клиента ({CLIENT ID}): 00001111-aaaa-2222-bbbb-3333cccc4444

  oidcOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/";
  oidcOptions.ClientId = "00001111-aaaa-2222-bbbb-3333cccc4444";
  

  Пример для "common" домена Microsoft Azure:

  "Общий" полномочия должны использоваться для мультитенантных приложений. Вы также можете использовать полномочия "common" для однотенантных приложений, но требуется настраиваемый IssuerValidator, как показано далее в этом разделе.

  oidcOptions.Authority = "https://login.microsoftonline.com/common/v2.0/";
  

• ResponseType: настраивает обработчик OIDC только для выполнения потока кода авторизации. Неявные гранты и гибридные потоки являются ненужными в этом режиме. Обработчик OIDC автоматически запрашивает соответствующие маркеры с помощью кода, возвращаемого из конечной точки авторизации.

  oidcOptions.ResponseType = OpenIdConnectResponseType.Code;
  

  Примечание.

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

• MapInboundClaims и настройка NameClaimType и RoleClaimType: многие серверы name OIDC используют "name" и "ClaimTypes" вместо значений по умолчанию SOAP/WS-Fed. Если MapInboundClaims задано значение false, обработчик не выполняет сопоставления утверждений, а имена утверждений из JWT используются непосредственно приложением. В следующем примере тип требований к роли задан как "roles", что подходит для Microsoft Entra ID (ME-ID). Дополнительные сведения см. в документации поставщика удостоверений.

  Примечание.

  MapInboundClaims Необходимо задать значение false для большинства поставщиков OIDC, что предотвращает переименование утверждений.

  oidcOptions.MapInboundClaims = false;
  oidcOptions.TokenValidationParameters.NameClaimType = "name";
  oidcOptions.TokenValidationParameters.RoleClaimType = "roles";
  

• Конфигурация пути: Пути должны соответствовать URI перенаправления (путь обратного вызова для входа) и пути перенаправления после выхода (путь обратного вызова после выхода), которые были настроены при регистрации приложения у поставщика OIDC. В портале Azure пути настраиваются в области проверки подлинности регистрации приложения. Пути входа и выхода должны быть зарегистрированы как URI перенаправления. Значения по умолчанию: /signin-oidc и /signout-callback-oidc.

  Настройте путь обратного вызова для выхода из системы в настройках провайдера OIDC приложения. В следующем примере заполнитель {PORT} является портом приложения:

  https://localhost:{PORT}/signin-oidc

  Примечание.

  Порт не требуется для localhost адресов при использовании идентификатора Microsoft Entra. Большинству других поставщиков OIDC требуется правильный порт.

  • SignedOutCallbackPath (ключ конфигурации: "SignedOutCallbackPath"): путь запроса в рамках базового пути приложения, перехваченный обработчиком OIDC, куда агент пользователя сначала возвращается после выхода из поставщика удостоверений. Пример приложения не задает значение для пути, так как используется значение по умолчанию "/signout-callback-oidc". После перехвата запроса обработчик OIDC перенаправляется в SignedOutRedirectUri или RedirectUri, если указано.

    Настройте путь обратного вызова для выхода из системы в настройках провайдера OIDC приложения. В следующем примере заполнитель {PORT} является портом приложения:

    https://localhost:{PORT}/signout-callback-oidc

    Примечание.

    При использовании Microsoft Entra ID укажите путь в конфигурации платформы для записей URI перенаправления на портале Entra или Azure. Порт не требуется при использовании Entra для адресов "localhost". Большинству других поставщиков OIDC требуется правильный порт. Если вы не добавите URI пути обратного вызова после выхода из системы в регистрацию приложения в Entra, Entra откажется перенаправить пользователя обратно в приложение и просто попросит его закрыть окно браузера.

  • RemoteSignOutPath: запросы, полученные по этому пути, приводят к тому, что обработчик вызывает выход, используя схему выхода.

    В следующем примере заполнитель {PORT} является портом приложения:

    https://localhost/signout-oidc

    Примечание.

    При использовании идентификатора Microsoft Entra задайте URL-адрес выхода front-channel на портале Entra или Azure. Порт не требуется при использовании Entra для адресов "localhost". Большинству других поставщиков OIDC требуется правильный порт.

    oidcOptions.CallbackPath = new PathString("{PATH}");
    oidcOptions.SignedOutCallbackPath = new PathString("{PATH}");
    oidcOptions.RemoteSignOutPath = new PathString("{PATH}");
    

    Примеры (значения по умолчанию):

    oidcOptions.CallbackPath = new PathString("/signin-oidc");
    oidcOptions.SignedOutCallbackPath = new PathString("/signout-callback-oidc");
    oidcOptions.RemoteSignOutPath = new PathString("/signout-oidc");
    

• (Microsoft Azure только с "общей" конечной точкой) TokenValidationParameters.IssuerValidator: Многие поставщики OIDC работают с проверкой издателя по умолчанию, но нам нужно учитывать параметризованный идентификатор клиента ({TENANT ID}), который возвращает https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Дополнительные сведения см. в статье SecurityTokenInvalidIssuerException с OpenID Connect и конечной точке Azure AD "common" (AzureAD/azure-activedirectory-identitymodel-extensions-for-dotnet#1731).

  Только для приложений, использующих Microsoft Entra ID или Azure AD B2C с конечной точкой «common»:

  var microsoftIssuerValidator = AadIssuerValidator.GetAadIssuerValidator(oidcOptions.Authority);
  oidcOptions.TokenValidationParameters.IssuerValidator = microsoftIssuerValidator.Validate;
  

Пример кода приложения

Проверьте пример приложения для следующих функций:

• Автоматическое обновление токена без взаимодействия пользователя с помощью настраиваемого cookie средства обновления (CookieOidcRefresher.cs).
• Серверный проект вызывает AddAuthenticationStateSerialization, чтобы добавить поставщика состояния проверки подлинности на стороне сервера, который используется PersistentComponentState для передачи состояния проверки подлинности клиенту. Клиент вызывает AddAuthenticationStateDeserialization для десериализации и использования состояния аутентификации, переданного сервером. Состояние аутентификации зафиксировано на все время существования приложения WebAssembly.
• Запросы к Blazor Web App проксируются к проекту веб-API серверной части (MinimalApiJwt). MapForwarder Program В файле осуществляется прямая пересылка HTTP-запросов, которые соответствуют указанному шаблону, к определенному назначению, используя конфигурацию по умолчанию для исходящего запроса, настраиваемые преобразования и HTTP-клиент по умолчанию:
  • При обработке компонента Weather на сервере, компонент использует класс ServerWeatherForecaster для посредничества в запросе данных о погоде с использованием маркера доступа пользователя. IHttpContextAccessor.HttpContext определяет, доступен ли HttpContext для использования методом GetWeatherForecastAsync. Дополнительные сведения см. в компонентах ASP.NET CoreRazor.
  • При отрисовке компонента на клиенте компонент использует ClientWeatherForecaster реализацию службы, которая использует предустановленный HttpClient (в файле клиентского проекта Program) для выполнения вызова веб-API в серверном проекте. Минимальный API-эндпоинт (/weather-forecast), определенный в файле Program серверного проекта, преобразует запрос, используя маркер доступа пользователя, чтобы получить данные о погоде.

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

Клиентский Blazor Web App проект (BlazorWebAppOidc.Client)

Проект BlazorWebAppOidc.Client — это клиентский проект Blazor Web App.

Клиент вызывает AddAuthenticationStateDeserialization для десериализации и использования состояния аутентификации, переданного сервером. Состояние аутентификации зафиксировано на все время существования приложения WebAssembly.

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

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

Проект серверного веб-API (MinimalApiJwt)

Проект MinimalApiJwt — это внутренний веб-API для нескольких интерфейсных проектов. Проект настраивает минимальную конечную точку API для данных о погоде. Запросы из Blazor Web App серверного проекта (BlazorWebAppOidc) перенаправляются через прокси на проект MinimalApiJwt.

Настройка

Настройте проект в вызове JwtBearerOptions в файле проекта AddJwtBearer с помощью Program.

• Audience: задает аудиторию для любого полученного токена OIDC.

  jwtOptions.Audience = "{APP ID URI}";
  

  Примечание.

  При использовании Microsoft Entra ID необходимо сопоставить значение только с путем URI идентификатора приложения, настроенного при добавлении области Weather.Get в разделе Предоставление API на портале Azure или Entra.

  Пример:

  URI идентификатора приложения ({APP ID URI}): https://{DIRECTORY NAME}.onmicrosoft.com/{CLIENT ID}

  • Имя каталога ({DIRECTORY NAME}): contoso
  • Идентификатор приложения (клиента) ({CLIENT ID}): 00001111-aaaa-2222-bbbb-3333cccc4444

  jwtOptions.Audience = "https://contoso.onmicrosoft.com/00001111-aaaa-2222-bbbb-3333cccc4444";
  

  Приведённый выше пример относится к приложению, зарегистрированному в клиенте с типом AAD B2C. Если приложение зарегистрировано в клиенте ME-ID, URI идентификатора приложения отличается, поэтому аудитория отличается.

  Пример:

  URI идентификатора приложения ({APP ID URI}): api://{CLIENT ID} с идентификатором приложения (идентификатор клиента) ({CLIENT ID}): 00001111-aaaa-2222-bbbb-3333cccc4444

  jwtOptions.Audience = "api://00001111-aaaa-2222-bbbb-3333cccc4444";
  

• Authority: Устанавливает полномочия для выполнения вызовов OIDC. Соотнесите значение с Уполномоченным, настроенным для обработчика OIDC в BlazorWebAppOidc/Program.cs:

  jwtOptions.Authority = "{AUTHORITY}";
  

  Пример:

  Орган ({AUTHORITY}): https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/ (использует идентификатор клиента aaaabbbb-0000-cccc-1111-dddd2222eeee)

  jwtOptions.Authority = "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/";
  

  Приведённый выше пример относится к приложению, зарегистрированному в клиенте с типом AAD B2C. Если приложение зарегистрировано в клиенте ME-ID, авторитет должен соответствовать издателю (iss) JWT, возвращаемого поставщиком удостоверений.

  jwtOptions.Authority = "https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/";
  

Минимальный API для данных о погоде

Безопасная конечная точка данных прогнозов погоды в файле проекта Program.

app.MapGet("/weather-forecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
}).RequireAuthorization();

Метод RequireAuthorization расширения требует авторизации для определения маршрута. Для всех контроллеров, добавляющихся в проект, добавьте [Authorize] атрибут в контроллер или действие.

Перенаправление на домашнюю страницу при выходе

Компонент LogInOrOut (Layout/LogInOrOut.razor) задает скрытое поле для возвращаемого URL-адреса (ReturnUrl) для текущего URL-адреса (currentURL). Когда пользователь выходит из приложения, поставщик удостоверений возвращает пользователя на страницу, из которой они выошли. Если пользователь выходит из безопасной страницы, он возвращается на ту же безопасную страницу и отправляется обратно через процесс проверки подлинности. Этот поток проверки подлинности является разумным, если пользователям нужно регулярно изменять учетные записи.

В качестве альтернативы используйте следующий компонент LogInOrOut, который не предоставляет возвращаемый URL-адрес при выходе.

Layout/LogInOrOut.razor:

<div class="nav-item px-3">
    <AuthorizeView>
        <Authorized>
            <form action="authentication/logout" method="post">
                <AntiforgeryToken />
                <button type="submit" class="nav-link">
                    <span class="bi bi-arrow-bar-left-nav-menu" aria-hidden="true">
                    </span> Logout @context.User.Identity?.Name
                </button>
            </form>
        </Authorized>
        <NotAuthorized>
            <a class="nav-link" href="authentication/login">
                <span class="bi bi-person-badge-nav-menu" aria-hidden="true"></span> 
                Login
            </a>
        </NotAuthorized>
    </AuthorizeView>
</div>

Обновление токена

Реализация пользовательского cookie обновления (CookieOidcRefresher.cs) автоматически обновляет утверждения пользователя при истечении их срока действия. Текущая реализация ожидает получения ID токена с точки окончания токенов в обмен на маркер обновления. Затем утверждения в этом токене идентификатора используются для замены утверждений пользователя.

Пример реализации не включает код для запроса утверждений из конечной точки UserInfo при обновлении токена. Дополнительные сведения см. в BlazorWebAppOidc AddOpenIdConnect with GetClaimsFromUserInfoEndpoint = true doesn't propogate role claims to client (dotnet/aspnetcore #58826).

Примечание.

Некоторые поставщики удостоверений возвращают токен доступа только при использовании токена обновления. CookieOidcRefresher можно обновить, добавив дополнительную логику, чтобы и дальше использовать предыдущий набор утверждений, сохранённых в системе аутентификации cookie, или использовать токен доступа для запроса утверждений из API точки UserInfo.

Криптографический элемент nonce

Nonce — это строковое значение, которое связывает сеанс клиента с идентификационным токеном, чтобы предотвратить атаки повторного воспроизведения.

Если при разработке и тестировании аутентификации возникает ошибка одноразового токена (nonce error), используйте новый сеанс браузера в режиме InPrivate/инкогнито для каждого прогона теста, независимо от того, насколько незначительны изменения в приложении или учетной записи тестировщика, так как устаревшие cookie данные могут привести к ошибке одноразового токена. Дополнительные сведения см. в разделе "Файлы cookie" и "Данные сайта".

Нонc не требуется и не используется, когда маркер обновления обменивается на новый маркер доступа. В примере приложения CookieOidcRefresher (CookieOidcRefresher.cs) намеренно задает значение OpenIdConnectProtocolValidator.RequireNonce для false.

Роли приложений для приложений, не зарегистрированных в Microsoft Entra (ME-ID)

Этот раздел относится к приложениям, которые не используют Microsoft Entra ID (ME-ID) в качестве поставщика удостоверений (). Сведения о приложениях, зарегистрированных с помощью ME-ID, см. в разделе "Роли приложений, зарегистрированных в Microsoft Entra (ME-ID).

Настройте тип утверждения роли (TokenValidationParameters.RoleClaimType) в OpenIdConnectOptionsProgram.cs:

oidcOptions.TokenValidationParameters.RoleClaimType = "{ROLE CLAIM TYPE}";

Для многих поставщиков удостоверений OIDC тип атрибута роли role. Проверьте документацию удостоверяющего центра для корректного значения.

Замените UserInfo класс в BlazorWebAppOidc.Client проекте следующим классом.

UserInfo.cs:

using Microsoft.AspNetCore.Components.WebAssembly.Authentication;
using System.Security.Claims;

namespace BlazorWebAppOidc.Client;

// Add properties to this class and update the server and client 
// AuthenticationStateProviders to expose more information about 
// the authenticated user to the client.
public sealed class UserInfo
{
    public required string UserId { get; init; }
    public required string Name { get; init; }
    public required string[] Roles { get; init; }

    public const string UserIdClaimType = "sub";
    public const string NameClaimType = "name";
    private const string RoleClaimType = "role";

    public static UserInfo FromClaimsPrincipal(ClaimsPrincipal principal) =>
        new()
        {
            UserId = GetRequiredClaim(principal, UserIdClaimType),
            Name = GetRequiredClaim(principal, NameClaimType),
            Roles = principal.FindAll(RoleClaimType).Select(c => c.Value)
                .ToArray(),
        };

    public ClaimsPrincipal ToClaimsPrincipal() =>
        new(new ClaimsIdentity(
            Roles.Select(role => new Claim(RoleClaimType, role))
                .Concat([
                    new Claim(UserIdClaimType, UserId),
                    new Claim(NameClaimType, Name),
                ]),
            authenticationType: nameof(UserInfo),
            nameType: NameClaimType,
            roleType: RoleClaimType));

    private static string GetRequiredClaim(ClaimsPrincipal principal,
        string claimType) =>
            principal.FindFirst(claimType)?.Value ??
            throw new InvalidOperationException(
                $"Could not find required '{claimType}' claim.");
}

На этом этапе Razor компоненты могут принимать авторизацию на основе ролей и политик. Роли приложения отображаются в role утверждениях, по одному утверждению для каждой роли.

Роли приложений для приложений, зарегистрированных в Microsoft Entra (ME-ID)

Используйте инструкции в этом разделе для реализации ролей приложений, групп безопасности ME-ID и встроенных ролей администратора ME-ID для приложений с помощью идентификатора Microsoft Entra ID (ME-ID).

Описанный в этом разделе подход настраивает ME-ID для отправки групп и ролей в заголовке аутентификации cookie. Если пользователи входят только в несколько групп безопасности и ролей, предложенный ниже подход должен работать для большинства хостинговых платформ без возникновения проблемы слишком длинных заголовков, например, при использовании хостинга IIS с ограничением длины заголовка по умолчанию 16 КБ (MaxRequestBytes). Если длина заголовка является проблемой из-за высокого уровня членства в группе или роли, мы рекомендуем не следовать инструкциям в этом разделе в пользу реализации Microsoft Graph для получения групп и ролей пользователя из ME-ID отдельно, подход, который не расширяет размер проверки подлинности cookie. Дополнительные сведения см. в разделе "Недопустимый запрос — слишком длинный запрос — сервер IIS" (dotnet/aspnetcore #57545).

Настройте тип утверждения роли (TokenValidationParameters.RoleClaimType) в OpenIdConnectOptionsProgram.cs. Задайте для параметра значение roles:

oidcOptions.TokenValidationParameters.RoleClaimType = "roles";

Хотя вы не можете назначать роли группам без учетной записи ME-ID Premium, вы можете назначать роли пользователям и получать утверждения ролей для пользователей со стандартной учетной записью Azure. Для использования рекомендаций в этом разделе не нужна учетная запись ME-ID Premium.

При работе с каталогом по умолчанию следуйте инструкциям в разделе «Добавление ролей приложению и их получение в токене» (документация по ME-ID) для настройки и назначения ролей. Если вы не работаете с каталогом по умолчанию, измените манифест приложения в портале Azure, чтобы вручную установить роли приложения в записи манифеста appRoles. Дополнительные сведения см. в разделе "Настройка утверждения роли" (документация по ME-ID).

Группы безопасности Azure пользователя приходят в утверждения, а встроенные назначения ролей администратора ME-ID пользователя приходят в хорошо известные идентификаторы () утверждений. Значения обоих типов заявок представляют собой идентификаторы GUID. При получении приложением эти утверждения можно использовать для установления авторизации роли и политики в Razor компонентах.

В манифесте приложения в портале Azure установите значение для атрибута groupMembershipClaimsAll. Значение All приводит к тому, что ME-ID отправляет все группы безопасности и распределения (groups утверждения) и роли (wids утверждения) вошедшего в систему пользователя. Чтобы задать groupMembershipClaims атрибут, выполните следующие действия.

1. Откройте регистрацию приложения в портал Azure.
2. Выберите Управление>Манифест на панели сбоку.
3. Найдите атрибут groupMembershipClaims.
4. Установите значение на All ("groupMembershipClaims": "All").
5. Выберите кнопку Сохранить.

Замените UserInfo класс в BlazorWebAppOidc.Client проекте следующим классом.

UserInfo.cs:

using Microsoft.AspNetCore.Components.WebAssembly.Authentication;
using System.Security.Claims;

namespace BlazorWebAppOidc.Client;

// Add properties to this class and update the server and client 
// AuthenticationStateProviders to expose more information about 
// the authenticated user to the client.
public sealed class UserInfo
{
    public required string UserId { get; init; }
    public required string Name { get; init; }
    public required string[] Roles { get; init; }
    public required string[] Groups { get; init; }
    public required string[] Wids { get; init; }

    public const string UserIdClaimType = "sub";
    public const string NameClaimType = "name";
    private const string RoleClaimType = "roles";
    private const string GroupsClaimType = "groups";
    private const string WidsClaimType = "wids";

    public static UserInfo FromClaimsPrincipal(ClaimsPrincipal principal) =>
        new()
        {
            UserId = GetRequiredClaim(principal, UserIdClaimType),
            Name = GetRequiredClaim(principal, NameClaimType),
            Roles = principal.FindAll(RoleClaimType).Select(c => c.Value)
                .ToArray(),
            Groups = principal.FindAll(GroupsClaimType).Select(c => c.Value)
                .ToArray(),
            Wids = principal.FindAll(WidsClaimType).Select(c => c.Value)
                .ToArray(),
        };

    public ClaimsPrincipal ToClaimsPrincipal() =>
        new(new ClaimsIdentity(
            Roles.Select(role => new Claim(RoleClaimType, role))
                .Concat(Groups.Select(role => new Claim(GroupsClaimType, role)))
                .Concat(Wids.Select(role => new Claim(WidsClaimType, role)))
                .Concat([
                    new Claim(UserIdClaimType, UserId),
                    new Claim(NameClaimType, Name),
                ]),
            authenticationType: nameof(UserInfo),
            nameType: NameClaimType,
            roleType: RoleClaimType));

    private static string GetRequiredClaim(ClaimsPrincipal principal,
        string claimType) =>
            principal.FindFirst(claimType)?.Value ??
            throw new InvalidOperationException(
                $"Could not find required '{claimType}' claim.");
}

На этом этапе Razor компоненты могут принимать авторизацию на основе ролей и политик:

• Роли приложения отображаются в roles утверждениях, по одному утверждению для каждой роли.
• Группы безопасности отображаются в groups утверждениях, по одному утверждению для каждой группы. Идентификаторы групп безопасности отображаются в портале Azure при создании группы безопасности и перечисляются при выборе Identity>>>.
• Встроенные роли администратора ME-ID отображаются в wids утверждениях, по одному утверждению для каждой роли. Утверждение wids со значением b79fbf4d-3ef9-4689-8143-76b194e85509 всегда отправляется ME-ID для негостевых учетных записей арендатора и не ссылается на роль администратора. Идентификаторы ролей администратора (идентификаторы ролей-шаблонов) отображаются в портале Azure при выборе Роли и администраторы, а затем многоточия (>) Описание для указанной роли. Идентификаторы шаблонов ролей также перечислены в встроенных ролях Microsoft Entra (документация по Entra).

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

Логирование

Серверное приложение — это стандартное приложение ASP.NET Core. Ознакомьтесь с руководством по ведению журнала ASP.NET Core, чтобы включить более низкий уровень ведения журнала в серверном приложении.

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

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

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

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

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

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

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

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

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

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

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

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

  Указанные выше форумы не принадлежат корпорации Майкрософт и не управляются ею.

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

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

  info: Авторизация не удалась Microsoft.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.
  • Нажмите кнопку Добавить.
  • Укажите путь к браузеру в поле Программа. Следующие пути к исполняемым файлам являются типичными расположениями установки для Windows 10. Если браузер установлен в другом расположении или вы используете операционную систему, отличную от Windows 10, укажите путь к исполняемому файлу браузера.
    • Microsoft Edge: C:\Program Files (x86)\Microsoft\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 Core SDK на машине разработки или изменения версий пакетов в самой программе. В некоторых случаях при выполнении крупных обновлений несогласованные пакеты могут нарушить работу приложения. Большинство этих проблем можно исправить следующим образом:

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

Примечание.

Использование версий пакета, несовместимых с требуемой платформой приложения, не поддерживается. Чтобы получить информацию о пакете, используйте NuGet Gallery.

Запуск серверного приложения

При тестировании и устранении Blazor Web Appнеполадок убедитесь, что приложение запущено из серверного проекта.

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

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

UserClaims.razor:

@page "/user-claims"
@using System.Security.Claims
@using Microsoft.AspNetCore.Authorization
@attribute [Authorize]

<PageTitle>User Claims</PageTitle>

<h1>User Claims</h1>

@if (claims.Any())
{
    <ul>
        @foreach (var claim in claims)
        {
            <li><b>@claim.Type:</b> @claim.Value</li>
        }
    </ul>
}

@code {
    private IEnumerable<Claim> claims = Enumerable.Empty<Claim>();

    [CascadingParameter]
    private Task<AuthenticationState>? AuthState { get; set; }

    protected override async Task OnInitializedAsync()
    {
        if (AuthState == null)
        {
            return;
        }

        var authState = await AuthState;
        claims = authState.User.Claims;
    }
}

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

• AzureAD/microsoft-identity-web Репозиторий GitHub: полезное руководство по реализации Microsoft Web для Microsoft Entra ID и Azure Active Directory B2C в приложениях ASP.NET Core, включая ссылки на примеры приложений и соответствующую документацию Azure. В настоящее время Blazor Web App не упоминаются прямо в документации Azure, но настройка и конфигурация Blazor Web App для ME-ID и размещения Azure такая же, как для любого веб-приложения ASP.NET Core.
• AuthenticationStateProvider служба
• Управление состоянием проверки подлинности в Blazor Web Apps
• Токен обновления во время выполнения http-запроса в Blazor интерактивном сервере с OIDC (dotnet/aspnetcore #55213)
• Защита данных в Blazor Web Appс помощью интерактивного автоматического рендеринга