Node.JS

Passport PixelPin OpenID Connect

Updated June 28th 2017

Step-by-step installation guide

Passport PixelPin OpenID Connect is a NodeJS module for authenticating with PixelPin using the passport openid connect authentication middleware and the OpenID Connect API.

Passport PixelPin OpenID Connect allows you to connect your website to PixelPin and let users authenticate using passwordless pictures. With Passport PixelPin OpenID Connect module your clients sign in to your store using their PixelPin pictures. There is no need to complete numerous forms for a successful registration.

To complete the installation, you'll need to create your PixelPin developer account.

Download the example website

Downloading an example website allows you to understand how to install Passport PixelPin OpenID Connect into a NodeJS website. The knowledge you'll learn from installing the module will allow you to install the module onto your own website.
  1. Download the example website from here.

  2. Extract the example Node.JS website into your preferred location.

  3. In your preferred CLI, go to the example NodeJS website's root directory and then type npm install to download all of the example website's dependencies.

  4. From the example Node.JS website's directory in your favourite CLI type node server to start the node server.

  5. Go to localhost to view the example website.

Installation

  1. In your favourite CLI, go to the example Node.JS website's root directory then type and run npm install passport. If successful, your output should look something like this:

  2. In the same directory type and run npm install passport-pixelpin-openidconnect. If successful, your output should look something like this:

  3. The installation is now complete.

Configuring the website

  1. Open the example NodeJS website in your favourite IDE or text editor.

  2. Open the example NodeJS server.js file.

  3. At the top of server.js on line 12 add the following code to load passport and passport-pixelpin-openidconnect modules:

    passport = require('passport'),
    PixelPinStrategy = require('Passport-PixelPin-OpenIDConnect').Strategy;

    so the top of your server.js file should look something like this:

  4. You'll need to retrieve your Client ID and Client Secret by creating a PixelPin developer account. To create a PixelPin developer account your callbackURL must match the Redirect URI which you'll use to create a PixelPin developer account. Your callbackURL and redirect URI is your websites base URL + /auth/pixelpin/callback', for example http(s)://www.google.co.uk/auth/pixelpin/callback would be Google's callbackURL and RedirectURI. A guide to create a PixelPin developer account can be found here.

  5. Next we'll be adding the PixelPin Strategy and configuring it. copy the following code into the server.js file on line 15:

    passport.use(new PixelPinStrategy({
        clientID: "--Client ID--",
        clientSecret: "--Client Secret--",
        responseType: "code",
        callbackURL: "http://local.nodejs.co.uk/auth/pixelpin/callback"
    },
     
    function(accessToken, refreshToken, profile, done) {
        process.nextTick(function () {
                return done(null, profile);
            });
        }
    ));

    Once you've retrieved your Client ID and Client Secret, type/copy and paste them where it says --Client ID-- and --Client Secret--.

  6. Next we'll be adding the code that serializes the user. Each subdequent request will not contain credentials, but rather the unique cookie that identifies the session in order to support signin sessions, Passport will serialise and deserialise 'user' instances to and from the session.

    Copy and paste the code below into the server.js file on line 29:

    passport.serializeUser(function(user, done) {
     
        //Use for storing data in your database.
        var userData = {
            id: user.id,
            email: user.email,
            firstName: user.firstName,
            lastName: user.lastName,
            street_address: user.street_address,
            locality: user.locality,
            region: user.region,
            postal_code: user.postal_code,
            country: user.country,
            dob: user.dob,
            gender: user.gender,
            phone: user.phone
        };
         
        done(null, user);
    });
     
     
    passport.deserializeUser(function(obj, done) {
        done(null, obj);
    });
  7. In a Connect or Express-based application, passport.initilize() middleware is required to initialize passport. If your application uses persistent signin session, 'passport.session()' middleware must also be used. So in server.js on line 64 insert the following code:

    		app.use(passport.initialize());
    		app.use(passport.session());

    So it'll look something like this:

  8. Two routes are required for PixelPin OpenID Connect authentication. The first route accepts the form submission. During authentication, the user will be redirected to PixelPin, the route enables you to choose which scopes you want to use. The second route is the URL to which the user will be returned too after they authenticated with PixelPin. So, in server.js on line 107 insert the following code:

    app.get('/auth/pixelpin',
        passport.authenticate('pixelpin', {scope: ['profile','email','phone','address']}),
        function(req,res){
    });
     
    app.get('/auth/pixelpin/callback',
        passport.authenticate('pixelpin', { failureRedirect: '/signin'}),
        function(req,res) {
            res.redirect('/layout');
    });
  9. To allow the user to sign in using Passport PixelPin OpenID Connect they need a button to start the process. It could be any kind of button/link as long as it links to '/auth/pixelpin' then it should work. So go to View/signin.ejs and View/register.ejs and insert the following code on line 55:

    signin.ejs:

    		<button class="btn btn-default" type="button" onclick="location.href='/auth/pixelpin'">Sign In Using PixelPin</button>

    register.ejs:

    		<button class="btn btn-default" type="button" onclick="location.href='/auth/pixelpin'">Register Using PixelPin</button>

    Click here to find out how you can add the PixelPin logo to the SSO button.

  10. To present the user data to the user you can use the data stored in session or query the data from your database, the example below is how to get user data from session data So go to View/account.ejs and insert the following code on line 52:

    Note: Some data may or may not come back from PixelPin depending on whether the user has added additional data. So if you're getting data from session, the data can come back as actual data or come back as unavailable
    <% if (user.email === "Not Set") { %>
    <h2>Email:<input type="text" name="email"><br></h2>
    <% } else { %>
    <h2>Email: <%= user.email %></h2>
    <% } %>
     
    <% if (user.id === "Not Set") { %>
    <h2>ID:<input type="text" name="id"><br></h2>
    <% } else { %>
    <h2>ID: <%= user.id %></h2>
    <% } %>
     
    <% if (user.firstName === "Not Set") { %>
    <h2>First Name:<input type="text" name="fName"><br></h2>
    <% } else { %>
    <h2>First Name: <%= user.firstName %></h2>
    <% } %>
     
    <% if (user.lastName === "Not Set") { %>
    <h2>Last Name:<input type="text" name="lName"><br></h2>
    <% } else { %>
    <h2>Last Name: <%= user.lastName %></h2>
    <% } %>
     
    <% if (user.street_address === "Not Set") { %>
    <h2>Street Address :<input type="text" name="streetAddress"><br></h2>
    <% } else { %>
    <h2>Street Address : <%= user.street_address %></h2>
    <% } %>
     
    <% if (user.locality === "Not Set") { %>
    <h2>Town/City: <input type="text" name="locality"><br></h2>
    <% } else { %>
    <h2>Town/City: <%= user.locality %></h2>
    <% } %>
     
    <% if (user.region === "Not Set") { %>
    <h2>Region:<input type="text" name="region"><br></h2>
    <% } else { %>
    <h2>Region: <%= user.region %></h2>
    <% } %>
     
    <% if (user.postal_code === "Not Set") { %>
    <h2>Post/Zip code:<input type="text" name="postalCode"><br></h2>
    <% } else { %>
    <h2>Post/Zip code: <%= user.postal_code %></h2>
    <% } %>
     
    <% if (user.country === "Not Set") { %>
    <h2>Country:<input type="text" name="country"><br></h2>
    <% } else { %>
    <h2>Country: <%= user.country %></h2>
    <% } %>
     
    <% if (user.dob === "Not Set") { %>
    <h2>DOB:<input type="text" name="dob"><br></h2>
    <% } else { %>
    <h2>DOB: <%= user.dob %></h2>
    <% } %>
     
    <% if (user.gender === "Not Set") { %>
    <h2>Gender:<input type="text" name="gender"><br></h2>
    <% } else { %>
    <h2>Gender: <%= user.gender %></h2>
    <% } %>
     
    <% if (user.phone === "Not Set") { %>
    <h2>Phone:<input type="text" name="phone"><br></h2>
    <% } else { %>
    <h2>Phone: <%= user.phone %></h2>
    <% } %>
  11. configuration is now finished.

Testing the module

Log in/Register page

If you added the signin/register button correctly the signin page should feature the 'Sign in with PixelPin' button:

Example logged in page

Once you've signed in using PixelPin, you can access the 'account' page where you can see all the data retrieved from PixelPin:

Contributing

PixelPin Igniter is an open-source project that allows developers using PixelPin to improve the plugin. The Github Repo can be found here.