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"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:
All other values are treated as "send as-is". |
length | string | Required | The length of the card number to send to ARX.
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 | Index | Key | System | Value |
---|---|---|---|---|---|
1 | general | 0 | updatesperpoll | Arx | 100 |
2 | webApi | 0 | baseUrl | Arx | https://localhost:5004 |
3 | webApi | 0 | username | Arx | nexus |
4 | webApi | 0 | password | Arx | nexus |
5 | card | 0 | defaultCardFormat | Arx | Solid prox |
6 | card | 0 | cardNumberIdentifierTypes | Arx | Mifare |
7 | card | 0 | length | Arx | 10 |
8 | card | 0 | 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:
All other values are treated as "send as-is". |
length | string | Required | The length of the card number to send to ARX.
ARX supports card number lengths of maximum 10 digits. |
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 |
value | string | Required | The value to use for this field. This has two possible values depending on the value of the static property:
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
cd <SMARTIDHOME>/compose/physicalaccess
docker-compose restart smartid-pa-arx
Copyright 2024 Technology Nexus Secured Business Solutions AB. All rights reserved.
Contact Nexus | https://www.nexusgroup.com | Disclaimer | Terms & Conditions