Українська
Сервіс автентифікації
Крок 1. Інтерфейс
Навіщо. Інтерфейс – це контракт, який викликатиме API. Його коментарі описують правила, не очевидні з назв: реєстрація одразу виконує вхід; токен оновлення працює один раз; повторне використання завершує всі сесії; вихід успішний навіть із невідомим токеном (клієнт, що виходить двічі, – не помилка).
Крок 2. Ротація та виявлення крадіжки
Навіщо. Токен оновлення живе 30 днів, тож він – цінна ціль. Chatex обмежує шкоду від викраденого токена за допомогою ротації (рис. 8.2): кожне оновлення відкликає наданий токен і видає новий. Законний браузер і зловмисник тепер мають копії того самого токена; хто використає його першим, отримає нову пару, а коли другий надасть старий токен, той уже відкликаний. Відкликаний токен, що повертається, може означати лише одне: його мали двоє, – тому сервіс відкликає всі сесії користувача, і обом доведеться знову входити з паролем, якого зловмисник не знає.
Рис. 8.2. Ротація токенів оновлення та виявлення повторного використання
Крок 3. Сервіс
Що зробити.
cs
using Chatex.Core.Common;
using Chatex.Core.Users;
using Chatex.Data.Abstractions;
using Chatex.Data.Entities;
using FluentValidation;
using Microsoft.AspNetCore.Identity;
using Microsoft.Extensions.Options;
namespace Chatex.Core.Auth;
public interface IAuthService
{
/// <summary>Creates the account and its profile, and signs the new user in.</summary>
Task<Result<AuthResult>> RegisterAsync(RegisterCommand command, ClientInfo client, CancellationToken cancellationToken = default);
Task<Result<AuthResult>> LoginAsync(LoginCommand command, ClientInfo client, CancellationToken cancellationToken = default);
/// <summary>
/// Exchanges a refresh token for a new token pair. Each refresh token works once; presenting a used one
/// signs the user out everywhere, because it means the token was stolen.
/// </summary>
Task<Result<AuthResult>> RefreshAsync(RefreshCommand command, ClientInfo client, CancellationToken cancellationToken = default);
/// <summary>Ends one session. Succeeds even if the token is unknown or already revoked.</summary>
Task<Result> LogoutAsync(RefreshCommand command, CancellationToken cancellationToken = default);
/// <summary>Ends every session of the user.</summary>
Task<Result> LogoutAllAsync(Guid userId, CancellationToken cancellationToken = default);
/// <summary>
/// Deletes refresh tokens that expired or were revoked more than one refresh token lifetime ago; returns how many.
/// Revoked tokens stay that long so a stolen token that comes back still signs the user out everywhere.
/// </summary>
Task<int> DeleteStaleRefreshTokensAsync(CancellationToken cancellationToken = default);
}
internal sealed class AuthService(
UserManager<User> userManager,
IUserRepository users,
IRefreshTokenRepository refreshTokens,
IUnitOfWork unitOfWork,
ITokenService tokens,
IOptions<JwtOptions> jwtOptions,
TimeProvider timeProvider,
IValidator<RegisterCommand> registerValidator,
IValidator<LoginCommand> loginValidator) : IAuthService
{
private const int MaxUserAgentLength = 512;
private const int MaxIpLength = 45;
public async Task<Result<AuthResult>> RegisterAsync(
RegisterCommand command, ClientInfo client, CancellationToken cancellationToken = default)
{
if (await registerValidator.ValidateToErrorAsync(command, cancellationToken) is { } invalid)
{
return invalid;
}
var user = new User { UserName = command.UserName.ToLowerInvariant(), Email = command.Email.Trim() };
return await unitOfWork.ExecuteInTransactionAsync<Result<AuthResult>>(async ct =>
{
var created = await userManager.CreateAsync(user, command.Password);
if (!created.Succeeded)
{
return ToError(created.Errors);
}
users.AddProfile(new UserProfile { UserId = user.Id, DisplayName = command.DisplayName.Trim() });
return await IssueTokensAsync(user, client, ct);
}, cancellationToken);
}
public async Task<Result<AuthResult>> LoginAsync(
LoginCommand command, ClientInfo client, CancellationToken cancellationToken = default)
{
if (await loginValidator.ValidateToErrorAsync(command, cancellationToken) is { } invalid)
{
return invalid;
}
var login = command.Login.Trim();
var user = login.Contains('@')
? await userManager.FindByEmailAsync(login)
: await userManager.FindByNameAsync(login);
if (user is null)
{
return AuthErrors.InvalidCredentials;
}
if (await userManager.IsLockedOutAsync(user))
{
return AuthErrors.LockedOut;
}
if (!await userManager.CheckPasswordAsync(user, command.Password))
{
await userManager.AccessFailedAsync(user);
return await userManager.IsLockedOutAsync(user) ? AuthErrors.LockedOut : AuthErrors.InvalidCredentials;
}
await userManager.ResetAccessFailedCountAsync(user);
return await IssueTokensAsync(user, client, cancellationToken);
}
public async Task<Result<AuthResult>> RefreshAsync(
RefreshCommand command, ClientInfo client, CancellationToken cancellationToken = default)
{
if (string.IsNullOrWhiteSpace(command.RefreshToken))
{
return AuthErrors.InvalidRefreshToken;
}
var now = timeProvider.GetUtcNow();
var current = await refreshTokens.GetByHashAsync(tokens.HashRefreshToken(command.RefreshToken), cancellationToken);
if (current is null || current.ExpiresAt <= now)
{
return AuthErrors.InvalidRefreshToken;
}
if (current.RevokedAt is not null)
{
// A used token came back: someone else holds a copy. End every session of this user.
await refreshTokens.RevokeAllForUserAsync(current.UserId, now, cancellationToken);
return AuthErrors.InvalidRefreshToken;
}
current.RevokedAt = now;
return await IssueTokensAsync(current.User, client, cancellationToken, replaces: current);
}
public async Task<Result> LogoutAsync(RefreshCommand command, CancellationToken cancellationToken = default)
{
if (string.IsNullOrWhiteSpace(command.RefreshToken))
{
return Result.Success;
}
var token = await refreshTokens.GetByHashAsync(tokens.HashRefreshToken(command.RefreshToken), cancellationToken);
if (token is { RevokedAt: null })
{
token.RevokedAt = timeProvider.GetUtcNow();
await unitOfWork.SaveChangesAsync(cancellationToken);
}
return Result.Success;
}
public async Task<Result> LogoutAllAsync(Guid userId, CancellationToken cancellationToken = default)
{
await refreshTokens.RevokeAllForUserAsync(userId, timeProvider.GetUtcNow(), cancellationToken);
return Result.Success;
}
public Task<int> DeleteStaleRefreshTokensAsync(CancellationToken cancellationToken = default) =>
refreshTokens.DeleteStaleAsync(timeProvider.GetUtcNow() - jwtOptions.Value.RefreshTokenLifetime, cancellationToken);
/// <summary>Stores a new refresh token (linking it from <paramref name="replaces"/>), saves, and returns both tokens.</summary>
private async Task<AuthResult> IssueTokensAsync(
User user, ClientInfo client, CancellationToken cancellationToken, RefreshToken? replaces = null)
{
var now = timeProvider.GetUtcNow();
var access = tokens.CreateAccessToken(user);
var refresh = tokens.CreateRefreshToken();
var entity = new RefreshToken
{
UserId = user.Id,
TokenHash = refresh.Hash,
ExpiresAt = now + jwtOptions.Value.RefreshTokenLifetime,
UserAgent = Truncate(client.UserAgent, MaxUserAgentLength),
CreatedByIp = Truncate(client.IpAddress, MaxIpLength),
};
refreshTokens.Add(entity);
if (replaces is not null)
{
replaces.ReplacedByTokenId = entity.Id;
}
await unitOfWork.SaveChangesAsync(cancellationToken);
// Loads the profile into the tracked user for the response.
var withProfile = await users.GetWithProfileAsync(user.Id, cancellationToken) ?? user;
return new AuthResult(access.Token, access.ExpiresAt, refresh.Token, entity.ExpiresAt, withProfile.ToMyProfileDto());
}
private static Error ToError(IEnumerable<IdentityError> errors)
{
var list = errors.ToList();
if (list.Any(e => e.Code == nameof(IdentityErrorDescriber.DuplicateUserName)))
{
return AuthErrors.UserNameTaken;
}
if (list.Any(e => e.Code == nameof(IdentityErrorDescriber.DuplicateEmail)))
{
return AuthErrors.EmailTaken;
}
return IdentityErrors.ToValidationError(list);
}
private static string? Truncate(string? value, int maxLength) =>
value?.Length > maxLength ? value[..maxLength] : value;
}Реєстрація
- Спершу команду перевіряють; недійсна команда ніколи не торкається бази даних.
- Ім’я користувача переводять у нижній регістр:
Aliceіalice– той самий ідентифікатор. Електронну адресу обрізають від пробілів. ExecuteInTransactionAsync<Result<AuthResult>>виконує всю реєстрацію в одній транзакції (тема 5):UserManager.CreateAsyncзберігає користувача, а потімIssueTokensAsyncзберігає профіль і перший токен оновлення. Якщо будь-який крок не вдасться – навіть очікуваною помилкою, повернутою як результат, – не повинно лишитися нічого. Аргумент типу записано явно, бо лямбда повертає і значенняError, і значенняAuthResult, а компілятор має знати, що вони означаютьResult<AuthResult>.ToErrorперетворює збої Identity на наші помилки:DuplicateUserNameіDuplicateEmailстають конфліктами, усе інше (слабкий пароль, недопустимі символи) – однією помилкою перевірки з подробицями за полями зIdentityErrors(тема 7).nameof(IdentityErrorDescriber.DuplicateUserName)дає код як рядок без «магічного» літерала.
Слушне запитання: коли лямбда повертає помилку, а не кидає виняток, чи відкочується транзакція? Ні – ExecuteInTransactionAsync фіксує зміни щоразу, коли лямбда завершується нормально. Якщо CreateAsync не вдався, Identity нічого не зберіг, тож відкочувати нічого. Пізніші збої всередині IssueTokensAsync – це винятки (втрачене з’єднання), і вони відкочують транзакцію.
Вхід
- Ім’я або електронна адреса: логін із
@шукають за адресою, інакше – за іменем користувача. - Порядок перевірок важливий. Невідомий користувач отримує
invalid_credentials. Заблокований користувач отримуєlocked_outдо перевірки пароля, тож заблокований обліковий запис не можна використати для підбору паролів. Хибний пароль зараховується як невдача черезAccessFailedAsync; п’ята невдача блокує обліковий запис на 15 хвилин (параметри задано вAddCoreнижче), і відповіддю одразу стаєlocked_out. - Правильний пароль скидає лічильник невдач і видає токени.
Оновлення
- Токен шукають за його хешем; сам токен ніколи не потрапляє в базу даних.
- Невідомий або прострочений токен:
invalid_refresh_token. - Відкликаний токен – це крадіжка (рис. 8.2):
RevokeAllForUserAsyncзавершує всі сесії, а відповідь – та сама невиразна помилка. - В іншому разі токен відкликають (
current.RevokedAt = now) і видають нову пару;IssueTokensAsyncпов’язує старий токен із наступником черезReplacedByTokenIdі зберігає обидві зміни однимSaveChangesAsync.
Вихід і очищення
LogoutAsyncвідкликає один токен, якщо він активний. Шаблон властивостейtoken is { RevokedAt: null }означає «не null і ще не відкликаний».LogoutAllAsyncвідкликає всі токени користувача (на сторінці налаштувань є «вийти всюди»).DeleteStaleRefreshTokensAsyncвидаляє токени, що закінчилися або були відкликані понад повний строк дії оновлення тому. Відкликаний токен має лишатися стільки часу: доки він усе одно не втратив би чинності, його повернення ще має розпізнаватися як крадіжка. Щогодинне завдання обслуговування з теми 13 викликає цей метод.
Видача токенів
IssueTokensAsync – єдине місце, де починаються сесії. Рядок user agent та IP-адресу обрізають до довжин стовпців із теми 4 методом Truncate – value[..maxLength] є діапазоном для рядка. Після збереження користувача завантажують разом із профілем, бо UserManager повернув його без профілю, а результату потрібне відображуване ім’я.
Крок 4. Реєстрація сервісів
Навіщо. Сервісу автентифікації потрібні UserManager з Identity (його реєструє AddData), сервіс токенів, перевіряльники й два види налаштувань: параметри JWT та власні параметри Identity – правила паролів і блокування облікового запису.
Що зробити. Розширте AddCore (нові рядки зеленим):
cs
using Chatex.Core.Auth;
using Chatex.Data;
using FluentValidation;
using Microsoft.AspNetCore.Identity;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
namespace Chatex.Core;
public static class DependencyInjection
{
public static IServiceCollection AddCore(this IServiceCollection services, IConfiguration configuration)
{
var connectionString = configuration.GetConnectionString("Chatex")
?? throw new InvalidOperationException("Connection string 'Chatex' is not configured.");
services.AddData(connectionString, o => o.RootPath = configuration["Storage:RootPath"] ?? "");
services.AddOptions<JwtOptions>()
.Bind(configuration.GetSection(JwtOptions.Section))
.ValidateDataAnnotations()
.ValidateOnStart();
services.Configure<IdentityOptions>(o =>
{
o.User.RequireUniqueEmail = true;
o.User.AllowedUserNameCharacters = "abcdefghijklmnopqrstuvwxyz0123456789_";
o.Password.RequiredLength = 8;
o.Password.RequireDigit = true;
o.Password.RequireLowercase = false;
o.Password.RequireUppercase = false;
o.Password.RequireNonAlphanumeric = false;
o.Lockout.MaxFailedAccessAttempts = 5;
o.Lockout.DefaultLockoutTimeSpan = TimeSpan.FromMinutes(15);
});
services.AddValidatorsFromAssemblyContaining<AuthService>(includeInternalTypes: true);
services.AddSingleton<ITokenService, TokenService>();
services.AddScoped<IAuthService, AuthService>();
return services;
}
}AddOptions<JwtOptions>().Bind(...).ValidateDataAnnotations().ValidateOnStart()зв’язує розділJwt, перевіряє атрибутиJwtOptionsі робить це під час запуску застосунку. Відсутній ключ підпису зупиняє запуск повідомленням, що називає властивість.Configure<IdentityOptions>задає правила Identity: унікальні адреси електронної пошти; імена користувачів із малих літер, цифр і підкреслень (сервіс спершу переводить ім’я в нижній регістр); паролі щонайменше з 8 символів із цифрою – довжина важить більше за правила складності; 5 невдалих спроб блокують обліковий запис на 15 хвилин.AddValidatorsFromAssemblyContaining<AuthService>(includeInternalTypes: true)знаходить коженAbstractValidator<T>у Chatex.Core і реєструє його якIValidator<T>. Наші перевіряльникиinternal, звідсиincludeInternalTypes. Кожен перевіряльник наступних тем реєструється цим одним рядком.ITokenService– singleton: він не зберігає стану на запит.IAuthServiceмає область дії scoped, як і репозиторії та контекст, які він використовує.
Перевірка
dotnet build проходить успішно. Сервіс завершено; наступний розділ його перевіряє.