This page:
Other services:
Management:
Best Practices:
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 iOS or Android devices they possess, and registered with Freja eID, allowing them to be referred to by relying parties through the use of one or more email addresses. A user may have also undergone an extended registration process achieving the status of Freja eID Extended or Plus. If so, relying parties can refer to such a user through a social security number. To access the Freja eID authentication service, a relying party must use SSL with client authentication, where the client certificate is obtained from Freja eID during the onboarding process.
In step one, a relying party invokes the Freja eID authentication service submitting a user identifier and, optionally, a Freja eID assurance qualifier (Freja eID or Freja eID+), and requests that the user approves authentication to a service operated by the relying party. Should the relying party service be residing on the same mobile device (i.e. accessed through a mobile browser or mobile app), the service can activate the Freja eID mobile application directly. Otherwise, the service will need to instruct the end user to start the Freja eID mobile application on one of the enabled devices. In step two, the Freja eID mobile application and authentication service work on presenting the login request to the end user and solicit approval for it. Finally, in step three, the relying party polls for the status of the authentication request until it receives a positive result or an error allowing it to proceed to allow or reject end-user access to its service, respectively.
Before you begin
Disclaimer
We retain the right to extend the API with new optional parameters, new response fields and error codes. Within the same API version, these additions shall be made strictly without altering existing response fields and error codes so as not to compromise your system's stability. Your application therefore MUST be able to handle unknown response fields and error codes. In the case of unknown response fields, the application SHOULD ignore them and process only those it understands. In the case of unknown error codes, the application MUST present a generic error message to the end-user.
There are several technical requirements that must be in place before the implementation can start. Please complete the checklist below before proceeding:
- Obtain an SSL/TLS client certificate providing you access to the Freja eID test environment.
- Import Freja eID Test root certificate as trusted into the trust store of your application.
- Using Freja eID mobile application, register one or more users with the Freja eID Test infrastructure.
Production checklist
In order to use Freja eID in a production environment, you must fulfill the following:
- Sign a contract allowing your organisation to access the production Freja eID Authentication service.
- Provide Freja eID with a logo suitable to represent your organisation in the mobile application, as well as a display name, a URL and a short description. Please note that:
- The logo must be delivered in one of the vector file formats: AI (Adobe Illustrator Artwork), EPS (Encapsulated PostScript) or editable PDF (Portable Document Format). The preferable format is AI (filename extension is .ai).
- The display name is restricted to the maximum length of 20 characters and the description should not exceed 75 characters. The URL can be up to 100 characters long.
- Obtain an SSL/TLS client certificate providing you access to the Freja eID production environment.
- Import Freja eID Production root certificate as trusted into the trust store of your application.
Initiate authentication method
This method is used by a relying party to initiate an authentication request. The method is intended for authentication in online contexts where the 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 a 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 a different relying party, will cancel both initiated authentication requests.
The method is called using HTTP POST through the URLs below:
System | Method 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" } userInfoType: string, mandatory. Describes the type of user information supplied to identify the end user. Currently one of: PHONE (end user's telephone number), EMAIL (end user's email), SSN (end user's social security number), CUST (a custom identifier), INFERRED (the user need not enter any identifier, their identity will be determined as a result of the authentication process). The INFERRED method is typically used in conjunction with QR codes. For more details please see Implementation - Troubleshooting and Best Practices. Note: Currently, CUST is not supported. userInfo: string, mandatory, 256 characters maximum. If userInfoType is EMAIL or PHONE, interpreted as a string value of the email or telephone number of the end user, respectively. If userInfoType is SSN, then it must be a Base64 encoding of the ssnuserinfo JSON structure described below. If userInfoType is CUST, then see custuserinfo below. 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). Note: If userInfoType is PHONE, the userInfo value MUST be in the form of: "+4673*******"; the leading plus '+' is present whereas the leading zero from the mobile phone operator code '0' is not. (See example below) Note: the combination of userInfoType INFERRED and userInfo N/A is used when the user is being authenticated by scanning a QR code. For more details please see Implementation - Troubleshooting and Best Practices. 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 email address), DATE_OF_BIRTH (date of birth), CUSTOM_IDENTIFIER (a unique, RP-specific, user identifier, set by the RP through the Custom Identifier Management), SSN (social security number and country ), RELYING_PARTY_USER_ID (a unique, user-specific value that allows the Relying Party to identify the same user across multiple sessions). Note: If the requested attribute is BASIC_USER_INFO, DATE_OF_BIRTH or SSN the minRegistrationLevel must be set to EXTENDED or PLUS. 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. | |
ssnuserinfo | { "country":"Country of SSN", "ssn":"Social security number of the end user" } 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, must be equal to "SE". | |
custuserinfo | Reserved for future use, not supported in current version of Freja eID. |
Example request with userInfoType set to EMAIL: |
---|
If you wish to initiate authentication request for a user with an email address joe.black@verisec.com and request their name, surname and SSN, follow these steps:
The HTTP body should be the following (compact format, line broken for clarity only): initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJFTUFJTCIsInVzZXJJbmZvIjoiam9lLmJsYWNrQHZlcmlzZWMuY29tIiwibWluUmVnaXN0cmF0aW9uTGV2Z WwiOiJFWFRFTkRFRCIsImF0dHJpYnV0ZXNUb1JldHVybiI6W3siYXR0cmlidXRlIjoiQkFTSUNfVVNFUl9JTkZPIn0seyJhdHRyaWJ1dGUiOiJTU04ifV19 |
Example request with userIntoType set to PHONE: |
---|
If you wish to initiate authentication request for a user with a phone number '+46731234567':
The HTTP body should be the following: initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJQSE9ORSIsInVzZXJJbmZvIjoiKzQ2NzMxMjM0NTY3IiwibWluUmVnaXN0cmF0aW9uTGV2ZWwiOiJCQVNJQyJ9 |
Example request with userIntoType set to SSN: |
---|
If you wish to initiate authentication request for a user with an SSN '198905218072' and country 'SE':
The HTTP body should be the following: initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJTU04iLCJ1c2VySW5mbyI6ImV5SmpiM1Z1ZEhKNUlqb2lVMFVpTENKemMyNGlPaUl4T1RnNU1EVXlNVGd3TnpJ aWZRPT0iLCAibWluUmVnaXN0cmF0aW9uTGV2ZWwiOiJQTFVTIn0= |
Example request with userIntoType set to INFERRED: |
---|
If you wish to authenticate a user via a QR code:
The HTTP body should be the following: initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJJTkZFUlJFRCIsInVzZXJJbmZvIjoiTi9BIn0= |
Possible errors returned by the method are the following:
Return code | 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. |
1010 | JSON request cannot be parsed. |
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). |
Methods for retrieving authentication results
There are two methods that can be used for fetching authentication results: one that returns a single result for a specified authentication reference (authRef returned from a call to Initiate authentication method), and one that returns multiple authentication results. The latter is the preferred way of fetching results in situations where a relying party has many concurrent authentications in progress, as it reduces the number of polling requests.
Get one authentication result method
The method is called using HTTP POST through the URLs below:
System | Method 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. As mentioned above, authentications are short-lived and, once initiated by a relying party, must be confirmed by an end user within two minutes. Consequently, fetching the result of an authentication for a given authentication reference is only possible within 10 minutes of the call to Initiate authentication method that returned the said reference. |
Example request: |
---|
If you wish to fetch an authentication result with the authentication reference previosly returned from a call to initAuthRequest (for a user with an email address joe.black@verisec.com), 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:
Return code | Explanation |
---|---|
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 email address", "dateOfBirth":"User's date of birth", "customIdentifier":"Custom identifier set by the RP", "ssn":{ "ssn":"Social security number of the end user", "country":"Country of SSN" }, "relyingPartyUserId": "Unique user ID reserved for Relying Parties" }, "details":"JWS signed data, see below" } 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 (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": { "basicUserInfo":{ "name":"User's name", "surname":"User's surname" }, "emailAddress":"User's email address", "dateOfBirth":"User's date of birth", "customIdentifier":"Custom identifier set by the RP", "ssn":{ "ssn":"Social security number of the end user", "country":"Country of SSN" }, "relyingPartyUserId":"Unique user ID reserved for Relying Parties" }, "timestamp":"Time when authentication confirmed by end user" } authRef: See authRef above. status: See status above. userInfoType: See userInfoType as described in Initiate authentication method. userInfo: See userInfo as described in Initiate authentication method. Note: If userInfoType was set to INFERRED in the initAuthRequest, then userInfoType will be INFERRED and the userInfo will be N/A. We recommend you explicitly ask for attributesToReturn in the initAuth method. minRegistrationLevel: See minRegistrationLevel as desribed 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 email address", "dateOfBirth":"User's date of birth", "customIdentifier":"Custom identifier set by the RP", "ssn":{ "ssn":"Social security number of the end user", "country":"Country of SSN" }, "relyingPartyUserId":"Unique user ID reserved for Relying Parties" } basicUserInfo: JSON object which contains user's name and surname. emailAddress: String, representing the user's email address. dateOfBirth: String, containing date of birth in format: YYYY-MM-DD customIdentifier: String, a unique, RP-specific, user identifier, set by the RP itself through the Custom Identifier Management. ssn: JSON object which contains social security number and country. relyingPartyUserId: string, mandatory. Represents a unique, user-specific value that allows the Relying Party to identify the same user across multiple sessions. |
Example data for APPROVED response, JSON response body:
{ "authRef":"12345-67890-abcdef", "status":"APPROVED", "details":"JWS content as per below", "requestedAttributes": { "basicUserInfo":{ "name":"John", "surname":"Doe" }, "customIdentifier":"vejodoe", "ssn":{ "ssn":"198511170040", "country":"SE" }, "relyingPartyUserId": "94039a98c8d" } }
Field | Value |
---|---|
Certificate info | See above. |
Header | See above. |
Payload | "authRef":"12345-67890-abcdef" |
Final JWS (compact format, line broken for clarity only) | (header omitted for brevity) eyJ1c2VySW5mbyI6ImpvaG4uZG9lQHNvbWVkb21haW4uY29tIiwicmVxdWVzdGVkQXR0cmlidXRlcyI6eyJjdXN0b21JZGVudGlmaWVy IjoidmVqb2RvZSIsImJhc2ljVXNlckluZm8iOnsic3VybmFtZSI6IkRvZSIsIm5hbWUiOiJKb2huIn0sInNzbiI6eyJjb3VudHJ5Ijoi U0UiLCJzc24iOiIxOTg1MTExNzAwNDAifSwiaW50ZWdyYXRvclNwZWNpZmljVXNlcklkIjoiODc2NGpnc2Y3ODNnc2sifSwidXNlcklu Zm9UeXBlIjoiRU1BSUwiLCJhdXRoUmVmIjoiMTIzNDUtNjc4OTAtYWJjZGVmIiwic3RhdHVzIjoiQVBQUk9WRUQiLCJ0aW1lc3RhbXAi OjE0OTEzODgxNjMzODl9.qEF5K4VRvuKc4VCoc4jBVY5bkqgrPKyEyVPe6eZoUh_mE9DVK_p2cldyKsVfEmKHqKFdKQyuEweS39lm20Q 2NlZq6kBgUb7C3AGR8Mlx-e0iAM2wlLqkQ6ke_U-42Y9G8m8PaWKNvOmSs8K_cfWGzNUsA5EzvNNJGljsdXWXR9Y3cFxzYg5tiwVlRQJ bJIdsuiOa7aP1JlOVZIa6T7Fz2jCxdtC0qaJBlIq3jZwz16mQHITyuWqf3kQfzJ8QiI9qJpF0U7B8fiSM9cLCP0kAVDd1ZVgChQnN8vv q6VjRbVySPTQUA7NBELd578ErFk_DcsvAGPnPR66DQnNqLI4taA |
Get authentication results method
The method allows a relying party to fetch the results of multiple outstanding authentications. It is our recommendation that relying parties generally use the aggregate method, as it is more efficient and reduces network traffic. This is the default behaviour of client libraries supplied by Freja eID.
The method is called using HTTP POST through the URLs below:
System | Method 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 or OUTSTANDING_AND_NEW. If 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. Sending OUTSTANDING_AND_NEW as the value will return only the status of outstanding (i.e. authentications still in progress) and completed but previously unreported statuses. NOTE: In the current implementation of the service must be equal to ALL. |
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:
Return code | Explanation |
---|---|
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":"John", "surname":"Doe" }, "emailAddress":"john.doe@somedomain.com", "dateOfBirth":"1987-10-18", "customIdentifier":"vejodoe", "ssn":{ "ssn":"198710180040", "country":"SE" }, "relyingPartyUserId": "94039a98c8d" }, }, { "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: 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 canceled 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). 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:
System | Method 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 fetch multiple authentication results, 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:
Return code | 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.