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

• Introduction

• Supported features

• Getting Started

  • Requirements
  • Connection Settings
  • Correlation Configuration
  • Field mapping
  • Remarks
    • Department Management
    • Permission Management
    • SCIM API Limitations
    • Manager Field in Field Mapping
  • Development resources
    • API endpoinst
    • Create a Provider in Zenya
  • Provisioning PowerShell V2 connector

• Getting help

• HelloID docs

Introduction

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.

Supported features

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

Getting Started

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.

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.

Connection settings

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.

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.

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.

Permission Management

• The current subpermission script manages only the goup membership changes that are initiated by Helloid. Manual changes are not detected.

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.

• 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 another SCIM provider in the system cannot be correlated.

Important

SCIM Identifier Conversion Required

Before implementing this connector, Zenya must perform a one-time operation to convert the SCIM identifiers of all existing users to the HelloID identity provider. This is essential to ensure that pre-existing user accounts can be managed by HelloID.

Contact the Zenya Hosting organization to request this conversion before attempting to correlate or manage existing users.

For user groups and memberships of user groups this conversion 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 the 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 in the permissions script cannot modify groups created with the SCIM interface.

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.

Development resources

API endpoints

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)

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.

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/