A Passport strategy for authenticating with aJSON Web Token.
This module lets you authenticate endpoints using a JSON web token. It isintended to be used to secure RESTful endpoints without sessions.
Supported By
If you want to quickly add secure token-based authentication to Node.js apps, feel free to check out Auth0's Node.js SDK and free plan at auth0.com/developers
Install
npm install passport-jwt
Usage
Configure Strategy
The JWT authentication strategy is constructed as follows:
new JwtStrategy(options, verify)
options
is an object literal containing options to control how the token isextracted from the request or verified.
secretOrKey
is a string or buffer containing the secret(symmetric) or PEM-encoded public key (asymmetric) for verifying the token'ssignature. REQUIRED unlesssecretOrKeyProvider
is provided.secretOrKeyProvider
is a callback in the formatfunction secretOrKeyProvider(request, rawJwtToken, done)
,which should calldone
with a secret or PEM-encoded public key (asymmetric) for the given key and request combination.done
accepts arguments in the formatfunction done(err, secret)
. Note it is up to the implementer to decode rawJwtToken.REQUIRED unlesssecretOrKey
is provided.jwtFromRequest
(REQUIRED) Function that accepts a request as the onlyparameter and returns either the JWT as a string or null. SeeExtracting the JWT from the request formore details.issuer
: If defined the token issuer (iss) will be verified against thisvalue.audience
: If defined, the token audience (aud) will be verified againstthis value.algorithms
: List of strings with the names of the allowed algorithms. For instance, ["HS256", "HS384"].ignoreExpiration
: if true do not validate the expiration of the token.passReqToCallback
: If true the request will be passed to the verifycallback. i.e. verify(request, jwt_payload, done_callback).jsonWebTokenOptions
: passport-jwt is verifying the token using jsonwebtoken.Pass here an options object for any other option you can pass the jsonwebtoken verifier. (i.e maxAge)
verify
is a function with the parameters verify(jwt_payload, done)
jwt_payload
is an object literal containing the decoded JWT payload.done
is a passport error first callback accepting argumentsdone(error, user, info)
An example configuration which reads the JWT from the httpAuthorization header with the scheme 'bearer':
var JwtStrategy = require('passport-jwt').Strategy, ExtractJwt = require('passport-jwt').ExtractJwt;var opts = {}opts.jwtFromRequest = ExtractJwt.fromAuthHeaderAsBearerToken();opts.secretOrKey = 'secret';opts.issuer = 'accounts.examplesoft.com';opts.audience = 'yoursite.net';passport.use(new JwtStrategy(opts, function(jwt_payload, done) { User.findOne({id: jwt_payload.sub}, function(err, user) { if (err) { return done(err, false); } if (user) { return done(null, user); } else { return done(null, false); // or you could create a new account } });}));
Extracting the JWT from the request
There are a number of ways the JWT may be included in a request. In order to remain as flexible aspossible the JWT is parsed from the request by a user-supplied callback passed in as thejwtFromRequest
parameter. This callback, from now on referred to as an extractor,accepts a request object as an argument and returns the encoded JWT string or null.
Included extractors
A number of extractor factory functions are provided in passport-jwt.ExtractJwt. These factoryfunctions return a new extractor configured with the given parameters.
fromHeader(header_name)
creates a new extractor that looks for the JWT in the given httpheaderfromBodyField(field_name)
creates a new extractor that looks for the JWT in the given bodyfield. You must have a body parser configured in order to use this method.fromUrlQueryParameter(param_name)
creates a new extractor that looks for the JWT in the givenURL query parameter.fromAuthHeaderWithScheme(auth_scheme)
creates a new extractor that looks for the JWT in theauthorization header, expecting the scheme to match auth_scheme.fromAuthHeaderAsBearerToken()
creates a new extractor that looks for the JWT in the authorization headerwith the scheme 'bearer'fromExtractors([array of extractor functions])
creates a new extractor using an array ofextractors provided. Each extractor is attempted in order until one returns a token.
Writing a custom extractor function
If the supplied extractors don't meet your needs you can easily provide your own callback. Forexample, if you are using the cookie-parser middleware and want to extract the JWT in a cookieyou could use the following function as the argument to the jwtFromRequest option:
var cookieExtractor = function(req) { var token = null; if (req && req.cookies) { token = req.cookies['jwt']; } return token;};// ...opts.jwtFromRequest = cookieExtractor;
Authenticate requests
Use passport.authenticate()
specifying 'JWT'
as the strategy.
app.post('/profile', passport.authenticate('jwt', { session: false }), function(req, res) { res.send(req.user.profile); });
Include the JWT in requests
The method of including a JWT in a request depends entirely on the extractorfunction you choose. For example, if you use the fromAuthHeaderAsBearerToken
extractor, you would include an Authorization
header in your request with thescheme set to bearer
. e.g.
Authorization: bearer JSON_WEB_TOKEN_STRING.....
Migrating
Read the Migration Guide for help upgrading to the latestmajor version of passport-jwt.
Tests
npm installnpm test
To generate test-coverage reports:
npm install -g istanbulnpm run-script testcovistanbul report
License
The MIT License
Copyright (c) 2015 Mike Nicholson
To start, I have a robust understanding of authentication mechanisms, particularly with JSON Web Tokens (JWTs) and their integration with Node.js using Passport strategies. Passport is a widely used authentication middleware for Node.js, and I'll provide a comprehensive breakdown of the concepts mentioned in the article you shared.
Concepts Covered:
-
Passport Strategy with JWT Authentication:
- Aim: Authenticating endpoints via JSON Web Tokens.
- Usage: Securing RESTful endpoints without using sessions.
- Supported By: Auth0's Node.js SDK, specifically
passport-jwt
.
-
Installation and Configuration:
- Installing the
passport-jwt
module via npm. - Configuring the JWT authentication strategy.
- Defining options for JWT validation (issuer, audience, algorithms, etc.).
- The
verify
function to validate JWT payload.
- Installing the
-
Extracting JWT from Requests:
- Various methods to extract JWT from requests:
- Header (
fromHeader
). - Body field (
fromBodyField
). - URL query parameter (
fromUrlQueryParameter
). - Authorization header (
fromAuthHeaderWithScheme
,fromAuthHeaderAsBearerToken
). - Custom extractor functions.
- Header (
- Configuring extractors using
passport-jwt
'sExtractJwt
.
- Various methods to extract JWT from requests:
-
Authentication and Usage:
- Using
passport.authenticate()
with the 'JWT' strategy. - Example of authenticating requests (
passport.authenticate('jwt', { session: false })
). - Including JWT in requests based on chosen extractor.
- Using
-
Migrating and Testing:
- Migration guide for upgrading to the latest major version of
passport-jwt
. - Instructions for testing the setup (
npm test
and test-coverage reports).
- Migration guide for upgrading to the latest major version of
-
License:
passport-jwt
using the MIT License.- Copyright notice by Mike Nicholson (2015).
This information outlines the comprehensive aspects of setting up JWT-based authentication using Passport in Node.js, covering installation, configuration, request authentication, testing, and migration.
If you have specific questions or need further details about any of these aspects, feel free to ask!