C# Academy · درس

بنية JWT والمطالبات

افهموا الترويسة والحمولة والتوقيع

بنية JWT والمطالبات درس مجاني في C# Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في C# Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة C# Academy 4 دروس في المجموع.

ما هو JWT؟

إن JSON Web Token (JWT) هو تنسيق رموز مدمج وآمن لعناوين URL، يُستخدم لنقل المطالبات بأمان بين طرفين. وفي ASP.NET Core، يُعد الطريقة الأكثر شيوعًا لمصادقة واجهات API عديمة الحالة.

إن JWT مجرد سلسلة تتكون من ثلاثة أجزاء مشفّرة بترميز Base64Url، تفصل بينها نقاط: header.payload.signature.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0Iiwicm9sZSI6ImFkbWluIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

الرأس

يصف الرأس كيفية توقيع الرمز. وهو كائن JSON صغير يُشفَّر بترميز Base64Url ليصبح المقطع الأول.

تسمّي alg خوارزمية التوقيع، مثل HS256 وRS256، بينما تكون typ في الغالب JWT.

{
  "alg": "HS256",
  "typ": "JWT"
}

الحمولة

تحمل الحمولة المطالبات، أي العبارات المتعلقة بالمستخدم والبيانات الوصفية الخاصة بالرمز. وهي المقطع الثاني.

مهم: الحمولة مشفّرة بالترميز فقط وليست مشفّرة. ويمكن لأي شخص فك ترميزها، لذا لا تضعوا الأسرار فيها مطلقًا.

{
  "sub": "1234",
  "name": "Alice",
  "role": "admin",
  "exp": 1735689600
}

التوقيع

يضمن التوقيع عدم العبث بالرمز. إذ يحسبه الخادم من الرأس المشفّر والحمولة المشفّرة ومفتاح سري.

إذا غيّر أي شخص حرفًا واحدًا من الحمولة، فلن يعود التوقيع مطابقًا، ويفشل التحقق.

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secretKey
)

المطالبات المسجلة

توحّد مواصفة JWT، وهي RFC 7519، بعض أسماء المطالبات. وتستخدم هذه الأسماء مفاتيح قصيرة من ثلاثة أحرف:

iss - المُصدِر
sub - الموضوع (معرّف المستخدم)
aud - الجمهور
exp - وقت انتهاء الصلاحية (بالثواني وفق Unix)
nbf - غير صالح قبل
iat - وقت الإصدار

{
  "iss": "https://api.myapp.com",
  "aud": "myapp-clients",
  "sub": "42",
  "exp": 1735689600,
  "iat": 1735686000
}

المطالبات المخصصة

بالإضافة إلى المجموعة المسجلة، يمكنكم إضافة أي مطالبات مخصصة يحتاج إليها تطبيقكم، مثل الأدوار والأذونات ومعرّفات المستأجر والبريد الإلكتروني وغير ذلك.

احرصوا على إبقاء الحمولة صغيرة، إذ تنتقل كل مطالبة مع كل طلب.

{
  "sub": "42",
  "email": "alice@myapp.com",
  "role": "admin",
  "tenant_id": "acme",
  "permissions": ["orders:read", "orders:write"]
}

المطالبات في ASP.NET Core

في .NET، يتم تمثيل المطالبات بالنوع System.Security.Claims.Claim. وكل مطالبة عبارة عن زوج من النوع / القيمة.

عند التحقق من صحة JWT، يحوّل ASP.NET Core كل إدخال في الحمولة إلى Claim ضمن ClaimsPrincipal الخاص بالمستخدم.

var claims = new List<Claim>
{
    new Claim(ClaimTypes.NameIdentifier, "42"),
    new Claim(ClaimTypes.Name, "Alice"),
    new Claim(ClaimTypes.Role, "admin"),
    new Claim("tenant_id", "acme")
};

ClaimsPrincipal وClaimsIdentity

يُمثَّل المستخدم الذي تمت مصادقته بواسطة ClaimsPrincipal، الذي يضم كائنًا واحدًا أو أكثر من نوع ClaimsIdentity، ويحتوي كل منها على مجموعة من المطالبات.

في وحدة التحكم، يمكنكم الوصول إليه عبر User.

// Inside a controller action
var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
bool isAdmin = User.IsInRole("admin");
string? tenant = User.FindFirst("tenant_id")?.Value;

تعيين نوع المطالبة

يعمد معالج JWT افتراضيًا إلى تعيين مفاتيح JWT المختصرة إلى أنواع مطالبات طويلة بتنسيق URI، فمثلًا يتحول sub إلى ClaimTypes.NameIdentifier.

للاحتفاظ بالأسماء المختصرة الأصلية، عطّلوا التعيين الوارد مرة واحدة عند بدء التشغيل.

JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear();
// Now User.FindFirst("sub") returns the raw 'sub' claim

لماذا لا نستخدم ملف تعريف ارتباط للجلسة فحسب؟

إن JWTs مكتفية ذاتيًا: إذ يمكن للخادم التحقق من صحتها باستخدام مفتاح التوقيع وحده، دون الاستعلام عن قاعدة بيانات أو استخدام مخزن جلسات على الخادم.

وهذا يجعلها مثالية لواجهات API التي تتوسع أفقيًا وللخدمات المصغّرة، حيث يمكن لأي عقدة التحقق من الرمز نفسه.

// Client sends the token on every request:
// Authorization: Bearer eyJhbGciOiJIUzI1Ni...

المفاضلة: الإبطال

بما أن JWT مكتفٍ ذاتيًا وموثوق به حتى انتهاء صلاحيته، فلا يمكنكم إبطال رمز واحد بسهولة قبل وقت exp الخاص به.

يتمثل الإجراء الشائع للتخفيف من ذلك في جعل رموز الوصول قصيرة العمر وربطها برموز تحديث، وهو موضوع سنتناوله لاحقًا في هذه الدورة.

// Short-lived access token
exp = iat + 15 * 60;  // 15 minutes

اختبار سريع

اختبروا فهمكم لبنية JWT.

مراجعة

تعلّمتم بنية JWT وكيفية عمل المطالبات في ASP.NET Core:

يتكون JWT من header.payload.signature، ويُرمَّز كل جزء منها باستخدام Base64Url.
تحتوي الحمولة على مطالبات مسجّلة ومخصصة، وهي مرمّزة وليست مشفّرة.
يضمن التوقيع سلامة البيانات باستخدام سر أو زوج من المفاتيح.
يحوّل .NET المطالبات إلى ClaimsPrincipal يمكنكم قراءته عبر User.

بعد ذلك، ستُعدّون ASP.NET Core للتحقق من صحة هذه الرموز.

الأسئلة الشائعة

هل درس «بنية JWT والمطالبات» مجاني؟

نعم — نص درس «بنية JWT والمطالبات» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة C# Academy، انتقل إلى CoddyKit PRO. تتضمن دورة C# Academy 4 دروس في المجموع.

ماذا ستتعلم في «بنية JWT والمطالبات»؟

افهموا الترويسة والحمولة والتوقيع تتمرن على C# Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ C# Academy؟

لا تُشترط خبرة سابقة. C# Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «بنية JWT والمطالبات»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس C# Academy هذا؟

نعم. كل درس في C# Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

بنية JWT والمطالبات
تهيئة مصادقة JWT Bearer
إصدار الرموز المميّزة
الرموز المميّزة للتحديث وانتهاء الصلاحية

← العودة إلى C# Academy