Skip to content

Commit 1cc0194

Browse files
rschouten97rschouten97
authored
Updated readme (#3)
1 parent 354588f commit 1cc0194

File tree

1 file changed

+77
-65
lines changed

1 file changed

+77
-65
lines changed

‎README.md‎

Lines changed: 77 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,103 @@
1-
| :information_source: Information |
2-
|:---------------------------|
3-
| 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. |
4-
<br />
1+
# HelloID-Conn-Prov-Target-Zenya
2+
Repository for HelloID Provisioning Target Connector to Zenya using the SCIM API
3+
4+
<a href="https://github.com/Tools4everBV/HelloID-Conn-Prov-Target-MicrosoftTeams-DirectRoutingPhonenumber/network/members"><img src="https://img.shields.io/github/forks/Tools4everBV/HelloID-Conn-Prov-Target-MicrosoftTeams-DirectRoutingPhonenumber" alt="Forks Badge"/></a>
5+
<a href="https://github.com/Tools4everBV/HelloID-Conn-Prov-Target-MicrosoftTeams-DirectRoutingPhonenumber/pulls"><img src="https://img.shields.io/github/issues-pr/Tools4everBV/HelloID-Conn-Prov-Target-MicrosoftTeams-DirectRoutingPhonenumber" alt="Pull Requests Badge"/></a>
6+
<a href="https://github.com/Tools4everBV/HelloID-Conn-Prov-Target-MicrosoftTeams-DirectRoutingPhonenumber/issues"><img src="https://img.shields.io/github/issues/Tools4everBV/HelloID-Conn-Prov-Target-MicrosoftTeams-DirectRoutingPhonenumber" alt="Issues Badge"/></a>
7+
<a href="https://github.com/Tools4everBV/HelloID-Conn-Prov-Target-MicrosoftTeams-DirectRoutingPhonenumber/graphs/contributors"><img alt="GitHub contributors" src="https://img.shields.io/github/contributors/Tools4everBV/HelloID-Conn-Prov-Target-MicrosoftTeams-DirectRoutingPhonenumber?color=2b9348"></a>
8+
9+
| :information_source: Information |
10+
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11+
| 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. |
512

613
<p align="center">
714
<img src="https://www.tools4ever.nl/connector-logos/zenya-logo.png">
815
</p
916
10-
## Versioning
11-
| Version | Description | Date |
12-
| - | - | - |
13-
| 1.1.3 | Added support to set title, manager and department | 2022/10/12 |
14-
| 1.1.2 | Updated with http error resolving | 2022/08/23 |
15-
| 1.1.1 | Updated with new logging | 2022/08/13 |
16-
| 1.1.0 | Updated with new logging and added group management | 2022/07/12 |
17-
| 1.0.0 | Initial release | 2020/08/06 |
18-
1917
<!-- TABLE OF CONTENTS -->
2018
## Table of Contents
21-
- [Versioning](#versioning)
22-
- [Table of Contents](#table-of-contents)
23-
- [Introduction](#introduction)
24-
- [Getting started](#getting-started)
25-
- [Connection settings](#connection-settings)
26-
- [Prerequisites](#prerequisites)
27-
- [Remarks](#remarks)
28-
- [Getting help](#getting-help)
29-
- [HelloID docs](#helloid-docs)
19+
- [HelloID-Conn-Prov-Target-Zenya](#helloid-conn-prov-target-zenya)
20+
- [Table of Contents](#table-of-contents)
21+
- [Requirements](#requirements)
22+
- [Introduction](#introduction)
23+
- [SCIM based API](#scim-based-api)
24+
- [Available actions](#available--actions)
25+
- [Getting started](#getting-started)
26+
- [Create Provider in Zenya](#create-provider-in-zenya)
27+
- [Allowing user and groups created by Zenya to be returned in the SCIM service](#allowing-user-and-groups-created-by-zenya-to-be-returned-in-the-scim-service)
28+
- [Connection settings](#connection-settings)
29+
- [Remarks](#remarks)
30+
- [Getting help](#getting-help)
31+
- [HelloID docs](#helloid-docs)
32+
33+
## Requirements
34+
- **SSO** configured on Zenya environment
35+
- Required to run **On-Premises** since it is not allowed to import a module with the Cloud Agent.
36+
- A **Registered Provider in Zenya**. Please see the Zenya Documentation (step 3) for the "How To": [Create Provider in Zenya](https://webshare.zenya.work/DocumentResource/709a648d-6300-4e42-a2a6-54ae02201873/Document.pdf?webshareid=y491fqpfwxhoo0kd&showinlinepdf=1).
37+
- Service Address
38+
- Client ID
39+
- Client Secret
3040

3141
## Introduction
32-
_HelloID-Conn-Prov-Target-Zenya is a _target_ connector. Zenya (formerly known as iProva) provides a set of API's that allow you to programmatically interact with it's data. The Zenya API is a scim (http://www.simplecloud.info) API. The HelloID connector allows you to create and manage Zenya accounts. Using entitlements it is possible to add account to groups.
33-
More information about supported API actions can be found on: https://identitymanagement.services.iprova.nl/swagger-ui/
42+
For this connector we have the option to create and manage Zenya user accounts and groups.
43+
44+
### SCIM based API
3445

35-
> Note that this connector is limited to the available functionalitiy of the SCIM API.
36-
- > We can only manage groups we actually created with HelloID. So only the groups we created through HelloID Resource Creation.
37-
- > Note that HelloID can __only create groups__. The groups will __not be deleted by HelloID__.
38-
- > We can only set a department that already exists in Zenya.
39-
- > For this, all departments must have a unique name (we can only match on name, so matching on code (or any other field) is not possible) within the entire tree (i.e., no duplicate names anywhere).
40-
- >In addition, maintenance of the departments (i.e., creating/deleting as well as setting the owner) will need to take place within Zenya.
41-
- > We can only set a manager that exists in Zenya and has been created by HelloID. For this, HelloID has to have granted the Account entitlement for the manager first.
42-
46+
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. For more information, please see: http://www.simplecloud.info
4347

44-
> Also please keep in mind that after you have created and tested the connector Infoland has to set the current users in scope of the synchronisation, if this is not done by Infoland every user will get a new account since accounts are connected to the connector.
48+
The HelloID connector uses the API endpoints listed in the table below.
4549

46-
> Since we user the SCIM API we cannot create/set the password of users, so SSO is required to manage the users using the SCIM API.
50+
| Endpoint | Description |
51+
| ------------ | ----------------------------------------------------------------------------------------------------------- |
52+
| /scim/users | API docs for Get Request: https://identitymanagement.services.iprova.nl/swagger-ui/#!/scim/GetUsersRequest |
53+
| /scim/groups | API docs for Get Request: https://identitymanagement.services.iprova.nl/swagger-ui/#!/scim/GetgroupsRequest |
4754

55+
### Available actions
4856
The HelloID connector consists of the template scripts shown in the following table.
4957

50-
| Action | Action(s) Performed | Comment |
51-
| ------------------------------- | --------------------------------------------- | --------- |
52-
| create.ps1 | Correlate or create Zenya user | |
53-
| update.ps1 | Update Zenya user | |
54-
| enable.ps1 | Enable Zenya user | |
55-
| disable.ps1 | Disable Zenya user | |
56-
| delete.ps1 | Delete Zenya user | Be careful when implementing this! There is no way to restore deleted users. |
57-
| resourceCreation.groups.departments.ps1 | Create Zenya groups for all departments in HelloID | This specific example uses the department objects as input. Please customize the script accordingly when using other input. |
58-
| permissions.groups.ps1 | Query the groups in Zenya | We can only query the groups in Zenya that HelloID has created. So creating the groups through Resource Creation is a requirement to manage the groups |
59-
| grantPermission.groups.ps1 | Grant a Zenya user to a Zenya group | We can only update the groups in Zenya that HelloID has created. So creating the groups through Resource Creation is a requirement to manage the groups |
60-
| revokePermission.groups.ps1 | Revoke a Zenya user to a Zenya group | We can only update the groups in Zenya that HelloID has created. So creating the groups through Resource Creation is a requirement to manage the groups |
58+
| Action | Action(s) Performed | Comment |
59+
| -------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
60+
| create.ps1 | Create (or update) and correlate a user account. | |
61+
| enable.ps1 | Enable a user account | |
62+
| update.ps1 | Update a user account | |
63+
| disable.ps1 | Disable a user account | |
64+
| delete.ps1 | Delete a user account | Be careful when implementing this! There is no way to restore deleted users. |
65+
| permissions.ps1 | Retrieves all groups and provides them as entitlements | |
66+
| grantPermission.ps1 | Add a user account to a group | |
67+
| revokePermission.ps1 | Remove a user account from a group | |
68+
| revokePermission.ps1 | Remove a user account from a group | |
69+
| resourceCreation.ps1 | Create a group for provided resource, e.g. department | |
6170

6271
<!-- GETTING STARTED -->
6372
## Getting started
73+
74+
### Create Provider in Zenya
75+
Please follow the Zenya Documentation (step 3) to [Create a Provider in Zenya](https://webshare.zenya.work/DocumentResource/709a648d-6300-4e42-a2a6-54ae02201873/Document.pdf?webshareid=y491fqpfwxhoo0kd&showinlinepdf=1)
76+
77+
### Allowing user and groups created by Zenya to be returned in the SCIM service
78+
By default, ONLY groups and users created by the identity provider or linked to it are returned in the SCIM service. However, there is a setting that Infoland can enable per provider, allowing the users and groups created by Zenya to be returned as well. If users/groups come from multiple sources (ADs, created within Zenya itself), please contact Infoland to ensure that the SCIM service returns everything, not just the users/groups synchronized through this process.
79+
For more information, please see (step 7): https://webshare.zenya.work/DocumentResource/709a648d-6300-4e42-a2a6-54ae02201873/Document.pdf?webshareid=y491fqpfwxhoo0kd&showinlinepdf=1
80+
6481
### Connection settings
6582
The following settings are required to connect to the API.
6683

67-
| Setting | Description | Mandatory |
68-
| --------------------- | ----------------------------------------------------------------- | ----------- |
69-
| Service Address | The Service Address of the SCIM API | Yes |
70-
| Client ID | The OAuth2 Client ID to connect to the SCIM API | Yes |
71-
| Client Secret | The OAuth2 Client Secret to connect to the SCIM API | Yes |
72-
| Toggle debug logging | When toggled, extra logging is shown. Note that this is only meant for debugging, please switch this off when in production. | No |
73-
74-
### Prerequisites
75-
- Zenya environment
76-
- SSO for Zenya environment
77-
- Registered Provider in Zenya. Please see the Zenya Documentation (step 3) for the "How To": [Create Provider in Zenya](https://webshare.zenya.work/DocumentResource/709a648d-6300-4e42-a2a6-54ae02201873/Document.pdf?webshareid=y491fqpfwxhoo0kd&showinlinepdf=1). The following values are needed to connect
78-
- Service Address
79-
- Client ID
80-
- Client Secret
84+
| Setting | Description | Mandatory |
85+
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------- |
86+
| Service Address | The Service Address of the SCIM API | Yes |
87+
| Client ID | The OAuth2 Client ID to connect to the SCIM API | Yes |
88+
| Client Secret | The OAuth2 Client Secret to connect to the SCIM API | Yes |
89+
| Toggle debug logging | When toggled, extra logging is shown. Note that this is only meant for debugging, please switch this off when in production. | No |
90+
8191

8292
### Remarks
83-
- > We can only manage groups we actually created with HelloID. So only the groups we created through HelloID Resource Creation.
84-
- > Note that HelloID can __only create groups__. The groups will __not be deleted by HelloID__.
85-
- > We can only set a department that already exists in Zenya.
86-
- > For this, all departments must have a unique name (we can only match on name, so matching on code (or any other field) is not possible) within the entire tree (i.e., no duplicate names anywhere).
87-
- >In addition, maintenance of the departments (i.e., creating/deleting as well as setting the owner) will need to take place within Zenya.
88-
- > We can only set a manager that exists in Zenya and has been created by HelloID. For this, HelloID has to have granted the Account entitlement for the manager first.
93+
- Infoland must define the current users within the synchronization scope. Failure to do so will result in every person being assigned a new user account.
94+
- Since we use the SCIM API, we cannot create/set the password of users, so Single Sign-On (SSO) is required to manage the users using the SCIM API.
95+
- Currently, we can only manage groups we actually created with HelloID. So only the groups we created through HelloID Resource Creation.
96+
- Note that HelloID can only create groups. The groups will not be deleted by HelloID.
97+
- Currently, we can only set a department that already exists in Zenya.
98+
- For this, all departments must have a unique name (we can only match on name, so matching on code or any other field is not possible) within the entire tree (i.e., no duplicate names anywhere).
99+
- In addition, maintenance of the departments (i.e., creating/deleting as well as setting the owner) will need to take place within Zenya.
100+
- Currently, we can only set a manager that exists in Zenya and has been created by HelloID. For this, HelloID has to have granted the Account entitlement for the manager first.
89101

90102
## Getting help
91103
> _For more information on how to configure a HelloID PowerShell connector, please refer to our [documentation](https://docs.helloid.com/hc/en-us/articles/360012558020-Configure-a-custom-PowerShell-target-system) pages_

0 commit comments

Comments
 (0)