Synchronizes Entra ID groups to HelloID Self service products
| ℹ️ Information |
|---|
| 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. |
The requirements to run this connector, such as, an App Registration, to be run on-premises, run with concurrent sessions set to a max. of 1, etc. An example is given below:
- Make sure you have Windows PowerShell 5.1 installed on the server where the HelloID agent and Service Automation agent are running.
- App ID & App Secret for the app registration with permissions to the Microsoft Graph API.
- Make sure the sychronization is configured to meet your requirements.
- Setup synchronization of Entra ID or local AD users and groups to HelloID.
- This can be either the local AD sync or the Entra ID sync.
If using the local AD sync, make sure the userAttribute "userPrincipalName" is mapped and synced. Also make sure to change the $taskVariableUserValue accordingly.
By using this connector, you will have the ability to create and remove HelloID SelfService Products based on groups in your Entra ID.
The products will be create for each group in scope. This way you won't have to manually create a product for each group.
And vice versa for the removing of the products. The products will be removed (or disabled, based on your preference) when a group is nog longer in scope. This way no products will remain that "should no longer exist".
This is intended for scenarios where there are (lots of) groups that we want to be requestable as a product. This group sync is desinged to work in combination with the Entra ID Groupmembersips to Productassignments Sync.
- Go to the
Manage portal > Security > APIsection. - Click on the
Add Api keybutton to create a new API key. - Optionally, you can add a note that will describe the purpose of this API key
- Optionally, you can restrict the IP addresses from which this API key can be used.
- Click on the
Savebutton to save the API key. - Go to the
Manage portal > Automation > Variable librarysection and confim that the auto variables specified in the connection settings are available.
By using this connector you will have the ability to manage Entra ID Guest accounts.
The first step to connect to Graph API and make requests, is to register a new Entra ID Application. The application is used to connect to the API and to manage permissions.
- Navigate to App Registrations in Entra ID, and select “New Registration” (Entra Portal > Entra ID > App Registration > New Application Registration).
- Next, give the application a name. In this example we are using “HelloID PowerShell” as application name.
- Specify who can use this application (Accounts in this organizational directory only).
- Specify the Redirect URI. You can enter any url as a redirect URI value. In this example we used http://localhost because it doesn't have to resolve.
- Click the “Register” button to finally create your new application.
Some key items regarding the application are the Application ID (which is the Client ID), the Directory ID (which is the Tenant ID) and Client Secret.
The Microsoft Graph documentation provides details on which permission are required for each permission type.
To assign your application the right permissions, navigate to Entra Portal > Entra ID >App Registrations. Select the application we created before, and select “API Permissions” or “View API Permissions”. To assign a new permission to your application, click the “Add a permission” button. From the “Request API Permissions” screen click “Microsoft Graph”. For this connector the following permissions are used as Application permissions:
- Read and Write all user’s full profiles by using User.ReadWrite.All
- Read and Write all groups in an organization’s directory by using Group.ReadWrite.All
- Read and Write data to an organization’s directory by using Directory.ReadWrite.All
Some high-privilege permissions can be set to admin-restricted and require an administrators consent to be granted.
To grant admin consent to our application press the “Grant admin consent for TENANT” button.
There are multiple ways to authenticate to the Graph API with each has its own pros and cons, in this example we are using the Authorization Code grant type.
- First we need to get the Client ID, go to the Entra Portal > Entra ID > App Registrations.
- Select your application and copy the Application (client) ID value.
- After we have the Client ID we also have to create a Client Secret.
- From the Entra Portal, go to Entra ID > App Registrations.
- Select the application we have created before, and select "Certificates and Secrets".
- Under “Client Secrets” click on the “New Client Secret” button to create a new secret.
- Provide a logical name for your secret in the Description field, and select the expiration date for your secret.
- It's IMPORTANT to copy the newly generated client secret, because you cannot see the value anymore after you close the page.
- At last we need to get the Tenant ID. This can be found in the Entra Portal by going to Entra ID > Overview.
| Variable name | Description | Notes |
|---|---|---|
| $portalBaseUrl | String value of HelloID Base Url | (Default Global Variable) |
| $portalApiKey | String value of HelloID Api Key | (Default Global Variable) |
| $portalApiSecret | String value of HelloID Api Secret | (Default Global Variable) |
| $EntraTenantId | String value of Entra ID Tenant ID | Recommended to set as Global Variable |
| $EntraAppID | String value of Entra ID App ID | Recommended to set as Global Variable |
| $EntraAppSecret | String value of Entra ID App Secret | Recommended to set as Global Variable |
| $entraIDGroupsSearchFilter | String value of seachfilter of which Entra ID groups to include | Optional, when no filter is provided ($entraIDGroupsSearchFilter = $null), all groups will be queried - Only displayName and description are supported with the search filter. Reference: https://learn.microsoft.com/en-us/graph/search-query-parameter?tabs=http#using-search-on-directory-object-collections |
| $productAccessGroup | String value of which HelloID group will have access to the products | Optional, if not found, the product is created without Access Group |
| $calculateProductResourceOwnerPrefixSuffix | Boolean value of whether to check for a specific "owner" group in HelloID to use as resource owner for the products | Optional, can only be used when the "owner group" exists and is available in HelloID |
| $calculatedResourceOwnerGroupSource | String value of source of the groups in HelloID | Optional, if left empty, this will result in creation of a new group |
| $calculatedResourceOwnerGroupPrefix | String value of prefix to recognize the owner group | Optional, the owner group will be queried based on the group name and the specified prefix and suffix - if both left empty, this will result in creation of a new group - if group is not found, it will be created |
| $calculatedResourceOwnerGroupSuffix | String value of suffix to recognize the owner group | Optional, the owner group will be queried based on the group name and the specified prefix and suffix - if both left empty, this will result in creation of a new group - if group is not found, it will be created |
| $productResourceOwner | String value of which HelloID group to use as resource owner for the products | Optional, if empty the groupname will be: "local/[group displayname] Resource Owners" |
| $productApprovalWorkflowId | String value of HelloID Approval Workflow GUID to use for the products | Optional, if empty. The Default HelloID Workflow is used. If specified Workflow does not exist the task will fail |
| $productVisibility | String value of which Visbility to use for the products | Supported values: All, Resource Owner And Manager, Resource Owner, Disabled. For more information, see the HelloID Docs here |
| $productRequestCommentOption | String value of which Comment Option to use for the products | Supported values: Optional, Hidden, Required. For more information, see the HelloID Docs here |
| $productAllowMultipleRequests | Boolean value of whether to allow Multiple Requests for the products | If True, the product can be requested unlimited times |
| $productFaIcon | String value of which Font Awesome icon to use for the products | For more valid icon names, see the Font Awesome cheat sheet here |
| $productCategory | String value of which HelloID category will be used for the products | Required, must be an existing category if not found, the task will fail |
| $productReturnOnUserDisable | Boolean value of whether to set the option Return Product On User Disable for the products | For more information, see the HelloID Docs here |
| $removeProduct | Boolean value of whether to remove the products when they are no longer in scope | If set to $false, obsolete products will be disabled |
| $overwriteExistingProduct | Boolean value of whether to overwrite existing products in scope with the specified properties of this task | If True, existing product will be overwritten with the input from this script (e.g. the approval worklow or icon). Only use this when you actually changed the product input. Note: Actions are always overwritten, no compare takes place between the current actions and the actions this sync would set |
| $overwriteAccessGroup | Boolean value of whether to overwrite existing access groups in scope with the specified access group this task | Should be on false by default, only set this to true to overwrite product access group - Only meant for "manual" bulk update, not daily scheduled. Note: Access group is always overwritten, no compare takes place between the current access group and the access group this sync would set |
| $ProductSkuPrefix | String value of prefix that will be used in the Code for the products | Optional, but recommended, when no SkuPrefix is provided the products won't be recognizable as created by this task |
| $entraIDGroupUniqueProperty | String value of name of the property that is unique for the Entra ID groups and will be used in the Code for the products | The default value ("id") is set be as unique as possible |
- The Products are created and removed by default. Make sure your configuration is correct to avoid unwanted removals (and change this to disable)
- This group sync is desinged to work in combination with the Entra ID Groupmembersips to Productassignments Sync.
For more information on how to configure a HelloID PowerShell scheduled task, 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/