An implementation of JSON Web Tokens.
This was developed against
draft-ietf-oauth-json-web-token-08. It makes use of node-jws
$ npm install jsonwebtoken
jwt.sign(payload, secretOrPrivateKey, options, [callback])
(Asynchronous) If a callback is supplied, callback is called with the JsonWebToken string
(Synchronous) Returns the JsonWebToken as string
payload could be an object literal, buffer or string. Please note that
exp is only set if the payload is an object literal.
secretOrPrivateKey is a string or buffer containing either the secret for HMAC algorithms, or the PEM
encoded private key for RSA and ECDSA.
expiresIn: expressed in seconds or a string describing a time span rauchg/ms. Eg:
notBefore: expressed in seconds or a string describing a time span rauchg/ms. Eg:
payload is not a buffer or a string, it will be coerced into a string
issuer are not provided, there is no default. The jwt generated won't include those properties in the payload.
Additional headers can be provided via the
Generated jwts will include an
iat claim by default unless
noTimestamp is specified.
// sign with default (HMAC SHA256)var jwt = ;var token = jwt;// sign with RSA SHA256var cert = fs; // get private keyvar token = jwt;// sign asynchronouslyjwt;
jwt.verify(token, secretOrPublicKey, [options, callback])
(Asynchronous) If a callback is supplied, function acts asynchronously. Callback passed the payload decoded if the signature (and optionally expiration, audience, issuer) are valid. If not, it will be passed the error.
(Synchronous) If a callback is not supplied, function acts synchronously. Returns the payload decoded if the signature (and optionally expiration, audience, issuer) are valid. If not, it will throw the error.
token is the JsonWebToken string
secretOrPublicKey is a string or buffer containing either the secret for HMAC algorithms, or the PEM
encoded public key for RSA and ECDSA.
algorithms: List of strings with the names of the allowed algorithms. For instance,
audience: if you want to check audience (
aud), provide a value here
issuer(optional): string or array of strings of valid values for the
truedo not validate the expiration of the token.
subject: if you want to check subject (
sub), provide a value here
// verify a token symmetric - synchronousvar decoded = jwt;console // bar// verify a token symmetricjwt;// invalid token - synchronoustryvar decoded = jwt;catcherr// err// invalid tokenjwt;// verify a token asymmetricvar cert = fs; // get public keyjwt;// verify audiencevar cert = fs; // get public keyjwt;// verify issuervar cert = fs; // get public keyjwt;// verify jwt idvar cert = fs; // get public keyjwt;// verify subjectvar cert = fs; // get public keyjwt;// alg mismatchvar cert = fs; // get public keyjwt;
jwt.decode(token [, options])
(Synchronous) Returns the decoded payload without verifying if the signature is valid.
Warning: This will not verify whether the signature is valid. You should not use this for untrusted messages. You most likely want to use
token is the JsonWebToken string
json: force JSON.parse on the payload even if the header doesn't contain
complete: return an object with the decoded payload and header.
// get the decoded payload ignoring signature, no secretOrPrivateKey neededvar decoded = jwt;// get the decoded payload and headervar decoded = jwt;console;console
jwt.refresh(token, expiresIn, secretOrPrivateKey [, callback])
Will refresh the given token. The token is expected to be decoded and valid. No checks will be performed on the token. The function will copy the values of the token, give it a new expiry time based on the given
expiresIn parameter and will return a new signed token using the
sign function and given secretOrPrivateKey.
token: is the decoded JsonWebToken string
expiresIn: New value to set when the token will expire.
secretOrPrivateKey: is a string or buffer containing either the secret for HMAC algorithms, or the PEM encoded private key for RSA and ECDSA.
callback: If a callback is supplied, callback is called with the newly refreshed JsonWebToken string
// ...var originalDecoded = jwt;var refreshed = jwt;console;// new 'exp' value is later in the future.console;
Errors & Codes
Possible thrown errors during verification. Error is the first argument of the verification callback.
Thrown error if the token is expired.
- name: 'TokenExpiredError'
- message: 'jwt expired'
- expiredAt: [ExpDate]
- name: 'JsonWebTokenError'
- 'jwt malformed'
- 'jwt signature is required'
- 'invalid signature'
- 'jwt audience invalid. expected: [OPTIONS AUDIENCE]'
- 'jwt issuer invalid. expected: [OPTIONS ISSUER]'
- 'jwt id invalid. expected: [OPTIONS JWT ID]'
- 'jwt subject invalid. expected: [OPTIONS SUBJECT]'
Array of supported algorithms. The following algorithms are currently supported.
|alg Parameter Value||Digital Signature or MAC Algorithm|
|HS256||HMAC using SHA-256 hash algorithm|
|HS384||HMAC using SHA-384 hash algorithm|
|HS512||HMAC using SHA-512 hash algorithm|
|RS256||RSASSA using SHA-256 hash algorithm|
|RS384||RSASSA using SHA-384 hash algorithm|
|RS512||RSASSA using SHA-512 hash algorithm|
|ES256||ECDSA using P-256 curve and SHA-256 hash algorithm|
|ES384||ECDSA using P-384 curve and SHA-384 hash algorithm|
|ES512||ECDSA using P-521 curve and SHA-512 hash algorithm|
|none||No digital signature or MAC value included|
- X.509 certificate chain is not checked
If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.
This project is licensed under the MIT license. See the LICENSE file for more info.