[null, null, null, {"document_url": "https://auth0.com/blog/iris-recognition-for-two-factor-authentication-with-ruby-on-rails/", "unformatted_src": "https://s3.eu-west-2.amazonaws.com/iris-blog-images/24442301.jpg", "src": "https://s3.eu-west-2.amazonaws.com/iris-blog-images/24442301.jpg", "alt_text": "Print"}, null, {"document_url": "https://auth0.com/blog/iris-recognition-for-two-factor-authentication-with-ruby-on-rails/", "unformatted_src": "https://s3.eu-west-2.amazonaws.com/iris-blog-images/24442301_blur.jpg", "src": "https://s3.eu-west-2.amazonaws.com/iris-blog-images/24442301_blur.jpg", "formatted_filename": "blur", "alt_text": "New Print", "rendered_width": 500}, null, {"document_url": "https://auth0.com/blog/iris-recognition-for-two-factor-authentication-with-ruby-on-rails/", "unformatted_src": "https://s3.eu-west-2.amazonaws.com/iris-blog-images/24442301_DIFF.png", "src": "https://s3.eu-west-2.amazonaws.com/iris-blog-images/24442301_DIFF.png", "formatted_filename": "DIFF", "alt_text": "Diff", "rendered_width": 500}, null, {"document_url": "https://auth0.com/blog/iris-recognition-for-two-factor-authentication-with-ruby-on-rails/", "unformatted_src": "https://s3.eu-west-2.amazonaws.com/iris-blog-images/eye1.jpg", "src": "https://s3.eu-west-2.amazonaws.com/iris-blog-images/eye1.jpg", "formatted_filename": "eye", "alt_text": "Right Eye", "rendered_width": 400}, {"document_url": "https://auth0.com/blog/iris-recognition-for-two-factor-authentication-with-ruby-on-rails/", "unformatted_src": "https://s3.eu-west-2.amazonaws.com/iris-blog-images/eye2.jpg", "src": "https://s3.eu-west-2.amazonaws.com/iris-blog-images/eye2.jpg", "formatted_filename": "eye", "alt_text": "Right Eye 02", "rendered_width": 400}, {"document_url": "https://auth0.com/blog/iris-recognition-for-two-factor-authentication-with-ruby-on-rails/", "unformatted_src": "https://s3.eu-west-2.amazonaws.com/iris-blog-images/eye-diff.png", "src": "https://s3.eu-west-2.amazonaws.com/iris-blog-images/eye-diff.png", "formatted_filename": "eye diff", "alt_text": "Right Eye diff", "rendered_width": 400}, null, {"document_url": "https://auth0.com/blog/iris-recognition-for-two-factor-authentication-with-ruby-on-rails/", "unformatted_src": "https://s3.eu-west-2.amazonaws.com/iris-blog-images/initial-iris-check-page.png", "src": "https://s3.eu-west-2.amazonaws.com/iris-blog-images/initial-iris-check-page.png", "formatted_filename": "initial iris check page", "alt_text": "Initial Iris Check Page", "rendered_width": 600}, null, null, null, null, null, {"document_url": "https://auth0.com/blog/iris-recognition-for-two-factor-authentication-with-ruby-on-rails/", "unformatted_src": "https://cdn.auth0.com/blog/guest-authors/pencil.png", "src": "https://cdn.auth0.com/blog/guest-authors/pencil.png", "formatted_filename": "pencil", "alt_text": "Auth0 Guest Author Program"}, null]
Iris Recognition for Two Factor Authentication with Ruby on Rails

Using Ruby on Rails to combine Auth0 Login with Iris Recognition for Two Factor Authentication Robin Percy

Technology Used

What, Why?

Social engineering methods are increasingly being used to gain access to User Credentials. While the provider maybe as secure as can be, they are not always the source of credential leaks. Obtaining usernames and passwords by effectively 'tricking' people into handing them over is becoming more and more common.

If a miscreant is to get hold of your account login details, naturally they will be able to access sensitive data. Of course, there are already many methods available to combat this, such as mobile 2 factor auth; I wanted to take a slightly different (more fun) approach to combat the situation.

The idea behind 'Eyeball' is to offer a multi-factor authentication scenario in which we use Auth0's login page as first-line login, then upon success offer Iris recognition as second-line. This means that if a User's account details are compromised, the offender would also have to have access to the User's eyeball. (Much less likely!)

From a technical standpoint, we will be building our own Image Comparison application utilising the ImageMagick subsystem.

IMPORTANT NOTE - As this app is just a proof of concept hack, I wouldn't recommend re-using any of this code in a production environment. This article is simply to be used as an inspiration to get the gist of the technology. Using ImageMagick is fine for this article, but if you want truly accurate and secure results, I would recommend looking at the pHash algorithm & library, and the Blockhash library. I will cover these libraries in the future in detail - showing production-ready, tested data.


We will be using Ruby / Rails to build this app. There is already a fantastic quick-start tutorial available, alongside a sample Rails application on the Auth0 Docs. Instead of starting from scratch, we will simply download this sample app and iterate on it!

Even more handy - Auth0 allows you to download this sample Rails app configured with your Auth0 API Keys already in! Head over here to download it.

For simplicity, we are going to be making an assumption. A User can't assign their own Iris image in the first place, and this will be upto an Admin. This reflects a more realistic enterprise situation, for instance a new employee would have their Iris scanned, then an Admin would add that Iris to their User Profile. In our application specifically, we will be reflecting this by storing, and accessing a iris_image_url in Auth0's metadata. This is just a path to the User's stored Iris image, that we shall use in comparison to the temporarily uploaded Iris image upon login.

Setting up our second-line defence routes

Our sample app already has Auth0's login setup and working. The Rails app also has a Dashboard route setup to be redirected to upon successful login. We need to setup a new route to act as a go-between after successful login and before the User actually gets to see their Dashboard.

Go ahead and run:

This will create a new route at iris/check that we can redirect to after a successful Auth0 login. We now need to edit our existing Auth0Controller to reflect this. Open up app/controllers/auth0_controller.rb and update the callback method as follows:

If you boot your app, and test the login you should now see we don't get to access our Dashboard, but get sent to our Iris Check page.

Building our Iris Recognition!

Now then, let's do something fun - facilitate our makeshift eyeball scanner!

While there are many API's available for Image Recognition, there are no simplistic ones available for specifically comparing two images, so we're going to roll our own. Whereas there are great arguments for choosing to use an existing API instead of building our own, it's a better learning experience in this case to do the latter.

Image processing for recognition / comparison is a very deep topic and can be expanded into Machine Learning and simply get deeper and deeper. For this article, we'll be building our Image Comparison system without the added benefit of Machine Learning. Worth noting - in real world scenarios, Iris Scanners have very advanced cameras and flashes allowing deep factoring of individual Iris'. For our proof of concept app, our mobile phone camera will suffice!

For now, we're going to use the application ImageMagick for our comparison functionality. This comes bundled with Ubuntu and is generally widely available. If you're on a Mac and don't want to download it from the net/app store - you can use Homebrew.

ImageMagick's Compare functionality takes an input of two images, and outputs both an image file with the pixel difference highlighted, and a numeric diff figure depending on which metric is used for analysis. ImageMagick compares the images by using Pixel Channels.

For the metric choices available, run the following command:

And to find out a little about each of them, see these docs.

For our application, we're going to use the Mean Absolute Error Count MAE option. This will give us the normalized, average pixel channel error distance.

Let's take this sample image of a Medieval print, do some testing, then put it all together into our Rails app! Assuming that the ImageMagick CLI is available in our bash profile, we can experiment with the following.. To create a secondary image of this print, which is largely the same, we will use ImageMagick's convert function to sharpen the image colours, and apply a gaussian blur. This will leave us with an image with the same dimensions, and with similar Pixel Channels. Let's run:

We should now have a second print image, that looks very similar, but does have subtle differences. As mentioned above, we will use the Mean Absolute Error Count metric to get a pixel channel difference between the two images, from ImageMagick's CLI.

Upon running that command, we should get returned in our STDERR output the numeric Diff: 4610. There will also be a third image file in our working directory called '24442301_DIFF.png' that highlights in the red spectrum pixel channel, the differences ImageMagick picked up between the two images: This image may look a little strange to our human eyes, but to ImageMagick, it's the only way of factoring a Diff. Whilst it's certainly an interesting image, it's pretty useless to us - we really only need the Diff figure - 4610.

The Diff figure represents the actual pixel difference between the two images. We know that there are 4610 pixels affected by our sharpen/blur action and now we need to translate this into a usable percentage difference that we can apply to any two images. For this, we're going to need to come up with an algorithm that suits our needs and that we can realiably use on an ongoing basis in our app.

We can acquire a reliable actual Diff percentage figure as long as we know a couple of variables: * The pixel Diff figure * The exact dimensions of the images or Pixel Count

You may think this is very straight forward, but it gets a little more difficult when we factor in that our image uploader may send us something an entirely different size to the image we have stored on file. In a Real World scenario, this is a big issue and we actually couldn't use ImageMagick without doing smart image resizing on our-side first! For the sake of this article, we're going to stick with ImageMagick, and imagine in our Utopian world that all images uploaded are the same size as the Iris images stored.

So now assuming our images are going to be the same size, we can use ImageMagick again to get the Pixel Count:

Running this, we've created a txt file containing the Pixel Count figure - 313995.

So - our algorithm; we know the end figure we want is the actual Diff percentage between the two images. The equation below should give us exactly what we need:

Working on the figures we already have - calculating our sum using the equation above should give us: 1.4682. So from this, we can reliably say that our two images have a 1.4682% difference in pixels. Or reversing this, we know that our images have a 98.5318% match.

As a secondary check, I also ran these images through the pHash c++ library using a much more advanced Radial Hash algorithm, and the diff match came out at 97.9%.

Now it's up to us to decide how much of a variation on this figure is acceptable and will allow a User to continue. To decide on this, I did some experimenting with two photos of my right eye taken on my iPhone. While the images don't look markedly different to me, the image processor must have seen a few things I didn't. Once again, running the script using the MAE metric, and using the -verbose option; the results came out as follows:

So the match from this came out at 87.45%. From this we can safely set the minimum match level in our App at around 85%. Again, this level depends entirely on your security requirements but considering this is just a sample app and not to be used in production - ours doesn't matter all too much!

Integration into our Rails App

So now we have our image recognition working, we need to integrate it into our app. The first thing we need to do is create an Image Uploader for our Users to take a photo of their Iris and upload it to compare with the stored image. For this, I'd recommend using the CarrierWave gem to create an uploader for our user's Iris.

Go ahead and add these to your Gemfile & bundle.

You can see how to integrate an Image uploader by following the docs here.

So once we've got our Image uploader in the frontend of our app, we can use the uploaded image from Carrierwave, to compare to our stored image. We need to call the Auth0 API to get our stored iris_image_url from the user's metadata, and compare the two with our image comparison hack.

Before that, we need to actually integrate our comparison algorithm into our Rails app.

Comparison method in Rails App

We should create a Method for our Iris comparison that we can call in our Controller. Let's change our iris_controller.rb to include the following:

So now we have working image comparison functionality that we can call within our Rails Controllers. We will be using this in our controllers/iris_controller on our /check page to compare the image that's uploaded by the user, against the image stored in the Metadata in Auth0.

Storing iris image in User Metadata

As I mentioned at the beginning of this article, we have already stored an Iris image in Amazon S3, and saved the URL as metadata in Auth0. There's a fantastic guide on setting data using the various API clients here. It should be noted that there is a difference between user_metadata and app_metadata within Auth0 and I feel I should explain. We need to use app_metadata to store our iris url. This is because users have read/write access to user_metadata, and therefore could potentially change the url of the Iris image to something completely different, and entirely bypass our system!

Worth noting at this point - the iris_url should only be accessible from the backend of our application, privately. Alongside this, the S3 hosted image should not be publicly accessible, and only available to your application. The images I have used are publicly available as they are just a demo for this article.

To get access to this metadata, we need to create a rule to add the user app_metadata in the id token. Go to your Auth0's dashboard. Create a new rule and add the following code:

Then we can simply use native Ruby and the session data returned from Auth0 and OmniAuth. We can obtain this data by using the auth hash returned from OmniAuth & Auth0. Open up your iris_controller.rb and add the following private method:

Once we've added that, let's just ensure it's working. Open up the file: views/iris/check.html.erb, and enter the following:

If you run your Rails app now, and go through the initial Auth0 Login Page successfully; you'll be redirected to the Iris/check page. Your app should reflect the following: From this we know that our OmniAuth Hash is returning everything we need for our image comparison. We would not usually display the iris_image_url, but for the sake of this demo I am for now. We can access the User's details such as email address, name etc. allowing us to provide a greeting, but realistically, we only need the http://example.com/iris_url metadata, and we can move onto the final stage of our app build!

Bringing it all together

As shown above, we can call our Comparison functionality and get our user's Metadata in our Controller. Now we need bring them together, and the only thing left for you to do is set your entry percentage rule, and setup the redirect to whichever page you wish to send successful entries to!

Open up iris_controller.rb and have it reflect this:

Note: Using Auth0's Centralised Login Page is a more secure way of utilising Auth0's user management technology.

Aside: Using Auth0 with Rails

We can easily set up authentication in our Rails apps with Auth0's Login Page. If you don't already have an Auth0 account, sign up for one now. Navigate to the Auth0 management dashboard, select Applications from the navigational menu, then select the app you want to connect with Rails.

Step 1: Install and initialize OmniAuth Auth0

Add the following dependencies to your Gemfile and run bundle install:

Create a file named auth0.rb under config/initializers and configure the OmniAuth middleware in it.


Head over to your Auth0 dashboard and register Allowed Callback URLs http://localhost:3000/auth/oauth2/callback and Allowed Logout URLs http://127.0.0.1:3000.

Step 3: Include Auth0's centralized login page

Add the following code to the view app/views/home/show.html.erb file:

~~~ html RoR Auth0 Sample

Step 1 - Login.

Login ~~~

Step 4: Protect routes

Create a controller concern controllers/concerns/secured.rb to control access to routes that require the user to be authenticated:

Include the concern in the dashboard controller controllers/dashboard_controller.rb to prevent unauthenticated users from accessing its routes:

Step 5: Configure logout

Use the following command to create the controller that will handle user logout:

To clear out all the objects stored within the session, call the reset_session method within the logout_controller/logout method. Learn more about reset_session here.


So there we have it! It's important to note that this article is not meant to supply a production-ready system. I wanted to give you an idea of some of the cool things we can do easily with Auth0 Login, and how simple it is to integrate into our applications!

Building user systems from scratch takes a long time - and as Developers, we're utilising more and more API's on a daily basis. Auth0 makes it incredibly simple for us to setup a highly secure, super scalable User System in a small fraction of the time it would have taken us to build it in-house.

Iris recognition is an incredibly complex topic when used in real-world scenarios - this Article is meant to inspire you with a basic idea on how one could be integrated with Auth0, and how you can utilise it as a second-line login system alongside Auth0 Login. For a more secure and realistic image comparison, check out the aformentioned pHash and Blockhash algorithms.

I'm always more than happy to chat through ideas on improving production security, and any ideas to do with cool new tech - so if you have any questions / comments, please reach out to me!

Thanks for reading! - @rbin

 Two-Factor Authentication Using Biometrics

João Angelo Auth0 Lock Is Here For Both B2C And B2B Login

