مولّد توكن JWT وفاحصه لخوارزميات HS256 وHS384 وHS512

طريقة الاستخدام

اكتب الترويسة (JSON) والحمولة (JSON). واستخدم اضبط iat على الآن أو اضبط nbf على الآن أو اضبط exp بعد لملء الأوقات.
اختر الخوارزمية واكتب المفتاح السري. واختر Base64 تحت ترميز المفتاح السري إن كان المفتاح مكتوباً بـ Base64.
انسخ التوكن. له ثلاثة أجزاء مفصولة بنقاط: الترويسة والحمولة والتوقيع.
الصق توكناً في التوكن المراد فحصه لترى إن كان توقيعه يطابق المفتاح السري أعلاه.

كيف يُوقَّع JWT

JSON Web Token (RFC 7519) ترويسة وحمولة، كل منهما كائن JSON مرمّز بـ Base64url (RFC 7515)، ويفصل بينهما نقطة. التوقيع هو HMAC لهذين الجزأين، ويُصنع بالمفتاح السري (RFC 7518، القسم 3.2). وتسمي الترويسة الخوارزمية في حقلها alg، وتضبط هذه الصفحة ذلك الحقل على الخوارزمية التي تختارها.

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

signing input = BASE64URL(header) . BASE64URL(payload)
signature    = HMAC-SHA-256(secret, signing input)
               (تستخدم HS384 وHS512 الدالتين HMAC-SHA-384 وHMAC-SHA-512)
token        = signing input . BASE64URL(signature)

الأوقات في الحمولة

المطالبات iat (وقت الإصدار) وnbf (لا قبل) وexp (وقت الانتهاء) أعداد NumericDate: عدد الثواني منذ 1 يناير 1970 في الساعة 00:00 بالتوقيت العالمي (RFC 7519، القسمان 2 و4.1). ولا يُقبل التوكن عند exp أو بعدها، ولا قبل nbf. وتكتب الأزرار الوقت من ساعة جهازك، فتعطي ساعة خاطئة وقتاً خاطئاً.

ما الذي يفعله الفحص وما لا يفعله

يعيد الفحص حساب HMAC للترويسة والحمولة كما لُصقتا تماماً، ويقارنه بالتوقيع. ويرفض alg none وكل خوارزمية غير HS256 وHS384 وHS512، فلا يستطيع التوكن أن يختار فحصاً أضعف.

ولا يفحص معنى المطالبات: هل iss هو المُصدِر الذي تتوقعه، أو هل يسمّي aud خدمتك. ويجب أن يفحص تطبيقك ذلك، كما توصي RFC 8725.

مثال محلول: HS256 بالمفتاح السري your-256-bit-secret

مع الترويسة {"alg": "HS256", "typ": "JWT"}، والحمولة {"sub": "1234567890", "name": "Ada Lovelace", "iat": 1516239022}، والمفتاح السري UTF-8 الـ your-256-bit-secret، تصنع الصفحة هذا التوكن:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFkYSBMb3ZlbGFjZSIsImlhdCI6MTUxNjIzOTAyMn0.nmm0qepYRjhNji3O-jq8Pvcr7l_me1_bomw4EJucQCU

فحصه بالمفتاح السري نفسه يعطي توقيعاً صالحاً. ليس في التوكن مطالبة exp أو nbf، فلا يمكن لأي وقت أن يجعله غير صالح. أما فحصه بمفتاح آخر فيُبلغ أن التوقيع لا يطابق.

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

هل يُرسل مفتاحي السري إلى خادم؟

لا. يُوقّع التوكن في متصفحك بواسطة SubtleCrypto الخاصة بالمتصفح. ويبقى المفتاح السري مادام الصفحة مفتوحة فقط، فلا يُرسل ولا يُخزَّن ولا يُسجَّل.

لماذا تقول الصفحة إن التوقيع يطابق، بينما ترفض مكتبتي التوكن؟

قد تفحص المكتبة أوقات exp أو nbf، أو الجمهور أو المُصدِر، أو قد تقرأ المفتاح السري بترميز آخر. اقرأ المفتاح كـ UTF-8 أو كـ Base64 بالطريقة نفسها التي تقرأ بها مكتبتك، وقارن الأوقات بساعة صحيحة.

لماذا يُرفض alg none؟

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

ما طول المفتاح السري الذي يجب أن يكون؟

يجب أن يكون بطول خرج دالة التجزئة على الأقل: 32 بايتاً لـ HS256، و48 لـ HS384، و64 لـ HS512 (RFC 7518، القسم 3.2). وتحذّر الصفحة عندما يكون المفتاح أقصر.

هل تستطيع هذه الصفحة إنشاء توكنات RS256 أو ES256؟

لا. تُوقّع الصفحة وتفحص بمفتاح مشترك فقط، باستخدام HS256 أو HS384 أو HS512. أما التوكنات الموقّعة بمفتاح RSA أو ECDSA خاص فتحتاج ذلك المفتاح، وهذه الصفحة لا تقبله.

متى أختار Base64 للمفتاح السري؟

فقط عندما يكون المفتاح مكتوباً بـ Base64، مثل قيمة k في مفتاح JSON Web Key. وفي غير ذلك يُقرأ المفتاح كنص UTF-8 كما كتبته تماماً، مع المسافات.

المصادر

آخر مراجعة للأرقام والنص: الثلاثاء، 30 جمادى الأولى 1448 بعد الهجرة.