• مدیر سایت
• اکتبر 15, 2019

راهنمای کامل پیاده‌سازی JWT Auth در Web API

در دنیای امروز، امنیت APIها یک انتخاب نیست؛ یک ضرورت است. 🛡️ با افزایش تبادل داده بین کلاینت‌ها (مثل اپلیکیشن‌های موبایل و وب) و سرور، نیاز به یک مکانیزم احراز هویت امن، سریع و مدرن بیش از پیش احساس می‌شود. اینجا است که JWT (JSON Web Token) به عنوان یک استاندارد طلایی وارد میدان می‌شود.در این مقاله جامع، به صورت گام به گام و با زبانی ساده، فرآیند پیاده‌سازی JWT Auth در Web API با استفاده از آخرین نسخه ASP.NET Core را بررسی می‌کنیم. هدف ما این است که شما پس از خواندن این مطلب، به راحتی بتوانید Endpoints های API خود را امن کنید.

JSON Web Token (JWT) چیست؟

اگر بخواهیم ساده بگوییم، JWT یک استاندارد باز (RFC 7519) برای ایجاد توکن‌های دسترسی است. این توکن‌ها به صورت یک رشته متنی فشرده و امن، اطلاعات کاربر را بین دو طرف (مثلاً کلاینت و سرور) منتقل می‌کنند.

یک توکن JWT از سه بخش اصلی تشکیل شده است که با نقطه (.) از هم جدا می‌شوند:

1. Header (سرآیند): نوع توکن (JWT) و الگوریتم رمزنگاری را مشخص می‌کند.
2. Payload (محموله): شامل اطلاعاتی به نام Claims است. این اطلاعات می‌توانند شناسه کاربر، نام، نقش‌ها (Roles) و زمان انقضای توکن باشند.
3. Signature (امضا): مهم‌ترین بخش امنیتی توکن است. این امضا با استفاده از سرآیند، محموله و یک کلید مخفی (Secret Key) روی سرور ایجاد می‌شود و تضمین می‌کند که توکن در مسیر دستکاری نشده است.

چرا باید از JWT در Web API استفاده کنیم؟ (مزیت‌ها)

استفاده از JWT در معماری‌های مدرن، به خصوص برای Web API ها، مزایای فوق‌العاده‌ای دارد که آن را از روش‌های قدیمی مانند Session-Cookie متمایز می‌کند.

• ✅ افزایش امنیت: با استفاده از امضای دیجیتال، از دستکاری اطلاعات جلوگیری می‌شود.
• 🔄 وضعیت‌ناپذیری (Stateless): سرور نیازی به ذخیره اطلاعات نشست (Session) کاربر ندارد. هر توکن تمام اطلاعات لازم را در خود دارد. این ویژگی مقیاس‌پذیری (Scalability) را به شدت افزایش می‌دهد.
• 🚀 سرعت و عملکرد بالا: چون نیازی به جستجو در دیتابیس برای هر درخواست نیست، فرآیند احراز هویت بسیار سریع‌تر انجام می‌شود.
• 🌐 سازگاری گسترده: JWT به راحتی در تمام پلتفرم‌ها (وب، موبایل، دسکتاپ) و زبان‌های برنامه‌نویسی قابل استفاده است.
• 🔗 مناسب برای معماری میکروسرویس: ارتباط امن بین سرویس‌های مختلف را به سادگی فراهم می‌کند.

کاربردهای رایج احراز هویت توکن-محور

احراز هویت مبتنی بر توکن، به خصوص JWT، در سناریوهای مختلفی کاربرد دارد. درک این کاربردها به شما کمک می‌کند تا از این تکنولوژی در جای درست استفاده کنید.

• 🔐 احراز هویت (Authentication): رایج‌ترین کاربرد. پس از ورود موفق کاربر، یک توکن JWT ایجاد شده و برای درخواست‌های بعدی استفاده می‌شود.
• 📝 مجوزدهی (Authorization): اطلاعات مربوط به سطح دسترسی و نقش‌های کاربر (مثلاً Admin یا User) می‌تواند درون توکن قرار گیرد. سرور با خواندن توکن، متوجه می‌شود کاربر به کدام منابع دسترسی دارد.
• 📨 تبادل امن اطلاعات: JWT یک راه عالی برای انتقال امن اطلاعات بین بخش‌های مختلف یک سیستم است، زیرا می‌توان از صحت و عدم دستکاری اطلاعات مطمئن بود.

راهنمای گام به گام پیاده‌سازی JWT Auth در ASP.NET Core

حالا به بخش عملی و جذاب ماجرا می‌رسیم. در این بخش، مراحل امن‌سازی یک Web API در ASP.NET Core را با هم طی می‌کنیم.

H3: پیش‌نیازها

• نصب آخرین نسخه .NET SDK
• یک ویرایشگر کد مانند Visual Studio 2022 یا VS Code

H3: مرحله ۱: ایجاد پروژه و نصب پکیج‌های لازم

ابتدا یک پروژه جدید ASP.NET Core Web API ایجاد کنید. سپس پکیج NuGet مورد نیاز برای کار با JWT را نصب کنید. این کار را می‌توانید از طریق Package Manager Console یا دستور زیر در ترمینال انجام دهید:

dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

H3: مرحله ۲: پیکربندی JWT در appsettings.json

بهترین کار این است که اطلاعات حساس مانند کلید مخفی را در فایل appsettings.json ذخیره کنید. این کار مدیریت و تغییر آن‌ها را آسان‌تر می‌کند.

{
  "Jwt": {
    "Issuer": "https://p.api.ir",
    "Audience": "https://p.api.ir",
    "Key": "ThisIsAStrongAndSecureSecretKeyForYourApplication123!"
  },
  // ... other settings
}

• Issuer: صادرکننده توکن (آدرس سرویس شما).
• Audience: دریافت‌کننده مجاز توکن (آدرس سرویس شما).
• Key: کلید مخفی بسیار مهم برای امضای توکن. این کلید باید طولانی و پیچیده باشد.

H3: مرحله ۳: تنظیمات سرویس احراز هویت در Program.cs

در فایل Program.cs (در نسخه‌های جدید .NET)، باید سرویس‌های احراز هویت و اعتبارسنجی JWT را پیکربندی کنیم.

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using System.Text;

var builder = WebApplication.CreateBuilder(args);
var configuration = builder.Configuration;

// Add services to the container.
builder.Services.AddControllers();

// 1. Add Authentication Services
builder.Services.AddAuthentication(options =>
{
    options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
// 2. Configure JWT Bearer
.AddJwtBearer(options =>
{
    options.TokenValidationParameters = new TokenValidationParameters
    {
        ValidateIssuer = true,
        ValidateAudience = true,
        ValidateLifetime = true,
        ValidateIssuerSigningKey = true,
        ValidIssuer = configuration["Jwt:Issuer"],
        ValidAudience = configuration["Jwt:Audience"],
        IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(configuration["Jwt:Key"]))
    };
});


var app = builder.Build();

// ... other middleware

app.UseHttpsRedirection();

// 3. Use Authentication & Authorization Middleware
app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();
app.Run();

در این کد، ما به اپلیکیشن می‌گوییم که از JWT Bearer به عنوان روش پیش‌فرض احراز هویت استفاده کند و پارامترهای اعتبارسنجی توکن را بر اساس مقادیر appsettings.json تنظیم کند.

H3: مرحله ۴: ساخت کنترلر برای تولید توکن

ما به یک Endpoint نیاز داریم تا پس از بررسی نام کاربری و رمز عبور، توکن JWT را برای کاربر صادر کند. یک کنترلر جدید به نام AuthController ایجاد کنید.

using Microsoft.AspNetCore.Mvc;
using Microsoft.IdentityModel.Tokens;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;

[ApiController]
[Route("api/[controller]")]
public class AuthController : ControllerBase
{
    private readonly IConfiguration _configuration;

    public AuthController(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    [HttpPost("login")]
    public IActionResult Login([FromBody] UserLogin model)
    {
        // In a real application, you would validate the user from a database.
        if (model.Username == "test" && model.Password == "password")
        {
            var token = GenerateJwtToken(model.Username);
            return Ok(new { token });
        }
        return Unauthorized();
    }

    private string GenerateJwtToken(string username)
    {
        var securityKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_configuration["Jwt:Key"]));
        var credentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);

        var claims = new[]
        {
            new Claim(JwtRegisteredClaimNames.Sub, username),
            new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString())
        };

        var token = new JwtSecurityToken(
            issuer: _configuration["Jwt:Issuer"],
            audience: _configuration["Jwt:Audience"],
            claims: claims,
            expires: DateTime.Now.AddMinutes(30),
            signingCredentials: credentials);

        return new JwtSecurityTokenHandler().WriteToken(token);
    }
}

public class UserLogin
{
    public string Username { get; set; }
    public string Password { get; set; }
}

H3: مرحله ۵: امن‌سازی Endpoints با [Authorize]

حالا می‌توانید هر کنترلر یا متدی را که می‌خواهید محافظت‌شده باشد، با اتریبیوت [Authorize] مشخص کنید.

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
[Authorize] // This entire controller is now protected
public class WeatherForecastController : ControllerBase
{
    [HttpGet]
    public IEnumerable<string> Get()
    {
        return new string[] { "Sunny", "Cloudy", "Rainy" };
    }
}

اکنون هر درخواستی به این کنترلر، باید یک توکن معتبر JWT در هدر Authorization خود داشته باشد.

ثبت‌نام و دریافت کلید API

قبل از اینکه API خود را به صورت عمومی منتشر کنید، معمولاً نیاز است تا سرویس خود را در یک پلتفرم مدیریتی ثبت کرده و کلیدهای لازم را دریافت نمایید. این کار به مدیریت دسترسی‌ها و امنیت کمک شایانی می‌کند. مراحل ثبت‌نام معمولاً به شرح زیر است:

1. 📋 به پورتال توسعه‌دهندگان به آدرس p.api.ir مراجعه کنید.
2. 👤 یک حساب کاربری ایجاد کرده و وارد پنل خود شوید.
3. 🔑 اپلیکیشن جدیدی ثبت کرده و کلیدهای API (شامل Secret Key) خود را دریافت نمایید. این کلید همان مقداری است که باید در appsettings.json قرار دهید.

در این مقاله، ما به طور کامل با مفهوم JWT، مزایا و کاربردهای آن آشنا شدیم. همچنین، فرآیند گام به گام پیاده‌سازی JWT Auth در Web API با ASP.NET Core را از نصب پکیج‌ها تا امن‌سازی Endpoints یاد گرفتیم. با اجرای این مراحل، شما یک لایه امنیتی قدرتمند و استاندارد به سرویس‌های خود اضافه کرده‌اید. 💎

امنیت یک فرآیند مداوم است. همیشه سعی کنید از کلیدهای مخفی قوی استفاده کنید و آن‌ها را در محیط‌های امن نگهداری نمایید.

آیا این راهنما برای شما مفید بود؟ اگر سوالی دارید یا از روش دیگری برای احراز هویت استفاده می‌کنید، تجربیات خود را در بخش نظرات با ما در میان بگذارید! 👇

• برچسب ها:
• آموزش jwt
• آموزش جیسون وب توکن
• پیاده سازی json web token
• پیاده سازی jwt