This page:

Services:

• Authentication Service
• Signature Service
• Organisation ID Service

Management:

• Integrator Relying Party Management
• Custom Identifier Management

Introduction/Overview

In this section we have compiled some examples of what we consider the best practices for integrating with our API as well as recommendations and solutions to possible problems you may encounter.

Troubleshooting and Recommendations

Authentication Service

Below we've listed several use cases where you may run into an issue when initiating an authentication request or fetching authentication results.

We recommend you read this section in its entirety, as the solution to your problem might be found in other, similar use cases. 

If you experience any issues not covered in this list, please contact us at partnersupport@frejaeid.com.

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 (Authentication Service) 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 fulfill the request. The custom URL should be constructed as follows:

frejaeid://?originAppScheme=abcdefgh

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

frejaeid://?originAppScheme=verisec://

On Android devices, this schema is added to the AndroidManifest.xml and on iOS devices to the Info.plist.

Internal error 54 will appear if this schema is not set properly on Android devices. On iOS devices, automatic redirection from your app to Freja eID and back will simply not work.

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 Service.

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. 1. Create initAuthRequest with "userInfoType":"INFERRED" and "userInfo":"N/A" for authentication.

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

      If you wish to initiate an authentication request for QR code authentication: Create the JSON structure {"userInfoType":"INFERRED","userInfo":"N/A"} Encode the JSON structure to Base64. 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. Create initSignRequest with "userInfoType":"INFERRED" and "userInfo":"N/A" for signing transaction.
      

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

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

      If you wish to initiate an signature request for QR code signing: Create the JSON structure  {"userInfoType":"INFERRED","userInfo":"N/A","minRegistrationLevel":"EXTENDED","title":"Sign transaction","expiry":1517526000000,"dataToSignType":"SIMPLE_UTF8_TEXT","dataToSign":{"text":"VGhpcyBpcyBhIHRleHQgZm9yIHNpZ24gdHJhbnNhY3Rpb24u"},"signatureType":"SIMPLE","attributesToReturn":[{"attribute":"BASIC_USER_INFO"}]} Encode the JSON structure to Base64. Create the HTTP POST request with a POST parameter name initSignRequest and the Base64 encoded JSON structure from the step 2 as its value. The HTTP body should be the following (compact format, line broken for clarity only): initSignRequest=eyJ1c2VySW5mb1R5cGUiOiJJTkZFUlJFRCIsInVzZXJJbmZvIjoiT i9BIiwibWluUmVnaXN0cmF0aW9uTGV2ZWwiOiJFWFRFTkRFRCIsInRpdGxlIjoiU2lnbi B0cmFuc2FjdGlvbiIsImV4cGlyeSI6MTUxNzUyNjAwMDAwMCwiZGF0YVRvU2lnblR5cGU iOiJTSU1QTEVfVVRGOF9URVhUIiwiZGF0YVRvU2lnbiI6eyJ0ZXh0IjoiVkdocGN5QnBj eUJoSUhSbGVIUWdabTl5SUhOcFoyNGdkSEpoYm5OaFkzUnBiMjR1In0sInNpZ25hdHVyZ VR5cGUiOiJTSU1QTEUiLCJhdHRyaWJ1dGVzVG9SZXR1cm4iOlt7ImF0dHJpYnV0ZSI6Ik JBU0lDX1VTRVJfSU5GTyJ9XX0=

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

      Response example:
      {"signRef":"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. 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: Create the JSON structure {"userInfoType":"INFERRED","userInfo":"N/A"} Encode the JSON structure to Base64. 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. Create initSignRequest with "userInfoType":"INFERRED" and "userInfo":"N/A" for signing transaction as described in section 1. b. for web browsers above.
      
      

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.