Как защитить Identity серверную часть веб-API для spAs

ASP.NET Core Identity предоставляет API-интерфейсы, которые обрабатывают проверку подлинности, авторизацию и управление удостоверениями. API позволяют защитить конечные точки серверной части веб-API с cookieпомощью проверки подлинности на основе. Существует параметр на основе токенов для клиентов, которые не могут использовать cookieего.

В этой статье показано, как защитить Identity серверную часть веб-API для таких служб, как Angular, React и Vue. Те же интерфейсы API серверной части можно использовать для защиты Blazor WebAssembly приложений.

Необходимые компоненты

Действия, описанные в этой статье, добавляют проверку подлинности и авторизацию в приложение ASP.NET Core Web API, которое:

• Не настроено для проверки подлинности.
• Целевые объекты или более поздние net8.0 версии.
• Может быть минимальным API или API на основе контроллера.

Некоторые инструкции по тестированию в этой статье используют пользовательский интерфейс Swagger, включенный в шаблон проекта. Пользовательский интерфейс Swagger не требуется использовать Identity с серверной частью веб-API.

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

Установите следующие пакеты NuGet:

• Microsoft.AspNetCore.Identity.EntityFrameworkCore — позволяет Identity работать с Entity Framework Core (EF Core).
• Тот, который позволяет EF Core работать с базой данных, например одним из следующих пакетов:
  • Microsoft.EntityFrameworkCore.SqlServer или
  • Microsoft.EntityFrameworkCore.Sqlite или
  • Microsoft.EntityFrameworkCore.InMemory.

Чтобы быстро приступить к работе, используйте базу данных в памяти.

Измените базу данных позже на SQLite или SQL Server, чтобы сохранить данные пользователей между сеансами при тестировании или использовании в рабочей среде. Это приводит к некоторой сложности по сравнению с памятью, так как требуется, чтобы база данных была создана с помощью миграций, как показано в руководстве по началу EF Core работы.

Установите эти пакеты с помощью диспетчера пакетов NuGet в Visual Studio или команды dotnet add package CLI.

Создайте IdentityDbContext.

Добавление класса с именем ApplicationDbContext , наследуемого от IdentityDbContext<TUser>:

using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;

public class ApplicationDbContext : IdentityDbContext<IdentityUser>
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) :
        base(options)
    { }
}

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

При добавлении кода, показанного на этих шагах, добавьте одну или несколько следующих using директив.

using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;

Настройка контекста EF Core

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

builder.Services.AddDbContext<ApplicationDbContext>(
    options => options.UseInMemoryDatabase("AppDb"));

Чтобы сохранить данные пользователей между сеансами при тестировании или использовании в рабочей среде, измените базу данных позже на SQLite или SQL Server.

Добавление Identity служб в контейнер

После вызова WebApplication.CreateBuilder(args)вызов вызовите AddAuthorization добавление служб в контейнер внедрения зависимостей (DI):

builder.Services.AddAuthorization();

Активация Identity API

После вызова, вызова WebApplication.CreateBuilder(args)AddIdentityApiEndpoints<TUser>(IServiceCollection) и AddEntityFrameworkStores<TContext>(IdentityBuilder).

builder.Services.AddIdentityApiEndpoints<IdentityUser>()
    .AddEntityFrameworkStores<ApplicationDbContext>();

По умолчанию активируются оба cookieмаркера и частные маркеры. Cookieмаркеры выдаются при входе, если useCookies параметр строки запроса в конечной точке trueвхода.

Маршруты карты Identity

После вызова builder.Build()вызовите MapIdentityApi<TUser>(IEndpointRouteBuilder) для сопоставления Identity конечных точек:

app.MapIdentityApi<IdentityUser>();

Защита выбранных конечных точек

Чтобы защитить конечную точку, используйте RequireAuthorization метод расширения для Map{Method} вызова, определяющего маршрут. Например:

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

Метод RequireAuthorization также можно использовать для:

• Защита конечных точек пользовательского интерфейса Swagger, как показано в следующем примере:

  app.MapSwagger().RequireAuthorization();
  

• Защита с определенным утверждением или разрешением, как показано в следующем примере:

  .RequireAuthorization("Admin");
  

В проекте веб-API на основе контроллера защита конечных точек путем применения атрибута [Authorize] к контроллеру или действию.

Проверка API

Быстрый способ проверки подлинности — использовать базу данных в памяти и пользовательский интерфейс Swagger, включенный в шаблон проекта. Ниже показано, как протестировать API с помощью пользовательского интерфейса Swagger. Убедитесь, что конечные точки пользовательского интерфейса Swagger не защищены.

Попытка доступа к защищенной конечной точке

• Запустите приложение и перейдите к пользовательскому интерфейсу Swagger.
• Разверните безопасную конечную точку, например /weatherforecast в проекте, созданном шаблоном веб-API.
• Выберите Опробовать.
• Выберите Выполнить. Ответ имеет значение 401 - not authorized.

Проверка регистрации

• Разверните /register и выберите "Попробовать".

• В разделе "Параметры" пользовательского интерфейса показан пример текста запроса:

  {
    "email": "string",
    "password": "string"
  }
  

• Замените "string" допустимым адресом электронной почты и паролем, а затем нажмите кнопку "Выполнить".

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

  • Буква в верхнем регистре
  • Буква в нижнем регистре
  • Числовое числовой цифры
  • Неэлементный символ

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

  {
    "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
      "PasswordTooShort": [
        "Passwords must be at least 6 characters."
      ],
      "PasswordRequiresNonAlphanumeric": [
        "Passwords must have at least one non alphanumeric character."
      ],
      "PasswordRequiresDigit": [
        "Passwords must have at least one digit ('0'-'9')."
      ],
      "PasswordRequiresLower": [
        "Passwords must have at least one lowercase ('a'-'z')."
      ]
    }
  }
  

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

  Успешная регистрация приводит к ответу 200 - OK .

Проверка имени входа

• Разверните /login и выберите " Попробовать". В тексте запроса примера показаны два дополнительных параметра:

  {
    "email": "string",
    "password": "string",
    "twoFactorCode": "string",
    "twoFactorRecoveryCode": "string"
  }
  

  Дополнительные JSсвойства ON не требуются для этого примера и могут быть удалены. Задайте для параметра useCookies значение true.

• Замените "string" адресом электронной почты и паролем, используемым для регистрации, а затем нажмите кнопку "Выполнить".

  Успешное имя входа приводит к ответу 200 - OK с заголовком cookie ответа.

Повторное тестирование защищенной конечной точки

После успешного входа повторно запустите безопасную конечную точку. Проверка подлинности cookie автоматически отправляется с запросом, и конечная точка авторизована. Cookie-основанная проверка подлинности безопасно встроена в браузер и "просто работает".

Тестирование с помощью клиентов nonbrowser

Некоторые веб-клиенты могут не включать cookieв заголовок по умолчанию:

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

• API JavaScript fetch по умолчанию не включает в себя cookie. Включите их, задав credentials значение include в параметрах.

• Выполняющийся HttpClient в Blazor WebAssembly приложении должен HttpRequestMessage включать учетные данные, как показано в следующем примере:

  request.SetBrowserRequestCredential(BrowserRequestCredentials.Include);
  

Использование проверки подлинности на основе маркеров безопасности

Для клиентов, которые не поддерживаются cookie, API входа предоставляет параметр для запроса маркеров. Выдается пользовательский маркер (который является владельцем платформы удостоверений ASP.NET Core), который можно использовать для проверки подлинности последующих запросов. Маркер передается в заголовке Authorization в качестве маркера носителя. Также предоставляется маркер обновления. Этот маркер позволяет приложению запрашивать новый маркер, когда срок действия старого маркера истекает без повторного входа пользователя.

Маркеры не являются стандартными JSвеб-токенами ON (JWTs). Использование пользовательских маркеров намеренно, так как встроенный Identity API предназначен в первую очередь для простых сценариев. Параметр токена не предназначен для полнофункционированного поставщика службы удостоверений или сервера маркеров, а вместо этого альтернативой cookie для клиентов, которые не могут использовать cookieего.

Чтобы использовать проверку подлинности на основе маркеров, задайте useCookies параметр строки запроса для false вызова конечной /login точки. Маркеры используют схему проверки подлинности носителя . С помощью маркера, возвращаемого из вызова /login, последующие вызовы защищенных конечных точек должны добавить заголовок Authorization: Bearer <token> , где <token> находится маркер доступа. Дополнительные сведения см. в разделе "Использование конечной POST /login точки " далее в этой статье.

Выход

Чтобы предоставить пользователю способ выхода из системы, определите конечную /logout точку, как показано в следующем примере:

app.MapPost("/logout", async (SignInManager<IdentityUser> signInManager,
    [FromBody] object empty) =>
{
    if (empty != null)
    {
        await signInManager.SignOutAsync();
        return Results.Ok();
    }
    return Results.Unauthorized();
})
.WithOpenApi()
.RequireAuthorization();

Укажите пустой JSобъект ON ({}) в тексте запроса при вызове этой конечной точки. Следующий код является примером вызова конечной точки выхода:

public signOut() {
  return this.http.post('/logout', {}, {
    withCredentials: true,
    observe: 'response',
    responseType: 'text'

Конечные MapIdentityApi<TUser> точки

Вызов для MapIdentityApi<TUser> добавления следующих конечных точек в приложение:

• POST /register
• POST /login
• POST /refresh
• GET /confirmEmail
• POST /resendConfirmationEmail
• POST /forgotPassword
• POST /reset Password
• POST /manage/2fa
• GET /manage/info
• POST /manage/info

Использование конечной POST /register точки

Текст запроса должен иметь Email и Password свойства:

{
  "email": "string",
  "password": "string",
}

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

• Тестирование регистрации ранее в этой статье.
• RegisterRequest.

Использование конечной POST /login точки

В тексте Email запроса и Password обязательны. Если включена TwoFactorCodeTwoFactorRecoveryCode двухфакторная проверка подлинности (2FA), либо требуется. Если 2FA не включена, опустите оба twoFactorCode и twoFactorRecoveryCode. Дополнительные сведения см. в разделе "Использование конечной POST /manage/2fa точки " далее в этой статье.

Вот пример текста запроса с 2FA не включен:

{
  "email": "string",
  "password": "string"
}

Ниже приведены примеры текста запроса с включенным 2FA:

• {
    "email": "string",
    "password": "string",
    "twoFactorCode": "string",
  }
  

• {
    "email": "string",
    "password": "string",
    "twoFactorRecoveryCode": "string"
  }
  

Конечная точка ожидает параметр строки запроса:

• useCookies — Задано значение true для cookieпроверки подлинности на основе. Задайте значение false или опущено для проверки подлинности на основе маркеров.

Дополнительные сведения о cookieпроверке подлинности на основе см. в разделе "Проверка входа" ранее в этой статье.

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

Если useCookies задано false или опущено, проверка подлинности на основе маркеров включена. Текст ответа содержит следующие свойства:

{
  "tokenType": "string",
  "accessToken": "string",
  "expiresIn": 0,
  "refreshToken": "string"
}

Дополнительные сведения об этих свойствах см. в разделе AccessTokenResponse.

Поместите маркер доступа в заголовок, чтобы выполнить прошедшие проверку подлинности запросы, как показано в следующем примере.

Authorization: Bearer {access token}

Когда срок действия маркера доступа истекает, вызовите конечную точку /refresh .

Использование конечной POST /refresh точки

Для использования только с проверкой подлинности на основе маркеров. Получает новый маркер доступа без повторного входа пользователя. Вызовите эту конечную точку, когда срок действия маркера доступа истекает.

Текст запроса содержит только текст RefreshTokenзапроса. Ниже приведен пример текста запроса:

{
  "refreshToken": "string"
}

Если вызов выполнен успешно, текст ответа является новым AccessTokenResponse, как показано в следующем примере:

{
  "tokenType": "string",
  "accessToken": "string",
  "expiresIn": 0,
  "refreshToken": "string"
}

Использование конечной GET /confirmEmail точки

Если Identity настроено подтверждение электронной почты, успешный вызов /register конечной точки отправляет сообщение электронной почты, содержащее ссылку на /confirmEmail конечную точку. Ссылка содержит следующие параметры строки запроса:

• userId
• code
• changedEmail — включается только в том случае, если пользователь изменил адрес электронной почты во время регистрации.

Identity предоставляет текст по умолчанию для сообщения электронной почты подтверждения. По умолчанию тема электронной почты — "Подтверждение электронной почты", а текст электронной почты выглядит следующим образом:

 Please confirm your account by <a href='https://contoso.com/confirmEmail?userId={user ID}&code={generated code}&changedEmail={new email address}'>clicking here</a>.

RequireConfirmedEmail Если для свойства задано trueзначение, пользователь не сможет войти, пока адрес электронной почты не будет подтвержден, щелкнув ссылку в сообщении электронной почты. Конечная /confirmEmail точка:

• Подтверждает адрес электронной почты и позволяет пользователю войти в систему.
• Возвращает текст "Спасибо за подтверждение электронной почты".

Чтобы настроить Identity подтверждение электронной почты, добавьте код для Program.cs задания RequireConfirmedEmailtrue и добавьте класс, реализующий IEmailSender контейнер DI. Например:

builder.Services.Configure<IdentityOptions>(options =>
{
    options.SignIn.RequireConfirmedEmail = true;
});

builder.Services.AddTransient<IEmailSender, EmailSender>();

Дополнительные сведения см. в разделе "Подтверждение учетной записи" и восстановление паролей в ASP.NET Core.

Identity предоставляет текст по умолчанию для других сообщений электронной почты, которые необходимо отправить, например для сброса 2FA и пароля. Чтобы настроить эти сообщения электронной почты, предоставьте пользовательскую реализацию IEmailSender интерфейса. В предыдущем примере — это класс, EmailSender реализующий IEmailSender. Дополнительные сведения, включая пример класса, реализующего IEmailSender, см. в разделе "Подтверждение учетной записи" и восстановление паролей в ASP.NET Core.

Использование конечной POST /resendConfirmationEmail точки

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

Текст запроса содержит только текст Emailзапроса. Ниже приведен пример текста запроса:

{
  "email": "string"
}

Дополнительные сведения см. в разделе "Использование конечной GET /confirmEmail точки " ранее в этой статье.

Использование конечной POST /forgotPassword точки

Создает сообщение электронной почты, содержащее код сброса пароля. Отправьте этот код /resetPassword в новый пароль.

Текст запроса содержит только текст Emailзапроса. Приведем пример:

{
  "email": "string"
}

Сведения о том, как включить Identity отправку сообщений электронной почты, см. в разделе "Использование конечной GET /confirmEmail точки".

Использование конечной POST /resetPassword точки

Вызовите эту конечную точку после получения кода сброса, вызвав конечную точку /forgotPassword .

Для текста запроса требуется Email, ResetCodeи NewPassword. Приведем пример:

{
  "email": "string",
  "resetCode": "string",
  "newPassword": "string"
}

Использование конечной POST /manage/2fa точки

Настраивает двухфакторную проверку подлинности (2FA) для пользователя. Если включена 2FA, для успешного входа требуется код, созданный приложением authenticator, в дополнение к адресу электронной почты и паролю.

Включить 2FA

Чтобы включить 2FA для текущего пользователя, прошедшего проверку подлинности, выполните следующие действия.

• Вызовите конечную точку /manage/2fa , отправив пустой JSобъект ON ({}) в тексте запроса.

• Текст отклика SharedKey предоставляет ряд других свойств, которые не нужны на данный момент. Общий ключ используется для настройки приложения authenticator. Пример текста отклика:

  {
    "sharedKey": "string",
    "recoveryCodesLeft": 0,
    "recoveryCodes": null,
    "isTwoFactorEnabled": false,
    "isMachineRemembered": false
  }
  

• Используйте общий ключ, чтобы получить одноразовый пароль на основе времени (TOTP). Дополнительные сведения см. в разделе "Включение создания QR-кода" для приложений проверки подлинности TOTP в ASP.NET Core.

• Вызовите конечную точку /manage/2fa , отправив TOTP и "enable": true в тексте запроса. Например:

  {
    "enable": true,
    "twoFactorCode": "string"
  }
  

• Текст ответа подтверждает, что IsTwoFactorEnabled имеет значение true и предоставляет RecoveryCodes. Код восстановления используются для входа, если приложение authenticator недоступно. Пример текста ответа после успешного включения 2FA:

  {
    "sharedKey": "string",
    "recoveryCodesLeft": 10,
    "recoveryCodes": [
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string",
      "string"
    ],
    "isTwoFactorEnabled": true,
    "isMachineRemembered": false
  }
  

Вход с помощью 2FA

Вызовите конечную точку /login , отправив адрес электронной почты, пароль и TOTP в тексте запроса. Например:

{
  "email": "string",
  "password": "string",
  "twoFactorCode": "string"
}

Если у пользователя нет доступа к приложению authenticator, войдите в систему, вызвав /login конечную точку с одним из код восстановления, предоставленных при включении 2FA. Текст запроса будет выглядеть как в следующем примере.

{
  "email": "string",
  "password": "string",
  "twoFactorRecoveryCode": "string"
}

Сброс код восстановления

Чтобы получить новую коллекцию код восстановления, вызовите эту конечную точку с ResetRecoveryCodes заданным значением true. Ниже приведен пример текста запроса:

{
  "resetRecoveryCodes": true
}

Сброс общего ключа

Чтобы получить новый случайный общий ключ, вызовите эту конечную точку с ResetSharedKey заданным значением true. Ниже приведен пример текста запроса:

{
  "resetSharedKey": true
}

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

Забыли компьютер

Чтобы очистить cookie флаг "запомнить меня", если он присутствует, вызовите эту конечную точку с ForgetMachine заданным значением true. Ниже приведен пример текста запроса:

{
  "forgetMachine": true
}

Эта конечная точка не влияет на проверку подлинности на основе маркеров.

Использование конечной GET /manage/info точки

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

Запрос не требует каких-либо параметров. Текст ответа содержит Email свойства и IsEmailConfirmed свойства, как показано в следующем примере:

{
  "email": "string",
  "isEmailConfirmed": true
}

Использование конечной POST /manage/info точки

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

{
  "newEmail": "string",
  "newPassword": "string",
  "oldPassword": "string"
}

Вот пример текста ответа:

{
  "email": "string",
  "isEmailConfirmed": false
}

См. также

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

• Выбор решения по управлению удостоверениями
• Identity решения по управлению веб-приложениями .NET
• Простая авторизация в ASP.NET Core
• Добавление, скачивание и удаление пользовательских данных Identity в проект ASP.NET Core
• Создание приложения ASP.NET Core с защитой данных пользователя с помощью авторизации
• Подтверждение учетной записи и восстановление пароля в ASP.NET Core
• Включение создания QR-кодов для приложений проверки подлинности TOTP в ASP.NET Core
• Пример серверной части веб-API для SPAs Http-файл показывает проверку подлинности на основе токенов. Например:
  • Не задано useCookies
  • Использует заголовок авторизации для передачи маркера
  • Показывает обновление для расширения сеанса без повторного входа пользователя
• Пример приложения Angular, которое используется Identity для защиты серверной части веб-API