Document toolboxDocument toolbox

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

Set up integration with Security Shells iSecure for connection with HID controllers

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

This article is valid for Smart ID 21.04 and later.

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

iSecure is an Access Control System provided by Security Shells and managed by a GUI and the service interacts with iSecure through the web-based iSecure API. iSecure is used to integrate with all versions of the HID access controllers VertX and EDGE. After integration, all administration of Users, Access Token and Entitlements (besides defining them) should be done in Identity Manager, never in iSecure. 

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

Prerequisites

The following prerequisites apply:

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

  • iSecure S/W Version-E-A2.4-Unlimited CI - 60 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.

Limitations and constraints

The following limitations apply: 

  • In iSecure, only one card can be assigned per employee. If the Physical Access service finds more than one card to one employee which matches the configuration, then the old assigned card will be replaced with the new. 

  • Before a card can be assigned to an employee, it must be available in the iSecure system and must match the card format.
    → See the section Create Card in iSecure below.

  • The following employee fields in iSecure are required: Emp Code, Company, Location and Department. Emp Code shall contain any unique data from user records, other fields can either be static in the configuration or mapped as user additional fields.

Configure iSecure Service data fields

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

iSecureApi

string

Required

URL of the iSecure API for import and export details.

group: export

key

Data type

Required or Optional

Description

key

Data type

Required or Optional

Description

cardNumberIdentifier

string

Required

This setting defines which type of identifier to use for card number.

Default: “mifare”.

empCodeField

string

Required

This setting defines which field to use for unique identification of users. It can be configured as follows. 

Examples:

  • user.ssn

  • user.[column name of user table]

  • useradditionalfield.[Type of additional field]

companyName

string

Required

This setting defines the name of the company, which is mapped to the iSecure field Company.

If a different value is to be used, then it can be configured as follows:

Example: useradditionalfield.company

locationName

string

Required

This setting defines the name of the location, which is mapped to the iSecure field Location.

If a different value is to be used, then it can be configured as follows:

Example: useradditionalfield.location

department

string

Required

This setting defines the name of the department, which is mapped to the iSecure field Department.

If a different value is to be used, then it can be configured as follows:

Example: useradditionalfield.department

accessType

string

Required

This setting defines the way of access using Card Readers.

The following values are available:

  • "CardOrCardAndPin" (Default)

  • "CardOrPin"

  • "PinOnly"

cardFormat

string

Required

This setting specifies the available card format in the iSecure application. To not use any formatting, select “NoFormat”.

Default: “NoFormat”.

subDept

string

Optional

This setting defines the name of the sub-department, which is mapped to the iSecure field Sub-Dept.

If a different value is to be used, then it can be configured as follows:

Example: useradditionalfield.subdepartment

Example 

Example with static settings for company, location and department: 

Id

Group

Index

Key

System

Value

Id

Group

Index

Key

System

Value

1

general 

0

iSecureApi

ISecure

http://localhost/isecureapi/

2

export

0

cardNumberIdentifier

ISecure

mifare

3

export

0

empCodeField

ISecure

user.ssn

4

export

0

companyName

ISecure

Nexus

5

export

0

locationName

ISecure

Stockholm

6

export

0

department

ISecure

IT

7

export

0

accessType

ISecure

CardORCardAndPin

8

export

0

cardFormat

ISecure

NoFormat

Example with user additional fields for company, location and department: 

Id

Group

Index

Key

System

Value

Id

Group

Index

Key

System

Value

1

general 

0

iSecureApi

ISecure

http://localhost/isecureapi/

2

export

0

cardNumberIdentifier

ISecure

mifare

3

export

0

empCodeField

ISecure

user.ssn

4

export

0

companyName

ISecure

useradditionalfield.company

5

export

0

locationName

ISecure

useradditionalfield.location

6

export

0

department

ISecure

useradditionalfield.department

7

export

0

accessType

ISecure

CardORCardAndPin

8

export

0

cardFormat

ISecure

NoFormat

iSecure 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 iSecure service: 

SR No

Physical Access field (Web API)

iSecure field (UI)

SR No

Physical Access field (Web API)

iSecure field (UI)

1

Value configured under setting empCodeField

Emp Code

2

Combination of givenName and FamilyName

Name

3

Value configured under setting companyName

Company

4

Value configured under setting Location

Location

5

Value configured under setting Department

Department

6

Value configured under setting subDept

Sub-Dept

7

Status column of user table

Status

8

Address of user from Address table

Address

Access token field mapping

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

SR No

Physical Access field (Web API)

iSecure field (UI)

SR No

Physical Access field (Web API)

iSecure field (UI)

1

Value configured under setting cardNumberIdentifier

Card Number

2

Default Configuration for cardFormat

CardFormat

3

USER-PIN (No Direct link)

Pin column of user table

4

Default Configuration for accessType

AccessType

Entitlement assignment field mapping

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

SR No

Physical Access field (Web API)

iSecure field (UI)

SR No

Physical Access field (Web API)

iSecure field (UI)

1

assigneeid (assignee -value)

Emp Code

2

ExternalId (ExternalId)

Access Groups Id (Access Groups Id, not on UI)

3

DisplayName (entitlement-DisplayName)

Access Group (Namn)

Restart service

Restart the Security Shells iSecure connector service:

Restart Physical Access Security Shells iSecure connector

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

Create card in iSecure

Before assigning a card to an employee in Physical Access, the card must be created in iSecure.

To create a card, follow these steps: 

  1. Log in to the iSecure system: 

    Example: iSecure URL

    http://localhost/isecure/Login.aspx

  2. Go to Controller Setup Data > Card Inventory. Click on the + (Plus) button.

  3. Add the card number and select a card format.
    If the desired card format not available, then create the card format or select No Format. To create a card format, follow these steps:  

    1. Go to Controller Setup Data > Card Formats. Click on the + (Plus) button.

    2. Add a name of the card format and save it.



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