Загрузка узла jsonwebtoken - Загрузка исходного кода узла jsonwebtoken

узел jsonwebtoken

Другой исходный код

1.0.0

Скачать

jsonwebtoken

Строить	Зависимость

Реализация веб-токенов JSON.

Он был разработан на основе draft-ietf-oauth-json-web-token-08 . Он использует node-jws

Установить

 $ npm установить jsonwebtoken

Примечания по миграции

С v8 на v9
С v7 на v8

Использование

jwt.sign(payload, secretOrPrivateKey, [опции, обратный вызов])

(Асинхронный) Если предоставлен обратный вызов, обратный вызов вызывается с 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 : выражается в секундах или строке, описывающей интервал времени версель/мс.
Например: 60 , "2 days" , "10h" , "7d" . Числовое значение интерпретируется как количество секунд. Если вы используете строку, обязательно укажите единицы времени (дни, часы и т. д.), в противном случае по умолчанию используется миллисекунда ( "120" равно "120ms" ).
notBefore : выражается в секундах или строке, описывающей интервал времени vercel/ms.
Например: 60 , "2 days" , "10h" , "7d" . Числовое значение интерпретируется как количество секунд. Если вы используете строку, обязательно укажите единицы времени (дни, часы и т. д.), в противном случае по умолчанию используется миллисекунда ( "120" равно "120ms" ).
audience
issuer
jwtid
subject
noTimestamp
header
keyid
mutatePayload : если true, функция знака будет напрямую изменять объект полезной нагрузки. Это полезно, если вам нужна необработанная ссылка на полезные данные после того, как к ним были применены утверждения, но до того, как они были закодированы в токен.
allowInsecureKeySizes : если true, разрешает использование закрытых ключей с модулем ниже 2048 для RSA.
allowInvalidAsymmetricKeyTypes : если true, разрешает асимметричные ключи, которые не соответствуют указанному алгоритму. Эта опция предназначена только для обратной совместимости, и ее следует избегать.

Значения по умолчанию для 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

 // подписываем с помощью RSA SHA256var PrivateKey = fs.readFileSync('private.key');var token = jwt.sign({ foo: 'bar' }, PrivateKey, { алгоритм: 'RS256' });

Подписывать асинхронно

 jwt.sign({ foo: 'bar' }, PrivateKey, {алгоритм: 'RS256' }, function(err, token) {
  console.log(токен);});

Задняя дата jwt 30 секунд

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

Срок действия токена (заявка на получение опыта)

Стандарт JWT определяет требование об истечении срока exp . Срок действия представлен как NumericDate :

Числовое значение JSON, представляющее количество секунд с 1970-01-01T00:00:00Z UTC до указанной даты/времени UTC, игнорируя дополнительные секунды. Это эквивалентно определению «Секунды с начала эпохи» в стандарте IEEE 1003.1, издание 2013 г. [POSIX.1], в котором каждый день составляет ровно 86400 секунд, за исключением того, что могут быть представлены нецелые значения. См. RFC 3339 [RFC3339] для получения подробной информации о дате/времени в целом и UTC в частности.

Это означает, что поле exp должно содержать количество секунд, прошедших с начала эпохи.

Подписание токена со сроком действия 1 час:

 jwt.sign({
  exp: Math.floor(Date.now() / 1000) + (60 * 60),
  данные: 'foobar'}, 'секрет');

Другой способ создать такой токен с помощью этой библиотеки:

 jwt.sign({
  data: 'foobar'}, 'secret', { expiresIn: 60 * 60 });//или еще лучше: jwt.sign({
  данные: 'foobar'}, 'secret', { expiresIn: '1h' });

jwt.verify(токен, secretOrPublicKey, [опции, обратный вызов])

(Асинхронный) Если указан обратный вызов, функция действует асинхронно. Обратный вызов вызывается с декодированными полезными данными, если подпись действительна и необязательный срок действия, аудитория или эмитент действительны. В противном случае он будет вызван с ошибкой.

(Синхронный) Если обратный вызов не указан, функция действует синхронно. Возвращает декодированные полезные данные, если подпись действительна и необязательный срок действия, аудитория или эмитент действительны. Если нет, то выдаст ошибку.

Предупреждение. Когда токен поступает из ненадежного источника (например, пользовательский ввод или внешние запросы), возвращаемые декодированные полезные данные следует обрабатывать как любой другой пользовательский ввод; пожалуйста, обязательно продезинфицируйте и работайте только с ожидаемыми свойствами

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']
rsa — ['RS256', 'RS384', 'RS512']
ec - ['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 : максимально допустимый возраст, в течение которого токены остаются действительными. Выражается в секундах или строке, описывающей интервал времени в верселях/мс.
Например: 1000 , "2 days" , "10h" , "7d" . Числовое значение интерпретируется как количество секунд. Если вы используете строку, обязательно укажите единицы времени (дни, часы и т. д.), в противном случае по умолчанию используется миллисекунда ( "120" равно "120ms" ).
clockTimestamp : время в секундах, которое следует использовать в качестве текущего времени для всех необходимых сравнений.
nonce : если вы хотите проверить утверждение nonce , укажите здесь строковое значение. Он используется в Open ID для токенов ID. (Примечания по реализации Open ID)
allowInvalidAsymmetricKeyTypes : если true, разрешает асимметричные ключи, которые не соответствуют указанному алгоритму. Эта опция предназначена только для обратной совместимости, и ее следует избегать.

 // проверяем токен симметрично - synchronousvar decoded = jwt.verify(token, 'shhhhh');console.log(decoded.foo) // bar// проверяем токен symmetricjwt.verify(token, 'shhhhh', function(err , декодировано) {
  console.log(decoded.foo) // bar});// неверный токен - synchronoustry {
  var decoded = jwt.verify(token, 'неправильный секрет');} catch(err) {
  // ошибка}// неверный токенjwt.verify(token, 'wrong-secret', function(err, decoded) {
  // ошибка
  // декодировано неопределенное});// проверяем токен asymmetricvar cert = fs.readFileSync('public.pem');  // получаем открытый ключjwt.verify(token, cert, function(err, decoded) {
  console.log(decoded.foo) // bar});// проверяем аудиториюvar cert = fs.readFileSync('public.pem');  // получаем открытый ключjwt.verify(token, cert, { Audience: 'urn:foo' }, function(err, decoded) {
  // если аудитория не соответствует, err == недопустимая аудитория}); // проверка Issuervar cert = fs.readFileSync('public.pem');  // получаем открытый ключjwt.verify(token, cert, { аудитория: 'urn:foo', эмитент: 'urn:issuer' }, function(err, decoded) {
  // если эмитент не совпадает, err == неверный эмитент}); // проверяем jwt idvar cert = fs.readFileSync('public.pem'); // проверяем jwt idvar cert = fs.readFileSync('public.pem');  // получаем открытый ключjwt.verify(token, cert, { Audience: 'urn:foo', Issuer: 'urn:issuer', jwtid: 'jwtid' }, function(err, decoded) {
  // если идентификатор jwt не совпадает, err == неверный идентификатор jwt});// проверяем subjectvar cert = fs.readFileSync('public.pem');  // получаем открытый ключjwt.verify(token, cert, { Audience: 'urn:foo', Issuer: 'urn:issuer', jwtid: 'jwtid', subject: 'subject' }, function(err, decoded) {
  // если тема не совпадает, err == неверная тема});// alg mismatchvar cert = fs.readFileSync('public.pem'); // получаем открытый ключjwt.verify(token, cert, { алгоритмы: ['RS256'] }, function (err, payload) {
  // if token alg != RS256, err == неверная подпись});// Проверка с помощью обратного вызова getKey // В примере используется https://github.com/auth0/node-jwks-rsa как способ получения ключей. 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, не проверяя его? (Нажмите, чтобы развернуть)

jwt.decode(токен [, параметры])

(Синхронный) Возвращает декодированные полезные данные без проверки правильности подписи.

Предупреждение. Это не позволит проверить действительность подписи. Не следует использовать это для ненадежных сообщений. Скорее всего, вместо этого вы захотите использовать jwt.verify .

Предупреждение. Когда токен поступает из ненадежного источника (например, пользовательского ввода или внешнего запроса), возвращаемые декодированные полезные данные следует обрабатывать как любой другой пользовательский ввод; пожалуйста, обязательно продезинфицируйте и работайте только с ожидаемыми свойствами

token — это строка JsonWebToken.

options :

json : принудительно использовать JSON.parse для полезных данных, даже если заголовок не содержит "typ":"JWT" .
complete : вернуть объект с декодированными полезными данными и заголовком.

Пример

 // получаем декодированную полезную нагрузку, игнорируя подпись, secretOrPrivateKey не требуетсяvar decoded = jwt.decode(token);// получаем декодированную полезную нагрузку и headervar decoded = jwt.decode(token, {complete: true});console.log(decoded. заголовок);console.log(decoded.payload)

Ошибки и коды

Возможные ошибки при проверке. Ошибка — это первый аргумент обратного вызова проверки.

TokenExpiredError

Выдается ошибка, если срок действия токена истек.

Объект ошибки:

имя: 'TokenExpiredError'
сообщение: «Срок действия jwt истек»
Срок действия истек: [ExpDate]

 jwt.verify(token, 'shhhhh', function(err, decoded) {
  if (err) {/* err = { name: 'TokenExpiredError', message: 'jwt expired', expiredAt: 1408621000 } */
  }});

JsonWebTokenError

Объект ошибки:

имя: 'JsonWebTokenError'
сообщение:

«неверный токен» — заголовок или полезная нагрузка не могут быть проанализированы
«jwt неверный формат» — токен не имеет трех компонентов (разделенных . ).
'требуется подпись jwt'
«неверная подпись»
'jwt аудитория недействительна. ожидается: [ВАРИАНТЫ АУДИТОРИИ]'
'эмитент jwt недействителен. ожидается: [ОПЦИИ ВЫСТАВЩИКА]'
'jwt идентификатор недействителен. ожидается: [ОПЦИИ JWT ID]'
'jwt тема недействительна. ожидается: [ОПЦИИ ТЕМА]'

 jwt.verify(token, 'shhhhh', function(err, decoded) {
  if (err) {/* err = { name: 'JsonWebTokenError', message: 'jwt Malformed' } */
  }});

Нотбефореррор

Вызывается, если текущее время предшествует требованию nbf.

Объект ошибки:

имя: 'NotBeforeError'
сообщение: «jwt не активен»
дата: 2018-10-04T16:10:44.000Z

 jwt.verify(token, 'shhhhh', function(err, decoded) {
  if (err) {/* err = { name: 'NotBeforeError', сообщение: 'jwt не активен', дата: 2018-10-04T16:10:44.000Z } */
  }});

Поддерживаемые алгоритмы

Массив поддерживаемых алгоритмов. В настоящее время поддерживаются следующие алгоритмы.

Значение параметра alg	Цифровая подпись или алгоритм MAC
ХС256	HMAC с использованием алгоритма хеширования SHA-256
ХС384	HMAC с использованием алгоритма хеширования SHA-384
ХС512	HMAC с использованием алгоритма хеширования SHA-512
RS256	RSASSA-PKCS1-v1_5 с использованием алгоритма хеширования SHA-256
RS384	RSASSA-PKCS1-v1_5 с использованием алгоритма хеширования SHA-384
RS512	RSASSA-PKCS1-v1_5 с использованием алгоритма хеширования SHA-512
ПС256	RSASSA-PSS с использованием алгоритма хэширования SHA-256 (только узел ^6.12.0 ИЛИ >=8.0.0)
ПС384	RSASSA-PSS с использованием алгоритма хеширования SHA-384 (только узел ^6.12.0 ИЛИ >=8.0.0)
ПС512	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

Прежде всего, мы рекомендуем вам тщательно подумать, не приведет ли автоматическое обновление JWT к какой-либо уязвимости в вашей системе.

Нам неудобно включать это в библиотеку, однако вы можете взглянуть на этот пример, чтобы показать, как это можно сделать. Помимо этого примера, есть проблема и запрос на включение, чтобы получить больше знаний по этой теме.

TODO

Цепочка сертификатов X.509 не проверяется

Отчеты о проблемах

Если вы обнаружили ошибку или у вас есть запрос на добавление функции, сообщите об этом в разделе проблем с репозиторием. Пожалуйста, не сообщайте об уязвимостях безопасности в общедоступном трекере проблем GitHub. Программа ответственного раскрытия подробно описывает процедуру раскрытия проблем безопасности.