/
Authentication Service

Authentication Service

Authentication Service Overview

The 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 mobile application on one or more devices they possess.

We differentiate between 3 types of users based on assurance of the user's identity.

  1. Basic - for users who have only registered with an email address

  2. Extended - for users whose identity was verified with an ID document

  3. Plus - for users whose identity has been verified to a higher level of assurance

The level of the user allows you to refer to them in different ways (via the userInfoType value). This is important because depending on the userInfoType you implement, that is the identifier that users will have to enter in your login form.

Types of userInfoType supported in Freja are:

  • INFERRED used for QR code authentication;

  • EMAIL with the user’s email;

  • PHONE with the user’s phone number;

  • SSN with the user’s Swedish personnummer.

  • UPI with the user’s unique personal identifier in Freja.

This page is written assuming you implement QR code authentication where userInfoType is set to INFERRED. This is the method of authentication we recommend as the safest and easiest to implement.

Most of the principles and logic described here apply to authentication with other userInfoType so you can still use this page for general information. For specific information about implementation with other userInfoType, you can refer to this page.

QR Code Authentication

With QR code authentication, users authenticate 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 does not need to 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, social security number 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.

This document goes more into depth regarding the Freja eID API. If you would like to see more details QR code login implementation, please refer to this page about Implementation and Best Practices.

Dynamic QR Code Implementation

If you would like more information about implementing dynamic QR codes, refer to this dedicated page about Dynamic QR Code Implementation.

Don’t Forget

There are several technical requirements that must be in place before implementation can begin. Please refer to the section 'Before You Begin' on this page.

Methods in the Authentication Service

The Freja eID Relying Party Authentication Service allows you to:

  1. Initiate an authentication request;

  2. Get one authentication result;

  3. Get multiple authentication results;

  4. Cancel an authentication request.

When it comes to getting authentication results, we recommend using the method for multiple results to reduce the number of polling requests.

Initiate Authentication Method

Use this method to initiate an authentication request. These requests are intended to be used when a user initiates an action to access your online service. Important features of this method are:

  1. Authentication requests are short-lived i.e. from the point of initiation the user has 2 minutes to confirm it via Freja;

  2. Only one active authentication request may exist for any given user at any given time. If the user initiates another authentication request either with your or another service, both will be cancelled.

The method is called using HTTP POST through the URLs below:

Environment

Endpoint

TEST

https://services.test.frejaeid.com/authentication/1.0/initAuthentication

PRODUCTION

https://services.prod.frejaeid.com/authentication/1.0/initAuthentication

JSON Example for initAuthRequest

The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:

{ "userInfoType":"User info type", "userInfo":"User information corresponding to user info type", "attributesToReturn":[ { "attribute":"Type of attribute to be returned" } ], "minRegistrationLevel":"Minimum required registration level of a user", "userConfirmationMethod":"Method used to confirm user's identity", "useDynamicQrCode":"Flag to enable dynamic QR code" }

  • userInfoType: string, mandatory. Describes the type of user information supplied to identify the end user. For QR code login should be set to INFERRED. Here the user does not type anything, they initiate authentication by using their device to scan the QR code presented to them on the login page of your service.

  • userInfo: If userInfoType is INFERRED, then userInfo must be set to: "N/A" because there is no data for the user to enter (see example below).

  • minRegistrationLevel: string, optional. Minimum required registration level of a user in order to approve/decline authentication. Can be BASIC, EXTENDED, PLUS or INFERRED. If not present, default level will be BASIC.

Concerning minRegistrationLevel

When set to INFERRED, the transaction can proceed without enforcing a specific registration level. Instead, the system will infer and use the user's actual registration level at runtime.

The set of returned attributes will vary based on the user's actual level.

For example, if the BASIC_USER_INFO attribute is requested and the user is at the BASIC level, the attribute will not be returned (null), as it is not available at that level. If the user is at EXTENDED or PLUS, the attribute will be included in the response.

In order to be able to use INFERRED as the minimal registration level, you must first get in touch with partnersupport@frejaeid.com.

  • userConfirmationMethod: string, optional. Used to specify the method by which the user's identity is confirmed when performing an action. Can be DEFAULT or DEFAULT_AND_FACE.

  • useDynamicQrCode: boolean, optional. Used to specify whether a dynamic QR code will be used.

  • attributesToReturn: list of objects, optional. When retrieving results, additional information about the user can be returned based on the type of attributes required through this parameter. Each object should contain one attribute. Currently supported attribute types 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),

    • ALL_PHONE_NUMBERS (all user's phone numbers)

    • DATE_OF_BIRTH (date of birth),

    • AGE (user's age based on their date of birth),

    • GENDER (user's gender),

    • PHOTO (user's photo, Base64 encoded JPEG bytes),

    • ADDRESSES (user's current addresses),

    • SSN (social security number and country),

    • DOCUMENT (data from the document used for registration),

    • REGISTRATION_LEVEL (user's registration level in Freja eID),

    • 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).

    • 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. For more info, see the section about Integrator Relying Party Management),

    • Additionally, to be able to request the following attributes you must get in touch with partnersupport@frejaeid.com first:

      • NFC_ID_PHOTO (user's photo from ID document, Base64 encoded JPEG bytes),

      • UNIQUE_PERSONAL_IDENTIFIER (user's unique personal identifier in Freja eID),

      • LOA_LEVEL (user's level of assurance (LOA) in Freja eID),

      • DOCUMENT_PHOTO (document photo, Base64 encoded JPEG bytes),

The following attributes: BASIC_USER_INFO, DATE_OF_BIRTH, AGE, PHOTO, ADDRESSES, SSN, DOCUMENT or DOCUMENT_PHOTO are not available for BASIC users.

Example Request with INFERRED userInfoType

  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 step 2 as its value.

The HTTP body should be the following:

initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJJTkZFUlJFRCIsInVzZXJJbmZvIjoiTi9BIn0=

Possible Errors

Code Returned

Explanation

0

Internal error.

1001

Invalid or missing userInfoType.

1002

Invalid or missing userInfo.

1003

Invalid restrict.

1004

You are not allowed to call this method.

1005

User has disabled your service.

1007

Invalid min registration level.

1008

Unknown Relying Party.

1009

You are not allowed to request integratorSpecificUserId parameter.

1010

JSON request cannot be parsed.

1012

User with the specified userInfo does not exist in Freja eID database.

2000

Authentication request failed. Previous authentication request was rejected due to security reasons.

2002

Invalid attributesToReturn parameter.

2003

Custom identifier has to exist when it is requested.

JSON Response Value

If HTTP 200 is returned from the method, the following return value will be present in the body of the response:

{ "authRef":"Reference to be submitted in getAuthResults method" }

  • authRef: string, mandatory. A reference unique to the transaction that can be used to query the result of a specific transaction.

JSON Response Value if useDynamicQrCode is set to TRUE

{ "authRef":"Reference to be submitted in getAuthResults method", "qrCodeSecret":"Secret used for generating dynamic QR code" }

  • authRef: string, mandatory. A reference unique to the transaction that can be used to query the result of a specific transaction.

  • qrCodeSecret: string, mandatory. Used to generate dynamic QR code in real time.

Get One Authentication Result Method

The method is called using HTTP POST through the URLs below:

Environment

Endpoint

TEST

https://services.test.frejaeid.com/authentication/1.0/getOneResult

PRODUCTION

https://services.prod.frejaeid.com/authentication/1.0/getOneResult

JSON Example for getOneAuthResultRequest

The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:

{ "authRef":"Authentication reference" }

authRef: string, mandatory. The value must be equal to an authentication reference previously returned from a call to the Initiate Authentication Method. Because authentications are short-lived, fetching the result of a given authRef is only possible within 10 minutes from the time the initial authentication request was made.

Example Request

If you wish to fetch an authentication result with the authentication reference previously returned from a call to initAuthRequest, follow these steps:

  1. Create the JSON structure {"authRef":"GOHPyJcoKLJ+zKCEy4abi6jOO+q5VK+S1+UO5OXRmOPu42ixvVnsVgs7ADYUfG8m"}

  2. Encode the JSON structure to Base64.

  3. Create the HTTP POST request with a POST parameter name getOneAuthResultRequest and the Base64 encoded JSON structure from step 2 as its value.

The HTTP body should be the following:

getOneAuthResultRequest=eyJhdXRoUmVmIjoiR09IUHlKY29LTEorektDRXk0YWJpNmpPTytxNVZLK1MxK1VPNU9YUm1PUHU0Mml4dlZuc1ZnczdBRFlVZkc4bSJ9

Possible Errors

Code Returned

Explanation

1004

You are not allowed to call this method.

1008

Unknown Relying Party.

1100

Invalid reference (for example, nonexistent or expired).

JSON Response Value

If HTTP 200 is returned from the method, the following return value will be present in the body of the response:

{ "authRef":"Authentication reference", "status":"Authentication status", "requestedAttributes":"Additional attributes about the user", "details":"JWS signed data" }

  • authRef: string, mandatory. The authentication reference of the authentication.

  • status: string, mandatory. One of:

    • STARTED (the transaction has been started but not yet delivered to Freja eID application associated with the end user),

    • DELIVERED_TO_MOBILE (the Freja eID app has downloaded the transaction),

    • CANCELED (the end user declined the authentication request),

    • RP_CANCELED (the authentication request was sent to the user but cancelled by the RP before the user could respond),

    • EXPIRED (the authentication request was not approved by the end user within the authentication validity limit of two minutes),

    • APPROVED (the authentication was successful) or

    • REJECTED (e.g. if you try to run more than one authentication transaction for the same user at the same time).

  • requestedAttributes: JSON object, optional. Provides additional attributes about a user if required in attributestToReturn parameter in related initAuthRequest and the status was equal to APPROVED. For more details see below.

  • details: JWS signed object, optional. Provides details and evidence of the authentication if status was equal to APPROVED. For more details see below.

requestedAttributes

Below is an example with all possible requestedAttributes and their information:

{ "basicUserInfo":{ "name":"User's name", "surname":"User's surname" }, "emailAddress":"User's primary email address", "allEmailAddresses":[ { "emailAddress":"User's email address" }, { "emailAddress":"User's email address" } ], "allPhoneNumbers":[ { "phoneNumber":"User's phone number" }, { "phoneNumber":"User's phone number" } ], "dateOfBirth":"User's date of birth", "age":"User's age", "gender":"User's gender", "photo":"User's photo, Base64 encoded JPEG bytes", "nfcIdPhoto":"User's photo from ID document, Base64 encoded JPEG bytes", "addresses":[ { "country":"Country", "city":"City", "postCode":"Postal code", "address1":"Street, number or equivalent", "address2":"Street, number or equivalent", "address3":"Street, number or equivalent", "validFrom":"Date from which the address is valid", "type":"Type of user's address", "sourceType":"Source from which the address is obtained" } ], "customIdentifier":"Custom identifier set by the Relying Party", "ssn":{ "ssn":"Social security number of the end user", "country":"Country of SSN" }, "document" : { "type":"Type of document used for registration e.g. passport", "country":"Document issuing country", "serialNumber":"Document serial number", "expirationDate":"Document expiration date" }, "documentPhoto":"Document photo, Base64 encoded JPEG bytes", "registrationLevel":"User's registration level in Freja eID", "uniquePersonalIdentifier":"User's unique personal identifier in Freja eID", "loaLevel":"User's level of assurance (LOA) in Freja eID", "relyingPartyUserId":"Unique user ID reserved for Relying Parties", "integratorSpecificUserId":"Unique user ID reserved for Integrators", "customIdentifier":"Unique identifier set by the Relying Party" }

  • basicUserInfo: JSON object which contains user's name and surname

  • emailAddress: String, representing the user's primary email address.

  • allEmailAddresses: List of JSON objects which contains all end user's registered email addresses. The list will contain the primary email address and up to 2 other email addresses user might have connected to their account. Email addresses will be randomly sorted. If the user does not have any additional email addresses registered, the list will contain only the primary email address.

  • allPhoneNumbers:  List of JSON objects which contains all end user's registered phone numbers. This list will contain up to 3 phone numbers the user might have connected to their account. If no phone number is registered for a given user, an empty list will be returned.

  • dateOfBirth: String containing date of birth in format: YYYY-MM-DD.

  • age: Integer, calculated based on the date of birth.

  • gender: MALE, FEMALE, UNSPECIFIED

  • photo: String, Base64 encoded JPEG bytes.

  • nfcIdPhoto: String, Base64 encoded JPEG bytes.

  • addresses: List of JSON objects which contains one or more end user's addresses. If no address is registered for a given user, an empty list will be returned. Each object will contain the following information:

    • country: String. Contains the ISO-3166 two-alphanumeric country code of the country where the user's address resides.

    • city: String. City in which the user's address resides.

    • postCode: String. Postal code of the city or city area in which the user's address resides. 

    • address 1, 2, 3: String. Up to three lines of address information containing, for example, street and number, house name or apartment number, and ‘care of’ or ‘attention’ designations, area or village clarifications. The number of lines in the response depends on the address information. At least one will be returned. 

    • validFrom: String. Date from which the address is valid, according to the source of information. Date is returned in format: YYYY-MM-DD (ISO-8601)

    • type: String. Type of address. Currently, can be RESIDENTIAL or POSTAL. 

    • sourceType: String. Type of source from which the information about the address has been obtained. Currently, only GOVERNMENT_REGISTRY can be returned. Namely, in the current version of Freja eID, the information about the end user's address is obtained from Statens personadressregister (SPAR).

  • ssn: JSON object which contains social security number and country.

    • ssn: string, mandatory. Expected SSN of the end user based on the document added to Freja eID.

      • If country equal to "SE", the value must be the 12-digit format of the Swedish "personnummer" without spaces or hyphens. E.g. 195210131234.

      • If country equal to ''NO'', the value must be the 11-digit format of the Norwegian "personnummer" without spaces or hyphens. E.g. 13105212345.

      • If country equal to ''FI'', the value must be the 10-characters format of the Finish ''koodi'', with the hyphen before the last four control characters. The hyphen can be replaced with the letter A. E.g. 131052-308T or 131052A308T.

      • If country equal to ''DK'', the value must be the 10-digit format of the Danish "personnummer" without spaces or hyphens. E.g. 1310521234.

    • country: string, mandatory. Contains the ISO-3166 two-alphanumeric country code of the country where the ID is issued.

  • document: List of JSON objects with information about the user's document used in registration. Each object will contain the following information:

    • type: String. The type of document used during registration abbreviated and returned as: "PASS" (passport), "DRILIC" (driving licence), "NATID" (national ID card), "IDSIS" (SIS-issued ID document), "TAXID" (document issued by the Swedish Tax Authority), and "OTHERID" (any other type of document).

    • country: String. Contains the ISO-3166 two-alphanumeric country code of the issuing country.

    • serialNumber: String representing the document's serial number.

    • expirationDate: String containing the document's expiration date in the format: YYYY-MM-DD.

  • documentPhoto: String, Base64 encoded JPEG bytes.

  • registrationLevel: the user's registration level in Freja eID, can be BASIC, EXTENDED or PLUS

  • uniquePersonalIdentifier: String, format dddd-dddddd-dddd. Last digit is check digit calculated using Luhn's algorithm. Unique user's identifier in Freja eID.

  • loaLevel: String. User's level of assurance (LOA) in Freja eID, values can be: "LOA1", "LOA2", "LOA3", "LOA3_NR".

  • relyingPartyUserId: String, mandatory. Represents a unique, user-specific value that allows the Relying Party to identify the same user across multiple sessions.

  • integratorSpecificUserId: String, represents a unique, user-specific value that allows Integrators to identify the same user across multiple sessions regardless of the Integrated Relying Party service that the user is using. For more info, see the section about Integrator Relying Party Management. 

  • customIdentifier: String, a unique, Relying Party-specific, user identifier, set by the Relying Party itself through the Custom Identifier Management.

details

JWS in compact serialised form as following:

BASE64URL(UTF8(JWS Protected Header)) || ’.’ || BASE64URL(JWS Payload) || ’.’ || BASE64URL(JWS Signature)

JWS Protected Header

{ "x5t":"SHA-1 digest of the signing certificate", "alg":"algorithm used to secure the JWS" }

  • x5t: mandatory, Base64URL encoding of the certificate's SHA-1 digest.

  • alg: mandatory, the value shall be RS256 which corresponds to 'RSA PKCS#1 signature with SHA-256'.

JWS Payload

{ "authRef":"Authentication reference", "status":"Authentication status", "userInfoType":"User info type", "userInfo":"User information corresponding to user info type", "minRegistrationLevel":"Minimum required registration level of a user", "requestedAttributes":{ JSON object, see below. }, "timestamp":"Time when authentication is confirmed by end user" }

  • authRef: See authRef as described in the Get One Authentication Result Method above).

  • status: See status as described in the Get One Authentication Result Method above).

  • userInfoType: INFERRED

  • userInfo: N/A

  • minRegistrationLevel: See minRegistrationLevel as described in Initiate Authentication Method.

  • requestedAttributes: JSON object, optional. See requestedAttributes as described in the Get One Authentication Result Method above).

  • timestamp: long, mandatory. Describes the time when the confirmation by the end user was validated on Freja eID server side. Expressed in milliseconds, since January 1, 1970, 00:00 UTC.

JSON Response Body with Mock Data for an APPROVED Response

{ "authRef":"12345-67890-abcdef", "status":"APPROVED", "details":"JWS content as per below", "requestedAttributes":{ "basicUserInfo":{ "name":"Joe", "surname":"Black" }, "emailAddress":"joe.black@frejaeid.com", "allEmailAddresses":[ { "emailAddress":"joe.black@frejaeid.com" }, { "emailAddress":"joebl@domain.com" } ], "allPhoneNumbers":[ { "phoneNumber":"+4600000000" }, { "phoneNumber":"+4611111111" } ], "dateOfBirth":"1985-11-17", "age":"36", "gender":"MALE", "photo":"SlBFRyBpbWFnZSBieXRlcyBnb2VzIGhlcmUgLi4u", "nfcIdPhoto":"aGVsbG93b3JsZF8yMDI1Q1RQX2V4YW1wbGU=", "addresses":[ { "country":"SE", "city":"Stockholm", "postCode":"11120", "address1":"C/O Joe Black", "address2":"Visdomsgatan 55", "validFrom":"2020-03-19", "type":"RESIDENTIAL", "sourceType":"GOVERNMENT_REGISTRY" }, { "country":"NO", "city":"Oslo", "postCode":"0001", "address1":"P.O. Box 456", "validFrom":"2020-03-19", "type":"POSTAL", "sourceType":"GOVERNMENT_REGISTRY" } ], "ssn":{ "ssn":"198511170040", "country":"SE" }, "document" : { "type":"PASS", "country":"SE", "serialNumber":"XA0000001", "expirationDate":"2027-01-01" }, "documentPhoto":"SlBFRyBpbWFnZSBieXRlcyBnb2VzIGhlcmUgLi4u" "registrationLevel":"PLUS", "uniquePersonalIdentifier": "5753-979204-7861", "loaLevel": "LOA3", "relyingPartyUserId":"94039a98c8d", "integratorSpecificUserId":"54059a95c8d", "customIdentifier":"vejobla" }

JWS Payload with Mock Data for an APPROVED Response

Certificate Info: for more information refer to REST API Documentation | [inlineExtension]Certificates in Freja eID

Header: BASE64URL(UTF8(JWS Protected Header)) || ’.’ || BASE64URL(JWS Payload) || ’.’ || BASE64URL(JWS Signature)

{ "authRef":"12345-67890-abcdef", "status":"APPROVED", "userInfoType":"EMAIL", "userInfo":"joe.black@freja.com", "requestedAttributes":{ "basicUserInfo":{ "name":"Joe", "surname":"Black" }, "emailAddress":"joe.black@freja.com", ... }, "timestamp":1584701027510 }

Final JWS

eyAiYXV0aFJlZiI6IjEyMzQ1LTY3ODkwLWFiY2RlZiIsICJzdGF0dXMiOiJBUFBST1ZFRCIsICJ1c2VySW5mb1R5cGUiOiJFTUFJTCIsICJ1c2VySW5mbyI6ImpvZS5ibGFja0B2ZXJpc2VjLmNvbSIsICJyZXF1ZXN0ZWRBdHRyaWJ1dGVzIjp7ICJiYXNpY1VzZXJJbmZvIjp7ICJuYW1lIjoiSm9lIiwgInN1cm5hbWUiOiJCbGFjayIgfSwgImVtYWlsQWRkcmVzcyI6ImpvZS5ibGFja0B2ZXJpc2VjLmNvbSIsICJhbGxFbWFpbEFkZHJlc3NlcyI6WyB7ICJlbWFpbEFkZHJlc3MiOiJqb2UuYmxhY2tAdmVyaXNlYy5jb20iIH0sIHsgImVtYWlsQWRkcmVzcyI6ImpvZWJsQGRvbWFpbi5jb20iIH0gXSwgImFsbFBob25lTnVtYmVycyI6WyB7ICJwaG9uZU51bWJlciI6Iis0NjAwMDAwMDAwIiB9LCB7ICJwaG9uZU51bWJlciI6Iis0NjExMTExMTExIiB9IF0sICJkYXRlT2ZCaXJ0aCI6IjE5ODUtMTEtMTciLCAiYWdlIjozNiwgImFkZHJlc3NlcyI6WyB7ICJjb3VudHJ5IjoiU0UiLCAiY2l0eSI6IlN0b2NraG9sbSIsICJwb3N0Q29kZSI6IjExMTIwIiwgImFkZHJlc3MxIjoiQy9PIEpvZSBCbGFjayIsICJhZGRyZXNzMiI6IlZpc2RvbXNnYXRhbiA1NSIsICJ2YWxpZEZyb20iOiIyMDIwLTAzLTE5IiwgInR5cGUiOiJSRVNJREVOVElBTCIsICJzb3VyY2VUeXBlIjoiR09WRVJOTUVOVF9SRUdJU1RSWSIgfSwgeyAiY291bnRyeSI6Ik5PIiwgImNpdHkiOiJPc2xvIiwgInBvc3RDb2RlIjoiMDAwMSIsICJhZGRyZXNzMSI6IlAuTy4gQm94IDQ1NiIsICJ2YWxpZEZyb20iOiIyMDIwLTAzLTE5IiwgInR5cGUiOiJQT1NUQUwiLCAic291cmNlVHlwZSI6IkdPVkVSTk1FTlRfUkVHSVNUUlkiIH0gXSwgInNzbiI6eyAic3NuIjoiMTk4NTExMTcwMDQwIiwgImNvdW50cnkiOiJTRSIgfSwgInJlZ2lzdHJhdGlvbkxldmVsIjoiUExVUyIsICJyZWx5aW5nUGFydHlVc2VySWQiOiI5NDAzOWE5OGM4ZCIsICJpbnRlZ3JhdG9yU3BlY2lmaWNVc2VySWQiOiI1NDA1OWE5NWM4ZCIsICJjdXN0b21JZGVudGlmaWVyIjoidmVqb2JsYSIsCiJwaG90byI6ImlWQk9SdzBLR2dvQUFBQU5TVWhFVWdBQUFod0FBQU5nQ0FJQUFBRG9DeVlsQUFBQUFYTlNSMElBcnM0YzZRQUFBQVJuUVUxQkFBQ3hqd3Y4WVFVQUFBQUpjRWhaY3dBQURzTUFBQTdEQWNkdnFHUUFBQ0FoU1VSQlZIaGU3ZDJ4ZFNKTDNzYmhtODNtUUE1S0ExY2hmSTQ4T2NpUkorY0dnS2trQ0VFSmJCYjd3V2htRUZVTmRIVy8wRUEvNXp6T25ZV0dRbWYvUDdvYWlYLys5My8vQVlBSVVRRWdSbFFBaUJFVkFHSkVCWUFZVVFFZ1JsUUFpQkVWQUdKRUJZQVlVUUVnUmxRQWlCRVZBR0pFQllBWVVRRWdSbFFBaUJFVkFHSkVCWUFZVVFFZ1JsUUFpQkVWQUdKRUJZQVlVUUVnUmxRQWlCRVZBR0pFQllBWVVRRWdSLi4uIiwKwqAgwqAgwqAgImNvdmlkQ2VydGlmaWNhdGVzIjp7CiJ2YWNjaW5lcyI6IHsKImNlcnRpZmljYXRlIjogIkhDMTpOQ0ZPWE4lVFNNQUhOLUhWTjhKN1VRTUo0LzNSWkxNNTJYR1AxV0cyRDU4KklYRjU5NVRYUjM4V0FCUk1CNTdGLzhYKkczTTlKVVBZMEJaVzQ6LkE2M0hOTlZSKkcwQzdQSEJPMzNSVzA1TEJQT0YgUVRZRjM0SEdPSUggOEwrNkgxU0YrNUYvM0UxSkFGLjc1IEpEWEkwM0w5Wkk0UTUlSDBBTjhDSjBQWkJJVEhQK1BSUk1KVlVNIEkvUFNNJUdBOElNJU8lS0kqVzAgLlVRKk4gUlAtK1IyWUJWNDRDJEJYR0RPOTg6MExQSE42RDdMTEsqMkg5LTg5VVYtMEwvOklTLU86UzlVWjQrRkpFIDRZM0xML0lJIDBPQzlTWDArKkI4NVQlNjIqNVBaRDVDQzlUMEglOks1UU5YL0dKWklJN0pTVE5COTUrMTZMRVRGNE4uU1MuUEtJWFIuVUlBWVVIMldWUUkwVEhYWlEuSjkxIEZJJUIyTEc3UEclIEIvVUkyWVU1TUFYU0crVzM0UElRSkFaR0EyOlVHJVUyRTRBU05NSDhNLTQwNUExT0stVUtWQ0ZCM0xCLjZESlBIQlMxNUMvS05LTTQkSUlYKkIxSlM5QUM5OU5FN1BIVFJPKzJJKjVDNkVBMlUkIDhDMlNUIElFJU4xKzI0VjdMRDFMWkJBTUFTMzA2V0RPMSIKfSwKInRlc3RzIjogeyJjZXJ0aWZpY2F0ZSI6IkhDMTpOQ0ZPWE4lVFNNQUhOLUgzTzQ6UFZIIEFKMkokOUowSUk2WUogNDNTTEcvRUJORzJONEZCT00kVjQ6TlFBIE06VUMqR1BYUzRNWktIWkEgS0U3RUMxIDNLOUxUNEQ0JUsqKklSMUwlOktFVjQ5OVRFVzYzWkNEN0xVWjIzNEpUUFZGSEhCWTRPLU8wRzEzSEgwLUslSUg3WTQvWDg2TU9CJVJIRE0uLUI2L0QwSkFRVFU4RDIlSDBBTjhTSjA2WUJVU01BTDg6SjVTSDYtRzkqRTkuJDA1RzkwRjNIWkk1VkElM0tRWUpYMUo6TksyQURWVEFBWkk2NkogT0tRTUkwT0lTVkJGT0pWVEExSEEtWElSQ0kgT0slSUo1UUJQN0pVN0JKWUoqSUo1T0ktWUlFNDZPOTNYTVI6IEtTJE45SFM1LVFKK1BBK1FJJUs0JE43Qk1JK1FWJU40K084JU1NRzI5QUY2TEZCODFRTUtRK01OL1ExOVFFOFEgUE9ET0YkNlJOUVEzWTc0WEwxL0xKTzlVVU0gUVVRL01OOjQzNTYqQlckJUwrLUpOLk4gTFRCV081OlFOK0EzMVVLWFBST1NOUFMrRFdHREk4RUglMkxVSTJPL0VHWUlZUzJHU1MlOFMvNDBBUUNJMiJ9LAoicmVjb3ZlcnkiOiB7ICJjZXJ0aWZpY2F0ZSI6IkhDMTpOQ0ZPWE4lVFNNQUhOLUhGTjRUVEM0IFNKV0taKjlHQkguIE1VOTY1SFJMWDgzTFE1NVVUU0pWUU9JVlVLMUpaWlBRQTNEUDRPVzYzMUFYNVFNOUlGWTFPU01OVjFMOFZORjZBWU1FMEY6TkUzS1VEOjEzWk01OjZFTDZFJTYwVDkzMlEuUlRSSDkvVVBORjY3SjZRVzZPVlFPUjYrRzkwLkctUjU0VzEuVUkyUEhVSUUgJDRaSkoqJUNOMVRUQjVDLU9URjFKKjNURkgyVjQyRjFDT1QkSEZDKklVWjQrRkpFIDRZM0xML0lJIDBISlA3TlZERUIxMkpEKjJEMEhINzgkWkoqREpXUDQyVzU6WVBISlVUUk04T0k5WU8gTEUzVVE1TUExVEg4TDJDUElHU1VIUE1VK1ZBV08yTzhVK1ZIKkZZWlEgSDk5MlcgJUpNU0dVVlBRUkhJWTErIEgxTzE2UDMqN1VGLkpKOEM3WEIvT0lGRDY1KlYwV0kqOVVVM0VKWVJKWDVINFU2OlYrWVRHUUZPUEU2WFZWJUxUVUtJN1VQRkRDUVUkSlZGOENROjVFOFVPSFIlK1YvRkM5KjggV004JEpWMjBNJE84MyIKICAgICAgICAgfSwKImFsbG93ZWQiOiB0cnVlCn0KwqAgwqB9LCAidGltZXN0YW1wIjoxNTg0NzAxMDI3NTEwIH0

Get Authentication Results Method

The method allows a relying party to fetch the results of multiple outstanding authentications. It is our recommendation that you generally use the aggregate method, as it is more efficient and reduces network traffic. This is the default behaviour of the client library supplied by Freja eID. 

The method is called using HTTP POST through the URLs below:

Environment

Endpoint

TEST

https://services.test.frejaeid.com/authentication/1.0/getResults

PRODUCTION

https://services.prod.frejaeid.com/authentication/1.0/getResults

JSON Example for getAuthResultsRequest

The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:

{ "includePrevious":"Include previously returned results" }

  • includePrevious: string, mandatory. Must be equal to ALL. Indicates that the complete list of authentications successfully initiated by the relying party within the last 10 minutes will be returned, including results for previously completed authentication results that have been reported through an earlier call to one of the methods for getting authentication results.

Example Request

If you wish to fetch multiple authentication results, follow these steps:

  1. Create the JSON structure {"includePrevious":"ALL"}

  2. Encode the JSON structure to Base64.

  3. Create the HTTP POST request with a POST parameter name getAuthResultsRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following:

getAuthResultsRequest=eyJpbmNsdWRlUHJldmlvdXMiOiJBTEwifQ==

Possible Errors

Code Returned

Explanation

1004

You are not allowed to call this method.

1008

Unknown Relying Party.

1200

Invalid or missing includePrevious parameter.

JSON Response Value

If HTTP 200 is returned from the method, the following return value will be present in the body of the response:

{ "authenticationResults":[ { "authRef":"Authentication reference", "status":"Authentication status", "details":"JWS signed data, see below", "requestedAttributes":{ "basicUserInfo":{ "name":"Joe", "surname":"Black" }, "emailAddress":"joe.black@freja.com", "allEmailAddresses":[ { "emailAddress":"joe.black@freja.com" }, { "emailAddress":"joebl@domain.com" } ], "allPhoneNumbers":[ { "phoneNumber":"+4600000000" }, { "phoneNumber":"+4611111111" } ], "dateOfBirth":"1987-10-18", "age":"34", "gender":"MALE", "photo":"SlBFRyBpbWFnZSBieXRlcyBnb2VzIGhlcmUgLi4u", "nfcIdPhoto":"aGVsbG93b3JsZF8yMDI1Q1RQX2V4YW1wbGU=", "addresses":[ { "country":"SE", "city":"Stockholm", "postCode":"11120", "address1":"c/o Joe Black", "address2":"Visdomsgatan 55", "validFrom":"2020-03-19", "type":"RESIDENTIAL", "sourceType":"GOVERNMENT_REGISTRY" }, { "country":"NO", "city":"Oslo", "postCode":"0001", "address1":"P.O. Box 456", "validFrom":"2020-03-19", "type":"POSTAL", "sourceType":"GOVERNMENT_REGISTRY" } ], "ssn":{ "ssn":"198710180040", "country":"SE" }, "document" : { "type":"PASS", "country":"SE", "serialNumber":"XA0000001", "expirationDate":"2027-01-01" }, "documentPhoto":"SlBFRyBpbWFnZSBieXRlcyBnb2VzIGhlcmUgLi4u", "registrationLevel":"PLUS", "uniquePersonalIdentifier": "5753-979204-7861", "loaLevel": "LOA3", "relyingPartyUserId":"94039a98c8d", "integratorSpecificUserId":"54059a95c8d", "customIdentifier":"vejobla" }, { "authRef":"..." } ] }

  • authenticationResults: an array of JSON objects, mandatory. An array of authentication result objects (if the authRef parameter was passed, the array will always be of length 1).

  • authRef: string, mandatory. The authentication reference of the authentication.

  • status: string, mandatory (see details as described in the Get One Authentication Result Method above).

  • details: JWS signed object (see details as described in the Get One Authentication Result Method above), optional.

  • requestedAttributes: JSON object (see details as described in the Get One Authentication Result Method above), optional.

Cancel Authentication Method

This method is used by a relying party to cancel an authentication request. The method is called using HTTP POST through the URLs below:

Environment

Endpoint

TEST

https://services.test.frejaeid.com/authentication/1.0/cancel