Authentication و JWT Bearer

.NET 10 | Identity Claims و Token Validation

Authentication هویت Caller را تعیین می‌کند. در APIهای مبتنی بر JWT، Token امضاشده Claimها را حمل می‌کند و Server باید Signature، Issuer، Audience و Lifetime را پیش از اعتماد به آن اعتبارسنجی کند.

این فصل با تمرکز بر قراردادهای قابل اتکا، مرزبندی مسئولیت‌ها و رفتار قابل پیش‌بینی در محیط واقعی تنظیم شده است. مثال‌ها بر پایه ASP.NET Core و .NET 10 نوشته شده‌اند.

1. چارچوب موضوع و مفاهیم اصلی

Authentication هویت Caller را تعیین می‌کند. در APIهای مبتنی بر JWT، Token امضاشده Claimها را حمل می‌کند و Server باید Signature، Issuer، Audience و Lifetime را پیش از اعتماد به آن اعتبارسنجی کند.

واژگان و قراردادهای این بخش باید در سراسر پروژه یکدست بمانند؛ تفاوت میان لایه HTTP، منطق برنامه و زیرساخت زمانی روشن می‌ماند که مسئولیت هر جزء به‌صورت صریح تعریف شود.

2. ساختار پیشنهادی در پروژه

AddAuthentication و AddJwtBearer ثبت می‌شوند و سپس UseAuthentication پیش از UseAuthorization قرار می‌گیرد. Key باید طول و Entropy مناسب داشته و خارج از Repository نگهداری شود.

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = jwt.Issuer,
            ValidAudience = jwt.Audience,
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(jwt.Key))
        };
    });

3. سناریوی اجرایی

پس از Login موفق، Access Token کوتاه‌عمر صادر می‌شود. Client آن را در Authorization Header ارسال می‌کند. Endpoint دارای Authorize تنها پس از اعتبارسنجی Token اجرا می‌شود.

در این سناریو، قرارداد ورودی و خروجی، مسیر شکست و رفتار قابل مشاهده سرویس باید پیش از جزئیات پیاده‌سازی مشخص شود. این رویکرد باعث می‌شود تغییرات بعدی بدون وابستگی پنهان و با امکان تست دقیق انجام شوند.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

[Authorize]
[HttpGet("me")]
public IActionResult Me()
{
    return Ok(new
    {
        UserId = User.FindFirstValue(ClaimTypes.NameIdentifier)
    });
}

4. اصول طراحی و نگهداری

پیاده‌سازی قابل نگهداری تنها به درست کار کردن در مسیر موفق محدود نیست. مرزهای مسئولیت، قابلیت مشاهده، امنیت، رفتار در خطا و امکان توسعه تدریجی باید هم‌زمان بررسی شوند.

• Access Token کوتاه‌عمر باشد.
• Clock skew و زمان Expiration آگاهانه تنظیم شود.
• Token حاوی Secret یا داده‌ای که نباید توسط Client دیده شود نباشد.
• Authentication و Authorization به‌عنوان دو مرحله مستقل در نظر گرفته شوند.

5. خطاهای رایج و کنترل آن‌ها

بخش مهمی از کیفیت یک API در نحوه جلوگیری از خطاهای تکرارشونده مشخص می‌شود. موارد زیر باید در بازبینی کد و تست‌های قبل از انتشار کنترل شوند.

• غیرفعال کردن ValidateLifetime.
• Key کوتاه یا Hard-coded.
• ذخیره Password خام در Claim.
• قرار دادن UseAuthorization قبل از UseAuthentication.

6. چک‌لیست نهایی فصل

• Issuer، Audience و Signature Validate می‌شوند.
• 401 برای نبود/نامعتبر بودن هویت تولید می‌شود.
• Token Expiration تست شده است.
• Secret کلید امضا امن نگهداری می‌شود.

7. جمع‌بندی

مفاهیم این فصل زمانی کامل محسوب می‌شوند که هم مسیر موفق و هم مسیر خطا قابل پیش‌بینی، قابل تست و قابل مشاهده باشند. طراحی نهایی باید با Contract API، امنیت و نیازهای نگهداری پروژه هماهنگ بماند.