.png?version=1&modificationDate=1662974309327&cacheVersion=1&api=v2)
Installation Manual | IM-20220907-MB-01 iProtect Access / Security | Functionalities |  | PDF Download |
2. Publication
April 2022,
TKH Security
Paasheuvelweg 20
1105BJ Amsterdam
The Netherlands
Tel.: +31-20-4620700
This manual represents the knowledge at the above-mentioned time. TKH security works non-stop to improve her products. For the most recent technical information please contact your consultant or dealer.
3. Introduction
This document is the installation and operations manual for access on iProtect card readers using an Android or Apple mobile phone with BLE connection.
3.1 Token Authority
To have a secure encrypted connection between the card reader and the mobile phone, a cloud based Token Authority is used. The mobile phone and the card reader must be part of the same Token Authority in order to decrypt the communication between mobile phone and card reader. The iProtect system can support one token authority. How this must be configured, will be described in this manual.
4. Necessities
4.1 iProtect License
To activate Cosmos Access on the iProtect system a license is required:
Description | Supported from iProtect version | License number |
|---|---|---|
Cosmos Access system | 10.01.37 | 1700 |
External services | 10.01.37 | 47 |
4.2 Mobile phone apps
There are two mobile apps available for Cosmos Access. These app can be downloaded from Google Play for Android- and in the App Store for Apple devices.
APP | Description |
|---|---|
Cosmos Access | For everyday use. The app serves as a digital access card |
Cosmos Config | This app is for the system installers. It is used to assign and de-assign readers to the Cosmos Access Token Authority (TA) and make reader specific settings |
4.3 Settings to check and which are mandatory
Please check/set the following settings:
The iProtect server needs to have an internet connection (mandatory)
DNS settings needs to be set
The time settings should be set correctly. Use an NTP server.
Set the time zone settings of the system correctly
Port 443 is used to communicate with the Token Authority
Ping to a public IP address. A proper reply is needed!
4.4 Supported hardware and software
Hardware / Software | Description | From version |
iProtect | SMS | 10.01.37 |
Pluto | Reader manager | 05.03.39 |
Orion | Orion firmware | 1.05.18 |
ApolloN | Reader manager | 05.03.39 |
RIO | RIO firmware | Future |
Sirius iX-serie reader | Card reader firmware | 2.5.20 |
Protocol | Clock/Data | |
Wiegand | ||
RS485 |
5. Setup Cosmos Access
The chapter below describes the steps that are necessary within iProtect.
5.1 Configure the Card configuration (Step 1)
To create a Service / Database link within iProtect for theToken Authority Service, a card configuration is mandatory.
5.1.1 Card data interpretation group
To enable a combination of physical cards and mobile devices, a Card Data Interpretation Group is needed.
In iProtect, browse to menu: Access | Settings | Card coding | Card data interpretation group.
Right click in the search field and choose “add Card data interpretation group”:
Field | Content |
Name | Logical name, e.g Cosmos Access group |
5.1.2 Card number presentation
Card Number Presentation is needed to determine how to enter- or display the card number.
In iProtect, browse to menu: Access | Settings | Card coding | Card number presentation.
Right click in the search field and choose “add Card number presentation”:
Field | Content |
Name | Logical name, e.g Cosmos Access |
Format | Alpha numeric |
Calculated length: | 10 |
5.1.3 Card data interpretation
Card data interpretation is needed to determine how to interpret the data from the mobile devices.
In iProtect, browse to menu: Access | Settings | Card coding | Card data interpretation.
Right click on the “Card number presentation” that was just created and choose “add Card data interpretation”.
5.1.3.1 For Clock/data (ABA) and RS485 readers
Field | Content |
Name | Logical name, e.g Cosmos Access |
Default card data interpretation | 32 bit number DECIMAL, click “set” |
Card data interpretation group | Cosmos Access group |
Tab: Format | Data length: 18 |
Tab: Card | Start: 2 |
Length: 17 |
5.1.3.1 For Wiegand readers
Field | Content |
Name | Logical name, e.g Cosmos Access-WG |
Default card data interpretation | Wiegand 26, click “set” |
Card data interpretation group | Cosmos Access group |
Tab: Format | Data length: 66 |
Tab: System code | Start: 1 |
Length: 0 | |
Code: | |
Tab: Card number | Start: 6 |
Length: 60 | |
Modulo: | |
Tab: Parity | Left: Odd |
Right: Odd | |
Left start: 1 | |
Right start: 34 | |
Left length: 33 | |
Right length: 33 |
When both Wiegand, Clock/data (ABA) and/ or RS485 readers are used. In that case Implement both the interpretations under the presentation.
5.2 Configure the Service / database link (Step 2)
In iProtect, browse to menu: Installation | Settings | Services | Database link:
Right click in the search field and choose “add database link”
Field | Content | Description |
Name | Logical name. e.g Cosmos Access | |
Active | “checked” | |
Tenant ID | The tenant id received from TKH security | |
Client ID | The client id received from TKH security | |
Client Secret | The client secret received from TKH security | |
Time out (sec.) | Default 45 seconds, do not change unless adviced by TKH | Basic interval timer for multiple Token Authority processes. Change of this setting will cause a reboot of the Service. |
Auth Domain | The Identity provider received from TKH security | Default: //auth.eu.token-authority.com |
Main Domain | The Connection URL received from TKH security | Default: //eu.token-authority.com |
Card data interpretation | e.g. Cosmos Access | Select one of the Card data interpretations that are also grouped. See step 1. |
Poll rate (%) | Default 100%. TKH security can advise whether this setting should be changed | How does it work (examples):
|
5.3.2 Overall functional state
The functional state shows the connection with the Token Authority:
Functional state | Description | Description |
Service fully functional | System is running properly |
|
Service partly functional | System is not running properly | Service cannot connect with Token Authority |
iProtect cannot connect to the Service | ||
Service in calamity mode | It will recover automatically after some time (could be hours) | There is too much traffic between iProtect and the Token Authority. This can occur with bulk import or with too many pending requests such as assign/revoke invitations or tasks. |
Polling for status updates is postponed
| ||
Service not functional | There is no connection with the Token Authority |
|
5.3 Configure card reader for Cosmos Access (step 3)
We assume that a card reader is already implemented in the iProtect system and works with conventional “RFID” cards or tags.
5.3.1 Search the reader
Browse to menu: Installation | Hardware | Reader.
Select the reader you want to use with Cosmos Access.
Cosmos Access is only supported by IX readers and connected to a Pluto-Orion (RS485 or USB).
5.3.2 Activate Cosmos Access on the reader
The option to activate Cosmos Access will be available when a Card data interpretation is selected who is part of the Cosmos Access group, created in step 1.
After Cosmos Access is activated on a reader, additional options and status are displayed within minutes:
Entity state | Description | Description |
To be assigned | Reader needs to be added to the Token Authority and must be provided with a Cosmos Access token | Cosmos Config app required |
To be unassigned | The Cosmos Access token needs to be deleted from the reader and the Token Authority | Cosmos Config app required |
Assigned | Access can be granted by using a mobile device | Cosmos Access app required |
Bluetooth is by default 10 minutes activated on the reader after reboot.
When assigning a new reader, please reboot- OR present an installer card to the reader. After one of theses actions, you have 10 minutes time to assign the reader with the Cosmos Config app to the Token Autority.
5.3.3 Reader provisioner group (RS485 card reader only)
By enabling Cosmos Access on a reader, a new type of identification is activated.
The system must know what to do with the data and how to handle it when a mobile device is presented. This information is described in a Reader provisioner file and needs to be set by every reader.
The following provisioner group must be selected in the readerdialog, see table below:
Used (RFID) card technology | Provisioner group |
TKH default Mifare or Desfire | Use: Pluto SiriusIX MifareSec, Desfire and BLE (system default) |
UID 4 bytes (10 dec) | Use: Pluto SiriusIX Serial 10 digits and BLE (system default) |
UID 7 bytes (17 dec) | Use: Pluto SiriusIX Serial 17 digits and BLE (system default) |
5.3.4 App Interaction options
In basic there are two types of granting access to the reader when using the Cosmos Access app.
Selection | Description |
TScan & Go | Presenting the mobile device nearby the reader to get access |
Select & Go | Nearby readers can be selected and opened in the app at the touch of a button (e.g. like parking barriers) |
Besides the behavior, the use of the mobile device by a specific reader can be set:
Selection | Description |
All - In background | The mobile device does not need to be unlocked before it is presented to the reader. When opening the app nearby readers can be selected and opened in the app at the touch of a button |
Select & Go | Nearby readers can be selected and opened in the app at the touch of a button |
Scan & Go - In background | The mobile device does not need to be unlocked before it is presented to the reader. |
Scan & Go and Select & Go | Mobile device needs to be unlocked before presenting it to the reader. Select & Go can also be used for this reader. |
Scan & Go - Device unlocked | Mobile device needs to be unlocked before presenting it to the reader. Select & Go cannot be used for this reader. |
5.3.5 Assign a reader to the Token Authority
After Cosmos Access is activated on a reader, the reader needs to be assigned to the Token Authority by using the Cosmos Config app. These readers will have the entity state: “To be assigned”.
iProtect checks for status changes in the Token Authority to see if the reader has already been (un)assigned.
Time after (un)assigning | Description |
0 – 10 minutes | Every 45 seconds it will be checked |
10 min – 1 hour | Every 180 seconds it will be checked |
1 hour – to invinity | Every 300 seconds it will be checked |
To be able to (un)assign a reader with the Cosmos Config app to the Token Autority, a card with config rights needs to be created within iProtect.
Follow the instructions in the app to Assign the reader. The reader will be available on the assign list. After this action, the reader can be used for Cosmos Access.
5.3.6 Unassign a reader from the Token Authority
This action must be performed to remove the card reader from the Cosmos Access Token Authority, when the reader should not work with Cosmos Access anymore.
When the Cosmos Access checkbox is deactivated, the entity state at the reader becomes “To be unassigned”. The reader needs to be Unassigned using the Cosmos Config app.
Follow the instructions in the app to Unassign the reader. The reader will be available on the Unassign list.
After this action, the reader cannot be used anymore for Cosmos Access until it is assigned again.
5.3.7 Installer rights system user
A system user with installer right has more rights in iProtect. This gives the person more status fields but also has rights to remove a defective reader from the Token Authority.
In iProtect, browse to menu: Installation | Authorization | System user
Search the system user where the ‘Installer rights’ should be activated and enable this. After enabling, please log-out and log-in again.
What does the Installer gets more:
Dialog | Added | Description |
Card | Synchonization status |
|
Reader | Synchonization status |
|
Force remove button | When reader cannot be unassigned (broken), it will remove the reader from the Token Autority. Be aware! When doing this action and the reader will be re-used again for Cosmos Access, the reader must be sent back to TKH-Security. |
When a reader needs to assigned to a new system / Token Authority, unassign the reader from the Token Authority first. Now the reader can be assigned to any other system / Token Authority.
When a reader needs to be replaced, unassign the reader from the Token Authority first. After the reader is replaced it needs to be assigned to the Token Authority again.
Version > =10.03 When the reader has the status “To be (un)assinged” for longer than 48 hours, a reader event will be generated “Task timed out”.
6. Maintenance and statuses
This chapter describes the maintenance that can be performed on the Token Authority using iProtect.
6.1 Status of Cosmos Access cards
Browse to iProtect menu: Access | Overviews | Status | Card token authority status.
In this dialogue the status is shown of all Cosmos Access cards. It is possible to search for “Registered” (accepted invites) and “Not registered” (not accepted invites).
6.2 Status of Cosmos Access card readers
Browse to iProtect menu: Installation | Overviews | Status | Reader token authority status.
In this dialogue the status is shown of all Cosmos Access card readers. It is possible to search for “Registered” (Assigned readers) and “Not registered” (unassigned readers).
6.3 Debug logging Token Authority
In case debug logging is needed this can be activated in the database link dialogue
In iProtect, browse to menu: Installation | Settings | Services | Database link. Search and select the Cosmos access service. Click the button “Enable”.
The extensive logging will be enabled for 10 minutes. The log is written in the “Catalina” log file. The logfile can be read and downloaded in the iProtect maintenance page, dialogue: Logging | User interface.
6.4 Iconsistency between iProtect Cosmos Access readers and the Token authority readers
Inconsistency can occur in some situations, for example: an old iProtect backup is used where some readers where not assigned yet to the Token Authority. In that case, the Token Authority has assigned readers that do not have the assigned status in iProtect. This can be corrected.
In iProtect, browse to menu: Installation | Settings | Services | Database link. At the dialogue “Unknown readers in token authority” click “Fetch”, in the result screen readers that are in the Token Authority but not in the iProtect system will be shown. When selected they can be removed from the Token Authority.
When reader(s) needs to be assigned again to the Token Authority, this can be done as is described at the chapter “configuration”.
6.5 Rate limmeter
The number of messages from iProtect to the Token Autority is limited in number and time. The number of available messages is reported to iProtect. If the number of messages became lower than 5%, a rate limmeter will start do it’s function. When the limiter is active actions initiated by a user are still executed, there is are however no synchronization calls so statuses will not change. When after some time there is space again (>5%) the synchronization calls will be sent again. If the rate limiter starts, an event will be created in the iProtect log.