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

Integra is an Access Control System provided by Bravida and managed by a GUI and API to interact with Integra through the EasyConnect V2. After integration, all administration of Users, Access Token and Entitlements (besides defining them) should be done in Identity Manager, never in Integra.

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

Important licensing information

From versions over 7.41 the Integra connector requires an extended license matching the EasyConnect Advanced connector.

Bravida’s new server hosting versions over 7.41 does a license check now (the old server does not) to authorize requests classified as basic or advanced. Nexus’ Smart ID Identity Manager requests are advanced requests and thus need an extended license.

If you are planning on upgrading to any version of Integra over 7.41 please contact Bravida and upgrade your license before upgrading.

Prerequisites

The following prerequisites apply:

Physical Access and the Bravida Integra Docker container/service are installed. See Deploy Smart ID.
Bravida Integra version 7.20 or later is required. Added https support in the PACS connector for v8.1. The service Integra EasyConnect v2 is required on Integra system to interact with Physical Access.
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 Integra Service data fields

The Integra 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

group: messagingqueue

key	Data type	Required or Optional	Description
server	string	Required	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.
username	string	Required	Username of message queue server. Default value: “guest”
password	string	Required	Password of message queue server. Default value: “guest”
system	string	Required	Defines which messaging queue to be used, either "rabbitmq" or "azureservicebus". Default value: "rabbitmq"

group: general

key Data type Required or Optional Description

deleteUserOnNoEntitlement

string

Optional

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

Valid values: true or false.

Default: true

deleteUserOnNoAccessToken

string

Optional

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

int

Optional

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

key

Data type

Required or Optional

Description

updatesPerPoll

int

Optional

The maximum number of messages read from the message queue.

Default: 100

group: integra

key

Data type

Required or Optional

Description

sessiontoken

string

Required

To communicate with the Integra client through the easy connect service we need session token. The Session token is unique GUID assigned to the user of the Integra client. We can find this session token inside IDA server setting configuration. Open IDA application located at {installation_path}\Bravida Integra\IDA\Ida.Server.Config.exe. Open the application and go to tab IEC2. Use the session token of valid Integra user.

parentFolderPath

string

Required

To export all user details to the specific folder of Integra we can use configuration. Default parent folder path is Administration\Kortinnehavare. If the path is incorrect, the service will not start and will throw an exception as Folder path not found. All folder path list is available in the table folder of the Integra database.

emailType

string

Required

This indicates which type of email to export to Integra. If email type is not found then the first email of emails list will be sent.

Default email type: work

group: export

key Data type Required or Optional Description

maxValidYears

int

Required

Max valid years for a card.

idcSystemNumbers

int

Optional

List of system numbers.

userfieldmappings

string

Optional

userfieldmappings is the combination of all additional fields which can be sent to Integra.

Currently, the following fields can be configured:

EmailAddress
Department
Description
FreeInfo1
FreeInfo2
FreeInfo3
UserInfo

To export these fields to Integra, do the following configuration:

Id	Group	Key	System	Value
17	export	userfieldmappings	Integra	useradditionalfield.Department,Department
18	export	userfieldmappings	Integra	email.Work,EmailAddress
19	export	userfieldmappings	Integra	useradditionalfield.FreeInfo1,FreeInfo1
20	export	userfieldmappings	Integra	useradditionalfield.UserInfo,UserInfo
21	export	userfieldmappings	Integra	useradditionalfield.Description,Description
22	export	userfieldmappings	Integra	useradditionalfield.FreeInfo2,FreeInfo2
23	export	userfieldmappings	Integra	useradditionalfield.FreeInfo3,FreeInfo3

The value in the configuration table_name.value_of_type_column,property_name_of_cardholder. This configuration setting is the mapping between the Physical Access table field and Integra cardholder model properties. User column fields can be sent by adding the configuration user.column_name_of_user_table,property_name_of_cardholder.

group: export.idcSystemNumber-{index}

The {index} is an Physical Access system number that shall map to a specific system number in Integra. This index must also exist in the idcSystemNumbers configuration. For example, if idcSystemNumbers-1 exists, then the configuration group export.idcSystemNumber-1 must be configured in the database. Each group holds settings for a specific Integra system number.

If this configuration setting is not added into the database then the default configuration, export.idcSystemNumber-default is used.

For each configuration group we have the following settings:

key	Data type	Required or Optional	Description
cardNumberIdentifierTypes	string	Required	This comma-separated list indicates which access token identifier is stored for this specific Integra system. If this list contains two columns separated by comma, then the system will check if the field exist on the card identifier. if they exist, then two card objects will be exported to Integra for that system. If any specified column does not contain a valid Integra card number for this system, then the export will fail for this card.
MaxCardNumberLength	int	Required	This parameter decides how long the card numbers can be when sending them to Integra. If they are longer, they will be trimmed down. Note that since card numbers are not sent “as-is” to Integra, there may be times where card numbers are not unique. If this occurs, the card will not be exported and an error will be logged. Integra requires card numbers of at least 6 digits. If `MaxCardNumberLength` is specified to less than 6 digits, the export will pad the card number with leading zeros and send a card number of 6 digits.
IntegraSystemNumber	int	Required	This is the system number in Integra.
exportPin	bool	Required	The value indicates if the pin code should be exported to Integra or not.
maxPinLength	int	Required	The value indicates the maximum length of the pin we can send to Integra. Minimum length of the pin is 4 by default. In Integra maximum length can be 6 and it depends on system number.
Exportable	bool	Required	The value indicates if cards shall be exported to this system in Integra. If this is false, none of the above configurations will be used.
CardNumberRange	string	Optional	The value indicates a number range for the card. If this configuration exists, then each card number exported to this system will be validated according to this range. If the card number is outside of the range, the card will not be exported to Integra. If this is not configured, all card numbers are deemed valid and will be exported to Integra.

Example

The following is an example of access token identifier mapping with Integra:

Id	Group	Key	system	value
6	export	idcSystemNumbers	Integra	default
7	export.idcSystemNumber-default	cardNumberIdentifierTypes	Integra	mifare
8	export.idcSystemNumber-default	maxCardNumberLength	Integra	6
9	export.idcSystemNumber-default	integraSystemNumber	Integra	1
10	export.idcSystemNumber-default	exportPin	Integra	TRUE
11	export.idcSystemNumber-default	maxPinLength	Integra	4
12	export.idcSystemNumber-default	Exportable	Integra	TRUE
13	export.idcSystemNumber-default	cardNumberRange	Integra	1-999999

The system will export all matching access token identifiers to all Integra systems where it gets a matching on cardNumberIdentifierTypes. In the example, if the access token contains a mifare identifier, then the data will be exported to the above system.

Configure Bravida Integra to allow deleting identities

When a cardholder is to be deleted in Integra, the service will attempt to just delete the cardholder immediately, without deleting the cards held by the cardholder first. By default, this is not allowed by Integra.

To allow this, configure Integra to either detach or delete cards automatically when the cardholder is deleted:

Open the Integra GUI.
Go to Alternativ > Inställningar and then to Objekt > Kortinnehavare > Radering.
Do either of the following settings:
1. To detach the cards, select “Frikoppla”.
2. To delete the cards, select “Tag bort”.

Bravida Integra 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 useradditionalfield in the database configuration.

User field mapping

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

SR No	Physical Access field (Web API)	Integra field (UI)
1	Id (Id)	ID (User ID Internal )
2	givenname (givenName)	FirstName (förnamn )
3	familyname (FamilyName)	lastName (efternamn)
4	Check Type Configuration and then map actual email Type(emails-type-value)	Emails (E-Post Address)
5	Ssn (SSN Birthdate Part)	Birthdate (Person Number first part)
6	Ssn (SSN ControlNo Part)	ControlNumber (Person Number second part)
7	Default Configuration for ParentFolderPath	ParentFolderPath (Directory in which User is exported)

Access token field mapping

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

SR No	Physical Access field (Web API)	Integra field (UI)
1	CardNumber (identifiers-type-value)	CardNumber (KortId)
2	Configuration Card Profile (identifiers-type-value)	CardSystemNumber (kortId)
3	USER-PIN(No Direct link)	PIN (PIN)
4	Card ValidFrom and ValidTo decide internally	CardStatus (Status)

Entitlement assignment field mapping

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

SR No	Physical Access field (Web API)	Integra field (UI)
1	assigneeid (assignee -value)	Card Holder ID (Selected User Name)
2	ExternalId (ExternalId)	AccessZoneId (AccessZone Id, not on UI)
3	DisplayName (entitlement-DisplayName)	Name (Namn)

Restart service

Restart the Bravida Integra connector service:
Restart Physical Access Bravida Integra connector
```
cd <SMARTIDHOME>/compose/physicalaccess
docker-compose restart smartid-pa-integra
```

Troubleshooting

If attempts by the service to delete cardholders in Integra fail with an error such as “Can’t delete Card Holder which have connected cards”, make sure Integra is configured as explained above.

This article is valid for Smart ID 21.04.1 and later.

Related information

Integrate physical access control system (PACS) with Identity Manager

Set up integration with Bravida Integra

Important licensing information

Prerequisites

Configure Integra Service data fields

[data-colorid=auv3xso8w2]{color:#333333} html[data-color-mode=dark] [data-colorid=auv3xso8w2]{color:#cccccc}[data-colorid=mad3nlxzpz]{color:#333333} html[data-color-mode=dark] [data-colorid=mad3nlxzpz]{color:#cccccc}group: messagingqueue

group: general

group: general

group: integra

group: export

group: export.idcSystemNumber-{index}

Example

User field mapping

Access token field mapping

Entitlement assignment field mapping

Restart service

Troubleshooting

Related information

group: messagingqueue