Implementation - Troubleshooting and Best Practices
This page:
Services:
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.
Use case | Issue | Explanation | Possible solutions and best practices |
---|---|---|---|
Authenticating users with personal identity number | User has not installed Freja eID app yet or is not on a required level of registration | Personal identity number (in our system also known as SSN) is a unique, nationwide number, used in many countries for identification purposes. This number is normally issued by the government and appears on identity documents. To be able to authenticate your users through their personal identity number, the minimum registration level in the authentication request must be set to EXTENDED or PLUS. This is the only way for Freja eID to obtain user's personal identity number. If a user has not added an ID document to their Freja eID account (equals to registration level EXTENDED) or upgraded to Freja eID Plus (equals to registration level PLUS), they cannot receive your request. For reasons of security and user protection, Freja eID Relying Party API currently does not inform you if a user you are trying to authenticate with personal identity number exists in our system. In any case, your authentication request will be processed. However, if the required personal identity number is not in our database, the request will remain ''hanging'' without actually getting to a user and will eventually expire. If you get too many authentication results with the status EXPIRED, there is a possibility that users have not installed Freja eID application yet or that they have not provided their personal identity number i.e. they have not added an ID document to their Freja eID account. Another case that might happen is that the user has added an ID document, but has not upgraded to Freja eID Plus, which is your required level of registration. In this case, the user will receive your request in the app but the action will be disabled. The app itself will instruct the user to upgrade to Freja eID Plus to complete the action. | To provide the best user experience, we recommend you provide your users with:
Inform your users that they should add an ID document to their Freja eID account and/or upgrade to Freja eID Plus to be able to use Freja eID for authentication against your service. If the required level of registration is PLUS, you can highlight that in the login form itself, putting the label 'Freja eID Plus' instead of just 'Freja eID' on our custom button. Feel free to direct users to Freja eID official website for any additional information. |
Authenticating users with email address | Email address does not exist | The email address the user has entered to access your service via Freja eID has not been registered in our system, meaning that either the user has not installed Freja eID at all, or has registered with another email address. Currently, for reasons of security and user protection, Freja eID Relying Party API does not inform you if a user you are trying to authenticate with email address exists in our system. In other words, even if the email address is not registered in our database, your request will be processed. When fetching authentication results, you will eventually receive the status EXPIRED. | Provide users with basic information about Freja eID. Instruct them how to download and install the Freja eID app, and then how to complete the basic registration. Your users should be aware that the email address they wish to use to access your service must be connected to their Freja eID account. It can be the same address they used to register or another email address connected to their Freja eID. For example, if you require a company email address for authentication, the user must have that email address added to their Freja eID account. This is done via My Pages web app, under User details section. Feel free to add links to app stores for downloading the app or refer to Freja eID official website for more information. |
User is not on a required level of registration | The user you are trying to authenticate is not on your required level of registration, e.g. you have required them to be on the EXTENDED or PLUS level and they have only done the basic registration. If this is the case, the user will receive your authentication request in their Freja eID app, but the action will be disabled. The app itself will instruct the user what to do in order to complete the action. | Inform your users that they need to add an ID document and/or upgrade to Freja eID Plus in order to access your service via Freja eID. Users will also be instructed on how to do this in the Freja eID app itself. If the required level of registration is PLUS, you can highlight that in the login form itself, putting the label 'Freja eID Plus' instead of just 'Freja eID' on our custom button. | |
Authenticating users with phone number | Phone number does not exist | The phone number the user has entered to access your service via Freja eID has not been registered in our system, meaning that either the user has not installed Freja eID at all or has not added a required phone number to their Freja eID account. Currently, for reasons of security and user protection, Freja eID Relying Party API does not inform you if a user you are trying to authenticate with phone number exists in our system. In other words, even if the phone number is not registered in our database, your request will be processed. When fetching authentication results, you will eventually receive the status EXPIRED. | Inform your users that they need to add a phone number to their Freja eID account and then use the same phone number to access your service. Adding phone number is done via My Pages, under User Details. |
User is not on a required level of registration | The user you are trying to authenticate is not on your required level of registration, e.g. you have required them to be on the EXTENDED or PLUS level and they have only done the basic registration. If this is the case, the user will receive your authentication request in their Freja eID app, but the action will be disabled. The app itself will instruct the user what to do in order to complete the action. | Inform your users that they need to add an ID document and/or upgrade to Freja eID Plus in order to access your service via Freja eID. Users will also be instructed on how to do this in the Freja eID app itself. If the required level of registration is PLUS, you can highlight that in the login form itself, putting the label 'Freja eID Plus' instead of just 'Freja eID' on our custom button. | |
General | User has disabled your service | All the services connected to Freja eID are by default enabled for all our users. However, the user can disable a specific service in My Pages - a web page connected to their Freja eID account, containing the information about offered services, action history and personal data overview. User can access My Pages once they perform the basic registration in the app - confirm an email address and set a PIN. Logging in to My Pages is done via the Freja eID app. If a user has disabled your service, you will receive the following error code: | We suggest you inform your users about this and prompt them to go to My Pages and enable your service again if they wish to use it. |
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:
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:// |
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.
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"} 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"} - Create the JSON structure
Perform URL encoding on the authRef received in the response.
Example of URL encoded authRef: W5IJKBH95h9KRhICimRia5otxkVuP36Aw5CRLYOteIQfx4bpfmvDnW7AbDugMjIa Insert the result into the following schema: frejaeid://bindUserToTransaction?transactionReference=
Example result: frejaeid://bindUserToTransaction?transactionReference=W5IJKBH95h9KRhICimRia5otxkVuP36Aw5CRLYOteIQfx4bpfmvDnW7AbDugMjIa Perform URL encoding on the previous schema.
Example result: frejaeid%3A%2F%2FbindUserToTransaction%3FtransactionReference%3DW5IJKBH95h9KRhICimRia5otxkVuP36Aw5CRLYOteIQfx4bpfmvDnW7AbDugMjIa 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 - 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.
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"} Create initSignRequest with "userInfoType":"INFERRED" and "userInfo":"N/A" for signing transaction as described in section 1. b. for web browsers above.
Perform URL encoding on the authRef received in the response.
Example of URL encoded authRef: W5IJKBH95h9KRhICimRia5otxkVuP36Aw5CRLYOteIQfx4bpfmvDnW7AbDugMjIa 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 - 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.