In this article, you will learn how to authenticate with GitHub using Passport.js in a Nodejs express app.
You can get the source code for this project here, this project can be used as a boilerplate code when setting up an express app that uses Passportjs for authentication.
Prerequisites:
- Basic Knowledge of NodeJS
- Node JS should be installed on your system. ## What is Passport.js?
Passport is authentication middleware for Node.js. It is very flexible and modular. A comprehensive set of strategies supports authentication using a username and password, Google, Facebook, Apple, Twitter, and more. Find out more about Passport here.
Creating a Github Application
Before using passport-github2, you must have a Github account and register an application with Github. If you have not done this, You can do that here.
Your Homepage URI and Callback URI should match the one in your application. Your application will be issued a Client ID and Client secret, which this strategy needs to work.
Setting up our Project
To start, create a Nodejs project by running this command.
npm init
Install the following packages by running these commands.
npm install express express-session ejs mongoose passport passport-github2 dotenv nodemon
If the command is successful, you will see something like the image below, node_modules
folder will be created and package-lock.json
file will also be created.
Below is the project structure for this project.
📦passportjs
┣ 📂controller
┃ ┣ 📜account.js
┃ ┗ 📜auth.js
┣ 📂model
┃ ┗ 📜UserModel.js
┣ 📂routes
┃ ┣ 📜account.js
┃ ┗ 📜auth.js
┣ 📂utils
┃ ┗ 📜github.js
┣ 📂views
┃ ┣ 📜account.ejs
┃ ┗ 📜index.ejs
┣ 📜.env
┣ 📜.gitignore
┣ 📜app.js
┣ 📜package-lock.json
┣ 📜package.json
┣ 📜README.md
┗ 📜server.js
Setting up our Express Server
At this point, our application set. Now let’s go ahead and set up our express server. To get started, first create server*.js
file* in the project root directory.
Next, import the mongoose for our database connection and dotenv
to lead our environment variables with the code below:
const mongoose = require('mongoose');
const dotenv = require('dotenv');
Next, create a .env
file in your project root directory, where we will store our environment variables later in this session. Then make the available in our application with the code below.
dotenv.config({ path: './.env' });
Import app.js into the code in this file export an express app, this app will be explained next in this article.
const app = require('./app');
Next, we make a connection to the mongoose database with the code below.
mongoose
.connect(process.env.DATABASE, { useUnifiedTopology: true })
.then(() => console.log('DB connection successful!'));
Next, we assign a port to the express application. The application will be listening to the port provided by the environment or port 8081 if there is no environment port.
const port = process.env.PORT || 8081;
app.listen(port, () => {
console.log(`App running on port ${port}...`);
});
The following line of codes listens for the following events uncaughtException
, unhandledRejection
, and SIGTERM
respectively, and shut down the server once either one of them occurs.
process.on('uncaughtException', err => {
console.log('UNCAUGHT EXCEPTION! 💥 Shutting down...');
console.log(err.name, err.message);
process.exit(1);
});
process.on('unhandledRejection', err => {
console.log('UNHANDLED REJECTION! 💥 Shutting down...');
console.log(err.name, err.message);
server.close(() => {
process.exit(1);
});
});
process.on('SIGTERM', () => {
console.log('👋 SIGTERM RECEIVED. Shutting down gracefully');
server.close(() => {
console.log('💥 Process terminated!');
});
});
Your .env
file should look like this. Put your credentials on the required fields.
DATABASE = your-mongo-db-uri
GITHUB_CLIENT_ID = your-github-app-client-id
GITHUB_CLIENT_SECRET = your-github-app-client-secret
GITHUB_CALLBACK_URL = your-github-app-callback-url
SESSION_SECRET = your-app-session-secret-it-can-be-any-string-of-your-choice
Setting up our Express Application
Now let’s go ahead and setup our express application. To get started, create an app.js
in the project root directory. first we import express
, next we import express-session
this is a middleware for handling user sessions in express.
Then import two route handlers on for handling authentication request and the other for handling request in user account. These route handlers will be explained next.
const express = require('express');
const session = require('express-session');
const authRouter = require('./routes/auth');
const accountRouter = require('./routes/account');
Here is where we create the express and by calling the express function which is a top level function exported by the express module and assign it to the app
variable.
const app = express();
Next, we configure the directory where the template files will be located. The first line of code set the view directory to /views
. The second line set the view engine to ejs. Learn more about ejs here.
app.set('views', __dirname + '/views');
app.set('view engine', 'ejs');
Next we use the express-session
middleware so that we can support persistent login from users. the session(options) receives an object of settings read the express-session documentation to learn more.
The default server-side session storage, MemoryStore, is not designed for a production environment. It will leak memory under most conditions, does not scale past a single process, and is meant for debugging and developing. For a list of stores, see compatible session stores.
app.use(
session(
{
secret: process.env.SESSION_SECRET,
resave: false,
saveUninitialized: false
}));
Here we redirect the user to the localhost:8081/auth
route once they visit localhost:8081/
app.get('/', function(req, res){
res.redirect('/auth');
});
Next, we configure two routers on the app for handling localhost:8081/auth/*
requests and the other for handling account request localhost:8081/account/*
these routers will be discussed next.
// set Routes
app.use('/auth', authRouter);
app.use('/account', accountRouter);
export the express app
module.exports = app;
Creating our Application Routers
First, we create a route directory. The files in this directory will be used as route handlers to handle different routes in our application.
Create Authentication Router
Create auth.js
file inside the route
directory, then import express
and passport
.
const express = require('express');
const passport = require('passport');
We import github
which is an authentication middleware based on passport GitHub strategy this middleware will be explained later in this article. Also, import authController
. This module is meant to contain a bunch of functions that control user authentication but for now, it just contains the logout function.
const github = require('./../utils/github');
const authController = require('./../controller/auth');
We configure passport to use the github
middleware.
passport.use(github);
Here we use the express.Router()
class to create modular, mountable route handlers. then we use the passport.initialize()
function in the router this function is needed to initialize passportjs
on our routes, passport.session()
function enables persistent login with passportjs
in our route it handles session.
const router = express.Router();
router.use(passport.initialize());
router.use(passport.session());
serializeUser
determines which data of the user object should be stored in the session. The result of the serializeUser
function is attached to the session as req.session.passport.user = {}
. Here we store the whole user object
The first argument of deserializeUser
corresponds to the user object that was given to the done
function. The object is attached to the request object as req.user
passport.serializeUser(function(user, done) {
done(null, user);
});
passport.deserializeUser(function(obj, done) {
done(null, obj);
});
This line of code renders the index.ejs
file in the view directory once the user visits the localhost:8081/auth
route.
router.get('/', function(req, res){
res.render('index', { user: req.user });
});
This line of codes tries to authenticate the user with GitHub once the
localhost:8081/auth/github
route is visited. It Redirect the user to a GitHub conscent page and request for the user authorization, once the user authorize the app, it redirects the user back to the callback url which is localhost:8081/auth/github/callback
for this application on successful login the user will be redirected to localhost:8081/account
by this line of code res.redirect('/account'));
.
router.get('/github', passport.authenticate('github', { scope: [ 'user:email' ] }));
router.get('/github/callback',
passport.authenticate('github', { failureRedirect: '/' }),
(req, res) => res.redirect('/account'));
Once the user visit localhost:8081/auth/logout
. the session will be destroyed and the user will have to login again.
router.get('/logout', authController.logout);
module.exports = router;
Create account routes
Create account.js
file inside the route
directory, the following codes below do the same function as the ones on auth.js
, accountController.js
contains functions for handling user accounts.
const express = require('express');
const passport = require('passport');
const accountController = require('./../controller/account');
const router = express.Router();
router.use(passport.initialize());
router.use(passport.session());
passport.serializeUser(function(user, done) {
done(null, user);
});
passport.deserializeUser(function(obj, done) {
done(null, obj);
});
This route handler, handles get requests sent to this route localhost:8081/account
.
router.get('/', accountController.user);
module.exports = router;
Creating Utility
First, we create a utils
directory. This directory is going to contain all our utility functions, for this project.
Create github middleware
This code exports a middleware this middleware is required when making an authentication request with passport-github2
strategy. Here we use passport-github2 strategy, we pass the configuration object which includes the ClientId
, ClientSecret
, and CallbackUrl
, these values should match the one used in creating the github application. if these values are correct and up to date the callback function with four parameters with be called
- accessToken - GitHub access Token
- refreshToken - GitHub refresh Token
- profile - contains user data gotten from GitHub
- done - this is callback function with two arguments error and data is called, the profile.id data is used to query the mongo database to check if the user account exists, if it doesn't exist the user is created with the data gotten from github.
User.findOne({githubId: profile.id })
checks if a user with the same github
profile exists in the database, if it does exist the return done(null, data);
function will be called with the user data. If no user exists the user will be created and the return done(null, data);
will be called with the user data.
const GitHubStrategy = require('passport-github2').Strategy;
const User = require('../model/UserModel');
module.exports = new GitHubStrategy({
clientID: process.env.GITHUB_CLIENT_ID,
clientSecret: process.env.GITHUB_CLIENT_SECRET,
callbackURL: process.env.GITHUB_CALLBACK_URL
},
function(accessToken, refreshToken, profile, done) {
User.findOne({githubId: profile.id }).then((data, err) => {
if (!data) return User.create({
githubId: profile.id,
fullname: profile.displayName,
username: profile.username,
location: profile._json.location,
phone: profile._json.phone,
email: profile._json.email,
profilePhoto: profile._json.avatar_url
}).then((data, err) => {
return done(null, data);
});
else return done(null, data);
});
}
);
Creating Database Model
Create a model
directory. This directory is going to contain all our database Models, for this project.
Create User Model
First, we create a userModel.js
file inside the model
directory, import mongoose
into the project, then create a user schema.
Everything in Mongoose starts with a Schema. Each schema maps to a MongoDB collection and defines the shape of the documents within that collection.
Models are fancy constructors compiled from Schema
definitions. An instance of a model is called a document. Models are responsible for creating and reading documents from the underlying MongoDB database.
const mongoose = require('mongoose');
const userSchema = new mongoose.Schema(
{
fullname: { type: String },
username: { type: String },
githubId: { type: String, unique: true },
location: { type: String },
phone: { type: String },
email: { type: String, lowercase: true },
profilePhoto: { type: String, default: '' }
},
{ timestamps: true }
);
const User = mongoose.model('User', userSchema);
module.exports = User;
Creating Controllers
Create a controller
directory. This directory is going to contain all our controllers for this project.
Authentication controller
The auth.js
controller contains one function logout
to destroy user session and redirect user to the homepage.
exports.logout = (req, res, next) => {
req.logout();
res.redirect('/');
};
Authentication controller
The account.js
controller contains one function user
, req.user
get the user data from the request parameter, if (!user) res.redirect('/');
redirect the user to localhost:8081/
if the user exist it readers the account.ejs
templete.
exports.user = (req, res, next) => {
const user = req.user;
if (!user) res.redirect('/');
res.render('account', {user: user});
};
Creating Views
Create a views
directory, this directory will hold all the ejs templating codes for the application.
Create the Index ejs template
Create a file index.ejs
inside the views
directory. This templete renders a link to authenticate with github when user session is not available <h2>Welcome! <a href="/auth/github">Login with GitHub</a> </h2>
and renders a link to view user account, when user session is available <h2>Hello, <%= user.fullname %> <a href="/account">View Account</a></h2>
.
<% if (!user) { %>
<h2>Welcome! <a href="/auth/github">Login with GitHub</a> </h2>
<% } else { %>
<h2>Hello, <%= user.fullname %> <a href="/account">View Account</a></h2>
<% } %>
Create the Account ejs template
Create a file account.ejs
inside the views
directory. This template simply displays user information, stored in the database.
<div>
<p>Full Name: <%= user.fullname %></p>
<p>Username: <%= user.username %></p>
<p>Email: <%= user.email %></p>
<p>location: <%= user.location %></p>
<p><a href="/auth/logout">Logout </a></p>
<img src=<%= user.profilePhoto %> />
</div>
Conclusion
In this article you have learned how to authenticate users, using passport-github2
strategy, You learned how to create and configure a github application, and maintain user sessions within your application while using ejs as templating engine.
Top comments (0)