/
Set up integration with ASSA ARX
Document toolboxDocument toolbox

Nexus Documentation
CURL vulnerability information (CVE-2023-38545) - Nexus awareness advisory on Microsoft's update KB5014754

Set up integration with ASSA ARX

Owned by Karolin Hemmingsson (Unlicensed)
Last updated: Feb 06, 2024 by Josefin Klang (Deactivated)
6 min read

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

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

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

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

Index

Key

System

Value

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

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

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

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

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)

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)

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)

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





Related content

Copyright 2024 Technology Nexus Secured Business Solutions AB. All rights reserved.
Contact Nexus | https://www.nexusgroup.com | Disclaimer | Terms & Conditions