PixelPin Developer Documentation

Ruby On Rails

Updated June 30th 2017

Tested with Ruby Version: 2.5.0 Tested with Rails Version: 5.2.0

Omniauth PixelPin

Step-by-step installation guide

  • Download the example website
  • Installation
  • Configuring the plugin
  • Modifying the website

Testing the module

Step-by-step installation guide

Omniauth-PixelPin is a Ruby on Rails Plugin for authenticating with PixelPin using OpenID Connect.

Omniauth-PixelPin allows you to connect your website to PixelPin and let users authenticate using passwordless pictures. With the Omniauth-PixelPin module, your clients sign in to your website using their PixelPin pictures. There is no need to complete numerous forms for a successful registration either.

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 Omniauth PixelPin into a Ruby on Rails website. The knowledge you'll learn from installing the module will allow you to install the module onto your own website.

Before starting the installation guide, you'll need the example website from our GitHub page found here.


  1. In the example website's Gemfile. Type gem 'omniauth-pixelpin' within the file and save it.

  2. Open up your favourite CLI and execute the following command to install omniauth-pixelpin: bundle update.

Configuring the Settings

  1. First go to config/initializers and create a new file called omniauth.rb.

  2. Copy the following code into omniauth.rb:

    Rails.application.config.middleware.use OmniAuth::Builder do
      provider :pixelpin, {
                name: :pixelpin,
                scope: ["openid", "profile", "email", "phone", "address"], 
                client_options: { 
                identifier: "",
                secret: "",
                redirect_uri: "http://www.example.co.uk/auth/pixelpin/callback",
      OmniAuth.config.on_failure = Proc.new do |env|
        # error_type = env['omniauth.error.type']
        # new_path = "#{env['SCRIPT_NAME']}#{OmniAuth.config.path_prefix}/failure?message=#{error_type}"
        # [301, {'Location' => new_path, 'Content-Type' => 'text/html'}, []]


  3. Next you'll need to Redirect_uri to create a developer account to get your Client ID and Client Secret. Your Redirect URI will be, for example: http(s)://www.example.co.uk/auth/pixelpin/callback. If you haven't created a PixelPin developer account before, a guide can be found here to guide your through the steps required to create a PixelPin developer account.

  4. Once you have created a PixelPin developer account. You'll need to copy the Client ID into where it says identifier, and copy the Client Secret into where it says secret. Remember to change the redirect_uri to match your Redirect URI.

Modifying the site

  1. First go to app/controllers and create a new file called sessions_controller.rb.

  2. copy the following code into sessions_controller.rb:

    class SessionsController < ApplicationController
      def create
        #render text: request.env['omniauth.auth'].to_yaml and return
          @user = User.from_omniauth(request.env['omniauth.auth'])
          session[:user_id] = @user.id
          flash[:success] = "Welcome, #{@user.first_name} #{@user.last_name}!"
         flash[:warning] = "There was an error while trying to authenticate you..."
        redirect_to root_path
      def destroy
        if current_user
        redirect_to root_path
      def auth_failure
        redirect_to root_path


  3. Next go to app/models and create a new file called user.rb.

  4. Copy the following code into user.rb:

    class User < ActiveRecord::Base
      class << self
        def from_omniauth(auth_hash)
          user = find_or_create_by(uid: auth_hash['uid'], provider: auth_hash['provider'])
          user.name = auth_hash['info']['name']
          user.first_name = auth_hash['info']['first_name']
          user.last_name = auth_hash['info']['last_name']
          user.email = auth_hash['info']['email']
          user.gender = auth_hash['info']['gender']
          user.phone = auth_hash['info']['phone']
          user.birthdate = auth_hash['info']['birthdate']
          user.street_address = auth_hash['info']['street_address']
          user.country = auth_hash['info']['country']
          user.region = auth_hash['info']['region']
          user.city = auth_hash['info']['city']
          user.zip = auth_hash['info']['zip']


  5. lastly go to app/controllers/application_controller.rb and paste the following code into the specified place:

    def current_user
      @current_user ||= User.find_by(id: session[:user_id])
    helper_method :current_user


Adding the SSO button

  1. Go to app/views/layouts/application.html.erb and replace the specified code between "Replace Start" and "Replace End" with the code below:

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

    <% if current_user %>
      <ul class="nav navbar-nav pull-right">
            <li><%= link_to 'Log Out', logout_path, method: :delete %></li>
          <% else %>
         <ul class="nav navbar-nav navbar-right">
           <li class="dropdown">
             <a class="dropdown-toggle" type="button" data-toggle="dropdown">Login in/Sign Up
             <span class="caret"></span></a>
             <ul class="dropdown-menu">
               <li><a class="btn btn-default" href="/auth/pixelpin"><b>Sign In Using PixelPin</b></a></li>
    <% end %>


  2. Go to app/views/pages/index.html.erb and replace the code inside the file with the following code:

    <% if current_user %>
      <div class="page-header">
        <h1>User Data:</h1>
      <div class="panel panel-default">
        <div class="panel-body">
            <li><strong>Provider:</strong> <%= current_user.provider %></li>
            <li><strong>uID:</strong> <%= current_user.uid %></li>
            <li><strong>Name:</strong> <%= current_user.first_name %> <%= current_user.last_name %></li>
            <li><strong>Email:</strong> <%= current_user.email %></li>
            <li><strong>Gender:</strong> <%= current_user.gender %></li>
            <li><strong>Phone:</strong> <%= current_user.phone %></li>
            <li><strong>Birthdate:</strong> <%= current_user.birthdate %> </li>
            <li><strong>Street Address:</strong> <%= current_user.street_address %></li>
            <li><strong>Country:</strong> <%= current_user.country %></li>
            <li><strong>Region:</strong> <%= current_user.region %></li>
            <li><strong>City:</strong> <%= current_user.city %></li>
            <li><strong>Zip:</strong> <%= current_user.zip %></li>
    <% else %>
      <%= render 'welcome' %>
    <% end %>


Testing the module

Test the module by clicking log in/sign up then pressing "Sign in Using PixelPin":


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