Document toolboxDocument toolbox

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

Set up integration with Dorma Kaba Exos

Owned by Ann Base (Deactivated)
Last updated: Mar 01, 2024 by Ylva AnderssonVersion comment
7 min read

This article includes updates for Smart ID 23.10.4.

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

Kaba exos 9300 is an Access Control System provided by dormakaba and managed by a GUI and API to interact with Kaba exos 9300. After integration, all administration of Users, Access Token and Entitlements (besides defining them) should be done in Identity Manager, never in Kaba exos 9300.

Kaba exos 9300 have User Media (Layouts) and User Media (cards) Inventory. You must add User Media in Inventory first and then you can assign that to User.

There are applicability types (All, Invalid, Default, Transitional and Visitor) for Access tokens in Kaba exo 9300 and Default(All) applicability is used while adding access token in Inventory. Card Inventory can be managed through the 'Badge Management' menu available in Kaba exos 9300 application UI.

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

Prerequisites

The following prerequisites apply:

  • Physical Access and the Kaba exos 9300 Docker container/service are installed. See Deploy Smart ID.

  • The Kaba exos 9300 Service is currently using Dorma Kaba Open API version 3.0.0 and to interact with Kaba exos 9300.

  • Kaba exos 9300 Docker container/service supports Kaba exos 9300 product version > 4.2.2.

  • 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 Kaba exos 9300 Service data fields

The Kaba exos 9300 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

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 edit 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

key

Data type

Required or Optional

Description

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

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

key

Data type

Required or Optional

Description

updatesPerPoll

int

Optional

The maximum number of messages read from the message queue.

Default: 100

group: system

key

Data type

Required or Optional

Description

key

Data type

Required or Optional

Description

apiUrl

string

Required

API URL of Kaba exos Restful Service of Kaba exos 9300 service.

Default: https://kabaexos

apiKey

string

Required

API Key Identifier provided with Kaba exos Rest API.

Default: MyApiKey

username

string

Required

Username to login into Kaba exos Rest API

password

string

Required

Password to login into Kaba exos Rest API

tenantId

string

Required

Tenant Id for kaba exos system.

Default: 1

group: export

key

Data type

Required or Optional

Description

key

Data type

Required or Optional

Description

EntitlementType

string

Required

EntitlementTypeis used to set which type of access elements Physical Access should import.

Currently, these EntitlementType are supported:

  • Profile - If EntitlementType is set to Profile, only Profile type access element are imported to Physical Access.

  • ProfileCollection - If EntitlementType is set to ProfileCollection, only ProfileCollection type access element are imported to Physical Access.

  • ProfileSuperCollection - If EntitlementType is set to ProfileSuperCollection, only ProfileSuperCollection type access element are imported to Physical Access.

  • DoorGroup - If EntitlementType is set to DoorGroup, DoorGroup type access element's and TimeProfile type access element's are imported to Physical Access.

  • AccessGrid - If EntitlementType is set to AccessGrid, AccessGrid type access element's and TimeProfile type access element's are imported to Physical Access.

  • AccessGridDepot - If EntitlementType is set to AccessGridDepot, AccessGridDepot type access element's and TimeProfile type access element's are imported to Physical Access.

  • AccessGridParking - If EntitlementType is set to AccessGridParking, AccessGridParking type access element's and TimeProfile type access element's are imported to Physical Access.

  • ComponentStandalone - If EntitlementType is set to ComponentStandalone, ComponentStandalone type access element's and TimeProfile type access element's are imported to Physical Access.

To have support for both types, add it like “Profile,DoorGroup”.

layoutIdentifierType

string

Required

This is a type of identifier which we want to use to refer layout of access token.

userfieldmappings

string

Optional

The userfieldmappings is the combination of all additional fields that can be sent to Kaba exos 9300. Currently, these fields can be configured:

  • PhoneNumber

  • BirthDate

  • Sex

  • EMail

  • Text

  • Comment

  • Nationality

  • Street

  • City

  • Zipcode

  • Country

To export these fields to Kaba exos 9300, add this configuration:

The value in the configuration setting is a combination of table_name.value_of_type_column, property_name_of_cardholder. This configuration setting is the mapping between PA3 table field and Kaba exos 9300 person model properties.

User column fields are sent by adding configuration like user.column_name_of_user_table, property_name_of_kaba_person.

group: export.card.default

This group defines how to export card numbers by default, when a card’s layout does not have a specific mapping.

key

Data type

Required or Optional

Description

key

Data type

Required or Optional

Description

layout

string

Required

The default identifier type to read layout.

Default: Default

userMediaApplicationId

int

Required

Internal Id of user media Application.

Default: 1

cardNameIdentifier

string

Required

The default identifier type to read card numbers.

Default: mifare

mediaApplicationDefinitions

string

Required

Name of media Application definition.

Default: Identification (CID) (0000)

mediaApplicationDefinitionIds

int

Required

Internal Id of media Application definition.

Default: 1

applicationDefinitionValueIdentifiers

string

Required

The identifier type to read application Definition Value.

Default: mifare

format

string

Required

The format that the card number should be converted into before exporting it to Kaba Exos 9300.

Valid values: Hex, Dec.

Default: Dec

length

int

Required

The length that the card number should be padded (with leading zeroes) to after converting it.

Default: 6

group: export.card

This group contains compound configuration elements using the config_index column. For each unique config_index value in this group, each key defined below must be defined exactly once. Note that this group is not required as a whole, and should only be used if you have specific requirements for one or more card layouts. This entire section is Optional.

key

Data type

Required or Optional

Description

key

Data type

Required or Optional

Description

layout

string

Required

The default identifier type to read layout.

Default: Media2

userMediaApplicationId

int

Required

Internal Id of user media Application.

Default: 1

cardNameIdentifier

string

Required

The default identifier type to read card numbers.

Default: cardName

mediaApplicationDefinitions

string

Required

Comma separated list of Name's of media Application definitions.

Default: Kaba Group Header+ (KGH+) (0001),Unique number (UID),Kaba Group Header (KGH) (0002)

mediaApplicationDefinitionIds

int

Required

Comma separated list of Internal Id's of media Application definitions.

Default: 9,10,11

applicationDefinitionValueIdentifiers

string

Required

Comma separated list of the identifier type's to read application Definition Values.

Default: mifare,uid,mifare

format

string

Required

Comma separated list of the format's that the card number should be converted into before exporting it to Kaba Exos 9300.

Valid values: Hex, Dec.

Default: dec,dec,dec

length

int

Required

Comma separated list of the length's that the card number should be padded (with leading zeroes) to after converting it.

Default: 6,8,6

Kaba exos 9300 field mapping

The service mainly transfers user data including related access tokens and entitlement assignments. In the service, default fields can be sent and additional fields can be mapped using extra field mappings.

User field mapping

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

SR No

Physical Access field (Web API)

Kaba exos 9300 field (UI)

SR No

Physical Access field (Web API)

Kaba exos 9300 field (UI)

2

givenname (givenName)

Staff Data -> FirstName

3

familyname (FamilyName)

Staff Data -> lastName

5

userType (userType)

Internal -> PersonType

Access token field mapping

For access token field mapping, the ACCESSTOKEN and ACCESSTOKENIDENTIFIER tables from the Physical Access database are mapped to the Kaba exos 9300 service fields. All details are available under Person Record.

SR No

Physical Access field (Web API)

Kaba exos 9300 field (UI)

SR No

Physical Access field (Web API)

Kaba exos 9300 field (UI)

1

CardNumber (identifiers-type-value)

User Medium->Assigned

User Medium -> Column[BadgeId and BadgeName]

2

Access Token ValidTo decide internally

User Medium-> Assigned

User Medium -> Column[ValidTo]

3

Layout (identifiers-type-value)

User Medium→ Layout

Entitlement assignment field mapping

For entitlement assignment field mapping, the ENTITLEMENTASSIGNMENT table from the Physical Access database is mapped to the Kaba exos 9300 service fields. All details are available under Person Record.

SR No

Physical Access field (Web API)

Kaba exos 9300 field (UI)

SR No

Physical Access field (Web API)

Kaba exos 9300 field (UI)

1

DisplayName (entitlement-DisplayName)

Access Rights -> Name

2

EntitlementType

Access Rights -> Internal

Restart service

Restart the Kaba exos 9300 connector service:

Restart Physical Access Kaba exos 9300 connector
cd <SMARTIDHOME>/compose/physicalaccess docker-compose restart smartid-pa-kabaexos

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