Authentication Service Client

 

Overview

Freja eID Authentication Service allows Relying Parties 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). Relying Parties can authenticate Freja eID users through one or more email addresses or phone numbers, as well as through the personal identity number (i.e. social security number) for users that have passed the extended registration flow. 

For more detailed information about the Authentication Service, please refer to Freja eID Relying Party Developers' Documentation.

Calling a 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 by a Relying Party to initiate an authentication request. The method is intended for authentication in online contexts, where access to the Relying Party’s service or application is initiated by the end user. The authentications are, therefore, short-lived – from the point of initiation, the user has a maximum of two minutes to confirm the authentication through Freja eID mobile application. Only one active authentication may exist for any given end user at any given time. An attempt to concurrently start a second authentication, by the same or different Relying Party, will cancel both initiated authentication requests.

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


/*
* Initiate authentication request can be created with EMAIL.
* Change the email value (joe.black@verisec.com in the example) to match your setup.
* See the example below.
*/
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.
* See the example below.
*/
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.
* See the example below.
*/
String phoneNum = "+467123456789";
InitiateAuthenticationRequest initiateAuthenticationRequest = InitiateAuthenticationRequest.createCustom()
                .setPhoneNumber(phoneNum)
                .build();

/*
* Initiate authentication request can be created as INFERRED by using the custom request builder. 
* See the example below.
*/
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, Relying Parties can request the minimum registration level the user should be on in order to complete the authentication. Supported levels are BASIC, EXTENDED and 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.
* See the example below.
*/
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

A Relying Party 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 email address), DATE_OF_BIRTH (user's date of birth), RELYING_PARTY_USER_ID (a unique, user-specific value that allows the Relying Party to identify the same user across multiple sessions), SSN (social security number/personal identity number and country) and CUSTOM_IDENTIFIER (a unique, Relying Party-specific, user identifier, set by the Relying Party through the Custom Identifier Management Client). If this is the case, it is necessary to pass another parameter in initiate authentication request builder - an array of attributes that represents that extra information required.

If the Relying Party is asking for attributes BASIC_USER_INFO, DATE_OF_BIRTH or SSN, the minRegistrationLevel parameter in the initAuthRequest must be set to EXTENDED or PLUS or the request will fail.


/*
* 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.DATE_OF_BIRTH, 
								  AttributeToReturn.RELYING_PARTY_USER_ID, 
								  AttributeToReturn.SSN, 
								  AttributeToReturn.CUSTOM_IDENTIFIER};
InitiateAuthenticationRequest initiateAuthenticationRequest = InitiateAuthenticationRequest.createCustom()
                .setEmail(email)
				.setMinRegistrationLevel(minRegistrationLevel)
                .setAttributesToReturn(attributes)
                .build();
String transactionReference = authenticationClient.initiate(initiateAuthenticationRequest); 

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

/*
* Parameter relyingPartyId represents a unique ID of the Relying Party
* for which the authentication request should be initiated.
*/
String relyingPartyId = "relying_party_id";

InitiateAuthenticationRequest initiateAuthenticationRequest = InitiateAuthenticationRequest.createCustom()
                .setEmail(email)
				.setRelyingPartyId(relyingPartyId)
                .build();

Integrator specific user id

An Integrated Relying Party can ask for additional information about the user in the same way as other Relying Parties, but can also ask for INTEGRATOR_SPECIFIC_USER_ID - 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.

/*
* Parameter relyingPartyId represents a unique ID of the Relying Party
* for which the authentication request should be initiated.
*/
String relyingPartyId = "relying_party_id";

/*
* When initiating authentication, you have to set relyingPartyId for every request.
* See the example below.
*/
String email = "joe.black@verisec.com";

AttributeToReturn[] attributes = {AttributeToReturn.INTEGRATOR_SPECIFIC_USER_ID};
InitiateAuthenticationRequest initiateAuthenticationRequest = InitiateAuthenticationRequest.createCustom()
                .setEmail(email)
				.setAttributesToReturn(attributes)
				.setRelyingPartyId(relyingPartyId)
                .build();
String transactionReference = authenticationClient.initiate(initiateAuthenticationRequest);


Get Authentication Result

This method is used by a Relying Party to fetch a single result for a specified authentication transaction reference (authRef returned from a call to Initiate Authentication method). 

Only Integrator Relying Parties can request integratorSpecificUserId and relyingPartyId has to be passed as a part of the request.

/*
* A reference unique to the transaction that can be used to query the result of a transaction.
*/
String authRef ="reference";
 
/*
* In case of getResult method, response type is AuthenticationResult.
* Response contains authentication reference passed during authentication initiation, status of the action,
* details (can be used for extra validation of response) and, if requested during authentication initiation
* and the action has been approved, response contains additional attributes (basicUserInfo - user's 
* name and surname, emailAddress - user's email address, dateOfBirth - user's date of birth, relyingPartyUserId,
* customIdentifier, ssn - country and ssn or integratorSpecificUserId).
* Request contains authentication transaction reference.
* See the example below.
*/
AuthenticationResultRequest authenticationResultRequest = AuthenticationResultRequest.create(authRef);
AuthenticationResult response = authenticationClient.getResult(authenticationResultRequest);
String receivedAuthRef = response.getAuthRef();
ActionStatus status = response.getStatus();
String details = response.getDetails();
RequestedAttributes requestedAttributes = response.getRequestedAttributes(); 
BasicUserInfo basicUserInfo = requestedAttributes.getBasicUserInfo();
String emailAddress = requestedAttributes.getEmailAddress();
SsnUserInfo ssn = requestedAttributes.getSsn();
String relyingPartyUserId = requestedAttributes.getRelyingPartyUserId();
String dateOfBirth = requestedAttributes.getDateOfBirth();
String customIdentifier = requestedAttributes.getCustomIdentifier();
String integratorSpecificUserId = requestedAttributes.getIntegratorSpecificUserId();


Get Final Authentication Result

This is a blocking method and is used by a Relying Party 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 a final status of the authentication action. If the maximum polling time expires before the action is completed, the method will throw an exception.

Only Integrator Relying Parties can request integratorSpecificUserId and relyingPartyId has to be passed as part of a request.

/*
* A reference unique to the transaction that can be used to query the result of that transaction.
*/
String authRef ="reference";
 
/*
* A maximum time in seconds to wait for a final status of action
* (to be approved, cancelled, rejected or expired).
*/
int maxWaitingTimeInSec = 120;
/*
* In case of pollForResult method, response type is AuthenticationResult.
* Response contains authentication reference passed during authentication initiation, status of the action, 
* details (can be used for extra validation of response) and, if requested during authentication initiation
* and the action has been approved, response contains additional attributes (basicUserInfo - user's 
* name and surname, emailAddress - user's email address, dateOfBirth - user's date of birth, relyingPartyUserId,
* customIdentifier, ssn - country and ssn or integratorSpecificUserId).
* If maxWaitingTimeInSec passes and authentication action is not completed with one of the final statuses,
* this method will throw FrejaEidClientPollingException.
*/
AuthenticationResultRequest authenticationResultRequest = AuthenticationResultRequest.create(authRef);
AuthenticationResult response = authenticationClient.pollForResult(authenticationResultRequest, maxWaitingTimeInSec);
String receivedAuthRef = response.getAuthRef();
ActionStatus status = response.getStatus();
String details = response.getDetails();
RequestedAttributes requestedAttributes = response.getRequestedAttributes(); 
BasicUserInfo basicUserInfo = requestedAttributes.getBasicUserInfo();
String emailAddress = requestedAttributes.getEmailAddress();
SsnUserInfo ssn = requestedAttributes.getSsn();
String relyingPartyUserId = requestedAttributes.getRelyingPartyUserId();
String dateOfBirth = requestedAttributes.getDateOfBirth();
String customIdentifier = requestedAttributes.getCustomIdentifier();
String integratorSpecificUserId = requestedAttributes.getIntegratorSpecificUserId();

Get Authentication Results

This method is used by a Relying Party to fetch the results of multiple outstanding authentications. 

Integrator Relying Parties have to pass relyingPartyId as part of the request.

/*
* Response type is list of authentication result.
* The response will contain a complete list of authentications, successfully initiated within
* last 10 minutes.
*/ 
AuthenticationResultsRequest authenticationResultsRequest = AuthenticationResultsRequest.create();
List<AuthenticationResult> response = authenticationClient.getResults(authenticationResultsRequest);

Cancel Authentication

This method is used to cancel an initiated authentication request.

Integrator Relying Parties have to pass relyingPartyId as a part of the request.

/*
* A reference unique to the transaction that can be used to cancel transaction.
*/
String authRef ="reference";
CancelAuthenticationRequest cancelRequest = CancelAuthenticationRequest.create(authRef);
authenticationClient.cancel(cancelRequest);

Logging and Error Handling

Details for logging and introduction to client exception can be found in the Logging and Error Handling.