Authentication Service Client

Overview

The Freja eID Authentication Service allows you to authenticate end users through the use of the Freja eID mobile application. The end user will have previously downloaded the Freja eID mobile application and registered with Freja eID. A user may have also undergone an extended registration process by adding an ID document or achieving the status of Freja eID Plus (Sweden only).

You can authenticate Freja eID users through their:

email address(es);
phone number(s);
personal identity number (i.e. social security number) for users that have passed the extended registration flow

For more detailed information about Freja eID Authentication Service API, please refer to our REST API Documentation.

Calling the Service

This section describes how to make calls to the Freja eID Authentication Service API and process the response.

Initiate Authentication

This method is used to initiate an authentication request.

This method is intended to be used in situations where your end users initiate access to your service. These types of authentications are short-lived i.e. from the moment of initiation, the end user has two minutes to confirm their identity via Freja eID.

As a security measure, only one authentication request may exist for any given end user at any given time. In case a user attempts to access either your or some other service while a previous authentication request is still pending, both will be rendered invalid.

For Integrators/Integrator Relying Parties

Relying Parties which are Integrators must set relyingPartyId per request and that can be done only with a custom request. Read more about how Integrator and Integrated Relying Parties can integrate with Freja here.


/*
* Initiate authentication request can be created with EMAIL.
* Change the email value (joe.black@verisec.com in the example) to 
* match your setup.
*/

String email = "joe.black@verisec.com";
InitiateAuthenticationRequest initiateAuthenticationRequest = 
    InitiateAuthenticationRequest
        .createDefaultWithEmail(email);

/*
* Initiate authentication request can be created with SSN.
* Change the ssn value ("123456789001" in the example) and country
* to match your setup.
*/

SsnUserInfo ssn = SsnUserInfo
        .create(Country.SWEDEN, "123456789001");
InitiateAuthenticationRequest initiateAuthenticationRequest =
    InitiateAuthenticationRequest
        .createDefaultWithSsn(ssn);

/*
* Initiate authentication request can be created with PHONE NUMBER
* by using the custom request builder.
* Change the phone number value ("+467123456789" in the example) 
* to match your setup.
*/

String phoneNum = "+467123456789";
InitiateAuthenticationRequest initiateAuthenticationRequest =
    InitiateAuthenticationRequest
        .createCustom()
        .setPhoneNumber(phoneNum)
        .build();

/*
* Initiate authentication request can be created as INFERRED
* by using the custom request builder.
*/

InitiateAuthenticationRequest initiateAuthenticationRequest = 
    InitiateAuthenticationRequest
        .createCustom()
        .setInferred()
        .build();

/*
* In case of Initiate authentication method, response type is String.
* The data in this response is the authentication transaction reference.
*/

String transactionReference = authenticationClient
        .initiate(initiateAuthenticationRequest);

Requesting a Minimum Registration Level

When initiating an authentication, you can request the minimum registration level the user should be on in order to complete the authentication. Supported levels are:

Basic
Extended
Plus

This parameter is optional. If not forwarded, the default value (BASIC) is used.

/*
* When initiating authentication, you can request the minimum registration level of the user.
*/

String email = "joe.black@verisec.com";
RegistrationState minRegistrationLevel = RegistrationState.PLUS;
InitiateAuthenticationRequest initiateAuthenticationRequest = 
    InitiateAuthenticationRequest
        .createCustom()
        .setEmail(email)
        .setMinRegistrationLevel(minRegistrationLevel)
        .build();
String transactionReference = authenticationClient
        .initiate(initiateAuthenticationRequest);

Requesting Additional User Information

You can also ask for additional information about the user. Currently, supported user attributes that can be requested are:

BASIC_USER_INFO (name and surname);
EMAIL_ADDRESS (user's primary email address);

If you would prefer an email with a specific email domain, please get in touch with partnersupport@frejaeid.com

ALL_EMAIL_ADDRESSES (all user's email addresses registered in Freja eID);
ALL_PHONE_NUMBERS (all user's phone numbers registered in Freja eID);
DATE_OF_BIRTH (user's date of birth);
AGE (user's age);
PHOTO (user’s photo, Base64 encoded JPEG bytes);
ADDRESSES (user's current physical addresses);
SSN (social security number/personal identity number and country);
DOCUMENT (user's document type, serial number, country and expiry time);
DOCUMENT_PHOTO (document photo, Base64 encoded JPEG bytes);

In order to be able to request the DOCUMENT_PHOTO attribute, you must first get in touch with partnersupport@frejaeid.com

RELYING_PARTY_USER_ID (a unique, user-specific value that allows the Relying Party to identify the same user across multiple sessions);
CUSTOM_IDENTIFIER (a unique, Relying Party-specific, user identifier, set by the Relying Party through the Custom Identifier Management Client);
REGISTRATION_LEVEL (the user's registration level in Freja eID);
COVID_CERTIFICATES (user's Covid-19 vaccination, test or recovery data);

If you wish to ask for any of these user attributes, you need to pass another parameter in initAuthRequest builder - an array of attributes that represents that extra information required.


/*
* Additional information about the user to be returned. Interpreted as a 
* set of attributes that represents that extra information required.
* The requested information is returned when fetching authentication 
* results.
*/

String email = "joe.black@verisec.com";
RegistrationState minRegistrationLevel = RegistrationState.EXTENDED;
AttributeToReturn[] attributes = {AttributeToReturn.BASIC_USER_INFO,
                                  AttributeToReturn.EMAIL_ADDRESS,
                                  AttributeToReturn.ALL_EMAIL_ADDRESSES,
                                  AttributeToReturn.ALL_PHONE_NUMBERS,
                                  AttributeToReturn.DATE_OF_BIRTH,
                                  AttributeToReturn.AGE,
                                  AttributeToReturn.PHOTO,
                                  AttributeToReturn.ADDRESSES,
                                  AttributeToReturn.SSN,
                                  AttributeToReturn.DOCUMENT,
                                  AttributeToReturn.DOCUMENT_PHOTO,
                                  AttributeToReturn.RELYING_PARTY_USER_ID,
                                  AttributeToReturn.CUSTOM_IDENTIFIER,
                                  AttributeToReturn.REGISTRATION_LEVEL,
                                  AttributeToReturn.COVID_CERTIFICATES
                                  };
InitiateAuthenticationRequest initiateAuthenticationRequest =
    InitiateAuthenticationRequest
        .createCustom()
        .setEmail(email)
        .setMinRegistrationLevel(minRegistrationLevel)
        .setAttributesToReturn(attributes)
        .build();
String transactionReference = authenticationClient
        .initiate(initiateAuthenticationRequest);

User confirmation method

User confirmation method defines how the user needs to confirm the transaction. Possible values for this parameter are DEFAULT and DEFAULT_AND_FACE.
By default, the user confirmation method is DEFAULT, which means that the user confirms transactions by using PIN or device biometrics.
Value DEFAULT_AND_FACE will request from user to perform face authentication in addition to PIN or device biometrics.

Concerning Integrators/Integrated Relying Parties

For each Integrated Relying Party, as well as the Integrator themselves, Freja eID generates a unique identifier called relyingPartyId. The Integrator needs to pass this identifier in each request. Read more about Integrator Relying Parties here.

Integrator-Specific User ID

Besides the above-mentioned attributes, Integrator Relying Parties can ask for an additional user attribute called INTEGRATOR_SPECIFIC_USER_ID. This is a unique, user-specific value that allows the Integrator to identify the same user across multiple sessions regardless of the Integrated Relying Party service that the user is using.

Get Authentication Result

This method is used to fetch a single result for a specified authentication transaction reference (authRef returned from a call to Initiate Authentication method described above)

Get Final Authentication Result

This is a blocking method and is used to fetch a single result with the final status (can be one of: rejected, approved, cancelled or expired) for a specified authentication reference. The method keeps polling until it receives the final status of the authentication action. If the maximum polling time expires before the action is completed, the method will throw an exception.

Get Authentication Results

This method is used to fetch the results of multiple outstanding authentications.

Generate Authentication QR Code

This method is used to generate a QR code for a specified authentication transaction reference (authRef returned from a call to Initiate Authentication method). The user can then authenticate themselves by scanning the generated QR code and approving the authentication action.

Cancel Authentication

This method is used to cancel an initiated authentication request.

Go to: