Download do nó jsonwebtoken - download do código-fonte do nó jsonwebtoken

nó jsonwebtoken

Outro código-fonte

1.0.0

Baixar

jsonwebtoken

Construir	Dependência

Uma implementação de JSON Web Tokens.

Isso foi desenvolvido em draft-ietf-oauth-json-web-token-08 . Faz uso de node-jws

Instalar

 $ npm instalar jsonwebtoken

Notas de migração

Da v8 à v9
Da v7 à v8

Uso

jwt.sign(carga útil, secretOrPrivateKey, [opções, retorno de chamada])

(Assíncrono) Se um retorno de chamada for fornecido, o retorno de chamada será chamado com err ou JWT.

(Síncrono) Retorna o JsonWebToken como string

payload pode ser um objeto literal, buffer ou string representando JSON válido.

Observe que exp ou qualquer outra declaração só será definida se a carga útil for um objeto literal. Cargas de buffer ou string não são verificadas quanto à validade JSON.

Se payload não for um buffer ou uma string, ela será transformada em uma string usando JSON.stringify .

secretOrPrivateKey é uma string (codificada em utf-8), buffer, objeto ou KeyObject contendo o segredo para algoritmos HMAC ou a chave privada codificada em PEM para RSA e ECDSA. No caso de uma chave privada com senha, um objeto { key, passphrase } pode ser usado (com base na documentação criptográfica), neste caso certifique-se de passar a opção de algorithm . Ao assinar com algoritmos RSA, o comprimento mínimo do módulo é 2.048, exceto quando a opção allowInsecureKeySizes está definida como true. Chaves privadas abaixo deste tamanho serão rejeitadas com erro.

options :

algorithm (padrão: HS256 )
expiresIn : expresso em segundos ou uma string descrevendo um intervalo de tempo vercel/ms.
Ex.: 60 , "2 days" , "10h" , "7d" . Um valor numérico é interpretado como uma contagem de segundos. Se você usar uma string, certifique-se de fornecer as unidades de tempo (dias, horas, etc.), caso contrário, a unidade de milissegundos será usada por padrão ( "120" é igual a "120ms" ).
notBefore : expresso em segundos ou uma string descrevendo um intervalo de tempo vercel/ms.
Ex.: 60 , "2 days" , "10h" , "7d" . Um valor numérico é interpretado como uma contagem de segundos. Se você usar uma string, certifique-se de fornecer as unidades de tempo (dias, horas, etc.), caso contrário, a unidade de milissegundos será usada por padrão ( "120" é igual a "120ms" ).
audience
issuer
jwtid
subject
noTimestamp
header
keyid
mutatePayload : se for verdade, a função de sinal modificará o objeto de carga útil diretamente. Isso é útil se você precisar de uma referência bruta à carga após as declarações terem sido aplicadas a ela, mas antes de ela ter sido codificada em um token.
allowInsecureKeySizes : se verdadeiro permite que chaves privadas com módulo abaixo de 2048 sejam usadas para RSA
allowInvalidAsymmetricKeyTypes : se verdadeiro, permite chaves assimétricas que não correspondem ao algoritmo especificado. Esta opção destina-se apenas à compatibilidade com versões anteriores e deve ser evitada.

Não há valores padrão para expiresIn , notBefore , audience , subject , issuer . Essas declarações também podem ser fornecidas diretamente na carga útil com exp , nbf , aud , sub e iss respectivamente, mas você não pode incluir em ambos os lugares.

Lembre-se de que exp , nbf e iat são NumericDate , consulte Expiração de token relacionada (reivindicação exp)

O cabeçalho pode ser personalizado por meio do objeto options.header .

Os jwts gerados incluirão uma declaração iat (emitida em) por padrão, a menos que noTimestamp seja especificado. Se iat for inserido na carga útil, ele será usado em vez do carimbo de data/hora real para calcular outras coisas, como exp dado um intervalo de tempo em options.expiresIn .

Sinal síncrono com padrão (HMAC SHA256)

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

Sinal Síncrono com RSA SHA256

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

Assinar de forma assíncrona

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

Atualizar um jwt em 30 segundos

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

Expiração do token (reivindicação de exp)

O padrão para JWT define uma declaração exp para expiração. A expiração é representada como NumericDate :

Um valor numérico JSON que representa o número de segundos de 1970-01-01T00:00:00Z UTC até a data/hora UTC especificada, ignorando os segundos bissextos. Isso é equivalente à definição "Segundos desde a época" do IEEE Std 1003.1, 2013 Edition [POSIX.1], em que cada dia é contabilizado por exatamente 86.400 segundos, exceto que valores não inteiros podem ser representados. Consulte RFC 3339 [RFC3339] para obter detalhes sobre data/hora em geral e UTC em particular.

Isso significa que o campo exp deve conter o número de segundos desde a época.

Assinando um token com 1 hora de expiração:

 jwt.sign({
  exp: Math.floor(Data.agora() / 1000) + (60 * 60),
  dados: 'foobar'}, 'secreto');

Outra forma de gerar um token como este com esta biblioteca é:

 jwt.sign({
  data: 'foobar'}, 'secret', { expiresIn: 60 * 60 });//ou melhor ainda:jwt.sign({
  dados: 'foobar'}, 'secreto', { expiraIn: '1h' });

jwt.verify(token, secretOrPublicKey, [opções, retorno de chamada])

(Assíncrono) Se um retorno de chamada for fornecido, a função atuará de forma assíncrona. O retorno de chamada será chamado com a carga útil decodificada se a assinatura for válida e a expiração, o público ou o emissor opcionais forem válidos. Caso contrário, será chamado com o erro.

(Síncrono) Se um retorno de chamada não for fornecido, a função atua de forma síncrona. Retorna a carga útil decodificada se a assinatura for válida e a expiração, o público ou o emissor opcionais forem válidos. Caso contrário, ocorrerá o erro.

Aviso: quando o token vem de uma fonte não confiável (por exemplo, entrada do usuário ou solicitações externas), a carga útil decodificada retornada deve ser tratada como qualquer outra entrada do usuário; certifique-se de higienizar e trabalhar apenas com propriedades esperadas

token é a string JsonWebToken

secretOrPublicKey é uma string (codificada em utf-8), buffer ou KeyObject contendo o segredo para algoritmos HMAC ou a chave pública codificada em PEM para RSA e ECDSA. Se jwt.verify for chamado de assíncrono, secretOrPublicKey pode ser uma função que deve buscar o segredo ou a chave pública. Veja abaixo um exemplo detalhado

Como mencionado neste comentário, existem outras bibliotecas que esperam segredos codificados em base64 (bytes aleatórios codificados em base64), se for esse o seu caso você pode passar Buffer.from(secret, 'base64') , fazendo isso o segredo será decodificado usando base64 e a verificação do token usará os bytes aleatórios originais.

options

algorithms : Lista de strings com os nomes dos algoritmos permitidos. Por exemplo, ["HS256", "HS384"] .
Se não for especificado, um padrão será usado com base no tipo de chave fornecida

segredo - ['HS256', 'HS384', 'HS512']
rsa - ['RS256', 'RS384', 'RS512']
ec - ['ES256', 'ES384', 'ES512']
padrão - ['RS256', 'RS384', 'RS512']

audience : se você quiser verificar o público ( aud ), forneça um valor aqui. O público pode ser verificado em uma string, uma expressão regular ou uma lista de strings e/ou expressões regulares.
Por exemplo: "urn:foo" , /urn:f[o]{2}/ , [/urn:f[o]{2}/, "urn:bar"]
complete : retorna um objeto com o { payload, header, signature } decodificado em vez de apenas o conteúdo usual da carga útil.
issuer (opcional): string ou array de strings de valores válidos para o campo iss .
jwtid (opcional): se você deseja verificar o ID do JWT ( jti ), forneça um valor de string aqui.
ignoreExpiration : se true não valida a expiração do token.
ignoreNotBefore ...
subject : se você quiser verificar subject ( sub ), forneça um valor aqui
clockTolerance : número de segundos a serem tolerados ao verificar as declarações nbf e exp , para lidar com pequenas diferenças de clock entre diferentes servidores
maxAge : a idade máxima permitida para que os tokens ainda sejam válidos. É expresso em segundos ou em uma string que descreve um intervalo de tempo vercel/ms.
Ex: 1000 , "2 days" , "10h" , "7d" . Um valor numérico é interpretado como uma contagem de segundos. Se você usar uma string, certifique-se de fornecer as unidades de tempo (dias, horas, etc.), caso contrário, a unidade de milissegundos será usada por padrão ( "120" é igual a "120ms" ).
clockTimestamp : o tempo em segundos que deve ser usado como hora atual para todas as comparações necessárias.
nonce : se você quiser verificar a reivindicação nonce , forneça um valor de string aqui. É usado no Open ID para os tokens de ID. (Notas de implementação do Open ID)
allowInvalidAsymmetricKeyTypes : se verdadeiro, permite chaves assimétricas que não correspondem ao algoritmo especificado. Esta opção destina-se apenas à compatibilidade com versões anteriores e deve ser evitada.

 // verifica um token simétrico - synchronousvar decoded = jwt.verify(token, 'shhhhh');console.log(decoded.foo) // bar// verifica um token symmetricjwt.verify(token, 'shhhhh', function(err , decodificado) {
  console.log(decoded.foo) // bar});// token inválido - synchronoustry {
  var decodificado = jwt.verify(token, 'segredo errado');} catch(err) {
  // err}// token inválidojwt.verify(token, 'segredo errado', function(err, decodificado) {
  //errar
  // decodificado indefinido});// verifica um token assimétricovar cert = fs.readFileSync('public.pem');  //obter public keyjwt.verify(token, cert, function(err, decoded) {
  console.log(decoded.foo) // bar});// verificar auditaudiovar cert = fs.readFileSync('public.pem');  //obter public keyjwt.verify(token, cert, {audience: 'urn:foo' }, function(err, decoded) {
  // se o público não corresponder, err == público inválido});// verificar issuervar cert = fs.readFileSync('public.pem');  //obter public keyjwt.verify(token, cert, {audience: 'urn:foo', issuer: 'urn:issuer' }, function(err, decoded) {
  // se o emissor for incompatível, err == emissor inválido});// verificar jwt idvar cert = fs.readFileSync('public.pem');  //obter public keyjwt.verify(token, cert, {audience: 'urn:foo', issuer: 'urn:issuer', jwtid: 'jwtid' }, function(err, decoded) {
  // se o id do jwt for incompatível, err == id do jwt inválido});// verificar subjectvar cert = fs.readFileSync('public.pem');  //obter public keyjwt.verify(token, cert, {audience: 'urn:foo', issuer: 'urn:issuer', jwtid: 'jwtid', subject: 'subject' }, function(err, decoded) {
  // se o assunto for incompatível, err == assunto inválido});// alg mismatchvar cert = fs.readFileSync('public.pem'); //obter public keyjwt.verify(token, cert, {algoritmos: ['RS256'] }, function (err, payload) {
  // if token alg != RS256, err == invalid subscription});// Verifique usando getKey callback// Exemplo usa https://github.com/auth0/node-jwks-rsa como forma de buscar as chaves. var jwksClient = require('jwks-rsa');var cliente = jwksClient({
  jwksUri: 'https://sandrino.auth0.com/.well-known/jwks.json'});função getKey(cabeçalho, retorno de chamada){
  client.getSigningKey(header.kid, function(err, key) {var SigningKey = key.publicKey || key.rsaPublicKey;callback(null, SigningKey);
  });}jwt.verify(token, getKey, opções, função(err, decodificado) {
  console.log(decoded.foo) //barra});

Precisa dar uma olhada em um JWT sem verificá-lo? (Clique para expandir)

jwt.decode(token [, opções])

(Síncrono) Retorna a carga decodificada sem verificar se a assinatura é válida.

Aviso: Isso não verificará se a assinatura é válida. Você não deve usar isso para mensagens não confiáveis. Você provavelmente deseja usar jwt.verify .

Aviso: quando o token vem de uma fonte não confiável (por exemplo, entrada do usuário ou solicitação externa), a carga útil decodificada retornada deve ser tratada como qualquer outra entrada do usuário; certifique-se de higienizar e trabalhar apenas com propriedades esperadas

token é a string JsonWebToken

options :

json : força JSON.parse na carga útil mesmo que o cabeçalho não contenha "typ":"JWT" .
complete : retorna um objeto com a carga útil e o cabeçalho decodificados.

Exemplo

 // obtém a carga útil decodificada ignorando a assinatura, sem secretOrPrivateKey necessáriovar decoded = jwt.decode(token);// obtém a carga útil decodificada e headervar decoded = jwt.decode(token, {complete: true});console.log(decoded. cabeçalho);console.log(decodificado.payload)

Erros e códigos

Possíveis erros gerados durante a verificação. Error é o primeiro argumento do retorno de chamada de verificação.

Erro TokenExpired

Erro gerado se o token expirou.

Objeto de erro:

nome: 'TokenExpiredError'
mensagem: 'jwt expirou'
expirado em: [Data de validade]

 jwt.verify(token, 'shhhhh', function(err, decodificado) {
  if (err) {/* err = { nome: 'TokenExpiredError', mensagem: 'jwt expirado', expiradoAt: 1408621000 } */
  }});

JsonWebTokenError

Objeto de erro:

nome: 'JsonWebTokenError'
mensagem:

'token inválido' - o cabeçalho ou a carga útil não puderam ser analisados
'jwt malformado' - o token não possui três componentes (delimitados por . )
'assinatura jwt é necessária'
'assinatura inválida'
'jwt público inválido. esperado: [OPÇÕES PÚBLICO]'
'Emissor jwt inválido. esperado: [EMISSOR DE OPÇÕES]'
'ID jwt inválido. esperado: [OPÇÕES JWT ID]'
'jwt assunto inválido. esperado: [OPÇÕES ASSUNTO]'

 jwt.verify(token, 'shhhhh', function(err, decodificado) {
  if (err) {/* err = { nome: 'JsonWebTokenError', mensagem: 'jwt malformado' } */
  }});

NotBeforeError

Lançado se a hora atual for anterior à reivindicação nbf.

Objeto de erro:

nome: 'NotBeforeError'
mensagem: 'jwt não ativo'
data: 2018-10-04T16:10:44.000Z

 jwt.verify(token, 'shhhhh', function(err, decodificado) {
  if (err) {/* err = { nome: 'NotBeforeError', mensagem: 'jwt não ativo', data: 2018-10-04T16:10:44.000Z } */
  }});

Algoritmos suportados

Matriz de algoritmos suportados. Os algoritmos a seguir são atualmente suportados.

Valor do parâmetro alg	Assinatura Digital ou Algoritmo MAC
HS256	HMAC usando algoritmo de hash SHA-256
HS384	HMAC usando algoritmo de hash SHA-384
HS512	HMAC usando algoritmo de hash SHA-512
RS256	RSASSA-PKCS1-v1_5 usando algoritmo de hash SHA-256
RS384	RSASSA-PKCS1-v1_5 usando algoritmo de hash SHA-384
RS512	RSASSA-PKCS1-v1_5 usando algoritmo de hash SHA-512
PS256	RSASSA-PSS usando algoritmo hash SHA-256 (somente nó ^6.12.0 OR >=8.0.0)
PS384	RSASSA-PSS usando algoritmo hash SHA-384 (somente nó ^6.12.0 OR >=8.0.0)
PS512	RSASSA-PSS usando algoritmo hash SHA-512 (somente nó ^6.12.0 OR >=8.0.0)
ES256	ECDSA usando curva P-256 e algoritmo hash SHA-256
ES384	ECDSA usando curva P-384 e algoritmo hash SHA-384
ES512	ECDSA usando curva P-521 e algoritmo hash SHA-512
nenhum	Nenhuma assinatura digital ou valor MAC incluído

Atualizando JWTs

Em primeiro lugar, recomendamos que você pense cuidadosamente se a atualização automática de um JWT não introduzirá nenhuma vulnerabilidade em seu sistema.

Não nos sentimos confortáveis em incluir isso como parte da biblioteca; no entanto, você pode dar uma olhada neste exemplo para mostrar como isso pode ser feito. Além desse exemplo, há um problema e uma solicitação pull para obter mais conhecimento sobre este tópico.

PENDÊNCIA

A cadeia de certificados X.509 não está verificada

Relatório de problemas

Se você encontrou um bug ou tem uma solicitação de recurso, relate-os na seção de problemas do repositório. Não relate vulnerabilidades de segurança no rastreador público de problemas do GitHub. O Programa de Divulgação Responsável detalha o procedimento para divulgação de questões de segurança.