Let’s Couple it! Freja eID with Rails.

I recently got a task to upgrade the authentication process withing my project. My client has chosen Freja eID as the secure authentication partner. In this article I will show you the steps that is needed to integrate Freja eID with Rails.

A bit about Freja eID

“Freja eID is an e-ID on your mobile which allows you to log in, sign and approve with your fingerprint or PIN. It also gives you full coverage of your digital activities and allows you to control what services you allow access to.”

I just copied the above description from their website. here is the link to it. you can find more information.

Freja eID

Breakdown of the steps

Here I am going to breakdown this article into following topics.

1. Register with Freja eID for the test environment.
2. Understand the API of Freja eID
3. Choose a good library (gem) to handle restful web services
4. Implementation

1. Register with Freja eID

I have written a article to guide you through this registration. Follow the following link to see the steps.

How to activate test environment in Freja eID

2. Understand the API / Authentication Process

Once you register with Freja eID, they’ll provide a detailed replying party developer’s guide. “Authentication Services” is topic to see to start implementation. But to get a better idea about the whole process read the full document.

Image 1 — Simple architecture of Freja eId authentication

First I have implemented a service call to Freja eID API with user email (A). After validating my request by Freja eID API they’ll send the notification to the related mobile device (B). Also I can start the mobile application using custom URL (D). Finally if the user has accepted the login Freja eID will send the confirmation response ( C ).

There are several requirements for the above process.

• Obtaining an SSL certificate which is providing you access to Freja eID
• Import root certificate

3. Choose a good library (gem)

To handle the http requests through out the project I have used a gem called “HTTPARTY”. Here is the link to look through the gem.

httparty | RubyGems.org | your community gem host

This gem is awesome to handle request response. So I started my work after adding this gem to my gemfile.

gem 'httparty', '~> 0.13.7'

4. Implementation

Refresh the bundle in your application after adding the httparty gem.

bundle install

4.1. Add the certificates

For this you can create a folder inside the config directory and name it as “certificates”. Download the two certificates from freja eID. One is for SSL(.pfx) and other one is the trust root certificate (.crt )

Image 2 — Certificates

4.2. Create a separate class to handle this process

For this I will create the class inside new folder named “freja_authentication” inside the lib directory and I will name the class as “secure_authentication.rb”

Image 3 — SecureAuthentication class in the lib directory

secure_authentication.rb

class SecureAuthentication
  require "base64"
  include HTTParty
end

We need base64 class to encode the data we are sending to Freja eID and I have included the HTTParty gem inside the class so that I can access it’s methods.

If you want to see the what is happening inside when there is a request you can add the following command inside the class, so that you will be able to see the full log about the request and the response.

debug_output $stdout

4.3. Mention the base URI

base_uri "https://auth.test.frejaeid.com"

4.4. Import Certificates

4.5. Create initialize authentication request method

This is the first call to Freja eID API. For this call we need the user email in a JSON format but encoded with Base64.

4.6. Create the method to get the result back from the API

Once we create the initial request to Freja eID with the correct request data, it should send us a authRef which is essential to get the result again. In here to get the result back we need the authref.

So your full class should be like this.

4.7. Session controller

Now we need to handle the controller where you have the login functionality. Before writing anything in my SessionController I wrote some methods in my user model to communicate with the SecureAuthentication class in the lib directory. ‘

user.rb

In the controller first step is to take the email and do initauthReuqest call and get the authRef.

sessions_controller.rb

email = params[:user_login]
user = User.new
response_from_init_auth = user.initAuthRequest(email)
authRef = response_from_init_auth['authRef']

And then write a loop for 2 minutes in order to polling for response.

So, if you get the APPROVED status you can allow the the user to enter the system.

DEMO

Login with email

Image 7 — Simple login page view

Log after clicking the sign in button

Image 8 — Rails server logs the request, initializing

you can see the authRef is coming as a response above.

Starting the loop with the authRef

Image 9 — Rails Server logs the response after the auth response

you can see the status now. It is as “STARTED” initially.

Now the the notification should come your mobile phone if you have registered as freja user and the status is “DELIVERED_TO_MOBILE”

Image 10 — Notification in the Freja eID mobile application

Image 11 — Pressing the right mark

Image 12 — Authenticate through the PIN

Image 13 — Success login message

After you get this message you will get the response with the status “APPROVED”.

def authenticate_from_freja(freja_status)
    unless freja_status == "APPROVED"
      return false
    else
      return true
    end
end