HelloID-Conn-SA-Sync-EntraID-Groupmemberships-To-SelfService-Productassignments

Synchronizes Entra ID groupmemberships to HelloID Self service productassignments

ℹ️ 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.

Table of Contents

• HelloID-Conn-SA-Sync-EntraID-Groupmemberships-To-SelfService-Productassignments
  • Table of Contents
  • Requirements
  • Introduction
  • Getting started
  • Getting started
    • Create an API key and secret for HelloID
    • Getting the Entra ID graph API access
      • Application Registration
      • Configuring App Permissions
      • Authentication and Authorization
    • Synchronization settings
  • Remarks
  • Getting help
  • HelloID Docs

Requirements

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

Introduction

By using this connector, you will have the ability to create and remove HelloID SelfService Productassignments based on groupmemberships in your Entra ID.

The products will be assigned to a user when they are already a member of the group that the product would make them member of. This way the product can be returned to revoke the groupmembership without having to first request all the products "you already have".

And vice versa for the removing of the productassignments. The products will be returned from a user when they are already no longer a member of the group that the product would make them member of. This way the product can be requested again without having to first return all the products "you already no longer have".

This is intended for scenarios where the groupmemberships are managed by other sources (e.g. manual actions or Provisioning) than the HelloID products to keep this in sync. This groupmembership sync is desinged to work in combination with the Entra ID Groups to Products Sync.

Getting started

Getting started

Create an API key and secret for HelloID

1. Go to the Manage portal > Security > API section.
2. Click on the Add Api key button to create a new API key.
3. Optionally, you can add a note that will describe the purpose of this API key
4. Optionally, you can restrict the IP addresses from which this API key can be used.
5. Click on the Save button to save the API key.
6. Go to the Manage portal > Automation > Variable library section and confim that the auto variables specified in the connection settings are available.

Getting the Entra ID graph API access

By using this connector you will have the ability to manage Entra ID Guest accounts.

Application Registration

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, and select “New Registration” (Entra Portal > Entra ID Directory > 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.

Configuring App Permissions

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

Authentication and Authorization

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 Directory > 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 Directory > 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 Active Directory > Overview.

Synchronization settings

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
$ProductSkuPrefix	String value of prefix filter of which HelloID Self service Products to include	Optional, when no SkuPrefix is provided ($ProductSkuPrefix = $null), all products will be queried
$PowerShellActionName	String value of name of the PowerShell action that grants the Entra ID user to the Entra ID group	The default value ("Add-EntraIDUserToEntraIDGroup") is set to match the value from the Entra ID Groups to Products Sync
$PowerShellActionVariableCorrelationProperty	String value of name of the property of HelloID Self service Product action variables to match to Entra ID Groups (name of the variable of the PowerShell action that contains the group)	The default value ("GroupId") is set to match the value from the Entra ID Groups to Products Sync, where Group is set as the variable name for the group for the Product actions. If your products are from a different source, change this accordingly (e.g. Group)
$entraIDGroupCorrelationProperty	String value of name of the property of Entra ID groups to match Groups in HelloID Self service Product actions (the group)	The default value ("id") is set to match the value from the Entra ID Groups to Products Sync, where the Entra ID group SamAccountName is set as the Group value for the Product actions. If your products are from a different source, change this accordingly (e.g. Name)
$entraIDUserCorrelationProperty	String value of name of the property of Entra ID users to match to HelloID users	The default value ("id") is set to match the value from the Entra ID Groups to Products Sync, where the Entra ID user ID is set to the HelloID User immutableId. If your users are from a different source, change this accordingly (e.g. userPrincipalName)
$helloIDUserCorrelationProperty	String value of name of the property of HelloID users to match to Entra ID users	The default value ("immutableId") is set to match the value from the Entra ID Sync, where the Entra ID user ID is set to the HelloID User immutableId. If your users are from a different source, change this accordingly (e.g. username)

Remarks

• The Productassignments are granted and revoked. Make sure your configuration is correct to avoid unwanted revokes
• This groupmembership sync is designed to work in combination with the Entra ID Groups to Products Sync. If your products are from a different source, this sync task might not work and needs changes accordingly.

Getting help

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

HelloID Docs

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