Document toolboxDocument toolbox

Set up AriadNext connector

This article describes how to set up an AriadNext connector. The connector generates a Two-Dimensional Document (2D-DOC) (a specific French barcode format) using the AriadNext external system. The purpose is to allow inclusion of data and ensure the authenticity of the document through digital signatures. 

<SMARTIDHOME>

In this article, <SMARTIDHOME> refers to /home/nexus, but this can be different depending on the setup.

Prerequisites

  • The Smart ID version needs to be 22.10.x as a minimum. 

Step-by-step instruction

Ensure that you have the required authorization and certificate for accessing the AriadNext SOAP service before using this connector. See "Set up AriadNext" below for more information.

The  AriadNext connector provides a REST endpoint for generating barcodes in unitary mode. The AriadNext connector acts as a proxy and supports a data structure similar as the one used by the Identity Manager Rest Process API. See "Rest call" in Miscellaneous standard service tasks in Identity Manager for more information. 

Generate a barcode

To generate a barcode: 

  1. Add a new service task called MISC: Execute REST client call to your process. 

  2. Add the following parameters. The values are arbitrary and need to be updated: 

Parameter

Mandatory

Value

Description

Parameter

Mandatory

Value

Description

URL

http://{ariad-next-connector-host}:{ariad-next-connector-port}/api/barcode

The URL endpoint where the data will be sent (must end with /api/barcode)

username

Any value to bypass the validation

 

password

Any value to bypass the validation

 

includeHttpResponseBodyInProcessMap

true

If the value is set to true, this parameter defines if the HTTP response body should be added to the process map

httpResponseBodyVariableName

httpResponseBody

The variable name used in a process afterwards to extract the image from the response body

markPosition

 

Default value:

  • NONE

Valid values:

  • TOP, BOTTOM, LEFT, RIGHT, NONE

The position of the 2D-DOC mark

outputFormat

 

Default value:

  • PNG

Valid values:

  • PNG, JPG, TIFF, GIF, BMP, TEXT, FONT_DMTX, FONT_ALPHA

The format of the output

issueCountry

 

Default value:

  • FR

The issue country of the document

firstnames

${Person_Firstname} (to send multiple first names, use the comma separator)

The first name(s)

lastname

${Person_Lastname} 

The last name

registrationNumber

${Person_RegistrationNumber}

The registration number of the card owner

organization

${Person_Organization}

The organization

documentId

${Person_DocumentId}

The internal unique identifier of the document

See a response example below:

Example: Response

<?xml version="1.0" encoding="UTF-8"?> <data>     <field name="image">image encoded as base 64</field>     <field name="width">21.599999999999998</field> <!-- width in millimeters -->     <field name="height">21.599999999999998</field> <!-- height in millimeters --> </data>
  1. Use the groovy script below to de-serialize the data and decode the image if applicable in another task of your process:

    def data = new de.nexus.utils.operators.XmlConverter(new StringReader(httpResponseBody)).asJaxBObject(de.nexus.data.xml.Data.class)
    def imageAsBase64 = data.toMap().get("image")
    def image = java.util.Base64.getDecoder().decode(imageAsBase64)
     
    Card_2DDOC = image

Set up AriadNext

The AriadNext system is configurable using the config/ariad-next.yaml file. You can configure host, security, and image polish settings in the configuration file.

Docker

  1. Open the environment file <SMARTIDHOME>/compose/smartid.env for editing. 

  2. Set the properties for the following three variables to fit your deployment:

    PRIME_CONNECTORS_VERSION=2305.0.0
    # -- AriadNext properties
    ARIAD_NEXT_CONNECTOR_PORT=7077
    ARIAD_NEXT_CONNECTOR_CERT_RESOLVER=le
    ARIAD_NEXT_CONNECTOR_PREFIX=ariad-next-connector

     

  3. Update the docker/compose/identitymanager/ariad-next-connector/docker-compose.yml

Tomcat (stand-alone)

  1. Adapt the config files in the WEB-INF/classes/config folder.

Retrieve card information

The AriadNext connector also provides an endpoint to retrieve card information (for example an endpoint that is used by INverify). When called, it starts a card process in Identity Manager Operator to provide the requested information. Optionally, the response from Identity Manager, in the form of a data map used by the process, can be converted into a custom JSON format.

  1. Configure the card endpoint in config/idm-operator.yaml. There you will also find a detailed description of all settings.

The settings cover:

  • The URL that will start an Identity Manager Operator process, for example:

ws/processes/<processId>/startGetDataAndExecute/<taskId>?tenantId=1&maxAttempts=10&interval=2000 

To get card information, use the Identity Manager REST API request "startGetDataAndExecute" since it starts the process and waits until the task "taskId" is executed and retrieves the data map. See Identity Manager Process REST API for more information. 

  • The list of parameters that will be passed to the process.

  • A custom transformation of the process data from XML to custom JSON format.

  • A mapping of process execution API responses into custom http response codes.

ReST call configuration:

  1. The HTTP method must be GET.

  2. URL:

http://{ariad-next-connector-host}:{ariad-next-connector-port}/api/card?param=value
  1. Query parameters: An optional list of parameters will be passed to Identity Manager Operator and added to the process map when the process is started.

  2. Authentication as described in config/idm-operator.yaml

  3. Define the JSON Format to transform the response body. See config/idm-operator.yaml for details.

  4. Define a mapping of responses to custom response codes. See config/idm-operator.yaml for details.

Copyright 2024 Technology Nexus Secured Business Solutions AB. All rights reserved.
Contact Nexus | https://www.nexusgroup.com | Disclaimer | Terms & Conditions