Set up integration with ASSA ARX

This article is valid for Smart ID 21.10 and later.

This article describes how to configure the ARX Service, to enable integration between Smart ID Identity Manager, Physical Access and ARX.

ARX is an Access Control System provided by ASSA ABLOY and managed by a GUI and the service interacts with ARX through a web-based API. After integration, all administration of Users, Access Token and Entitlements (besides defining them) should be done in Identity Manager, never in ARX.

For details on which data can be imported and exported from ARX, see About import and export to Physical Access.

Prerequisites

The following prerequisites apply:

Physical Access and the ASSA ARX service are deployed. See Deploy Smart ID.
ARX client version 4.1 is required.
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 ARX Service data fields

The ARX 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: general

key

Data type

Required or Optional

Description

updatesPerPoll

int

Optional

The maximum number of messages read from the message queue.

Default: 100

group: webApi

key

Data type

Required or Optional

Description

baseUrl

string

Required

The base URL where to find the webApi of ARX.

Example of baseUrl

CODE

"https://localhost:5004"

username

string

Required

Username for authenticating to the ARX webApi.

password

string

Required

Password for authenticating to the ARX webApi.

group: card

key	Data type	Required or Optional	Description
defaultCardFormat	string	Required	A default card format in ARX, which all cards without an explicit mapping in cardFormatMappings will receive when exporting. Default: “Solid prox”
cardNumberIdentifierTypes	string	Required	A list of identifier types in AccessToken that can be used as card number for the cards. All cards that should be exported must have a value in at least one of the specified identifiers, otherwise a transfer error will be reported back to Physical Access. Default: “mifare”
encoding	string	Required	ARX supports different formats for the card number. If no value is specified, the card number will be sent as-is. The following values are valid: “EM-PROX” (default) “EM-PROX-HEX” All other values are treated as "send as-is".
length	string	Required	The length of the card number to send to ARX. If the card number is shorter than the specified length, then it will be padded with 0's. ARX supports card number lengths of maximum 10 digits. The card number length must not exceed the value 4294967295. Physical Access will throw an error if the card number exceeds this value.

Example

Example values for required fields of ARX:

Id	Group	Key	System	Value
1	general	updatesperpoll	Arx	100
2	webApi	baseUrl	Arx	https://localhost:5004
3	webApi	username	Arx	nexus
4	webApi	password	Arx	nexus
5	card	defaultCardFormat	Arx	Solid prox
6	card	cardNumberIdentifierTypes	Arx	Mifare
7	card	length	Arx	10
8	card	encoding	Arx	EM-PROX

group: cardFormatMappings

The ARX server has a set of card formats to which we can map, based on the identifier types that are configured in the setting cardFormatMappings.cardNumberIdentifierTypes. Each configured mapping has four different required parameters.

If no additional mapping exists, all cards will be exported using the default card format configured in card (see above). Each cardFormatMappings setting must have a unique index number as shown in the example below.

key	Data type	Required or Optional	Description
cardNumberIdentifierTypes	string	Required	A list of identifier types in AccessToken that can be used as card number for the cards. All cards that should be exported must have a value in at least one of the specified identifiers, otherwise a transfer error will be reported back to Physical Access.
format	string	Required	The format in ARX to map the card to. This setting is case sensitive on ARX.
encoding	string	Required	ARX supports different formats for the card number. If no value is specified, the card number will be sent as-is. The following values are valid: “EM-PROX” (default) “EM-PROX-HEX” All other values are treated as "send as-is".
length	string	Required	The length of the card number to send to ARX. If the card number is shorter than the specified length, then it will be padded with 0's. ARX supports card number lengths of maximum 10 digits. The card number length must not exceed the value 4294967295. Physical Access will throw an error if the card number exceeds this value.

Example

Example configuration for card format settings:

Id	Group	Index	Key	System	Value
1	cardFormatMappings	0	cardNumberIdentifierTypes	Arx	mifare
2	cardFormatMappings	0	format	Arx	Solid prox
3	cardFormatMappings	0	length	Arx	10
4	cardFormatMappings	0	encoding	Arx	EM-PROX
5	cardFormatMappings	1	cardNumberIdentifierTypes	Arx	magnetic stripe
6	cardFormatMappings	1	format	Arx	Solid prox
7	cardFormatMappings	1	length	Arx	10
8	cardFormatMappings	1	encoding	Arx

group: extraField

In addition to the standard fields, ARX can have extra fields for persons.

For each configured extraField, all properties defined below are required in the database.

key

Data type

Required or Optional

Description

name

string

Required

The name of the extra field in ARX. This must match the name exactly of an extra field which is already configured in ARX.

The list of extraField names are located in the ARX menu bar in System > Extended fields for person. Use the value of the name column for this setting.

value

string

Required

The value to use for this field. This has two possible values depending on the value of the static property:

If static is true, then the value can be any string value and this will be used for all persons that are exported to ARX.
If static is false, then the value must refer to any of the following table fields:
- user.{name of column in user table}
- useradditionalfield.{type of field}
- address.{type of field}
- phone.{type of field}
- email.{type of field}

For more details see the example below.

static

bool

Required

Set to true if a static value should be exported to ARX for all persons, or false if a user additional field is configured.

Example

Example configuration for extraFields:

Id	Group	Index	Key	System	Value
1	extraField	0	name	Arx	Title
2	extraField	0	value	Arx	user.title
3	extraField	0	static	Arx	false
4	extraField	1	name	Arx	PhoneNumber
5	extraField	1	value	Arx	phone.home
6	extraField	1	static	Arx	false
7	extraField	2	name	Arx	Department
8	extraField	2	value	Arx	IT
9	extraField	2	static	Arx	true

ARX field mapping

The service mainly transfers user data including related access tokens and entitlement assignments. The tables below show the default field mapping.

If needed, additional fields can be configured, using the SCIM API and extraFields in the database configuration.

User field mapping

By default, the following data is mapped between the USER table in the Physical Access and the ARX service:

SR No	Physical Access field (Web API)	ARX field (UI)
1	UserReferenceId column value of USER table	ID
2	givenName	First Name
3	FamilyName	Last Name
4	Pin	Pin Code
5	Ssn	Description

Access token field mapping

By default, the following data is mapped between the ACCESSTOKEN and ACCESSTOKENIDENTIFIER tables in the Physical Access and the ARX service:

SR No

Physical Access field (Web API)

ARX field (UI)

1

Based on configuration setting for card.

See more details in group: cardFormatMappings above.

Credentials > Credential Format

2

Default Configuration for cardFormat

Credentials > Credential Number

Entitlement assignment field mapping

By default, the following data is mapped between the ENTITLEMENTASSIGNMENT table in the Physical Access and the ARX service:

SR No	Physical Access field (Web API)	ARX field (UI)
1	DisplayName (entitlement-DisplayName)	Access Categories > Name

Restart ARX service

Restart the ASSA ARX connector service:

Restart Physical Access with the ASSA ARX connector

CODE

cd <SMARTIDHOME>/compose/physicalaccess
docker-compose restart smartid-pa-arx