Important
This repository contains only the connector and configuration code. The implementer is responsible for acquiring connection details such as the username, password, certificate, etc. You may also 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.
HelloID-Conn-Prov-Target-Zenya is a target connector. It utilizes a set of SCIM and REST API's That manages user accounts and user permissions in Zenya.
The following features are available:
| Feature | Supported | Actions | Remarks |
|---|---|---|---|
| Account Lifecycle | ✅ | Create, Update, Enable, Disable, Delete | |
| Permissions | ✅ | Retrieve, Grant, Revoke | Static and Dynamic |
| Resources | ✅ | Create | User Groups from contract departments |
| Entitlement Import: Accounts | ✅ | - | |
| Entitlement Import: Permissions | ✅ | - | |
| Governance Reconciliation Resolutions | ✅ | Disable, Delete |
-
SSO Configuration: Ensure SSO is configured in the Zenya environment.
-
Registered Provider in Zenya: Refer to the Zenya documentation for detailed instructions: Create Provider in Zenya.
When correlation of pre-existing accounts is required, make sure to contact the Zenya Hosting orginazation to move the relevant user account to this provider, prior of your correlation attempt, as only user accounts registered to the specific provider can be managed.
The following settings are required to connect to the API.
| Setting | Description | Mandatory |
|---|---|---|
| ScimBaseUrl | The SCIM BaseUrl of the SCIM endpoint | Yes |
| ScimClientId | The SCIM Client ID of the Provider for External User Management in Zenya | Yes |
| ScimClientSecret | The SCIM Client Secret of the Provider for External User Management in Zenya | Yes |
| SetDepartment | Checkbox to whether or not to set the department in Zenya | |
| SetManager | Checkbox to whether or not to set the manager in Zenya | |
| ApiBaseUrl | The REST BaseUrl to the API interface | Yes (when using permissions) |
| ApiClientId | The REST Client ID of the Registered API client | Yes (when using permissions) |
| ApiClientSecret | The REST Password to connect to the API | Yes (when using permissions) |
SCIM and API endpoints Zenya provides both a SCIM endpoint and a API endpoint. For technical reasons (see remarks section), both are required.
- Concurrent Sessions: Limit HelloID concurrent sessions to a maximum of 2 to avoid timeout errors, as the Zenya SCIM API has a rate limit on the number of requests per minute.
The correlation configuration specifies which properties are used to match accounts in Zenya with users in HelloID.
To properly set up the correlation:
-
Open the
Correlationtab. -
Specify the following configuration:
Setting Value Person Correlation Field UserNameAccount Correlation Field Username
Important
Currently, the Person Correlation Field (UserName) is not used in the correlation process. Only the Account Correlation Field (Username) is active because ExternalId cannot be queried via the SCIM API.
However, configuring the Person Correlation Field is advisable to prepare for future updates, such as the upcoming Governance Module. This module will require person-to-account mappings, so setting this field now helps ensure readiness for future features.
Ensure the Account Correlation Field is set to Username to align with the SCIM API's capabilities. Verify that your setup is supported by the SCIM API documentation.
Tip
For more information on correlation, please refer to our correlation documentation pages.
The field mapping can be imported by using the fieldMapping.json file.
- In Zenya, department names must be unique across the entire hierarchy. Matching is done based on the department name alone, so any duplicates, even in different parts of the structure, will cause issues.
- The current subpermission script manages only the goup membership changes that are initiated by Helloid. Manual changes are not detected.
-
The Zenya SCIM API does not allow for setting or managing user passwords, so Single Sign-On (SSO) is required for user management.
-
The SCIM service only returns users (and groups and other objects) that were created by the specific identity provider or are linked to it. This means that accounts that are already existing and created manually in zenya or with an other scim provided in the system cannot be correlated.
However, Infoland can perform an operation that allows users created within Zenya to be moved to the Identity provider you registerd for use in HelloId, So these users can be managed. It is adviced that this procedure is performed before creating any users in zenya with helloid.
For user groups and memberships of user groups this procedure cannot be used, as the groups themselves are not exclusively managed by the registered SCIM Provider. For this reason the group memberships are managed by means of the API interface, which does have access to the "normal" groups created with de Zenya Gui.
Note that this also means that the resource scripts that create groups need to use the API interface and not the SCIM interface, as the API interface used int de permissions script in cannot modify groups created with the SCIM interface.
- For more information, refer to step 7 in the Zenya documentation: Zenya Documentation.
-
The
Managerfield is optional and represents the manager's ID for the user. This field is read-only. -
Note: The
Managerfield uses a "None" mapping because the value is calculated within the scripts. We can only assign a manager who exists in Zenya and was created by HelloID. Before assigning a manager, HelloID must first grant the Account entitlement to the manager.
The following API endpoints are utilized by this connector:
| Endpoint | Description |
|---|---|
| /scim/users | Get users (GET) |
| /scim/users | Create user (POST) |
| /scim/users/{id} | Update user (PATCH) |
| /scim/users/{id} | Delete user (DELETE) |
| /api/user_groups | Get groups (GET) |
| /api/user_groups | Create group (POST) |
| /api/user_groups/{id} | Update group (PATCH) |
| /api/user_groups/members | Get group members (GET) |
To start using the HelloID-Zenya connector, you first need to create a provider in Zenya. Follow these steps:
-
Access the Zenya Documentation:
- Go to the Zenya Documentation.
-
Follow Step 3:
- Navigate to Step 3 in the documentation, which provides detailed instructions on how to create a provider in Zenya.
- Complete the setup by taking note of the required information, including the Service Address, Client ID, and Client Secret.
By default, the SCIM service only returns users and groups that were created by the identity provider or linked to it. However, you can configure Zenya to also return users and groups that were created within Zenya itself.
Follow these steps:
-
Contact Infoland:
- Reach out to Infoland to request that the SCIM service returns all users , not just those synchronized through the identity provider.
-
Enable SCIM Service Setting:
- Ensure that the setting to include Zenya-created users in the SCIM service is enabled. This is particularly important if your environment includes users and groups from multiple sources, such as Active Directory and Zenya itself.
-
Verify Configuration:
- After Infoland enables this setting, verify that all necessary users and groups are being returned by the SCIM service.
For more detailed information, refer to Step 7 of the Zenya Documentation.
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/