Українська
Токени
Крок 1. Два токени
Навіщо. Після входу браузер має доводити, хто він, у кожному запиті. Chatex використовує два токени з різними завданнями (табл. 8.1):
Таблиця 8.1. Токен доступу й токен оновлення
| Токен доступу | Токен оновлення | |
|---|---|---|
| Що це | підписаний JWT з ідентифікатором користувача | 32 випадкові байти |
| Строк дії | 15 хвилин | 30 днів |
| Коли надсилається | з кожним запитом до API і під час з’єднання SignalR | лише з POST /api/auth/refresh |
| Де зберігає браузер | у пам’яті застосунку Angular | у cookie HttpOnly (тема 13) |
| Де зберігає сервер | ніде – його підтверджує підпис | хеш SHA-256 у refresh_tokens |
| Чи можна відкликати | ні, він просто спливає | так, будь-коли |
Така пара поєднує сильні сторони обох. Перевірка токена доступу не потребує бази даних: API перевіряє підпис і строк дії, а це швидко для кожного запиту й кожного повідомлення WebSocket. Але такий токен не можна відкликати, тому він живе лише 15 хвилин. Токен оновлення перевіряється за базою даних, тож його можна відкликати – під час виходу, зміни пароля, виявлення крадіжки – і він кожні 15 хвилин поновлює токен доступу.
JWT зсередини
JSON Web Token (RFC 7519) – це три частини в кодуванні Base64Url, розділені крапками: заголовок ({"alg":"HS256","typ":"JWT"}), корисне навантаження з твердженнями (claims) ({"sub":"0199…","unique_name":"alice","exp":1763213400,…}) і підпис перших двох частин. Корисне навантаження може прочитати будь-хто – вставте токен на jwt.io – але створити дійсний підпис може лише власник ключа. Chatex підписує за HMAC-SHA256: один секретний ключ, відомий лише серверу, і підписує, і перевіряє. Ніколи не кладіть секрети в твердження.
Крок 2. Пакети
Що зробити. Бізнес-рівню потрібні ще чотири пакети: бібліотека JWT, допоміжні засоби реєстрації FluentValidation і розширення параметрів, що зв’язують і перевіряють налаштування.
powershell
dotnet add Source/Chatex.Core package Microsoft.IdentityModel.JsonWebTokenspowershell
dotnet add Source/Chatex.Core package FluentValidation.DependencyInjectionExtensionspowershell
dotnet add Source/Chatex.Core package Microsoft.Extensions.Options.ConfigurationExtensionspowershell
dotnet add Source/Chatex.Core package Microsoft.Extensions.Options.DataAnnotationsxml
<Project Sdk="Microsoft.NET.Sdk">
<ItemGroup>
<ProjectReference Include="..\Chatex.Data\Chatex.Data.csproj" />
</ItemGroup>
<ItemGroup>
<PackageReference Include="FluentValidation" />
<PackageReference Include="FluentValidation.DependencyInjectionExtensions" />
<PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" />
<PackageReference Include="Microsoft.Extensions.Options.ConfigurationExtensions" />
<PackageReference Include="Microsoft.Extensions.Options.DataAnnotations" />
<PackageReference Include="Microsoft.IdentityModel.JsonWebTokens" />
</ItemGroup>
</Project>Файл проєкту тепер остаточний.
Крок 3. Налаштування токенів
Навіщо. Видавець, одержувач, ключ підпису й два строки дії – це налаштування: ключ для розробки лежить у appsettings.Development.json, робочий – у змінній середовища на сервері. Шаблон параметрів (options pattern) зв’язує їх із класом, а анотації даних на властивостях описують, які налаштування дійсні. Ключ із 10 символів має зупинити застосунок під час запуску, а не змушувати кожен вхід завершуватися помилкою згодом.
Що зробити. Створіть папку Auth:
cs
using System.ComponentModel.DataAnnotations;
using System.Text;
using Microsoft.IdentityModel.Tokens;
namespace Chatex.Core.Auth;
/// <summary>Settings for access and refresh tokens, bound from the <c>Jwt</c> configuration section.</summary>
public sealed class JwtOptions
{
public const string Section = "Jwt";
[Required]
public string Issuer { get; set; } = "";
[Required]
public string Audience { get; set; } = "";
/// <summary>HMAC-SHA256 key, at least 32 characters. Keep it out of source control in production.</summary>
[Required]
[MinLength(32)]
public string SigningKey { get; set; } = "";
[Range(typeof(TimeSpan), "00:01:00", "1.00:00:00")]
public TimeSpan AccessTokenLifetime { get; set; } = TimeSpan.FromMinutes(15);
[Range(typeof(TimeSpan), "01:00:00", "365.00:00:00")]
public TimeSpan RefreshTokenLifetime { get; set; } = TimeSpan.FromDays(30);
/// <summary>The key both for signing (here) and for validating tokens (in the Api).</summary>
public SymmetricSecurityKey CreateSigningKey() => new(Encoding.UTF8.GetBytes(SigningKey));
}Sectionназиває розділ конфігурації ("Jwt"), тож зв’язування й документація використовують одну константу.[Required],[MinLength(32)],[Range(...)]перевіряєValidateDataAnnotations(), коли параметри реєструються вAddCore(наприкінці цієї теми). Для HMAC-SHA256 ключ має містити щонайменше 256 біт; 32 символи UTF-8 – це щонайменше 32 байти.- Налаштування
TimeSpanзаписують у JSON текстом ("00:15:00"); атрибутRangeізtypeof(TimeSpan)порівнює їх як проміжки часу. CreateSigningKeyперетворює текстовий ключ на об’єкт ключа бібліотеки JWT. API викликає той самий метод у темі 13 для перевірки токенів, тож підписування й перевірка не можуть розійтися.
Крок 4. Сервіс токенів
Навіщо. Створення токенів – технічна робота з гострими кутами (мітки часу, твердження, поводження з ключем, випадковість). Один невеликий сервіс за інтерфейсом виконує її, щоб сервіс автентифікації лишався читабельним, а тест міг перевірити результат.
Що зробити.
cs
using System.Buffers.Text;
using System.Security.Claims;
using System.Security.Cryptography;
using System.Text;
using Chatex.Data.Entities;
using Microsoft.Extensions.Options;
using Microsoft.IdentityModel.JsonWebTokens;
using Microsoft.IdentityModel.Tokens;
namespace Chatex.Core.Auth;
public sealed record AccessToken(string Token, DateTimeOffset ExpiresAt);
/// <summary>A new refresh token: <see cref="Token"/> goes to the client, only <see cref="Hash"/> is stored.</summary>
public sealed record NewRefreshToken(string Token, string Hash);
public interface ITokenService
{
AccessToken CreateAccessToken(User user);
NewRefreshToken CreateRefreshToken();
string HashRefreshToken(string token);
}
internal sealed class TokenService(IOptions<JwtOptions> options, TimeProvider timeProvider) : ITokenService
{
private readonly JsonWebTokenHandler _handler = new() { SetDefaultTimesOnTokenCreation = false };
public AccessToken CreateAccessToken(User user)
{
var jwt = options.Value;
var now = timeProvider.GetUtcNow();
var expiresAt = now + jwt.AccessTokenLifetime;
var token = _handler.CreateToken(new SecurityTokenDescriptor
{
Issuer = jwt.Issuer,
Audience = jwt.Audience,
IssuedAt = now.UtcDateTime,
NotBefore = now.UtcDateTime,
Expires = expiresAt.UtcDateTime,
Subject = new ClaimsIdentity(
[
new Claim(JwtRegisteredClaimNames.Sub, user.Id.ToString()),
new Claim(JwtRegisteredClaimNames.UniqueName, user.UserName!),
new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString()),
]),
SigningCredentials = new SigningCredentials(jwt.CreateSigningKey(), SecurityAlgorithms.HmacSha256),
});
return new AccessToken(token, expiresAt);
}
public NewRefreshToken CreateRefreshToken()
{
var token = Base64Url.EncodeToString(RandomNumberGenerator.GetBytes(32));
return new NewRefreshToken(token, HashRefreshToken(token));
}
public string HashRefreshToken(string token) =>
Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(token)));
}Токен доступу:
JsonWebTokenHandler– сучасний обробник JWT ізMicrosoft.IdentityModel. Його створюють один раз на сервіс; сервіс зареєстровано як singleton.SetDefaultTimesOnTokenCreation = falseзабороняє обробнику проставляти час за справжнім годинником. Chatex сам задаєIssuedAt,NotBeforeіExpiresз упровадженогоTimeProvider, тож тест із підробленим годинником отримує токени, узгоджені з цим годинником.- Три твердження:
sub(subject) – ідентифікатор користувача, який API читає в кожному запиті;unique_name– ім’я користувача, зручне для журналів;jti(JWT id) – унікальний ідентифікатор цього токена.
Токен оновлення:
RandomNumberGenerator.GetBytes(32)бере 256 випадкових бітів із криптографічного генератора операційної системи – ніколи не використовуйтеRandomдля секретів. Base64Url перетворює їх на 43-символьний рядок, безпечний у cookie.HashRefreshTokenзберігає хеш SHA-256 як шістнадцяткові цифри нижнього регістру. Чому тут швидкий хеш, коли для паролів потрібен повільний? Пароль короткий і вгадуваний, тож зловмисник із хешами пробує мільйони варіантів; повільний алгоритм здорожчує кожну спробу. Токен оновлення має 256 випадкових бітів: вгадувати нічого, тож швидкого хеша досить, щоб украдена база даних не мала цінності.NewRefreshTokenповертає обидва значення: токен іде клієнту один раз, хеш – до бази даних.
Перевірка
dotnet build проходить успішно. TokenService – internal і ще не зареєстрований; його використає сервіс автентифікації далі в цій темі.