Migration Guide

Note: This guide is meant to be for existing customers that migrate to the new version of the ID validator. If you are a new customer, you can skip reading this migration guide.

The aim of this guide is to support you in adjusting the ID Validator Integration in your system to match the newest and best iteration of the cidaas ID Validator so far. We made sure to include feedback we received and tried our best to make the process as streamlined as possible. As a result many of the previously needed steps are no longer needed.

We will go over all mandatory steps and important APIs and showcase what changed and what needs to be adjusted from your end.

Adjusting the client credentials application

In order to enable your system and the cidaas system to communicate in a secure and authorized manner, your existing cidaas application has to be altered. To perform all basic operations the application needs following scopes:

Scope	Permission
`cidaas:idval_process_start`	Authorizes to create a new ID Validation case in the system
`cidaas:idval_process_read`	Authorizes to read the current status of an ID Validation case
`cidaas:idval_result_read`	Authorizes to read the result of an ID Validation case

Furthermore there are additional scopes which are not strictly mandatory, but might be necessary to perform other operations within the cidaas system

Scope	Permission
`cidaas:media_read`	Authorizes to request a media file of an ID Validation case
`cidaas:idval_settings_read`	Authorizes to request details of ID Validation setting(s)
`cidaas:idval_settings_write`	Authorizes to create or modify ID Validation setting(s)
`cidaas:idval_settings_delete`	Authorizes to delete ID Validation setting(s)

Further information about the API endpoints and which scopes have to be present in the token can be found in our API Documentation.

Adjusting the ID Validation Setting(s)

Some of the previously existing options within the ID Validation Settings do no longer exist or have been renamed.

Following options have been removed:

Option	Reason for Removal	Alternative
`client_id`	Removed due to no longer being relevant	-
`hide_header_ui`	Removed due to being redundant	Can be configured within an ID Validation Theme
`face_recognition_sync`	Removed due to no longer being relevant	-
`flow_steps`	Removed due to no longer being relevant	-
`template_name`	Removed due to no longer being relevant	-
`flow_type`	Removed due to being redundant	New option -> `mode`
`idvalidator_uri`	Removed due to no longer being relevant	-
`disable_device_switch`	disable_device_switch	-

Following options have been added:

Option	Function	Availability
`mode`	Indicates which ID Validation Mode shall be used when performing an ID Validation Case using this setting	Mandatory
`themeName`	Indicates which ID Validation Theme will be applied when performing an ID Validation Case using this setting	Mandatory
`consentURL`	Links to the consent URL that will be used during ID validation	Mandatory
`prevalidation_config`	Configuration object for the newly introduced task `prevalidation`	Optional
`document_data_matching_config`	Configuration object for the newly introduced task `document_data_matching`	Optional

Since all seeded and manually created ID Validation Settings need to be adjusted once the old system is replaced with the new system, the transition will most likely be performed by the cidaas system.

Whitelabeling / Customization

In your existing integration the whitelabeling information of the cidaas applicitation that was configured in the ID Validation Setting dictated the look of the ID Validator UI. From now on a more powerful theming system allows to finetune the look and feel of the ID Validator UI.

In order to create a Theme, please head in the browser of your choice to the cidaas Admin UI at <yourTenantURL>/admin-ui. Once you are logged in open the section Hosted Pages in the sidebar. Afterwards in the main view select the tab Theming. In here you can create a new Theme. See below for an example theme and which options are available. Detailed information can be found in the Technical Integration Guide.

:root{
    --idval-font-family: 'Lato', serif;
    --idval-background-image: url('https://www.cidaas.com/wp-content/uploads/2024/03/cidaas-connect-2024.jpg');   
    --idval-header-visibility: visible;
    --idval-header-logo-position: 'flex-start';
    --idval-header-background-color: #f7941d;
    --idval-header-logo-url: url('https://www.cidaas.com/wp-content/uploads/2021/05/cidaas-black-logo-300x77.png');  
    --idval-button-background-color: #000000;
    --idval-button-font-color: #FFFFFF;    
}

Creating an ID Validation Case

In your existing integration you are calling POST <yourTenantURL>/idval-sign-srv/caseinvocation to register a new ID Validation case.

In order to register a new ID Validation case in the system the following endpoint has to be called:

POST <yourTenantURL>/id-val-srv/processes - <yourTenantURL> refers to your cidaas tenant e.g. https://demo.cidaas.de

It is important to note that the service path has changed from idval-sign-srv to id-val-srv! This is the case for all ID Validation related API Endpoints.

The request's payload needs to be adjusted to include the data as follows (using example data):

{
    "validation_settings_id": "9838425c-4f8d-4d7b-b758-59e80dab0813",
    "external_reference": "idValidation_83293820",
    "redirect_url": "https://demo.cidaas.de/id-validation-result",
    "unique_user_id": "378b381d-cbb6-44f6-ba6f-68b34db03ac9",
    "user_id_type": "sub"   
}

Depending on the use case and selected ID Mode in the ID Validation Setting the payload might need following extension:

{
    "validation_settings_id": "9838425c-4f8d-4d7b-b758-59e80dab0813",
    "external_reference": "idValidation_83293820",
    "redirect_url": "https://demo.cidaas.de/id-validation-result",
    "unique_user_id": "378b381d-cbb6-44f6-ba6f-68b34db03ac9",
    "user_id_type": "sub",
    "custom_attributes": {
        "given_names": "Hans",
        "surname": "Langer",
        "date_of_birth": "1965-04-19",
        "document_number": "L69HXN420",
        [...]
    }
}

To identify whether the field custom_attributes is mandatory and which data needs to be included, please refer to our general Technical Integration Guide.

On a successful request the response will have a 200 OK HTTP status code including a payload:

{
    "success": true,
    "status": 200,
    "data": {
        "processId": "af7da0bd-0f88-4e4c-9254-987bfad3188a",
        "caseId": "f2482250-0d17-4d50-8963-f4b0e5551530",
        "executionStatus": "paused",
        "user_task_url": "https://demo.cidaas.de/id-validator-webapp/processes/af7da0bd-0f88-4e4c-9254-987bfad3188a/tasks/prevalidate",
        "user_redirect_url": "https://demo.cidaas.de/id-validation-result",
        "browser_redirect": false
    }
}

Requesting the Result of an ID Validation Case

In your existing integration you are calling GET <yourTenantURL>/idval-sign-srv/cases/:caseID/result to request the result of an ID Validation case.

Change this to GET <yourTenantURL>/id-val-srv/idcases/:caseID/result.

On a successful request the response will have have an 200 OK HTTP status code including a payload. To view the complete payload of the response check out the API Documentation.

Adjusting the client credentials application​

Adjusting the ID Validation Setting(s)​

Whitelabeling / Customization​

Creating an ID Validation Case​

Requesting the Result of an ID Validation Case​

Adjusting the client credentials application

Adjusting the ID Validation Setting(s)

Whitelabeling / Customization

Creating an ID Validation Case

Requesting the Result of an ID Validation Case