Set up integration with UniLock
- Ann Base (Deactivated)
- Josefin Klang (Deactivated)
- Ylva Andersson
This article is valid for Smart ID 21.04 and later.
This article describes how to configure the UniLock Service, to enable integration between Smart ID Identity Manager, Physical Access and the UniLock Service.
UniLock is an Access Control System provided by Unitek and managed by a GUI and a web service on the server. The service interacts with UniLock through a web service and with a direct connection to the UniLock database. After integration, all administration of Users, Access Token and Entitlements (besides defining them) should be done in Identity Manager, never in UniLock.
For details on which data can be imported and exported from UniLock, see About import and export to Physical Access.
A user can have maximum 4 cards. If more than 4 cards are assigned, the first 4 active cards based on their accesstoken.identifier.id will be transferred, and a warning will be shown for the rest of the cards. If there is any inactive card already present in the Unilock system and Physical Access has 4 active cards, it will be replaced with the active cards.
If OnlyExportActiveCards = false and a person has less than 4 active cards and has some inactive cards, the system will transfer all active cards followed by inactive cards, maximum 4 cards will get transferred.
Prerequisites
The following prerequisites apply:
Physical Access and the UniLock Docker container/service are installed. See Deploy Smart ID.
The message queue server must be running.
If MIFARE card technology is used, the PACS MIFARE number must be available as raw data (not encrypted, truncated, or similar).
A working network connection to the connected physical access control systems (PACS) must be in place.
Configure UniLock Service data fields
The UniLock data is configured in the configuration table in the Physical Access database. All configuration is cached when the service starts so any configuration changes will require the service to be restarted in order to take effect.
Configure database
For information about how to connect to a PACS system, see Connect to a PACS system in PACS admin panel.
For information about group: messagingqueue, see Physical Access database - common parameters.
group: unilock.general
key | Data type | Required or Optional | Description |
|---|---|---|---|
updatesPerPoll | int | Optional | The maximum number of messages read from the message queue. Default: 100 |
group: unilock.export
key | Data type | Required or Optional | Description |
|---|---|---|---|
connectionString | string | Required | The connection string for the UniLock system. Example: user id=user; password=password; server=localhost; database=unilockDB; connection timeout=30; |
group: unilock.webservice
key | Data type | Required or Optional | Description |
|---|---|---|---|
host | string | Required | The host (and possibly the port number) address to the UniLock web service |
username | string | Optional | The username to use when authenticating to the UniLock web service. It is strongly recommended to use authentication. |
password | string | Optional | The password to use when authenticating to the UniLock web service. It is strongly recommended to use authentication. |
group: unilock.import
key | Data type | Required or Optional | Description |
|---|---|---|---|
identificationFieldId | int | Required | The field used in UniLock to insert our identification value, that is, user.id. The value must be in range 2-14. |
displayName | string | Required | Display name in UniLock. This field is used as an identifier in UniLock and contains user properties. This setting must start with a valid property name and end with a valid property name. A maximum of four properties with any number of characters in between. If the provided display name exceeds 50 characters, the display name will be adjusted to the first 50 characters. Example: “{user.id} - {user.givenname} {user.familyname}”. Note: Make sure the first 50 characters in the display name are unique otherwise the user and access token may be overwritten in UniLock. |
cardDisplayName | string | Required | Holds the value of ‘key text’ field of card in UniLock. This setting must start with a valid property name and end with a valid property name. This property is type of Identifier in Access Token Identifier. A maximum of four properties with any number of characters in between. If the provided display name exceeds 50 characters, the display name will be adjusted to the first 50 characters. Example: “{layout}-{mifare}”. |
cardNumberColumn | string | Required | Used to configure which Identifier of “accesstokenidentifier” table should refer to card number. Default: “mifare” column is used. |
onlyExportActiveCards | bool | Required | This field is used to transfer person data based on card status and entitlements assigned. If onlyExportActiveCards is set to true then the system will transfer person only if person has at least one active card and active entitlement assigned. In case of existing person, and if all existing cards are blocked or become inactive, the system will remove person’s identity from Unilock. If onlyExportActiveCards is set to false then the system will transfer person data if card is inactive or blocked as existing functionality as it is. Default: set to false. |
UniLock field mapping
The UniLock service needs a mapping for each field in Physical Access that should be transferred to UniLock. Only fields that are mapped will be transferred. The mapping must consist of an Physical Access column from User and index of the stamdata-field to use in UniLock. If the specified column does not exist or the stamdata-field index is out of range (valid range is [0, 14]) the service will stop with an error.
Example: The following mapping will map the firstname and lastname to the specified stamdata-fields in UniLock.
Id | group | index | key | system | Value |
|---|---|---|---|---|---|
3 | unilock.mappings | 0 | user.givenname | UniLock | 0 |
4 | unilock.mappings | 0 | user.familyname | UniLock | 1 |
Card format mapping (Optional)
Unilock support card format mapping in HEX and ASCII format with card number length and format type as ‘BigEndian’ and ‘LittleEndian’ for HEX format. To use card format mapping all below fields are mandatory in configuration table (Configuration). If below settings are missing in the configuration then format type will be HEX by default without encoding card number.
key | Data type | Required or Optional | Description |
|---|---|---|---|
cardNumberFormat | string | Required | Used to set conversion format of card number. Supported formats are HEX and ASCII. |
cardNumberMaxLength | string | Required | Used to set maximum length of card number after conversion to specific format. Default: 8 characters. |
cardNumberFormatType | string | Required | Used to formatting type and holds value ‘BigEndian’ or ‘LittleEndian’ for HEX format. |
Restart service
Restart the UniLock connetor service:
Restart Physical Access UniLock connector
cd <SMARTIDHOME>/compose/physicalaccess
docker-compose restart smartid-pa-unilockCopyright 2024 Technology Nexus Secured Business Solutions AB. All rights reserved.
Contact Nexus | https://www.nexusgroup.com | Disclaimer | Terms & Conditions