HelloID-Conn-Prov-Target-Microsoft-Entra-ID

[!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.

Table of contents

• HelloID-Conn-Prov-Target-Microsoft-Entra-ID
  • Table of contents
  • Requirements
  • Remarks
    • Account Creation Limitations
    • Supported Group Types
    • Managing Permissions in Teams
    • Creating Guest Accounts
    • Inviting Guest Accounts
    • Handling Null Values in Field Mapping
      • Example:
  • Introduction
  • Getting started
    • Provisioning PowerShell V2 connector
      • Correlation configuration
      • Field mapping
    • Connection settings
  • Connector setup
    • Application Registration
    • Configuring App Permissions
    • Authentication and Authorization
  • Getting help
  • HelloID docs

Requirements

1. HelloID Environment:
   • Set up your HelloID environment.
   • Install the HelloID Provisioning agent (cloud or on-prem).
2. Graph API Credentials:
   • Create an App Registration in Microsoft Entra ID.
   • Add API permissions for your app:
     • Application permissions:
       • User.ReadWrite.All: Read and write all user’s full profiles.
       • Group.ReadWrite.All: Read and write all groups in an organization’s directory.
       • GroupMember.ReadWrite.All: Read and write all group memberships.
       • UserAuthenticationMethod.ReadWrite.All: Read and write all users’ authentication methods.
       • User.Invite.All: Invite guest users to the organization.
       • User-Phone.ReadWrite.All: Read and write all user mobile phone and business phones.
   • Create access credentials for your app:
     • Create a client secret for your app.

Remarks

Account Creation Limitations

• The Graph API has limitations when creating accounts. As a result, accounts may be created without all attributes. Since the correlation value is mandatory, HelloID can correlate the account when retrying the action.

Supported Group Types

• The Microsoft Graph API exclusively supports Microsoft 365 and Security groups. Mail-enabled security groups and Distribution groups cannot be managed via this API. To manage these types of groups, use the Exchange Online connector.

Managing Permissions in Teams

• The script for dynamically managing permissions in Teams is similar to that for Groups, with an added filter for Teams-enabled groups. This is because a Team is inherently an M365 group, allowing us to manage its members within the group context rather than within Teams itself.

Creating Guest Accounts

• Direct creation of Microsoft Entra ID Guest accounts (with login names under the tenant domain) is preferred.
• By specifying the userType as ‘Guest’ in the mapping, Guest accounts with login names under the tenant domain can be created effortlessly.

Inviting Guest Accounts

• “Invite as Guest” is supported by using a separate targetconnector.
• Use the create-script and the fieldmapping from the guestInvite folder. The orginal config and other event scripts can be used from the original connector.
• Manager can be set of an invited guest but is not based on a managerreference. The manager is searched by the corresponding employeeid, cause mostly the managerreference is not available as a GuestInvited account.
• User credentials and e-mailaddress are based on an external e-mailaddress of the employee

Authentication Methods

• Granting and revoking email and phone authentication methods are supported.
• Chance mapping in the grantPermissions.ps1 according to the HelloID person model.
• Configure OnlySetWhenEmpty and RemoveWhenRevokingEntitlement settings in permissions.ps1 if needed.
  • Revoking authentication methods can give issues when the default method is revoking before others. This is the reason that our best practice is setting this value to $false.

Handling Null Values in Field Mapping

• The script filters out all field mappings with the value $null. If the value in the HelloID person model is $null, it is also filtered out. If this behavior is not desired, change the mapping to complex and ensure you return a string with a space or empty when the value is $null. This way, the value is correctly handled by the script.

Example:

function getCompanyName() {
  let companyName = Person.PrimaryContract.Employer.Name;
  if (companyName === null) {
    companyName = " ";
  }
  return companyName;
}
getCompanyName();

**

Limitations Without Exchange Online Connector

This connector is designed exclusively for Entra ID and does not integrate with Exchange Online. As a result, it has the following limitations compared to the built-in Azure AD connector:

ProxyAddress Expansion with Aliases

• It cannot expand ProxyAddress with additional aliases, which is crucial for managing multiple email addresses for a single user.

[!NOTE]
If the mail and userPrincipalName fields are different, the mail value will automatically become the primary SMTP address, and the userPrincipalName will be added as an alias.

Modifying showInAddressList

• It cannot modify the showInAddressList attribute, which determines whether a user appears in the global address list (GAL).

Mailbox Creation/Activation

• Mailboxes cannot be created or activated until a license is assigned, causing delays in email setup for new users.

Introduction

HelloID-Conn-Prov-Target-Microsoft-Entra-ID is a target connector. Microsoft provides a set of REST API’s that allow you to programmatically interact with its data. The Microsoft Entra ID connector uses the API endpoints listed in the table below.

The following lifecycle actions are available:

Getting started

By using this connector you will have the ability to seamlessly create and user accounts and groups in Microsoft Entra ID. Additionally, you can set the MFA phone or email settings.

Connecting to Microsoft the Microsoft Graph API is straightforward. Simply utilize the API Key and API Secret pair.
For further details, refer to the following pages in the Microsoft Docs:

• Use the Microsoft Graph API.
• User Properties.
• Supported User Properties for Correlation.

Provisioning PowerShell V2 connector

Correlation configuration

The correlation configuration is used to specify which properties will be used to match an existing account within Microsoft Entra ID to a person in HelloID.

To properly setup the correlation:

1. Open the Correlation tab.

2. Specify the following configuration:

   | Setting | Value |
   | ————————————- | —————— |
   | Enable correlation | True |
   | Person correlation field | ExternalId |
   | Account correlation field | employeeId |

[!IMPORTANT]
The account correlation field is added to the create action. If you use a different value then employeeId, please make sure this is support by the graph api

[!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.

Connection settings

The following settings are required to connect to the API.

Connector setup

Application Registration

The first step to connect to the Graph API and make requests is to register a new Microsoft Entra ID Application. This application will be used to connect to the API and manage permissions.

Follow these steps:

1. Navigate to App Registrations:

   • Go to the Microsoft Entra ID Portal.
   • Navigate to Microsoft Entra ID > App registrations.
   • Click on New registration.

2. Register the Application:

   • Name: Enter a name for your application (e.g., “HelloID PowerShell”).
   • Supported Account Types: Choose who can use this application (e.g., “Accounts in this organizational directory only”).
   • Redirect URI: Choose the platform as Web and enter a redirect URI (e.g., http://localhost).

3. Complete the Registration:

   • Click the Register button to create your new application.

For more detailed instructions, please see the official Microsoft documentation: Quickstart: Register an app in the Microsoft identity platform.

Configuring App Permissions

Next, configure the necessary API permissions for your Microsoft Entra ID application. For this connector, we use the Microsoft Graph API.

Follow these steps:

1. In your Microsoft Entra ID application, navigate to the API Permissions section.
2. Click on Add a permission.
3. Select Microsoft Graph.
4. Choose Application permissions and add the following:
   • User.ReadWrite.All: Read and write all user’s full profiles.
   • Group.ReadWrite.All: Read and write all groups in an organization’s directory.
   • GroupMember.ReadWrite.All: Read and write all group memberships.
   • UserAuthenticationMethod.ReadWrite.All: Read and write all users’ authentication methods.
   • User.Invite.All: Invite guest users to the organization.
5. Click Add permissions.
6. If required, click on Grant admin consent for [Your Tenant] to grant the necessary permissions.

For more detailed instructions, please see the official Microsoft documentation: Quickstart: Configure a client application to access a web API.

Authentication and Authorization

To authenticate to the Graph API using the Authorization Code grant type, you need to obtain the necessary credentials. We recommend using the Client secret.

Follow these steps:

1. Get the Tenant ID:

   • In the Microsoft Entra ID Portal, go to Azure Active Directory > Overview.
   • Copy the Tenant ID from the Overview page.

2. Get the Client ID:

   • Go to the Microsoft Entra ID Portal.
   • Navigate to Azure Active Directory > App registrations.
   • Select your application and copy the Application (client) ID value.

3. Create a Client Secret:

   • In the Microsoft Entra ID Portal, go to Azure Active Directory > App registrations.
   • Select the application you created earlier.
   • Navigate to Certificates & secrets.
   • Under Client secrets, click on New client secret.
   • Provide a description for your secret and select an expiration date.
   • Click Add and copy the newly generated client secret. Important: You cannot view the client secret value again after you close the page, so make sure to copy it immediately.

For more detailed instructions, please see the official Microsoft documentation: Add credentials.

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/