Synopsis

If this synopsis confuses you, or you have any doubts, we recommend you visit the Getting Started page.

1. Initialize Gatekeeper

Initialize gatekeeper after your session module and provide a User Serializer and User Deserealizer

import gatekeeper from 'gatekeeper-authentication';
// Initialize your session module (express-session, for example)
app.use(session({ secret: 'I love Grothendieck Universes!' }));
// Initialize Gatekeeper
app.use(gatekeeper.initialize({
    userSerializer: (user) => user.id,
    userDeserializer: (id) => {
        /* Here we are returning an arbitrary user
        for the sake of the example */
        return { id: id, username: 'David Hilbert' };
    }
}));

2. Create providers

You can create your providers in the routes file, or can declare them in a separate file and import them in your routes (we will see how to use them in our routes in a second) -- this is the recommended approach. Here's an example (you can also visit our Providers page to know how to implement your favorite providers):

authenticationProviders.js

import gatekeeper from 'gatekeeper-authentication';
import GoogleProvider from 'gatekeeper-authentication/providers/google';
import GithubProvider from 'gatekeeper-authentication/providers/github';

export const GoogleAuth = new GoogleProvider({
    clientId: '<YOUR CLIENT ID>',
    clientSecret: '<YOUR CLIENT SECRET>'
    // The OAuth2 callback/redirect url you registered
    // (the URL in which this provider will be used)
    callbackURL: 'https://yourdomainorlocalhost.com/auth/google'
}, function handler(refresh_token, access_token, profile) => {
    return profile;
});

export const GithubAuth = new GithubProvider({
    clientId: '<YOUR CLIENT ID>',
    clientSecret: '<YOUR CLIENT SECRET>'
    // The OAuth2 callback/redirect url you registered
    // (the URL in which this provider will be used)
    callbackURL: 'https://yourdomainorlocalhost.com/auth/github'
}, function handler(refresh_token, access_token, profile) => {
    return profile;
});

/* Notice that we can use the prebuilt providers as many times as we want
to create multiple providers that do different things! */
export const GithubAuthWithSmileyFace = new GithubProvider({
    clientId: '<YOUR CLIENT ID>',
    clientSecret: '<YOUR CLIENT SECRET>'
    // The OAuth2 callback/redirect url you registered
    // (the URL in which this provider will be used)
    callbackURL: 'https://yourdomainorlocalhost.com/auth/smiley/github'
}, function handler(refresh_token, access_token, profile) => {
    profile.name = profile.name + ' :D';
    return profile;
});

3. Start using gatekeeper in your login and protected routes!

Login

For login routes (the route you want a user to visit when they want to log in to your application) use gatekeeper.authenticateWithProvider(theProviderYouWantToUse):

warning

Important: When using OAuth2 providers on login routes, make sure you use gatekeeper.authenticateWithProvider(yourProvider) in a GET route, as the user will be redirected to the provider's site to log in.

import gatekeeper from 'gatekeeper-authentication';
import GithubProvider from 'gatekeeper-authentication/providers/github';

const GithubAuth = new GithubProvider({
    clientId: '<YOUR CLIENT ID>',
    clientSecret: '<YOUR CLIENT SECRET>'
    callbackURL: 'https://yourdomainorlocalhost.com/auth/github'
}, function handler(refresh_token, access_token, profile) => {
    return profile;
});

const GithubAuthWithSmileyFace = new GithubProvider({
    clientId: '<YOUR CLIENT ID>',
    clientSecret: '<YOUR CLIENT SECRET>'
    callbackURL: 'https://yourdomainorlocalhost.com/auth/smiley/github'
}, function handler(refresh_token, access_token, profile) => {
    profile.name = profile.name + ':D';
    return profile;
});

router.get(
    '/auth/smiley/github',
    gatekeeper.authenticateWithProvider(GithubAuthWithSmileyFace),
    (req, res) => {
        return res.json({ user: req.session.user, success: true });
    }
);

router.get(
    '/auth/github',
    gatekeeper.authenticateWithProvider(GithubAuth),
    (req, res) => {
        return res.json({ user: req.session.user, success: true });
    }
);

Or if you have your providers in a different file (the recommended approach), say, authenticationProviders.js,

authenticationProviders.js

import { GithubAuth, GithubAuthWithSmileyFace } from './authenticationProviders'

router.get(
    '/auth/smiley/github',
    gatekeeper.authenticateWithProvider(GithubAuthWithSmileyFace),
    (req, res) => {
        return res.json({ user: req.session.user, success: true });
    }
);

router.get(
    '/auth/github',
    gatekeeper.authenticateWithProvider(GithubAuth),
    (req, res) => {
        return res.json({ user: req.session.user, success: true });
    }
);

How to access the user once it has logged in?

Once the user has been authenticated, you can access it through req.session.user.

Protecting routes

To protect a route, you can call gatekeeper.protect as a route middleware and pass to it a failure handler that specifies what to do in case the user is not authenticated (if you don't provide a failure handler, gatekeeper will just return a 401 status code response). Let's see it in action:

router.get('/protected', gatekeeper.protect((req, res, next) => {
	return res.redirect('/auth/google');
}), (req, res) => res.send('The user', req.session.user.id, 'is authenticated!'));

✔️ That's it! Now you application has a secure, easy-to-use, and flexible authentication system with Gatekeeper! 🔐

We now recommend you visit our Providers page to learn how to implement your favorite providers.