HelloID-Conn-Prov-Target-Zenya

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.

Table of Contents

• HelloID-Conn-Prov-Target-Zenya
  • Table of Contents
  • Requirements
  • Remarks
    • Department Management
    • SCIM API Limitations
    • Manager Field in Field Mapping
  • Introduction
    • Actions
  • Getting Started
    • Create a Provider in Zenya
    • Allowing Users and Groups Created by Zenya to Be Returned in the SCIM Service
    • Provisioning PowerShell V2 connector
      • Correlation Configuration
      • Field mapping
    • Connection Settings
  • Getting help
  • HelloID docs

Requirements

• 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.
  • Service Address
  • Client ID
  • Client Secret
• 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.

Remarks

Department Management

• 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.

SCIM API Limitations

• The Zenya SCIM API does not allow for setting or managing user passwords, so Single Sign-On (SSO) is required for user management.

• By default, the SCIM service only returns users and groups that were created by the identity provider or are linked to it. However, Infoland can enable a setting that allows users and groups created within Zenya to be included as well.

• This is particularly important if your users or groups come from multiple sources, such as Active Directory or Zenya itself. To ensure the SCIM service returns all relevant data—not just the users and groups synchronized through HelloID—contact Infoland to configure this setting properly.

• For more information, refer to step 7 in the Zenya documentation: Zenya Documentation.

Manager Field in Field Mapping

• The Manager field is optional and represents the manager's ID for the user. This field is read-only.

• Note: The Manager field 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.

Introduction

This connector allows you to update employee information in SDB HR. It is primarily used to write back the email address that HelloID generates for systems like Active Directory or Azure Active Directory.

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)
/scim/groups	Get groups (GET)
/scim/groups	Create group (POST)
/scim/groups/{id}	Update group (PATCH)

Actions

Action	Description	Comment
create.ps1	Create (or update) and correlate a user account
enable.ps1	Enable a user account
update.ps1	Update a user account
disable.ps1	Disable a user account
delete.ps1	Delete a user account	Be cautious; deleted users cannot be restored.
permissions.ps1	Retrieve all groups and provide them as entitlements
grantPermission.ps1	Add a user account to a group
revokePermission.ps1	Remove a user account from a group
subPermissions.ps1	Add/remove a user account to/from a group
resourceCreation.ps1	Create a group for a specified resource (e.g., department)

Getting Started

Create a Provider in Zenya

To start using the HelloID-Zenya connector, you first need to create a provider in Zenya. Follow these steps:

1. Access the Zenya Documentation:

   • Go to the Zenya Documentation.

2. 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.

Allowing Users and Groups Created by Zenya to Be Returned in the SCIM Service

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:

1. Contact Infoland:

   • Reach out to Infoland to request that the SCIM service returns all users and groups, not just those synchronized through the identity provider.

2. Enable SCIM Service Setting:

   • Ensure that the setting to include Zenya-created users and groups 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.

3. 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.

Provisioning PowerShell V2 connector

Correlation Configuration

The correlation configuration specifies which properties are used to match accounts in Zenya with users in HelloID.

To properly set up the correlation:

1. Open the Correlation tab.

2. Specify the following configuration:

   Setting	Value
   Person Correlation Field	UserName
   Account 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.

Field mapping

The field mapping can be imported by using the fieldMapping.json file.

Connection Settings

The following settings are required to connect to the Zenya SCIM API:

Setting	Description	Mandatory
Service Address	The URL of the SCIM API service.	Yes
Client ID	The OAuth2 Client ID used to authenticate with the SCIM API.	Yes
Client Secret	The OAuth2 Client Secret used to authenticate with the SCIM API.	Yes
Set Department in Zenya	When enabled, this setting will map and set the department value. Note: Only departments that already exist in Zenya can be assigned, and all department names must be unique. Department maintenance (creation, deletion, and owner assignment) must be done directly in Zenya.	No
Set Manager in Zenya	When enabled, this setting will map and set the manager value. Note: Only managers who exist in Zenya and were created by HelloID can be assigned. Ensure HelloID has granted the Account entitlement to the manager beforehand.	No
Toggle debug logging	Displays debug logging when toggled. Switch off in production	No

Getting help

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.

HelloID docs

The official HelloID documentation can be found at: https://docs.helloid.com/