Custom Identifier Management

Owned by Former user (Deleted)
Last updated: May 23, 2023 by Aleksandar Laban
4 min read


This page:

Services:

Management:

Best practices:

Overview

Freja eID allows Relying parties (RP) to manage a single, RP-specific attribute, through the Custom identifier management service. 

A typical use of this option would be to allow for login identifiers specific to your organisation to be returned within the result of authentication. In other words, the end user can use their preferred identifier at login, e.g. email address. Freja eID performs the translation to the custom identifier, previously configured by the RP, e.g. employee number or domain login. In such a way, it is straightforward for RPs to map user identifiers to those known within their internal systems, without the need to store this mapping in an internal database or LDAP.

A custom identifier must be unique within the requesting relying party system inside the Freja eID service. In other words, Freja eID does not allow two identical custom attributes to be set by the same RP. In order to set a custom identifier for a user, the RP needs to obtain the existing user information for that user in the Freja eID system (e.g. the email address the user has connected to Freja eID or the social security number, if the user is on the Freja eID+ level) and pass it in the call to Freja eID services. 

Set custom identifier method

This method is used by a relying party to set a custom identifier for a specific user. As said before, the existing user information for that user in the Freja eID system must be passed as a parameter of this method.

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

System
Method endpoints
Test
https://services.test.frejaeid.com/user/manage/1.0/setCustomIdentifier
Production
https://services.prod.frejaeid.com/user/manage/1.0/setCustomIdentifier


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

Parameter name
Value
setCustomIdentifierRequest
{
   "userInfoType":"EMAIL",
   "userInfo":"john.doe@verisec.com",
   "customIdentifier":"vejodoe"
}

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

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.

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)

customIdentifier: string, mandatory, 128 characters maximum. The custom attribute to be set for the end user. Must be unique within the requesting relying party system inside the Freja eID service.

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

Example request:

If you wish to set a custom identifier for a user with an email address joe.black@verisec.com, follow these steps:

  1. Create the JSON structure {"userInfoType":"EMAIL","userInfo":"joe.black@verisec.com","customIdentifier":"vejodoe"}
  2. Encode the JSON structure to Base64.
  3. Create the HTTP POST request with a POST parameter name setCustomIdentifier and the Base64 encoded JSON structure from the step 2 as its value.

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

setCustomIdentifierRequest=eyJ1c2VySW5mb1R5cGUiOiJFTUFJTCIsInVzZXJJbmZvIjoiam9lLmJ
sYWNrQHZlcmlzZWMuY29tIiwgImN1c3RvbUlkZW50aWZpZXIiOiAidmVqb2RvZSJ9
Example request with userIntoType set to PHONE:

If you wish to set a custom identifier for a user with a phone number '+46731234567', follow these steps:

  1. Create the JSON structure {"userInfoType":"PHONE","userInfo":"+46731234567","customIdentifier":"vejodoe"}
  2. Encode the JSON structure to Base64.
  3. Create the HTTP POST request with a POST parameter name setCustomIdentifier and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following:

setCustomIdentifierRequest=eyJ1c2VySW5mb1R5cGUiOiJQSE9ORSIsInVzZXJJbmZvIjoiKzQ2NzM
xMjM0NTYiLCAiY3VzdG9tSWRlbnRpZmllciI6ICJ2ZWpvZG9lIn0=


Possible errors returned by the method are the following:

Return code
Explanation
1001Invalid or missing userInfoType.
1002Invalid or missing userInfo.
1008Unknown relying party.
1010JSON request cannot be parsed.
5000Invalid or missing customIdentifier.
5002You have already used this custom identifier.

If the request is successfully processed, the HTTP 204 is returned from this method. Read more about HTTP response codes in General information about Freja eID RESTful APIs. 

Delete custom identifier method

This method is used by a relying party to delete a custom identifier for a specific user.

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

System
Method endpoints
Test
https://services.test.frejaeid.com/user/manage/1.0/deleteCustomIdentifier
Production
https://services.prod.frejaeid.com/user/manage/1.0/deleteCustomIdentifier

 

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

Parameter name
Value
deleteCustomIdentifierRequest
{
   "customIdentifier":"vejodoe"
}

customIdentifier: string, mandatory, 256 characters maximum. The custom attribute to be deleted.

Example request:

If you wish to delete a custom identifier ''vejodoe'', follow these steps:

  1. Create the JSON structure {"customIdentifier":"vejodoe"}
  2. Encode the JSON structure to Base64.
  3. Create the HTTP POST request with a POST parameter name deleteCustomIdentifier and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following:

deleteCustomIdentifierRequest=eyJjdXN0b21JZGVudGlmaWVyIjoidmVqb2RvZSJ9

 

Possible errors returned by the method are the following:

Return code
Explanation
1008Unknown relying party.
5000Invalid or missing customIdentifier.
5001There is no user for given custom identifier.

If the request is successfully processed, the HTTP 204 is returned from this method. Read more about HTTP response codes in General information about Freja eID RESTful APIs. 

 

Go to: