Implementation - Best Practices

 

 

Copyright Statement

The specifications and information regarding the product in this manual are subject to change without prior notice. All statements, information, and recommendations in this manual are believed to be accurate but are presented without warranty of any kind, expressed or implied. Users must take full responsibility for their use of any products.

© 2017-2018 Verisec Freja eID AB. All rights reserved.

Introduction/Overview

In this section we have compiled some examples of what we consider the best practices for integrating with our API.

Launching the Freja eID App Automatically

The Freja eID application can be started automatically from the relying party mobile application or from the browser, returning the control back once the user has processed the action (i.e. approved or declined).

The Initiate authentication method can be invoked from a browser or an application on the mobile phone on which the Freja eID app is installed. The invocation is actually performed through opening a custom URL with a scheme registered by the Freja eID app. Preconditions for a successful operation are, therefore, that the Freja eID is installed on the device the custom URL is invoked, and that the mobile device is online, as the Freja eID must contact the Freja eID infrastructure in order to fulfil the request. The custom URL should be constructed as follows:

Custom URL scheme for invoking the identify method
frejaeid://?originAppScheme=abcdefgh

where ''abcdefgh'' stands for your custom scheme like in the example below:

Example custom URL scheme
frejaeid://?originAppScheme=verisec://

Authentication Service

QR Code Authentication

Qr code authentication is a new method that is supported by the Freja eID Authentication service. In essence, a user authenticates themselves by scanning a generated QR code and approving the authentication action. This method is very secure because users must physically be presented with a QR code to scan, otherwise an action cannot be generated in their name.

On mobile the process is even simpler since the user needn't scan a QR code physically. Everything takes place within their device thereby making authentication even more secure because the authentication process is initiated and approved on the same device. In addition, this method is the most user friendly since it foregoes typing in user identifiers (emails, phone numbers etc.).

In summary, we recommend implementing this kind of authentication because:

  • It is much more user friendly, especially on mobile.
  • It is a much safer method of authentication.

Implementing QR Code Authentication

In this method the end user is authenticated via a QR code.

There is a difference between implementing this in a web browser and mobile browser/app.

In both cases the user doesn't need to enter any identifier e.g. email, phone number etc. However, if you need details about the user that can be specified in the attributesToReturn parameter in the initAuthRequest. Retrieving the authentication results for this method is the same as for other authentication methods. For more details please see Authentication Services.

Javascript Code Snippet

 If your company uses javascript, this code snippet shows how this can be implemented in javascript.

 

/**
* This method is used for generating and displaying QR code for authentication on web browser or
* opening Freja eID app to finish authentication when user is on mobile browser.
*
* param qrCodeGenerationServiceAddress - address of qrCode generation service. It can be
* https://resources.prod.frejaeid.com or https://resources.test.frejaeid.com depending on
* environment.
* param authRef - authentication reference received in response from initAuth method
* param mobileBrowserReturnAddress - address where the user should be returned after finishing
* authentication. 
*/
function handleQrCodeAuthentication(qrCodeGenerationServiceAddress, authRef, mobileBrowserReturnAddress) {
    var urlEncodedAuthRef = encodeURIComponent(authRef);
    var frejaEidAuhtenticationSchema = "frejaeid://bindUserToTransaction?transactionReference=" + urlEncodedAuthRef;
    // this method checks if user is on mobile browser
	if (isItMobile()) {
        window.location = frejaEidAuhtenticationSchema + "&originAppScheme=" + mobileBrowserReturnAddress;
    } else {
        var urlEncodedGenerateQrCodeParameter = encodeURIComponent(frejaEidAuhtenticationSchema);
        $("#qrCodeImage").attr("src", qrCodeGenerationServiceAddress+"/qrcode/generate?qrcodedata=" + urlEncodedGenerateQrCodeParameter);
        $("#qrCodePopup").css("display", "flex");
    }
}


Web Browser

The QR code is displayed to users on the Relying Party's web page. They scan it with Freja eID and approve the authentication action in the app.

The following is the required procedure for successfully implementing QR code authentication in the web browser.

  1. Create initAuthRequest with "userInfoType":"INFERRED" and "userInfo":"N/A".

    Example of initAuthRequest with "userInfoType":"INFERRED" and "userInfo":"N/A"

    If you wish to initiate an authentication request for QR code authentication:

    1. Create the JSON structure {"userInfoType":"INFERRED","userInfo":"N/A"}
    2. Encode the JSON structure to Base64.
    3. Create the HTTP POST request with a POST parameter name initAuthRequest and the Base64 encoded JSON structure from the step 2 as its value.

    The HTTP body should be the following:

    initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJJTkZFUlJFRCIsInVzZXJJbmZvIjoiTi9BIn0=


    The response contains the authentication reference for the request you issued:

    Response example:
    {"authRef":"W5IJKBH95h9KRhICimRia5otxkVuP36Aw5CRLYOteIQfx4bpfmvDnW7AbDugMjIa"}



  2. Perform URL encoding on the authRef received in the response.

    Example of URL encoded authRef:
    W5IJKBH95h9KRhICimRia5otxkVuP36Aw5CRLYOteIQfx4bpfmvDnW7AbDugMjIa



  3. Insert the result into the following schema: frejaeid://bindUserToTransaction?transactionReference=

    Example result:
    frejaeid://bindUserToTransaction?transactionReference=W5IJKBH95h9KRhICimRia5otxkVuP36Aw5CRLYOteIQfx4bpfmvDnW7AbDugMjIa



  4. Perform URL encoding on the previous schema.

    Example result:
    frejaeid%3A%2F%2FbindUserToTransaction%3FtransactionReference%3DW5IJKBH95h9KRhICimRia5otxkVuP36Aw5CRLYOteIQfx4bpfmvDnW7AbDugMjIa



  5. Use this as the parameter for the HTTP GET method which generates Freja eID QR code:

    Example HTTP GET method for the test environment:
    https://resources.test.frejaeid.com/qrcode/generate?qrcodedata=frejaeid%3A%2F%2FbindUserToTransaction%3FtransactionReference%3DW5IJKBH95h9KRhICimRia5otxkVuP36Aw5CRLYOteIQfx4bpfmvDnW7AbDugMjIa
    Example HTTP GET method for the production environment:
    https://resources.prod.frejaeid.com/qrcode/generate?qrcodedata=frejaeid%3A%2F%2FbindUserToTransaction%3FtransactionReference%3DW5IJKBH95h9KRhICimRia5otxkVuP36Aw5CRLYOteIQfx4bpfmvDnW7AbDugMjIa



  6. Display the generated QR code as an image on your web page for the user to scan.

Mobile Browser/App

The QR code is NOT displayed to users, rather, there is only a 'Log In with Freja eID' button. This starts the Freja eID app where they approve the authentication action and are then taken back to the website.

  1. Create initAuthRequest with "userInfoType":"INFERRED" and "userInfo":"N/A".

    Example of initAuthRequest with "userInfoType":"INFERRED" and "userInfo":"N/A"

    If you wish to initiate an authentication request for QR code authentication:

    1. Create the JSON structure {"userInfoType":"INFERRED","userInfo":"N/A"}
    2. Encode the JSON structure to Base64.
    3. Create the HTTP POST request with a POST parameter name initAuthRequest and the Base64 encoded JSON structure from the step 2 as its value.

    The HTTP body should be the following:

    initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJJTkZFUlJFRCIsInVzZXJJbmZvIjoiTi9BIn0=


    The response contains the authentication reference for the request you issued:

    Response example:
    {"authRef":"W5IJKBH95h9KRhICimRia5otxkVuP36Aw5CRLYOteIQfx4bpfmvDnW7AbDugMjIa"}



  2. Perform URL encoding on the authRef received in the response.

    Example of URL encoded authRef:
    W5IJKBH95h9KRhICimRia5otxkVuP36Aw5CRLYOteIQfx4bpfmvDnW7AbDugMjIa



  3. Insert the result into the following schema: frejaeid://bindUserToTransaction?transactionReference=...&originAppScheme=yourwebsiteaddress.com
    The "originAppScheme" serves to redirect the user after authentication to the specified url e.g. your website.

    Example result:
    frejaeid://bindUserToTransaction?transactionReference=W5IJKBH95h9KRhICimRia5otxkVuP36Aw5CRLYOteIQfx4bpfmvDnW7AbDugMjIa&originAppScheme=yourwebsiteaddress.com



  4. By clicking the log in button the user acts upon the schema which will navigate them to the Freja eID app to finish the authentication process. After that, "originAppScheme" will navigate the user to the specified url.