Unduh node jsonwebtoken - pengunduhan kode sumber node jsonwebtoken

simpul jsonwebtoken

Kode sumber lainnya

1.0.0

Unduh

jsonwebtoken

Membangun	Ketergantungan

Implementasi Token Web JSON.

Ini dikembangkan terhadap draft-ietf-oauth-json-web-token-08 . Itu menggunakan node-jws

Memasang

 $ npm instal jsonwebtoken

Catatan migrasi

Dari v8 hingga v9
Dari v7 hingga v8

Penggunaan

jwt.sign(payload, secretOrPrivateKey, [opsi, panggilan balik])

(Asynchronous) Jika panggilan balik diberikan, panggilan balik tersebut dipanggil dengan err atau JWT.

(Sinkron) Mengembalikan JsonWebToken sebagai string

payload bisa berupa objek literal, buffer, atau string yang mewakili JSON yang valid.

Harap dicatat bahwa exp atau klaim lainnya hanya ditetapkan jika muatannya adalah objek literal. Payload buffer atau string tidak diperiksa validitas JSONnya.

Jika payload bukan buffer atau string, payload akan dipaksa menjadi string menggunakan JSON.stringify .

secretOrPrivateKey adalah string (yang dikodekan utf-8), buffer, objek, atau KeyObject yang berisi rahasia untuk algoritme HMAC atau kunci pribadi yang dikodekan PEM untuk RSA dan ECDSA. Dalam hal kunci pribadi dengan frasa sandi, objek { key, passphrase } dapat digunakan (berdasarkan dokumentasi kripto), dalam hal ini pastikan Anda meneruskan opsi algorithm . Saat menandatangani dengan algoritme RSA, panjang modulus minimum adalah 2048 kecuali jika opsiallowInsecureKeySizes disetel ke true. Kunci pribadi di bawah ukuran ini akan ditolak karena kesalahan.

options :

algorithm (default: HS256 )
expiresIn : dinyatakan dalam detik atau string yang menjelaskan rentang waktu vercel/ms.
Misalnya: 60 , "2 days" , "10h" , "7d" . Nilai numerik diartikan sebagai hitungan detik. Jika Anda menggunakan string, pastikan Anda memberikan satuan waktu (hari, jam, dll), jika tidak, satuan milidetik digunakan secara default ( "120" sama dengan "120ms" ).
notBefore : dinyatakan dalam detik atau string yang menjelaskan rentang waktu vercel/ms.
Misalnya: 60 , "2 days" , "10h" , "7d" . Nilai numerik diartikan sebagai hitungan detik. Jika Anda menggunakan string, pastikan Anda memberikan satuan waktu (hari, jam, dll), jika tidak, satuan milidetik digunakan secara default ( "120" sama dengan "120ms" ).
audience
issuer
jwtid
subject
noTimestamp
header
keyid
mutatePayload : jika benar, fungsi tanda akan memodifikasi objek payload secara langsung. Hal ini berguna jika Anda memerlukan referensi mentah ke payload setelah klaim diterapkan padanya tetapi sebelum dikodekan menjadi token.
allowInsecureKeySizes : jika benar mengizinkan kunci pribadi dengan modulus di bawah 2048 digunakan untuk RSA
allowInvalidAsymmetricKeyTypes : jika benar, mengizinkan kunci asimetris yang tidak cocok dengan algoritma yang ditentukan. Opsi ini ditujukan hanya untuk kompatibilitas ke belakang dan harus dihindari.

Tidak ada nilai default untuk expiresIn , notBefore , audience , subject , issuer . Klaim ini juga dapat diberikan dalam payload secara langsung dengan exp , nbf , aud , sub dan iss masing-masing, tetapi Anda tidak dapat menyertakan di kedua tempat tersebut.

Ingatlah bahwa exp , nbf dan iat adalah NumericDate , lihat Kedaluwarsa Token terkait (klaim exp)

Header dapat dikustomisasi melalui objek options.header .

Jwts yang dihasilkan akan menyertakan klaim iat (dikeluarkan pada) secara default kecuali noTimestamp ditentukan. Jika iat dimasukkan ke dalam payload, ia akan digunakan sebagai pengganti stempel waktu sebenarnya untuk menghitung hal-hal lain seperti exp dengan rentang waktu di options.expiresIn .

Tanda Sinkron dengan default (HMAC SHA256)

 var jwt = memerlukan('jsonwebtoken');var token = jwt.sign({ foo: 'bar' }, 'shhhhh');

Tanda Sinkron dengan RSA SHA256

 // masuk dengan RSA SHA256var privateKey = fs.readFileSync('private.key');var token = jwt.sign({ foo: 'bar' }, privateKey, { algoritma: 'RS256' });

Masuk secara asinkron

 jwt.sign({ foo: 'bar' }, privateKey, { algoritma: 'RS256' }, function(err, token) {
  konsol.log(token);});

Tanggal mundur jwt 30 detik

 var old_token = jwt.sign({ foo: 'bar', iat: Math.floor(Date.now() / 1000) - 30 }, 'shhhhh');

Kedaluwarsa Token (klaim exp)

Standar JWT mendefinisikan klaim exp untuk kedaluwarsa. Kedaluwarsa direpresentasikan sebagai NumericDate :

Nilai numerik JSON yang mewakili jumlah detik dari 01-01-1970T00:00:00Z UTC hingga tanggal/waktu UTC yang ditentukan, mengabaikan detik kabisat. Ini setara dengan definisi IEEE Std 1003.1, 2013 Edition [POSIX.1] "Seconds Since the Epoch", yang mana setiap hari dihitung tepat 86400 detik, selain itu nilai non-integer dapat direpresentasikan. Lihat RFC 3339 [RFC3339] untuk rincian mengenai tanggal/waktu secara umum dan UTC pada khususnya.

Artinya kolom exp harus berisi jumlah detik sejak epoch.

Menandatangani token dengan masa berlaku 1 jam:

 jwt.tanda({
  contoh: Math.floor(Tanggal.sekarang() / 1000) + (60 * 60),
  data: 'foobar'}, 'rahasia');

Cara lain untuk menghasilkan token seperti ini dengan perpustakaan ini adalah:

 jwt.tanda({
  data: 'foobar'}, 'secret', { expiredIn: 60 * 60 });//atau lebih baik lagi:jwt.sign({
  data: 'foobar'}, 'rahasia', { expiredIn: '1h' });

jwt.verify(token, secretOrPublicKey, [opsi, panggilan balik])

(Asynchronous) Jika panggilan balik diberikan, fungsi bertindak secara asinkron. Callback dipanggil dengan payload yang didekodekan jika tanda tangan valid dan masa berlaku opsional, audiens, atau penerbit valid. Jika tidak, maka akan dipanggil dengan error.

(Sinkron) Jika panggilan balik tidak diberikan, fungsi bertindak secara sinkron. Mengembalikan payload yang didekodekan jika tanda tangan valid dan masa berlaku opsional, audiens, atau penerbit valid. Jika tidak, maka akan muncul kesalahan.

Peringatan: Jika token berasal dari sumber yang tidak tepercaya (misalnya masukan pengguna atau permintaan eksternal), payload dekode yang dikembalikan harus diperlakukan seperti masukan pengguna lainnya; harap pastikan untuk melakukan sanitasi dan hanya bekerja dengan properti yang diharapkan

token adalah string JsonWebToken

secretOrPublicKey adalah string (berkode utf-8), buffer, atau KeyObject yang berisi rahasia untuk algoritma HMAC, atau kunci publik yang dikodekan PEM untuk RSA dan ECDSA. Jika jwt.verify disebut asynchronous, secretOrPublicKey dapat berupa fungsi yang harus mengambil rahasia atau kunci publik. Lihat di bawah untuk contoh detailnya

Seperti yang disebutkan dalam komentar ini, ada perpustakaan lain yang mengharapkan rahasia yang disandikan base64 (byte acak yang disandikan menggunakan base64), jika itu kasus Anda, Anda dapat meneruskan Buffer.from(secret, 'base64') , dengan melakukan ini rahasianya akan didekodekan menggunakan base64 dan verifikasi token akan menggunakan byte acak asli.

options

algorithms : Daftar string dengan nama algoritma yang diizinkan. Misalnya, ["HS256", "HS384"] .
Jika tidak ditentukan, default akan digunakan berdasarkan jenis kunci yang disediakan

rahasia - ['HS256', 'HS384', 'HS512']
rsa - ['RS256', 'RS384', 'RS512']
ec - ['ES256', 'ES384', 'ES512']
bawaan - ['RS256', 'RS384', 'RS512']

audience : jika Anda ingin memeriksa audiens ( aud ), berikan nilai di sini. Audiens dapat diperiksa berdasarkan string, ekspresi reguler, atau daftar string dan/atau ekspresi reguler.
Misalnya: "urn:foo" , /urn:f[o]{2}/ , [/urn:f[o]{2}/, "urn:bar"]
complete : mengembalikan objek dengan { payload, header, signature } yang didekodekan, bukan hanya konten payload biasa.
issuer (opsional): string atau larik string dengan nilai yang valid untuk bidang iss .
jwtid (opsional): jika Anda ingin memeriksa ID JWT ( jti ), berikan nilai string di sini.
ignoreExpiration : jika true jangan validasi masa berlaku token.
ignoreNotBefore ...
subject : jika ingin memeriksa subject ( sub ), berikan nilai di sini
clockTolerance : jumlah detik yang dapat ditoleransi ketika memeriksa klaim nbf dan exp , untuk menangani perbedaan jam yang kecil di antara server yang berbeda
maxAge : usia maksimum yang diperbolehkan agar token masih valid. Hal ini dinyatakan dalam detik atau string yang menggambarkan rentang waktu vercel/ms.
Misalnya: 1000 , "2 days" , "10h" , "7d" . Nilai numerik diartikan sebagai hitungan detik. Jika Anda menggunakan string, pastikan Anda memberikan satuan waktu (hari, jam, dll), jika tidak, satuan milidetik digunakan secara default ( "120" sama dengan "120ms" ).
clockTimestamp : waktu dalam detik yang harus digunakan sebagai waktu saat ini untuk semua perbandingan yang diperlukan.
nonce : jika Anda ingin memeriksa klaim nonce , berikan nilai string di sini. Ini digunakan pada Open ID untuk Token ID. (Buka catatan implementasi ID)
allowInvalidAsymmetricKeyTypes : jika benar, mengizinkan kunci asimetris yang tidak cocok dengan algoritma yang ditentukan. Opsi ini ditujukan hanya untuk kompatibilitas ke belakang dan harus dihindari.

 // verifikasi token simetris - synchronousvar decode = jwt.verify(token, 'shhhhh');console.log(decoded.foo) // bar// verifikasi token symmetricjwt.verify(token, 'shhhhh', function(err , diterjemahkan) {
  console.log(decoded.foo) // bar});// token tidak valid - synchronoustry {
  var diterjemahkan = jwt.verify(token, 'rahasia-salah');} catch(err) {
  // err}// tokenjwt.verify(token, 'rahasia salah', function(err, diterjemahkan) tidak valid {
  // salah
  // didekodekan undefinisi});// verifikasi token asymmetricvar cert = fs.readFileSync('public.pem');  // dapatkan kunci publikjwt.verify(token, cert, function(err, decode) {
  console.log(decoded.foo) // bar});// verifikasi audiensvar cert = fs.readFileSync('public.pem');  // dapatkan kunci publikjwt.verify(token, cert, { audiens: 'urn:foo' }, function(err, diterjemahkan) {
  // jika audiens tidak cocok, err == audiens tidak valid});// verifikasi issuervar cert = fs.readFileSync('public.pem');  // dapatkan kunci publikjwt.verify(token, cert, { audiens: 'urn:foo', penerbit: 'urn:issuer' }, function(err, diterjemahkan) {
  // jika penerbit tidak cocok, err == penerbit tidak valid});// verifikasi jwt idvar cert = fs.readFileSync('public.pem');  // dapatkan kunci publikjwt.verify(token, cert, { audiens: 'urn:foo', penerbit: 'urn:issuer', jwtid: 'jwtid' }, function(err, diterjemahkan) {
  // jika id jwt tidak cocok, err == id jwt tidak valid});// verifikasi subjectvar cert = fs.readFileSync('public.pem');  // dapatkan kunci publikjwt.verify(token, cert, { audiens: 'urn:foo', penerbit: 'urn:issuer', jwtid: 'jwtid', subjek: 'subjek' }, function(err, diterjemahkan) {
  // jika subjek tidak cocok, err == subjek tidak valid});// alg mismatchvar cert = fs.readFileSync('public.pem'); // dapatkan kunci publikjwt.verify(token, cert, { algoritma: ['RS256'] }, function (err, payload) {
  // jika token alg != RS256, err == tanda tangan tidak valid});// Verifikasi menggunakan panggilan balik getKey// Contoh menggunakan https://github.com/auth0/node-jwks-rsa sebagai cara untuk mengambil kunci. var jwksClient = memerlukan('jwks-rsa');var klien = 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, decode) {
  console.log(decoded.foo) // bar});

Perlu mengintip JWT tanpa memverifikasinya? (Klik untuk memperluas)

jwt.decode(token [, opsi])

(Sinkron) Mengembalikan payload yang didekodekan tanpa memverifikasi apakah tanda tangannya valid.

Peringatan: Ini tidak akan memverifikasi apakah tanda tangan itu valid. Anda tidak boleh menggunakan ini untuk pesan yang tidak tepercaya. Kemungkinan besar Anda ingin menggunakan jwt.verify sebagai gantinya.

Peringatan: Jika token berasal dari sumber yang tidak tepercaya (misalnya masukan pengguna atau permintaan eksternal), payload dekode yang dikembalikan harus diperlakukan seperti masukan pengguna lainnya; harap pastikan untuk melakukan sanitasi dan hanya bekerja dengan properti yang diharapkan

token adalah string JsonWebToken

options :

json : memaksa JSON.parse pada payload meskipun header tidak berisi "typ":"JWT" .
complete : mengembalikan objek dengan payload dan header yang didekodekan.

Contoh

 // dapatkan payload yang didekode dengan mengabaikan tanda tangan, tidak diperlukan secretOrPrivateKeyvar decode = jwt.decode(token);// dapatkan payload yang didekode dan headervar decode = jwt.decode(token, {complete: true});console.log(decoded. header);console.log(decoded.payload)

Kesalahan & Kode

Kemungkinan kesalahan terjadi selama verifikasi. Kesalahan adalah argumen pertama dari panggilan balik verifikasi.

TokenExpiredError

Kesalahan muncul jika token sudah habis masa berlakunya.

Objek kesalahan:

nama: 'TokenExpiredError'
pesan: 'jwt kadaluwarsa'
kadaluarsaPada: [Tanggal Kedaluwarsa]

 jwt.verify(token, 'shhhhh', function(err, diterjemahkan) {
  if (err) {/* err = { nama: 'TokenExpiredError', pesan: 'jwt kadaluarsa', expiredAt: 1408621000 } */
  }});

JsonWebTokenError

Objek kesalahan:

nama: 'JsonWebTokenError'
pesan:

'token tidak valid' - header atau payload tidak dapat diuraikan
'jwt malformed' - token tidak memiliki tiga komponen (dibatasi oleh a . )
'tanda tangan jwt diperlukan'
'tanda tangan tidak sah'
'jwt penonton tidak valid. diharapkan: [OPTIONS AUDIENCE]'
'jwt penerbit tidak valid. diharapkan: [PENERBIT OPSI]'
'jwt id tidak valid. diharapkan: [ID JWT OPSI]'
'jwt subjek tidak valid. diharapkan: [SUBJEK OPSI]'

 jwt.verify(token, 'shhhhh', function(err, diterjemahkan) {
  if (err) {/* err = { nama: 'JsonWebTokenError', pesan: 'jwt salah format' } */
  }});

BukanSebelum Kesalahan

Dilempar jika waktu saat ini sebelum klaim nbf.

Objek kesalahan:

nama: 'Tidak Sebelum Kesalahan'
pesan: 'jwt tidak aktif'
tanggal: 04-10-2018T16:10:44.000Z

 jwt.verify(token, 'shhhhh', function(err, diterjemahkan) {
  if (err) {/* err = { nama: 'NotBeforeError', pesan: 'jwt tidak aktif', tanggal: 04-10-2018T16:10:44.000Z } */
  }});

Algoritma didukung

Berbagai algoritma yang didukung. Algoritme berikut saat ini didukung.

alg Nilai Parameter	Tanda Tangan Digital atau Algoritma MAC
HS256	HMAC menggunakan algoritma hash SHA-256
HS384	HMAC menggunakan algoritma hash SHA-384
HS512	HMAC menggunakan algoritma hash SHA-512
RS256	RSASSA-PKCS1-v1_5 menggunakan algoritma hash SHA-256
RS384	RSASSA-PKCS1-v1_5 menggunakan algoritma hash SHA-384
RS512	RSASSA-PKCS1-v1_5 menggunakan algoritma hash SHA-512
PS256	RSASSA-PSS menggunakan algoritma hash SHA-256 (hanya node ^6.12.0 ATAU >=8.0.0)
PS384	RSASSA-PSS menggunakan algoritma hash SHA-384 (hanya node ^6.12.0 ATAU >=8.0.0)
PS512	RSASSA-PSS menggunakan algoritma hash SHA-512 (hanya node ^6.12.0 ATAU >=8.0.0)
ES256	ECDSA menggunakan kurva P-256 dan algoritma hash SHA-256
ES384	ECDSA menggunakan kurva P-384 dan algoritma hash SHA-384
ES512	ECDSA menggunakan kurva P-521 dan algoritma hash SHA-512
tidak ada	Tidak ada tanda tangan digital atau nilai MAC yang disertakan

JWT yang menyegarkan

Pertama-tama, kami menyarankan Anda untuk berpikir hati-hati jika menyegarkan JWT secara otomatis tidak akan menimbulkan kerentanan apa pun di sistem Anda.

Kami merasa tidak nyaman memasukkan ini sebagai bagian dari perpustakaan, namun Anda dapat melihat contoh ini untuk menunjukkan bagaimana hal ini dapat dicapai. Selain contoh tersebut, terdapat masalah dan pull request untuk mendapatkan lebih banyak pengetahuan tentang topik ini.

TODO

Rantai sertifikat X.509 tidak dicentang

Pelaporan Masalah

Jika Anda menemukan bug atau jika Anda memiliki permintaan fitur, silakan laporkan di bagian masalah repositori ini. Harap jangan laporkan kerentanan keamanan pada pelacak masalah GitHub publik. Program Pengungkapan yang Bertanggung Jawab merinci prosedur untuk mengungkapkan masalah keamanan.