Authentication Service
- Aleksandar Laban
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 eID mobile application on one or more devices they possess.
We differentiate between 3 types of users based on assurance of the user's identity.
- Basic - for users who have only registered with an email address
- Extended - for users whose identity was verified with an ID document (list of supported countries can be seen in the app)
- Plus - for users whose identity was further verified with a physical meeting in addition to an ID document (only available in Sweden)
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.
Important information!
This guide is written from the point of view of QR code authentication where the userInfoType is set to INFERRED. This is the method of authentication we recommend as the safest and easiest to implement.
More About QR Code Implementation
Qr code authentication is supported by the Freja eID Authentication service. In essence, a user authenticates 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 needn't 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 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.
Before You Begin
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
The Freja eID Relying Party Authentication Service allows you to:
- Initiate an authentication request;
- Get one authentication result;
- Get multiple authentication results;
- 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:
- Authentication requests are short-lived i.e. from the point of initiation the user has 2 minutes to confirm it via Freja eID;
- 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 |
The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:
Parameter name | Value | |
initAuthRequest | { "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" } 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 or PLUS. If not present, default level will be BASIC. 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. 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:
|
Example request with the userInfoType set to INFERRED |
The HTTP body should be the following: initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJJTkZFUlJFRCIsInVzZXJJbmZvIjoiTi9BIn0= |
Possible errors returned by the method are the following:
Code Returned | Explanation |
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. |
If HTTP 200 is returned from the method, the following return value will be present in the body of the response:
JSON response value in body |
{ "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 (see Get authentication results method below). |
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 |
The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:
Parameter name | Value |
getOneAuthResultRequest | { "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:
The HTTP body should be the following (compact format, line broken for clarity only): getOneAuthResultRequest=eyJhdXRoUmVmIjoiR09IUHlKY29LTEorektDRXk0YWJpNmpPTytxNV ZLK1MxK1VPNU9YUm1PUHU0Mml4dlZuc1ZnczdBRFlVZkc4bSJ9 |
Possible errors returned by the method are the following:
Code returned | Explanation |
1004 | You are not allowed to call this method. |
1008 | Unknown Relying Party. |
1100 | Invalid reference (for example, nonexistent or expired). |
If HTTP 200 is returned from the method, the following return value will be present in the body of the response:
JSON response value in body | ||
Response Body | { "authRef":"Authentication reference", "status":"Authentication status", "requestedAttributes":{ "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", "photo":"User's photo, 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 RP", "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", "relyingPartyUserId":"Unique user ID reserved for Relying Parties", "integratorSpecificUserId":"Unique user ID reserved for Integrators", "details":"JWS signed data, see below" } authRef: string, mandatory. The authentication reference of the authentication. status: string, mandatory. One of:
requestedAttributes: JSON object (see below), optional. Provides additional attributes about a user if required in attributestToReturn parameter in related initAuthRequest and the status was equal to APPROVED. details: JWS signed object (see below), optional. Provides details and evidence of the authentication if status was equal to APPROVED. | |
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 above. status: See status above. userInfoType: INFERRED userInfo: N/A minRegistrationLevel: See minRegistrationLevel as described in Initiate authentication method. requestedAttributes: JSON object, optional. See requestedAttributes below. 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. | |
requestedAttributes | { "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", "photo":"User's photo, 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", "relyingPartyUserId":"Unique user ID reserved for Relying Parties", "integratorSpecificUserId":"Unique user ID reserved for Integrators" } 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. photo: 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. ssn: JSON object which contains social security number and country. document: List of JSON objects with information about the user's document used in registration. Each object will contain the following information:
documentPhoto: String, Base64 encoded JPEG bytes. registrationLevel: the user's registration level in Freja eID, can be BASIC, EXTENDED or PLUS 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. | |
ssn | ssn: string, mandatory. Expected SSN of the end user based on the document added to Freja eID.
country: string, mandatory. Contains the ISO-3166 two-alphanumeric country code of the country where the SSN is issued. In the current version of Freja eID, one of: ''SE'' (Sweden), ''NO'' (Norway), ''FI'' (Finland), ''DK'' (Denmark). |
Example data for APPROVED response, JSON response body:
{ "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", "photo":"SlBFRyBpbWFnZSBieXRlcyBnb2VzIGhlcmUgLi4u", "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", "relyingPartyUserId":"94039a98c8d", "integratorSpecificUserId":"54059a95c8d", "customIdentifier":"vejobla" }
Example data for APPROVED response, JWS payload:
Field | Value |
Certificate Info | See above. |
Header | See above. |
Payload | { "authRef":"12345-67890-abcdef", "status":"APPROVED", "userInfoType":"EMAIL", "userInfo":"joe.black@verisec.com", "requestedAttributes":{ "basicUserInfo":{ "name":"Joe", "surname":"Black" }, "emailAddress":"joe.black@verisec.com", ... }, "timestamp":1584701027510 } |
Final JWS (compact format, line broken for clarity only) | eyAiYXV0aFJlZiI6IjEyMzQ1LTY3ODkwLWFiY2RlZiIsICJzdGF0dXMiOiJBUFBST1ZFRCIsICJ1c2VySW5mb1R5cGUiOiJFTU FJTCIsICJ1c2VySW5mbyI6ImpvZS5ibGFja0B2ZXJpc2VjLmNvbSIsICJyZXF1ZXN0ZWRBdHRyaWJ1dGVzIjp7ICJiYXNpY1 VzZXJJbmZvIjp7ICJuYW1lIjoiSm9lIiwgInN1cm5hbWUiOiJCbGFjayIgfSwgImVtYWlsQWRkcmVzcyI6ImpvZS5ibGFja0B2Z XJpc2VjLmNvbSIsICJhbGxFbWFpbEFkZHJlc3NlcyI6WyB7ICJlbWFpbEFkZHJlc3MiOiJqb2UuYmxhY2tAdmVyaXNlYy5jb 20iIH0sIHsgImVtYWlsQWRkcmVzcyI6ImpvZWJsQGRvbWFpbi5jb20iIH0gXSwgImFsbFBob25lTnVtYmVycyI6WyB7ICJw aG9uZU51bWJlciI6Iis0NjAwMDAwMDAwIiB9LCB7ICJwaG9uZU51bWJlciI6Iis0NjExMTExMTExIiB9IF0sICJkYXRlT2ZCaX J0aCI6IjE5ODUtMTEtMTciLCAiYWdlIjozNiwgImFkZHJlc3NlcyI6WyB7ICJjb3VudHJ5IjoiU0UiLCAiY2l0eSI6IlN0b2NraG9 sbSIsICJwb3N0Q29kZSI6IjExMTIwIiwgImFkZHJlc3MxIjoiQy9PIEpvZSBCbGFjayIsICJhZGRyZXNzMiI6IlZpc2RvbXNnYX RhbiA1NSIsICJ2YWxpZEZyb20iOiIyMDIwLTAzLTE5IiwgInR5cGUiOiJSRVNJREVOVElBTCIsICJzb3VyY2VUeXBlIjoiR09W RVJOTUVOVF9SRUdJU1RSWSIgfSwgeyAiY291bnRyeSI6Ik5PIiwgImNpdHkiOiJPc2xvIiwgInBvc3RDb2RlIjoiMDAwMSIsI CJhZGRyZXNzMSI6IlAuTy4gQm94IDQ1NiIsICJ2YWxpZEZyb20iOiIyMDIwLTAzLTE5IiwgInR5cGUiOiJQT1NUQUwiLCAi c291cmNlVHlwZSI6IkdPVkVSTk1FTlRfUkVHSVNUUlkiIH0gXSwgInNzbiI6eyAic3NuIjoiMTk4NTExMTcwMDQwIiwgImN vdW50cnkiOiJTRSIgfSwgInJlZ2lzdHJhdGlvbkxldmVsIjoiUExVUyIsICJyZWx5aW5nUGFydHlVc2VySWQiOiI5NDAzOWE 5OGM4ZCIsICJpbnRlZ3JhdG9yU3BlY2lmaWNVc2VySWQiOiI1NDA1OWE5NWM4ZCIsICJjdXN0b21JZGVudGlmaWVyI joidmVqb2JsYSIsCiJwaG90byI6ImlWQk9SdzBLR2dvQUFBQU5TVWhFVWdBQUFod0FBQU5nQ0FJQUFBRG9DeVlsQ UFBQUFYTlNSMElBcnM0YzZRQUFBQVJuUVUxQkFBQ3hqd3Y4WVFVQUFBQUpjRWhaY3dBQURzTUFBQTdEQWNkd nFHUUFBQ0FoU1VSQlZIaGU3ZDJ4ZFNKTDNzYmhtODNtUUE1S0ExY2hmSTQ4T2NpUkorY0dnS2trQ0VFSmJCYjd3 V2htRUZVTmRIVy8wRUEvNXp6T25ZV0dRbWYvUDdvYWlYLys5My8vQVlBSVVRRWdSbFFBaUJFVkFHSkVCWUFZV VFFZ1JsUUFpQkVWQUdKRUJZQVlVUUVnUmxRQWlCRVZBR0pFQllBWVVRRWdSbFFBaUJFVkFHSkVCWUFZVVFFZ 1JsUUFpQkVWQUdKRUJZQVlVUUVnUmxRQWlCRVZBR0pFQllBWVVRRWdSLi4uIiwKwqAgwqAgwqAgImNvdmlkQ2V ydGlmaWNhdGVzIjp7CiJ2YWNjaW5lcyI6IHsKImNlcnRpZmljYXRlIjogIkhDMTpOQ0ZPWE4lVFNNQUhOLUhWTjhKN1V RTUo0LzNSWkxNNTJYR1AxV0cyRDU4KklYRjU5NVRYUjM4V0FCUk1CNTdGLzhYKkczTTlKVVBZMEJaVzQ6LkE2M0 hOTlZSKkcwQzdQSEJPMzNSVzA1TEJQT0YgUVRZRjM0SEdPSUggOEwrNkgxU0YrNUYvM0UxSkFGLjc1IEpEWEkwM 0w5Wkk0UTUlSDBBTjhDSjBQWkJJVEhQK1BSUk1KVlVNIEkvUFNNJUdBOElNJU8lS0kqVzAgLlVRKk4gUlAtK1IyWUJ WNDRDJEJYR0RPOTg6MExQSE42RDdMTEsqMkg5LTg5VVYtMEwvOklTLU86UzlVWjQrRkpFIDRZM0xML0lJIDBPQz lTWDArKkI4NVQlNjIqNVBaRDVDQzlUMEglOks1UU5YL0dKWklJN0pTVE5COTUrMTZMRVRGNE4uU1MuUEtJWFIuVUl BWVVIMldWUUkwVEhYWlEuSjkxIEZJJUIyTEc3UEclIEIvVUkyWVU1TUFYU0crVzM0UElRSkFaR0EyOlVHJVUyRTRBU05 NSDhNLTQwNUExT0stVUtWQ0ZCM0xCLjZESlBIQlMxNUMvS05LTTQkSUlYKkIxSlM5QUM5OU5FN1BIVFJPKzJJKjVDN kVBMlUkIDhDMlNUIElFJU4xKzI0VjdMRDFMWkJBTUFTMzA2V0RPMSIKfSwKInRlc3RzIjogeyJjZXJ0aWZpY2F0ZSI6Ikh DMTpOQ0ZPWE4lVFNNQUhOLUgzTzQ6UFZIIEFKMkokOUowSUk2WUogNDNTTEcvRUJORzJONEZCT00kVjQ6TlFBI E06VUMqR1BYUzRNWktIWkEgS0U3RUMxIDNLOUxUNEQ0JUsqKklSMUwlOktFVjQ5OVRFVzYzWkNEN0xVWjIzNEpUU FZGSEhCWTRPLU8wRzEzSEgwLUslSUg3WTQvWDg2TU9CJVJIRE0uLUI2L0QwSkFRVFU4RDIlSDBBTjhTSjA2WUJVU0 1BTDg6SjVTSDYtRzkqRTkuJDA1RzkwRjNIWkk1VkElM0tRWUpYMUo6TksyQURWVEFBWkk2NkogT0tRTUkwT0lTVkJGT 0pWVEExSEEtWElSQ0kgT0slSUo1UUJQN0pVN0JKWUoqSUo1T0ktWUlFNDZPOTNYTVI6IEtTJE45SFM1LVFKK1BBK1FJ JUs0JE43Qk1JK1FWJU40K084JU1NRzI5QUY2TEZCODFRTUtRK01OL1ExOVFFOFEgUE9ET0YkNlJOUVEzWTc0WEwxL 0xKTzlVVU0gUVVRL01OOjQzNTYqQlckJUwrLUpOLk4gTFRCV081OlFOK0EzMVVLWFBST1NOUFMrRFdHREk4RUglMkx VSTJPL0VHWUlZUzJHU1MlOFMvNDBBUUNJMiJ9LAoicmVjb3ZlcnkiOiB7ICJjZXJ0aWZpY2F0ZSI6IkhDMTpOQ0ZPWE4 lVFNNQUhOLUhGTjRUVEM0IFNKV0taKjlHQkguIE1VOTY1SFJMWDgzTFE1NVVUU0pWUU9JVlVLMUpaWlBRQTNEUDRP VzYzMUFYNVFNOUlGWTFPU01OVjFMOFZORjZBWU1FMEY6TkUzS1VEOjEzWk01OjZFTDZFJTYwVDkzMlEuUlRSSDkvV VBORjY3SjZRVzZPVlFPUjYrRzkwLkctUjU0VzEuVUkyUEhVSUUgJDRaSkoqJUNOMVRUQjVDLU9URjFKKjNURkgyVjQyRj FDT1QkSEZDKklVWjQrRkpFIDRZM0xML0lJIDBISlA3TlZERUIxMkpEKjJEMEhINzgkWkoqREpXUDQyVzU6WVBISlVUUk0 4T0k5WU8gTEUzVVE1TUExVEg4TDJDUElHU1VIUE1VK1ZBV08yTzhVK1ZIKkZZWlEgSDk5MlcgJUpNU0dVVlBRUkhJW TErIEgxTzE2UDMqN1VGLkpKOEM3WEIvT0lGRDY1KlYwV0kqOVVVM0VKWVJKWDVINFU2OlYrWVRHUUZPUEU2WFZW JUxUVUtJN1VQRkRDUVUkSlZGOENROjVFOFVPSFIlK1YvRkM5KjggV004JEpWMjBNJE84MyIKICAgICAgICAgfSwKImFs bG93ZWQiOiB0cnVlCn0KwqAgwqB9LCAidGltZXN0YW1wIjoxNTg0NzAxMDI3NTEwIH0 |
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 |
The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:
Parameter name | Value |
getAuthResultsRequest | { "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:
The HTTP body should be the following: getAuthResultsRequest=eyJpbmNsdWRlUHJldmlvdXMiOiJBTEwifQ== |
Possible errors returned by the method are the following:
Code returned | Explanation |
1004 | You are not allowed to call this method. |
1008 | Unknown Relying Party. |
1200 | Invalid or missing includePrevious parameter. |
If HTTP 200 is returned from the method, the following return value will be present in the body of the response:
JSON response value in body | |
Response body | { "authenticationResults":[ { "authRef":"Authentication reference", "status":"Authentication status", "relyingPartyUserId":"Unique user ID reserved for Relying Parties", "details":"JWS signed data, see below", "requestedAttributes":{ "basicUserInfo":{ "name":"Joe", "surname":"Black" }, "emailAddress":"joe.black@verisec.com", "allEmailAddresses":[ { "emailAddress":"joe.black@verisec.com" }, { "emailAddress":"joebl@domain.com" } ], "allPhoneNumbers":[ { "phoneNumber":"+4600000000" }, { "phoneNumber":"+4611111111" } ], "dateOfBirth":"1987-10-18", "age":"34", "photo":"SlBFRyBpbWFnZSBieXRlcyBnb2VzIGhlcmUgLi4u", "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", "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. One of:
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 |
Production | https://services.prod.frejaeid.com/authentication/1.0/cancel |
The parameter of the method is a Base64 UTF8-encoded JSON payload according to the following:
Parameter name | Value |
cancelAuthRequest | { "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. |
Example request |
If you wish to cancel an authentication request, follow these steps:
The HTTP body should be the following (line broken for clarity only): cancelAuthRequest=eyJhdXRoUmVmIjoiR09IUHlKY29LTEorektDRXk0YWJpNmpPTytxNVZLK1MxK1VP NU9YUm1PUHU0Mml4dlZuc1ZnczdBRFlVZkc4bSJ9 |
Possible errors returned by the method are the following:
Code returned | Explanation |
1004 | You are not allowed to call this method. |
1008 | Unknown Relying Party. |
1100 | Invalid reference (for example, nonexistent or expired). |
If HTTP 200 is returned from the method, the request was successfully fulfilled.
Authentication With Different userInfoType
Although we recommend implementing authentication via QR codes and the INFERRED userInfoType, we also support authentication via the following:
- EMAIL (the user's registered email)
- PHONE (the user's registered phone number)
- SSN (the user's social security number)
For more details regarding this implementation, please see this page.