Custom Identifier Management Client


Table of contents

Other clients:

Overview

Freja eID allows Relying Parties to manage a single, Relying Party-specific attribute, through the Custom Identifier Management Service. 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 Relying Party.

In order to set a custom identifier for a user, the Relying Party 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, their phone number or their personal identity number, if the user has been verified with an ID document, or has achieved the status of Freja eID Plus in Sweden) and pass it in the call to Freja eID services. Once the custom identifier is set for a user, the Relying Party can ask for that additional information about the user to be returned when initialising an authentication request. 

For more detailed information about the Custom Identifier Management, please refer to Freja eID Relying Party Developers' Documentation.

Initialising Custom Identifier Client

Build an instance of the CustomIdentifierClientApi interface as shown in the examples below. Note that the CustomIdentifierClient has its own Builder class, which is used for instantiation of CustomIdentifierClient objects. This way of creating objects requires passing mandatory parameters in the Builder constructor, while the rest of the parameters can be passed through the Builder setter functions.

Calling a Service

This section describes how to make calls to the Freja eID API in order to set or delete a custom identifier. 

Set Custom Identifier

This method is used 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.

/*
* Initiate authentication request can be created with EMAIL.
* Change the email value (joe.black@verisec.com in the example) to match your setup.
* See the example below.
*/
String email = "joe.black@verisec.com";
/*
* The custom attribute to be set for the end user, it's interpreted as string value. 
* Must be unique within the requesting Relying Party system inside the Freja eID service. 
*/
String customIdentifier = "joeblack";
SetCustomIdentifierRequest setCustomIdentifierRequest = SetCustomIdentifierRequest.createDefaultWithEmail(email, customIdentifier);
/*
 * As final result of Set custom identifier method, a custom identifier is
 * set for user. No additional information is returned.
*/
customIdentifierClient.set(setCustomIdentifierRequest);


Delete Custom Identifier

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

/*
* The custom attribute to be deleted for the end user, it's interpreted as string value. 
* Must exist within the requesting Relying Party system inside the Freja eID service. 
*/
String customIdentifier = "joeblack";
/*
* Delete custom identifier request can be created with custom identifier
* See the example below.
*/
DeleteCustomIdentifierRequest deleteCustomIdentifierRequest = DeleteCustomIdentifierRequest.create(customIdentifier);
/*
 * As final result of Delete custom identifier method, custom identifier is
 * deleted for a user within requesting Relying Party system. No additional information is returned.
*/
customIdentifierClient.delete(deleteCustomIdentifierRequest);

For each Integrated Relying Party, as well as for the Integrator Relying Party itself, Freja eID generates a unique identifier called relyingPartyId. The Integrator Relying Party needs to pass this identifier in each request. Read more about Integrator and Integrated Relying Parties here

/*
* Parameter relyingPartyId represents a unique ID of the Relying Party
* for which the set/delete custom identifier request should be initiated.
*/
String relyingPartyId = "relying_party_id";

/*
* Set custom identifier request with relyingPartyId.
*/
SetCustomIdentifierRequest.createCustom()
						  .setEmailAndCustomIdentifier(email, customIdentifier)
						  .setRelyingPartyId(relyingPartyId)
						  .build();
/*
* Delete custom identifier request with relyingPartyId.
*/
DeleteCustomIdentifierRequest.create(customIdentifier, relyingPartyId);

Logging and Error Handling

Details for logging and introduction to client exception can be found in the Logging and Error Handling.