Как использовать Identity для защиты серверной части веб-API для SPA

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

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

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

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

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

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

Установка пакетов 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"
  }
  

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

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

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

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

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

Тестирование с помощью клиентов, которые не являются браузерами

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

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

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

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

  request.SetBrowserRequestCredential(BrowserRequestCredentials.Include);
  

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

Мы рекомендуем использовать файлы cookie в приложениях на основе браузера, так как по умолчанию браузер автоматически обрабатывает их без предоставления им доступа к JavaScript.

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

Маркеры не являются стандартными JSON Web Tokens (JWTs). Использование пользовательских значков намеренно, так как встроенный Identity API в основном предназначен для простых сценариев. Параметр токена не предназначен для полноценного поставщика услуг идентификации или сервера токенов, а вместо этого служит альтернативой варианту 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();

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

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 /resetPassword
• POST /manage/2fa
• GET /manage/info
• POST /manage/info

Используйте конечную точку POST /register

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

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

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

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

Используйте конечную точку POST /login

В теле запроса Email и Password обязательны. Если включена двухфакторная проверка подлинности (2FA), требуется либо TwoFactorCode, либо TwoFactorRecoveryCode. Если 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, чтобы установить RequireConfirmedEmail на true, и добавьте класс, который реализует IEmailSender в DI-контейнер. Например:

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

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

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

Identity предоставляет текст по умолчанию для других сообщений электронной почты, которые необходимо отправить, например, для двухфакторной аутентификации и сброса пароля. Чтобы настроить эти сообщения электронной почты, предоставьте пользовательскую реализацию 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 , отправив пустой объект JSON ({}) в тексте запроса.

• Тело ответа содержит 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. Коды восстановления используются для входа, если приложение для аутентификации недоступно. Пример текста ответа после успешного включения 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"
}

Если у пользователя нет доступа к приложению аутентификатор, войдите в систему, вызвав /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