When importing users or other data from external systems, it is recommended that REST API provided by the Ubisecure CustomerID is used.

Users can be created by using the functions provided by the REST API or by using the import tool provided in the installation package.

uniqueID length

It should be noted that uniqueID assigned to each user is required to conform to RFC 4122, see Import File Structure (User) below. This requires the uniqueID to be exactly 36 characters long and laid out in a pattern like xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. See below how to generate UUIDs.

Import Tool

Overview

With Import Tool you are able to create a large amount of organizations, users and roles to Ubisecure CustomerID. Also, you are able to modify user details and role memberships. The data must be stored to a set of files and then can be imported.

For full support of extended characters, the data file must be saved in UTF-8 format without BOM (byte order mark). See http://en.wikipedia.org/wiki/UTF-8#Byte_order_mark

Authentication

Import script uses REST commands with Basic Authentication, meaning Basic Authentication needs to be enabled and correct credentials need to be available during usage of script.

By default Basic Authentication is enabled, but if you have disabled it with rest.passwordauthentication.enabled in eidm2.properties you need to re-enable it:

rest.passwordauthentication.enabled = true

For credentials, rest.username and rest.password in linux/win32.config cannot be empty and need to match the ones in eidm2.properties.

If you decide to change values in linux/win32.config, you need to run setup.sh/setup.cmd script in /usr/local/ubisecure/customerid/application/ folder. Changes to eidm2.properties require Wildfly restart.

Running

Import tool on Windows is located at C:\Program Files\Ubisecure\customerid\ application\tools\importtool\import.cmd. On Linux the respective path is /usr/local/ubisecure/customerid/tools/import.sh .
Using the import tool is a straight forward process; the command takes a list of filenames as a parameter and imports the data found in them to the system. For example:

import.cmd importdata.cid

would read the file importdata.cid and take the data therein to the system.

Error Policies

The behavior of the import tool in error situations can be affected using two parameters: the error policy and the duplicate policy.

The error policy defines what the import tool should do if an error occurs. Error can be a communication error with the Ubisecure CustomerID system, an operation failure or an error raised by the duplicate policy defined further below.

The error policy is set with the –errors parameter. The parameter supports the following values:

STOP: An error causes the import process to stop.
IGNORE: The import process continues despite the error, but an error is reported in the program output.

The duplicate policy defines what the import tool should do when an entity in the import data is already present in the system. For organizations this means an organization with the same entity name. For users the existence of a duplicate is resolved using all the unique attributes of a user entity, namely ssn, email and login.
The duplicate policy is set with the –duplicates parameter. The parameter supports the following values:

SKIP: If a duplicate entity is found with the given data the entity is skipped and import proceeds with the entity next in turn.
ERROR: A duplicate found causes an error which in turn is handled as per error policy defined by –errors parameter.
ADD: If a duplicate is found the additional data related to the entity is taken to the system i.e. for organization additional roles are created and for users the roleassignments are updated. Note: entity attributes are not updated.

For example calling import tool as follows:

import.cmd -errors stop -duplicates error importdata.cid

would import entities normally but if at any point an entity to be added is already found in the system the process would stop.

Import File Structure (Organization)

Compulsory values:

entity: organization
id: ENTITYNAME

Optional values:

virtual: true | false (default: false)
friendlyName: FRIENDLYNAME (default: empty)
organizationClass: ORGANIZATIONTYPE (default: empty)
membership: ENTITYNAME (multivalued)
role: ROLENAME (multivalued)
<custom attribute>: VALUE

NOTE: You don't need to include those roles to the organization definition that will be added to the organization automatically based on the organization type definition in the eidm2.properties file.

Example:

entity: organization
id: Example Organization/Example Department
virtual: false
friendlyName: Example
membership: Project1
membership: Project2
role: OrganizationMainUser
role: OrganizationUser
idnumber: 1234

Import File Structure (Role)

Compulsory values:

entity: role
role: ENTITYNAME
Supported characters are ("a-zA-Z") with Scandinavian characters ("äöåÄÖÅ"), numbers ("0-9"), space (" ") and ",._-". All other characters are replaced with a space.

Example:

entity: role
role: Example Organization/TestRole

Import File Structure (User)

Compulsory values:

entity: user
organization: ENTITYNAME
Optional values:
uniqueID: UUID (format must conform to RFC4122 ABNF, otherwise import will fail. default: generated value, cannot be used when importing to AD)
uid: USERNAME (compulsory if new user)
firstname: FIRSTNAME
surname: SURNAME
email: EMAIL (compulsory if new user)
mobile: MOBILE
hetu: SSN
locale: LOCALE
roles.remove: true | false (default: false)
role: ENTITYNAME
password: PASSWORD
sms.activated: true | false (default: true)
otp.activated: true | false (default: false)
otp.state: OTPSTATE
create: true | false (default: false)
<custom attribute>: VALUE

Example:

entity: user
organization: Example Organization
uniqueID: d78db826-9469-44ed-9c95-4825ce3cdf06
uid: john.smith
firstname: John
surname: Smith
email: john.smith@example.com
mobile: +358505551234
roles.remove: true
role: eIDM/eIDMUser
role: Example Organization/OrganizationUser
role: Example Organization/OrganizationMainUser
role: Another Example/OrganizationMainUser
password: pass
create: true
customerid: 12345

Generating UUIDs in Linux command line

UUIDs can be generated in Linux by use of the uuidgen command, simply issue the command like below:

uuidgen

Generating UUIDs in Windows command line

In Windows, UUIDs are probably most easily generated with Powershell. You can invoke the appropriate Powershell command from a regular command prompt by issuing command:

powershell -command "[Guid]::NewGuid()"

Browser not supported