Nexus' software components have new names:

Nexus PRIME -> Smart ID Identity Manager
Nexus Certificate Manager -> Smart ID Certificate Manager
Nexus Hybrid Access Gateway -> Smart ID Digital Access component
Nexus Personal -> Smart ID clients

Go to Nexus homepage for overviews of Nexus' solutions, customer cases, news and more.


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.


Expand/Collapse All

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.

To change the database configuration:

  1. Log in to Physical Access admin panel as an admin user.
    All configured PACS connector services are listed, as well as Generic configurations to define the messaging queue. 
  2. Click on a system to do updates.
    All database entries are listed. 
  3. To update an entry, click on the icon. Edit as needed and then click Update
  4. To create an entry, click on +Create. Select Group, enter Key, Value and Index, and then click Create

group: messagingqueue

keyData typeRequired or OptionalDescription
serverstringRequired

IP Address of Message Queue Server. If it is installed on the local server then we can use localhost. If we are accessing this server remotely then need to mention IP address.

usernamestringRequired

Username of message queue server.

Default value: “guest”

passwordstringRequired

Password of message queue server.

Default value: “guest”

systemstringRequired

Defines which messaging queue to be used, either "rabbitmq" or "azureservicebus".

Default value: "rabbitmq"

group: general

keyData typeRequired or OptionalDescription
deleteUserOnNoEntitlementstringOptional

Defines if the user shall be deleted if no active entitlement assignment are present for that user.

Valid values: true or false.

Default: true

deleteUserOnNoAccessTokenstringOptional

Defines if the user shall be deleted if no active access tokens are present for that user.

Valid values: true or false.

Default: true 

heartbeatInterval

intOptional

Heartbeat interval is the time difference between two successive heartbeats, and it is used to know if the system is in active (running) or in inactive (stopped) state.

Default value and minimum value: 60 seconds. If it is set less than 60 seconds, it will be considered as 60 seconds to update the status.

group: unilock.general

keyData typeRequired or OptionalDescription
updatesPerPollintOptional

The maximum number of messages read from the message queue.

Default: 100

group: unilock.export

keyData typeRequired or OptionalDescription
connectionStringstringRequired

The connection string for the UniLock system.

Example: user id=user; password=password; server=localhost; database=unilockDB; connection timeout=30;

group: unilock.webservice

keyData typeRequired or OptionalDescription
hoststringRequiredThe host (and possibly the port number) address to the UniLock web service
usernamestringOptionalThe username to use when authenticating to the UniLock web service. It is strongly recommended to use authentication.
passwordstringOptionalThe password to use when authenticating to the UniLock web service. It is strongly recommended to use authentication.

group: unilock.import

keyData typeRequired or OptionalDescription
identificationFieldIdintRequiredThe field used in UniLock to insert our identification value, that is, user.id. The value must be in range 2-14.
displayNamestringRequired

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.

cardDisplayNamestringRequired

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}”.

cardNumberColumnstringRequired

Used to configure which Identifier of “accesstokenidentifier” table should refer to card number.

Default: “mifare” column is used.

onlyExportActiveCardsboolRequired

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.

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.

IdgroupindexkeysystemValue
3unilock.mappings0user.givennameUniLock0
4unilock.mappings0user.familynameUniLock1

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.

keyData typeRequired or OptionalDescription
cardNumberFormatstringRequiredUsed to set conversion format of card number. Supported formats are HEX and ASCII.
cardNumberMaxLengthstringRequired

Used to set maximum length of card number after conversion to specific format.

Default: 8 characters.

cardNumberFormatTypestringRequiredUsed to formatting type and holds value ‘BigEndian’ or ‘LittleEndian’ for HEX format.

Restart service

  1. Restart the UniLock connector service:

    Restart Physical Access UniLock connector
    cd <SMARTIDHOME>/compose/physicalaccess
    docker-compose restart smartid-pa-unilock

This article is valid for Smart ID 21.04 and later.

Related information

Integrate Identity Manager with physical access control system (PACS)