| يبني | التبعية |
|---|---|
تنفيذ JSON Web Tokens.
تم تطوير هذا مقابل draft-ietf-oauth-json-web-token-08 . يستخدم العقدة jws
$ npm install jsonwebtoken (غير متزامن) إذا تم توفير رد اتصال، فسيتم استدعاء رد الاتصال مع err أو JWT.
(متزامن) يُرجع JsonWebToken كسلسلة
يمكن أن تكون payload عبارة عن كائن حرفي أو مخزن مؤقت أو سلسلة تمثل JSON صالحًا.
يرجى ملاحظة أنه يتم تعيين
expأو أي مطالبة أخرى فقط إذا كانت الحمولة عبارة عن كائن حرفي. لم يتم التحقق من حمولات المخزن المؤقت أو السلسلة للتأكد من صحة JSON.
إذا لم تكن
payloadمخزنًا مؤقتًا أو سلسلة، فسيتم إجبارها على تحويلها إلى سلسلة باستخدامJSON.stringify.
secretOrPrivateKey عبارة عن سلسلة (بترميز utf-8) أو مخزن مؤقت أو كائن أو KeyObject تحتوي إما على سر خوارزميات HMAC أو المفتاح الخاص المشفر PEM لـ RSA وECDSA. في حالة وجود مفتاح خاص مع عبارة مرور، يمكن استخدام كائن { key, passphrase } (استنادًا إلى وثائق التشفير)، في هذه الحالة تأكد من تمرير خيار algorithm . عند التوقيع باستخدام خوارزميات RSA، يكون الحد الأدنى لطول المعامل هو 2048 إلا عندما يتم تعيين خيارallowInsecureKeySizes على true. سيتم رفض المفاتيح الخاصة التي يقل حجمها عن هذا الحجم مع حدوث خطأ.
options :
algorithm (الافتراضي: HS256 )expiresIn : يتم التعبير عنها بالثواني أو سلسلة تصف فترة زمنية vercel/ms.على سبيل المثال:
60،"2 days"،"10h"،"7d". يتم تفسير القيمة الرقمية على أنها عدد الثواني. إذا كنت تستخدم سلسلة فتأكد من توفير وحدات الوقت (الأيام والساعات وما إلى ذلك)، وإلا فسيتم استخدام وحدة المللي ثانية افتراضيًا ("120"تساوي"120ms").
notBefore : يتم التعبير عنه بالثواني أو بسلسلة تصف فترة زمنية vercel/ms.على سبيل المثال:
60،"2 days"،"10h"،"7d". يتم تفسير القيمة الرقمية على أنها عدد الثواني. إذا كنت تستخدم سلسلة فتأكد من توفير وحدات الوقت (الأيام والساعات وما إلى ذلك)، وإلا فسيتم استخدام وحدة المللي ثانية افتراضيًا ("120"تساوي"120ms").
audienceissuerjwtidsubjectnoTimestampheaderkeyidmutatePayload : إذا كان صحيحًا، فستقوم وظيفة الإشارة بتعديل كائن الحمولة مباشرة. يعد هذا مفيدًا إذا كنت بحاجة إلى مرجع أولي للحمولة بعد تطبيق المطالبات عليها ولكن قبل ترميزها في رمز مميز.allowInsecureKeySizes : إذا كان صحيحًا، فإنه يسمح باستخدام المفاتيح الخاصة ذات المعامل الأقل من 2048 لـ RSAallowInvalidAsymmetricKeyTypes : إذا كان صحيحًا، فإنه يسمح بالمفاتيح غير المتماثلة التي لا تتطابق مع الخوارزمية المحددة. هذا الخيار مخصص فقط للتوافق مع الإصدارات السابقة ويجب تجنبه.لا توجد قيم افتراضية
expiresIn،notBefore،audience،subject،issuer. يمكن أيضًا توفير هذه المطالبات في الحمولة مباشرة معexpوnbfوaudوsubوissعلى التوالي، ولكن لا يمكنك تضمينها في كلا المكانين.
تذكر أن exp و nbf و iat هي NumericDate ، راجع انتهاء صلاحية الرمز ذي الصلة (مطالبة exp)
يمكن تخصيص الرأس عبر كائن options.header .
ستتضمن jwts المُنشأة مطالبة iat (صدرت في) افتراضيًا ما لم يتم تحديد noTimestamp . إذا تم إدراج iat في الحمولة، فسيتم استخدامه بدلاً من الطابع الزمني الحقيقي لحساب أشياء أخرى مثل exp المعطاة لنطاق زمني في options.expiresIn .
تسجيل متزامن افتراضي (HMAC SHA256)
var jwt = require ( 'jsonwebtoken' ) ;
var token = jwt . sign ( { foo : 'bar' } , 'shhhhh' ) ;علامة متزامنة مع RSA SHA256
// sign with RSA SHA256
var privateKey = fs . readFileSync ( 'private.key' ) ;
var token = jwt . sign ( { foo : 'bar' } , privateKey , { algorithm : 'RS256' } ) ;التوقيع بشكل غير متزامن
jwt . sign ( { foo : 'bar' } , privateKey , { algorithm : 'RS256' } , function ( err , token ) {
console . log ( token ) ;
} ) ;تاريخ خلفي JWT 30 ثانية
var older_token = jwt . sign ( { foo : 'bar' , iat : Math . floor ( Date . now ( ) / 1000 ) - 30 } , 'shhhhh' ) ; يحدد معيار JWT مطالبة انتهاء exp . يتم تمثيل انتهاء الصلاحية كـ NumericDate :
قيمة رقمية JSON تمثل عدد الثواني من 1970-01-01T00:00:00Z UTC حتى تاريخ/وقت UTC المحدد، مع تجاهل الثواني الكبيسة. وهذا يعادل تعريف IEEE Std 1003.1, 2013 Edition [POSIX.1] "الثواني منذ العصر"، حيث يتم حساب كل يوم بـ 86400 ثانية بالضبط، بخلاف تلك القيم غير الصحيحة التي يمكن تمثيلها. راجع RFC 3339 [RFC3339] للحصول على تفاصيل بخصوص التاريخ/الأوقات بشكل عام والتوقيت العالمي المنسق (UTC) بشكل خاص.
وهذا يعني أن حقل exp يجب أن يحتوي على عدد الثواني منذ العصر.
توقيع رمز مميز مع انتهاء الصلاحية لمدة ساعة واحدة:
jwt . sign ( {
exp : Math . floor ( Date . now ( ) / 1000 ) + ( 60 * 60 ) ,
data : 'foobar'
} , 'secret' ) ;هناك طريقة أخرى لإنشاء رمز مميز مثل هذا باستخدام هذه المكتبة وهي:
jwt . sign ( {
data : 'foobar'
} , 'secret' , { expiresIn : 60 * 60 } ) ;
//or even better:
jwt . sign ( {
data : 'foobar'
} , 'secret' , { expiresIn : '1h' } ) ;(غير متزامن) إذا تم توفير رد اتصال، تعمل الوظيفة بشكل غير متزامن. يتم استدعاء رد الاتصال باستخدام الحمولة التي تم فك تشفيرها إذا كان التوقيع صالحًا وانتهاء الصلاحية الاختياري أو الجمهور أو المُصدر صالحًا. إذا لم يكن كذلك، سيتم استدعاؤه مع الخطأ.
(متزامن) إذا لم يتم توفير رد اتصال، تعمل الوظيفة بشكل متزامن. إرجاع الحمولة النافعة التي تم فك تشفيرها إذا كان التوقيع صالحًا وانتهاء الصلاحية الاختياري أو الجمهور أو المُصدر صالحًا. إذا لم يكن الأمر كذلك، فإنه سيتم رمي الخطأ.
تحذير: عندما يأتي الرمز من مصدر غير موثوق به (على سبيل المثال، إدخال المستخدم أو الطلبات الخارجية)، يجب التعامل مع الحمولة النافعة التي تم فك تشفيرها مثل أي إدخال مستخدم آخر؛ يرجى التأكد من التعقيم والعمل فقط مع الخصائص المتوقعة
token هو سلسلة JsonWebToken
secretOrPublicKey عبارة عن سلسلة (بترميز utf-8)، أو مخزن مؤقت، أو KeyObject تحتوي إما على سر خوارزميات HMAC، أو المفتاح العام المشفر PEM لـ RSA وECDSA. إذا تم استدعاء jwt.verify غير متزامن، فيمكن أن يكون secretOrPublicKey دالة يجب أن تجلب المفتاح السري أو المفتاح العام. انظر أدناه للحصول على مثال مفصل
كما هو مذكور في هذا التعليق، هناك مكتبات أخرى تتوقع أسرارًا مشفرة باستخدام base64 (بايت عشوائي مشفرة باستخدام base64)، إذا كانت هذه هي حالتك، فيمكنك تمرير Buffer.from(secret, 'base64') ، ومن خلال القيام بذلك سيتم فك تشفير السر باستخدام base64 وسيستخدم التحقق من الرمز المميز البايتات العشوائية الأصلية.
options
algorithms : قائمة السلاسل بأسماء الخوارزميات المسموح بها. على سبيل المثال، ["HS256", "HS384"] .إذا لم يتم تحديدها، فسيتم استخدام الإعدادات الافتراضية بناءً على نوع المفتاح المقدم
- سر - ['HS256'، 'HS384'، 'HS512']
- آر إس إيه - ['RS256'، 'RS384'، 'RS512']
- المفوضية الأوروبية - ['ES256'، 'ES384'، 'ES512']
- الافتراضي - ['RS256'، 'RS384'، 'RS512']
audience : إذا كنت تريد التحقق من الجمهور ( aud ) ، فقم بتوفير قيمة هنا. يمكن التحقق من الجمهور مقابل سلسلة أو تعبير عادي أو قائمة سلاسل و/أو تعبيرات عادية.على سبيل المثال:
"urn:foo",/urn:f[o]{2}/,[/urn:f[o]{2}/, "urn:bar"]
complete : قم بإرجاع كائن مع { payload, header, signature } الذي تم فك تشفيره بدلاً من المحتوى المعتاد للحمولة فقط.issuer (اختياري): سلسلة أو مجموعة من السلاسل ذات القيم الصالحة لحقل iss .jwtid (اختياري): إذا كنت تريد التحقق من معرف JWT ( jti )، فقم بتوفير قيمة سلسلة هنا.ignoreExpiration : إذا كان true فلا تتحقق من صحة انتهاء صلاحية الرمز المميز.ignoreNotBefore ...subject : إذا كنت تريد التحقق من الموضوع ( sub )، فقم بتوفير قيمة هناclockTolerance : عدد الثواني التي يجب تحملها عند التحقق من مطالبات nbf و exp ، للتعامل مع الاختلافات الصغيرة في الساعة بين الخوادم المختلفةmaxAge : الحد الأقصى لعمر الرموز المميزة حتى تظل صالحة. يتم التعبير عنها بالثواني أو بسلسلة تصف فترة زمنية vercel/ms.على سبيل المثال:
1000،"2 days"،"10h"،"7d". يتم تفسير القيمة الرقمية على أنها عدد الثواني. إذا كنت تستخدم سلسلة فتأكد من توفير وحدات الوقت (الأيام والساعات وما إلى ذلك)، وإلا فسيتم استخدام وحدة المللي ثانية افتراضيًا ("120"تساوي"120ms").
clockTimestamp : الوقت بالثواني الذي يجب استخدامه كالوقت الحالي لجميع المقارنات الضرورية.nonce : إذا كنت تريد التحقق من مطالبة nonce ، فقم بتوفير قيمة سلسلة هنا. يتم استخدامه على Open ID لرموز المعرف. (ملاحظات تنفيذ معرف مفتوح)allowInvalidAsymmetricKeyTypes : إذا كان صحيحًا، فإنه يسمح بالمفاتيح غير المتماثلة التي لا تتطابق مع الخوارزمية المحددة. هذا الخيار مخصص فقط للتوافق مع الإصدارات السابقة ويجب تجنبه. // verify a token symmetric - synchronous
var decoded = jwt . verify ( token , 'shhhhh' ) ;
console . log ( decoded . foo ) // bar
// verify a token symmetric
jwt . verify ( token , 'shhhhh' , function ( err , decoded ) {
console . log ( decoded . foo ) // bar
} ) ;
// invalid token - synchronous
try {
var decoded = jwt . verify ( token , 'wrong-secret' ) ;
} catch ( err ) {
// err
}
// invalid token
jwt . verify ( token , 'wrong-secret' , function ( err , decoded ) {
// err
// decoded undefined
} ) ;
// verify a token asymmetric
var cert = fs . readFileSync ( 'public.pem' ) ; // get public key
jwt . verify ( token , cert , function ( err , decoded ) {
console . log ( decoded . foo ) // bar
} ) ;
// verify audience
var cert = fs . readFileSync ( 'public.pem' ) ; // get public key
jwt . verify ( token , cert , { audience : 'urn:foo' } , function ( err , decoded ) {
// if audience mismatch, err == invalid audience
} ) ;
// verify issuer
var cert = fs . readFileSync ( 'public.pem' ) ; // get public key
jwt . verify ( token , cert , { audience : 'urn:foo' , issuer : 'urn:issuer' } , function ( err , decoded ) {
// if issuer mismatch, err == invalid issuer
} ) ;
// verify jwt id
var cert = fs . readFileSync ( 'public.pem' ) ; // get public key
jwt . verify ( token , cert , { audience : 'urn:foo' , issuer : 'urn:issuer' , jwtid : 'jwtid' } , function ( err , decoded ) {
// if jwt id mismatch, err == invalid jwt id
} ) ;
// verify subject
var cert = fs . readFileSync ( 'public.pem' ) ; // get public key
jwt . verify ( token , cert , { audience : 'urn:foo' , issuer : 'urn:issuer' , jwtid : 'jwtid' , subject : 'subject' } , function ( err , decoded ) {
// if subject mismatch, err == invalid subject
} ) ;
// alg mismatch
var cert = fs . readFileSync ( 'public.pem' ) ; // get public key
jwt . verify ( token , cert , { algorithms : [ 'RS256' ] } , function ( err , payload ) {
// if token alg != RS256, err == invalid signature
} ) ;
// Verify using getKey callback
// Example uses https://github.com/auth0/node-jwks-rsa as a way to fetch the keys.
var jwksClient = require ( 'jwks-rsa' ) ;
var client = jwksClient ( {
jwksUri : 'https://sandrino.auth0.com/.well-known/jwks.json'
} ) ;
function getKey ( header , callback ) {
client . getSigningKey ( header . kid , function ( err , key ) {
var signingKey = key . publicKey || key . rsaPublicKey ;
callback ( null , signingKey ) ;
} ) ;
}
jwt . verify ( token , getKey , options , function ( err , decoded ) {
console . log ( decoded . foo ) // bar
} ) ;(متزامن) يُرجع الحمولة النافعة التي تم فك تشفيرها دون التحقق من صحة التوقيع.
تحذير: لن يتم التحقق من صحة التوقيع. يجب ألا تستخدم هذا للرسائل غير الموثوق بها. أنت على الأرجح تريد استخدام
jwt.verifyبدلاً من ذلك.
تحذير: عندما يأتي الرمز من مصدر غير موثوق به (على سبيل المثال إدخال المستخدم أو طلب خارجي)، يجب التعامل مع الحمولة النافعة التي تم فك تشفيرها مثل أي إدخال مستخدم آخر؛ يرجى التأكد من التعقيم والعمل فقط مع الخصائص المتوقعة
token هو سلسلة JsonWebToken
options :
json : فرض JSON.parse على الحمولة حتى لو كان الرأس لا يحتوي على "typ":"JWT" .complete : قم بإرجاع كائن مع الحمولة والرأس الذي تم فك تشفيره.مثال
// get the decoded payload ignoring signature, no secretOrPrivateKey needed
var decoded = jwt . decode ( token ) ;
// get the decoded payload and header
var decoded = jwt . decode ( token , { complete : true } ) ;
console . log ( decoded . header ) ;
console . log ( decoded . payload ) الأخطاء المحتملة التي تم إلقاؤها أثناء التحقق. الخطأ هو الوسيطة الأولى لاستدعاء التحقق.
تم طرح خطأ في حالة انتهاء صلاحية الرمز المميز.
كائن الخطأ:
jwt . verify ( token , 'shhhhh' , function ( err , decoded ) {
if ( err ) {
/*
err = {
name: 'TokenExpiredError',
message: 'jwt expired',
expiredAt: 1408621000
}
*/
}
} ) ;كائن الخطأ:
. ) jwt . verify ( token , 'shhhhh' , function ( err , decoded ) {
if ( err ) {
/*
err = {
name: 'JsonWebTokenError',
message: 'jwt malformed'
}
*/
}
} ) ;يتم طرحه إذا كان الوقت الحالي قبل المطالبة بـ nbf.
كائن الخطأ:
jwt . verify ( token , 'shhhhh' , function ( err , decoded ) {
if ( err ) {
/*
err = {
name: 'NotBeforeError',
message: 'jwt not active',
date: 2018-10-04T16:10:44.000Z
}
*/
}
} ) ; مجموعة من الخوارزميات المدعومة. الخوارزميات التالية مدعومة حاليًا.
| قيمة المعلمة alg | التوقيع الرقمي أو خوارزمية MAC |
|---|---|
| HS256 | HMAC باستخدام خوارزمية التجزئة SHA-256 |
| HS384 | HMAC باستخدام خوارزمية التجزئة SHA-384 |
| HS512 | HMAC باستخدام خوارزمية التجزئة SHA-512 |
| RS256 | RSASSA-PKCS1-v1_5 باستخدام خوارزمية التجزئة SHA-256 |
| RS384 | RSASSA-PKCS1-v1_5 باستخدام خوارزمية التجزئة SHA-384 |
| RS512 | RSASSA-PKCS1-v1_5 باستخدام خوارزمية التجزئة SHA-512 |
| PS256 | RSASSA-PSS باستخدام خوارزمية التجزئة SHA-256 (العقدة فقط ^6.12.0 أو >=8.0.0) |
| PS384 | RSASSA-PSS باستخدام خوارزمية التجزئة SHA-384 (العقدة فقط ^6.12.0 أو >=8.0.0) |
| PS512 | RSASSA-PSS باستخدام خوارزمية التجزئة SHA-512 (العقدة فقط ^6.12.0 أو >=8.0.0) |
| ES256 | ECDSA باستخدام منحنى P-256 وخوارزمية التجزئة SHA-256 |
| ES384 | ECDSA باستخدام منحنى P-384 وخوارزمية التجزئة SHA-384 |
| ES512 | ECDSA باستخدام منحنى P-521 وخوارزمية التجزئة SHA-512 |
| لا أحد | لم يتم تضمين التوقيع الرقمي أو قيمة MAC |
أولاً، ننصحك بالتفكير مليًا إذا كان التحديث التلقائي لـ JWT لن يؤدي إلى ظهور أي ثغرة أمنية في نظامك.
نحن لسنا مرتاحين لتضمين هذا كجزء من المكتبة، ومع ذلك، يمكنك إلقاء نظرة على هذا المثال لإظهار كيف يمكن تحقيق ذلك. وبصرف النظر عن هذا المثال، هناك مشكلة وطلب سحب للحصول على مزيد من المعرفة حول هذا الموضوع.
إذا وجدت خطأ ما أو إذا كان لديك طلب ميزة، فيرجى الإبلاغ عنه في قسم مشكلات المستودع هذا. يرجى عدم الإبلاغ عن الثغرات الأمنية في متتبع مشكلات GitHub العام. يوضح برنامج الإفصاح المسؤول تفاصيل إجراءات الكشف عن المشكلات الأمنية.
مصادقة0
هذا المشروع مرخص بموجب ترخيص MIT. راجع ملف الترخيص لمزيد من المعلومات.
