/
Custom Identifier Management

Custom Identifier Management

Overview of Custom Identifier Management

Freja 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 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 service. In other words, Freja 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 system (e.g. the email address the user has connected to Freja or the social security number, if the user is on the Freja+ level) and pass it in the call to Freja 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:

Environment

Endpoint

Environment

Endpoint

TEST

https://services.test.frejaeid.com/user/manage/1.0/setCustomIdentifier

PRODUCTION

https://services.prod.frejaeid.com/user/manage/1.0/setCustomIdentifier

JSON Example for setCustomIdentifierRequest

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", "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), UPI (user’s unique personal identifier in Freja).

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

EMAIL userInfoType Example Request

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

  1. Create the JSON structure {"userInfoType":"EMAIL","userInfo":"joe.black@freja.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

PHONE userInfoType Example Request

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=

UPI userInfoType Example Request

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

  1. Create the JSON structure {"userInfoType":"UPI","userInfo":"5633-823597-7862","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=eyJ1c2VySW5mb1R5cGUiOiJVUEkiLCJ1c2VySW5mbyI6IjU2MzMtODIzN Tk3LTc4NjIiLCJjdXN0b21JZGVudGlmaWVyIjoidmVqb2RvZSJ9

Possible Errors

Code Returned

Explanation

Code Returned

Explanation

1001

Invalid or missing userInfoType.

1002

Invalid or missing userInfo.

1008

Unknown relying party.

1010

JSON request cannot be parsed.

5000

Invalid or missing customIdentifier.

5002

You have already used this custom identifier.

If the request is successfully processed, HTTP 204 is returned from this method.

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:

Environment

Endpoint

Environment

Endpoint

TEST

https://services.test.frejaeid.com/user/manage/1.0/deleteCustomIdentifier

PRODUCTION

https://services.prod.frejaeid.com/user/manage/1.0/deleteCustomIdentifier

JSON Example for deleteCustomIdentifierRequest

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

{ "customIdentifier":"vejodoe" }

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

EMAIL userInfoType 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

Code Returned

Explanation

Code Returned

Explanation

1008

Unknown relying party.

5000

Invalid or missing customIdentifier.

5001

There is no user for given custom identifier.

If the request is successfully processed, the HTTP 204 is returned from this method.