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.
- HelloID-Conn-Prov-Target-Zivver
HelloID-Conn-Prov-Target-Zivver is a target connector. Zivver provides secure communication solutions, primarily focused on email and file transfer. It offers a platform designed to protect sensitive information, such as personal data or confidential business data, from unauthorized access and interception.
SCIM stands for System for Cross-domain Identity Management. It is an open standard protocol that simplifies the management of user identities and related information across different systems and domains.
The HelloID connector uses the API endpoints listed in the table below.
| Endpoint | Description |
|---|---|
| /users | GET / POST / PATCH actions to read and write the user in Zivver |
| /groups | GET / PATCH actions to read and write functional accounts in Zivver |
Tip
For more information on the Zivver API, please refer to the Zivver website.
The following lifecycle events are available:
| Event | Description |
|---|---|
| create.ps1 | Create (or update) and correlate an account. Also, enable the account |
| enable.ps1 | Enable the account |
| update.ps1 | Update the account |
| disable.ps1 | Disable the account |
| delete.ps1 | Only disables the account. Deleting an account is not supported |
| grantPermission.ps1 | Grants permission to the account |
| revokePermission.ps1 | Revokes permission from the account |
| entitlements.ps1 | Retrieves all entitlements |
| configuration.json | Default configuration.json |
| fieldMapping.json | Default fieldMapping.json |
The purpose of this connector is to manage user account provisioning within Zivver.
In addition, the connector manages:
- Permissions / Named in Zivver: functional accounts
The following settings are required to connect to the API.
| Setting | Description | Mandatory | Example |
|---|---|---|---|
| BaseUrl | The URL to the API | Yes | https://app.zivver.com |
| Token | The bearer token to authenticate to the API | Yes | _ |
The correlation configuration is used to specify which properties will be used to match an existing account within Zivver to a person in HelloID.
To properly setup the correlation:
-
Open the
Correlationtab. -
Specify the following configuration:
| Setting | Value |
|---|---|
| Enable correlation | True |
| Person correlation field | `` |
| Account correlation field | userName |
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.
Note
Mapping a SCIM property like urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.division is not possible in the field mapping. For this reason, the field mapping is mapped in the Powershell account lifecycle scripts. When adding additional fields please keep in mind you have to enrich the mapping in the PowerShell scripts. Search for Change mapping here for all the mapping locations in the Powershell account lifecycle scripts.
Important
Granting and revoking groups is done by editing members after receiving the group members. For this reason, the concurrent actions need to be set to 1.
When HelloID sends too many requests it is possible to receive the error below.
Error:
{
"code": 429,
"message": "Too Many Requests",
"emptiedBucketDetails": {
"limiterId": "cab",
"budget": 50,
"windowSeconds": 10
},
"reference": "https://tools.ietf.org/html/draft-polli-ratelimit-headers-02"
}To use Single Sign On in Zivver the SsoAccountKey needs to be filled. In our experience implementing this, we learned that we needed to add the SsoAccountKey to every PUT call on the user to Zivver. This value is not returned by Zivver when using the GET call.
Important
Because Zivver doesn't return SsoAccountKey in the GET call. The connector doesn't know when to update this value. The connector now only updates this field when another value requires an update. Please keep this in mind while implementing this connector.
The HelloID connector is designed to manage the following properties of the user object:
name.formattedurn:ietf:params:scim:schemas:extension:enterprise:2.0:User.divisionurn:ietf:params:scim:schemas:zivver:0.1:User.SsoAccountKeyactiveuserName
❗ Properties not mentioned above, are not managed or handled by HelloID.
Zivver only supports the HTTP.PUT method for updating user accounts, requiring the entire user object to be included in each call. If a partial PUT is used without the SsoAccountKey the SSO in Zivver will break.
The Zivver user response is used and enriched with the necessary updates. This is how we ensure the entire user GET response is included in each PUT call.
The field mapping object division is mapped to a property called urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.division. If the division can't be found within Zivver, an error will be thrown (By Zivver). Error: Invalid division: {name of division}. As a result, the create/update lifecycle action will fail.
Tip
If you're not using division, map this field to the fixed value '/'. This is how Zivver returns an empty division so the Compare-Object keeps working in the script.
For more information on how to configure a HelloID PowerShell connector, please refer to our documentation pages
If you need help, feel free to ask questions on our forum
The official HelloID documentation can be found at: https://docs.helloid.com/