/
Authentication Service - Other userInfoType

Authentication Service - Other userInfoType

Overview

This page details the implementation of authentication via email, phone number or ssn (social security number) i.e. when the userInfoType is set to EMAIL, PHONE, SSN or UPI. In practice, this means that this is the information the your users will need to enter into your login form to begin authentication.

Concerning Methods

The main Authentication Service page describes all 4 methods in the Freja API:

  1. Initiate authentication

  2. Get one result

  3. Get all results

  4. Cancel authentication

This page will only focus on the Initiate Authentication method when the userInfoType is set to EMAIL, PHONE, SSN or UPI.

Initiate Authentication Method

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

Environment

Endpoint

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. Currently one of:

    • EMAIL (end user's email),

    • PHONE (end user's telephone number),

    • SSN (end user's social security number),

    • UPI (end user’s unique personal identifier in Freja),

    • INFERRED (check main Authentication Service page for more details).

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

For userInfoType set to PHONE, the value must be in the following format: "+4673*******"; the leading '+' sign is present, but the leading '0' for the mobile phone operator code is not.

  • userInfo: string, mandatory, 256 characters maximum.

    • For userInfoType set to SSN, is must be a Base64 encoding of the ssnuserinfo JSON structure as follows:

{     "country":"Country of SSN",     "ssn":"Social security number of the end user" }

Where:

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

  • ssn: string, mandatory. Expected SSN of the end user as per pre-registration.

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

  • attributesToReturn

  • minRegistrationLevel

  • userConfirmationMethod

  • useDynamicQrCode

For more details check the main Authentication Service page.

EMAIL userInfoType Example Request

If you wish to initiate authentication request for a user with an email address joe.black@frejaeid.com and request their name, surname and SSN, follow these steps:

  1. Create the JSON structure {"userInfoType":"EMAIL","userInfo":"joe.black@frejaeid.com","minRegistrationLevel":"EXTENDED","attributesToReturn":[{"attribute":"BASIC_USER_INFO"},{"attribute":"SSN"}]}

  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 (compact format, line broken for clarity only):

initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJFTUFJTCIsInVzZXJJbmZvIjoiam9lLmJsYWNrQH ZlcmlzZWMuY29tIiwibWluUmVnaXN0cmF0aW9uTGV2ZWwiOiJFWFRFTkRFRCIsImF0dHJpYnV0ZXNU b1JldHVybiI6W3siYXR0cmlidXRlIjoiQkFTSUNfVVNFUl9JTkZPIn0seyJhdHRyaWJ1dGUiOiJTU0 4ifV19

PHONE userInfoType Example Request

If you wish to initiate authentication request for a user with a phone number '+46731234567':

  1. Create the JSON structure {"userInfoType":"PHONE","userInfo":"+46731234567","minRegistrationLevel":"BASIC"}

  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 (compact format, line broken for clarity only):

initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJQSE9ORSIsInVzZXJJbmZvIjoiKzQ2NzMxMjM0NT Y3IiwibWluUmVnaXN0cmF0aW9uTGV2ZWwiOiJCQVNJQyJ9

SSN userInfoType Example Request

If you wish to initiate authentication request for a user with an SSN '198905218072' and country 'SE':

  1. Create the JSON structure {"country":"SE","ssn":"198905218072"}, then do the base64 of this JSON.

  2. 'eyJjb3VudHJ5IjoiU0UiLCJzc24iOiIxOTg5MDUyMTgwNzIifQ==', which is the userInfo value in our request.

  3. Create the JSON structure {"userInfoType":"SSN","userInfo":"eyJjb3VudHJ5IjoiU0UiLCJzc24iOiIxOTg5MDUyMTgwNzIifQ==", "minRegistrationLevel":"PLUS"}

  4. Encode the JSON structure to Base64.

  5. Create the HTTP POST request with a POST parameter name initAuthRequest and the Base64 encoded JSON structure from step 4 as its value.

The HTTP body should be the following (compact format, line broken for clarity only):

initAuthRequest=eyJ1c2VySW5mb1R5cGUiOiJTU04iLCJ1c2VySW5mbyI6ImV5SmpiM1Z1ZEhKNU lqb2lVMFVpTENKemMyNGlPaUl4T1RnNU1EVXlNVGd3TnpJaWZRPT0iLCAibWluUmVnaXN0cmF0aW9u TGV2ZWwiOiJQTFVTIn0=

UPI userInfoType Example Request

If you wish to initiate authentication request for a user with unique personal identifier '5633-823597-7862', follow these steps:

  1. Create the JSON structure:{"userInfoType":"UPI","userInfo":"5633-823597-7862","minRegistrationLevel":"BASIC"}

  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=eyJ1c2VySW5mb1R5cGUiOiJVUEkiLCJ1c2VySW5mbyI6IjU2MzMtODIzNTk3LT c4NjIiLCJtaW5SZWdpc3RyYXRpb25MZXZlbCI6IkJBU0lDIn0=

Possible Errors

Code Returned

Explanation

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.