Important
This repository contains the connector and configuration code only. The implementer is responsible to acquire the connection details such as username, password, certificate, etc. You might even need to sign a contract or agreement with the supplier before implementing this connector. Please contact the client's application manager to coordinate the connector requirements.
| Note that this is a complex connector. Please contact your local Tools4ever sales representative for further information and details about the implementation of this connector |
| Note that this connector is "a work in progress" and therefore not ready to use in your production environment. |
- HelloID-Conn-Prov-Target-IProtect
- Table of contents
- Introduction
- Getting started
- Remarks
- AccessKeys Not Managed
- Employee and Person Account
- Correlation on FirstName and (Last) Name
- Uniqueness Check for Person Object (FirstName and (Last) Name)
- Enable and Disable Linked AccessKey
- Delete Account with Removed Linked AccessKeys
- Permission Grants and Revokes on AccessKeys
- SQL Queries
- Reboarding
- Development resources
- Getting help
- HelloID docs
HelloID-Conn-Prov-Target-IProtect is a target connector. IProtect provides a set of REST API's that allow you to programmatically interact with its data.
-
IProtect Permissions:
An IProtect account ("systeemgebruiker") must be created with sufficient rights to query and update the employees and AccessKeys Make sure that the box "Synchronisatie Beheerder" is checked in the "Detail Systeemgebruiker", and that the account has sufficient rights to query and update the IProtect database. -
To verify this: login into the web GUI of IProtect with this account and check: The ability to successfully query the accesskey, employee and user tables with this account
-
Local Agent:
The connector should be run from a local agent. -
Concurrent sessions:
Concurrent sessions in HelloID should be set to a maximum of 1! This is because a logout action may logout all connected sessions. -
SubPermissions:
-
Enable SubPermission to be able to see to which accessKeys the permissions are granted.
The following settings are required to connect to the API.
| Setting | Description | Mandatory |
|---|---|---|
| UserName | The UserName to connect to the API | Yes |
| Password | The Password to connect to the API | Yes |
| BaseUrl | The URL to the API ( https://<ip>:<port>/Webcontrols) |
Yes |
The correlation configuration is used to specify which properties will be used to match an existing account within IProtect to a person in HelloID.
| Setting | Value |
|---|---|
| Enable correlation | True |
| Person correlation field | ExternalId |
| Account correlation field | Employee.SalaryNR |
More information about
EmployeeandPersoncorrelation please refer to: Correlation on FirstName and (Last) Name
Tip
For more information on correlation, please refer to our correlation documentation pages.
The following lifecycle actions are available:
| Action | Description |
|---|---|
| create.ps1 | Creates a new person and employee account. |
| delete.ps1 | Removes an existing person and employee account, and removes the link of linked AccessKeys. |
| disable.ps1 | Disables an account, by disabling the linked AccessKeys. Sets the "VALID" property to false. |
| enable.ps1 | Enables an account, by enabling the linked AccessKeys. Sets the "VALID" property to true. |
| update.ps1 | Updates the attributes of a person and employee account. |
| UniquenessCheck.ps1 | Validate if the person combination FirstName and (last)Name is unique |
| permissions/groups/grantPermission.ps1 | Grants specific KeyGroup permissions to each Accesskey linked to the account. |
| permissions/groups/revokePermission.ps1 | Revokes specific KeyGroup permissions from each Accesskey linked to the account. |
| permissions/groups/permissions.ps1 | Retrieves all available keyGroups permissions. |
| configuration.json | Contains the connection settings and general configuration for the connector. |
| fieldMapping.json | Defines mappings between person fields and target system person account fields. |
The field mapping can be imported by using the fieldMapping.json file.
- The scope of the connector is to manage Persons and Employees, as well as perform grants, revokes, and enable or disable linked AccessKeys. However, managing AccessKeys—such as creating, updating, or linking them—is NOT in scope.
- This also means that when a person receives a new or additional AccessKey, the AccessKey must be manually enabled, and the permissions should be copied from the existing key.
- With one exception, the linked AccessKey will be removed from the account during the delete action. See Delete Account with Removed Linked AccessKeys.
Although this connector manages Employees, we cannot ignore the Person object. This is a separate object within IProtect. An Employee object cannot exist without a Person object; however, the reverse is possible. The field mapping is divided into Person and Employee properties, with the connector code handling the rest.
During correlation, the connector correlates based on the Employee.SalaryNR using a combined query to retrieve both the Person and Employee objects at once. Once this query returns a positive result, the account will be correlated. If no Employee is found, a separate query is performed to retrieve only the Person object based on FirstName and (Last) Name to avoid errors and duplicate accounts, and correlates the person account when one is found.
The uniqueness check ensures that the Person object is unique within the IProtect environment. The script validates the personTable for FirstName and (Last)Name. If an account is found, it checks whether an Employee account is linked. Only if an employee account is also found does the uniqueness check determine that the person object is NOT unique. If there is only a Person account without a linked Employee account, that Person account will be correlated.
- The Enable and Disable scripts grant and revoke the AccessKey linked to a user account in IProtect, but not the account itself. An Account object does not have an active property.
- The connector does not update newly assigned AccessKeys that are linked after "Account Access" has been granted.
- Before deleting the Person and Employee, the Delete action first unlinks all linked AccessKeys.
- By unlinking the AccessKey from the account. The connector does not remove unmanaged permissions from the AccessKey, which means, in theory, that the unlinked AccessKey may still contain permissions. Keep this in mind when linking a previously used AccessKey to a new account.
- If there are still unmanaged AccessKeys on the account, the deletion of the Person associated with the account may fail.
- KeyGroup permissions are granted or revoked on each linked AccessKey of the IProtect account.
- If no linked AccessKey is present during the permission granting process, the grant script will result in an error and retry until an AccessKey is linked.
- The connector does not update newly assigned AccessKeys after the permission has been granted.
- The best practice should be when a person receives a new AccessKey the granted permissions are copied for an existing Key.
- To apply permissions to newly linked AccessKeys with HelloID, you can place the grant script asan update script and manually run "Force update permissions in the definition."
- The connector largely consists of SQL queries that are sent to the IProtect endpoints. There are some restrictions compared to standard SQL, which can be found in the documentation.
- The linking key between the Employee and Person objects is the
PersonId.
Reboarding an employee after they are deleted from HelloID is supported, with one side note. AccessKeys are automatically unlinked from the account during the delete action and will not be present when the employee is recreated.
The following endpoints are used by the connector
| Endpoint | Description |
|---|---|
| /xmlsql | Session cookie and all sql calls |
| /j_security_check | Session login |
- "iProtect API v2.10.doc Description of the xmlsql api, used for generic sql queries and updates
- "Jdbc handleiding v0.3.pdf" Some info regarding the (limitations of) the supported sql
Tip
For more information on how to configure a HelloID PowerShell connector, please refer to our documentation pages.
Tip
If you need help, feel free to ask questions on our forum.
The official HelloID documentation can be found at: https://docs.helloid.com/