Customer instructions can be found from here.

Steps in that guidance must be taken before Microsoft Graph API Connector can be fully configured.

In this chapter is described configuration instructions for Entra connector to be able connect to customers Entra ID. 

For configuring provisioning , you will need access to Efecte Platform configuration console.

Prerequisites: 
Install Microsoft related certificates: https://docs.efecte.com/internal-configuration-instructions/install-ad-certificates-for-efecte-provisioning-engine

1. Open the Efecte Administration area (a gear symbol).
2. Open Connectors view.
3. Choose New connector 

4. Select Data Source type to be Microsoft Entra

5. Give name for the connector and add Entra connection settings:

• Connector name - give your connector a friendly name (name can be changed afterwards)
• Application (client) ID - GUID object of the client application in Microsoft Entra console
• Directory (tenant) ID - GUID object of the Microsoft Entra tenant
• Login URL - Custom domain name of the Microsoft Entra tenant
• Graph API URL - Usually set to 'https://graph.microsoft.com',editable for custom reasons

6. Fill in authentication method

• Secret - fill in secret key value. Value for secret key is copied from Microsoft Entra portal
• Certificate - download the alias name of the public name of the key used in Microsoft Entra certificate login
  
  
   

7. Fulfill WebAPI user information

• WebAPI user - select correct WebAPI user which is used when writing data from customers AD to customers Efecte solution
• WebAPI password - password for the WebAPI user

8. Save connector information

• Press test connection to validate that connection information is set correctly
  
  

9. Customers Efecte solution is now able to connect to customers Entra ID

• Next step is to configure scheduled task for data read or event task for data writing. 

Entra connector is used for to read user and group information from Customers Entra Directory and it is configured from Efecte Service Management platform by creating scheduled-based provisioning task.   

How to create new task for Scheduled Provisioning

For configuring scheduled-based provisioning task, you will need access to Efecte Platform configuration console.

Note! If connector is not created, you have to create first “new connector” and after that you are able to create new tasks.

1. Open the Efecte Platform configuration view (a gear symbol).
2. Open Connectors view.
3. Choose connector for which scheduled-based task is configured
4. Select new task under the correct connector

5. Define scheduling for the task (if and how scheduled task should be run periodically). Choose scheduling sequence, which depends how much data is read to customers Efecte solution.

Recommended scheduling sequence, depends how much data is read from customers directory to the Efecte solution and is import partial or full load. 

Example scheduling for reading groups and user accounts. 

5.  Fill in task details

• Fill in unique task name for the scheduled-based task
• Task usage indicated that is the task used for reading data, writing data or to authentication. Note that If event type is changed afterwards it can break the workflows.
• Mappings type depends what type of information is read from the directory
  • Identity and access rights - are used when user account and group information is read from the directory
  • Single (identity only) - are used when only user account information is read from the directory
  • Single (access right only) - are used when only group information is read from the directory
  • Generic (one template) - are used when a generic information is read from the directory, usually other than Users/Groups

Fill in filtering details

• Fetch data
  • Full - all information is read according to defined filtering
  • Incremental - only changed information is delivered to Efecte solution
• Import users parameter - Additional Graph API query filter applied when Users are being extracted.
• Import groups parameter - Additional Graph API query filter applied when Groups are being extracted. More info about filters in chapter Graph API filters & testing
• Microsoft Entra query - Graph API query filter applied when Generic objects are being extracted. More info about filters in chapter Graph API filters & testing
• Query headers - Custom headers added to final query during Users / Groups / other data extraction. 
  EPE adds these headers automatically, so no need to explicitly add these:
  “Content-Type”, “application/json”
"Authorization", “Bearer token”
"Accept", “application/json”
  
   More info about filters in chapter Graph API import and filters

• Excluded Users - Users to be excluded from import to ESM. Object IDs of the Users to exclude (separated by newlines)
• Excluded Groups - Groups to be excluded from import to ESM. Object IDs of the Groups to exclude (separated by newlines)
• Import users based on group-memberships - Allows to define lists of the Groups based on which Users will be included or excluded into the final result set

Fill in failure information

Optional settings for failure handling, if scheduled task fails it can create data card to Efecte ESM that displays the error. If failure settings are defined , the administrator does not need to manually check the status of scheduled tasks.

• Failure template - Select a Template of datacard which will be created in case of any errors during provisioning (connection to data sources,timeouts,etc.)
• Failure folder - Select folder where failure data card is stored.
• Failure attribute - Select an attribute where in the Failure Template should the error information be stored in. Select text type attribute.
   

Example of IGA admin task, which also can contain instructions how to solve the issues,

6. Fill in identity mappings

Users are imported to IGA Account template and it is mandatory to set Target folder, datasourceid and unique values which are used for identifying users between customers Entra Directory and Efecte solution. 

• Target template - Select a template to define attribute mappings
• Target folder - Select a folder from a list of folders. The list is narrowed down to match compatibility with selected Template.

• Data Source Type mapping - optional. If it is set, it writes connectors type to that attribute.
• Task Id mapping - Task id number is written to this attribute.
• Set value to datacard fo object deleted from source system - This functionality is activated by setting checkbox on. When someobject that was previously read from 3rd party system to solution is deleted from 3rd party system (meaning this task query doesn't return it anymore). This scheduled task notices thatis was deleted and marks that datacard selected attribute with value you want. This can be for example used to set Status attribute to Deleted (as shown in below example screenshot). This functionality functions only for task type Full not for Incremental.

• Attribute mappings
  1. External attribute - which attribute from the directory is mapped to Efecte
  2. Local attribute - to which attribute in Efecte directory attribute is mapped to.

7. Adding additional attributes

It is possible to set additional attributes, which are read from user accounts in Entra ID, by choosing New attribute

8. Fill in Access Rights Mappings

Groups are read to IGA Entitlement template and it is mandatory to set target folder, datasourceid and unique values which are used for identifying users between customers Entra directory and Efecte solution.

• Target template - Select a template to define attribute mappings
• Target folder - Select a folder from a list of folders. The list is narrowed down to match compatibility with selected Template.

• Data Source Type mapping - optional. If it is set, it writes connectors type to that attribute.
• Task Id mapping - Task id number is written to this attribute.
• Set value to datacard fo object deleted from source system - This functionality is activated by setting checkbox on. When someobject that was previously read from 3rd party system to solution is deleted from 3rd party system (meaning this task query doesn't return it anymore). This scheduled task notices thatis was deleted and marks that datacard selected attribute with value you want. This can be for example used to set Status attribute to Deleted (as shown in below example screenshot). This functionality functions only for task type Full not for Incremental.

• Attribute mappings
  1. External attribute - which attribute from the directory is mapped to Efecte
  2. Local attribute - to which attribute in Efecte directory attribute is mapped to.
• It is possible to set additional attributes, which are read from user accounts in directory, by choosing New attribute

9. Nested groups mapping
If you want to fetch nested group information (group membership of other group) from Entra ID, you can do it with memberOf attribute on Access Rights Mappings.

Right side is from Entra ID, and right side is from M42 Pro/IGA solution:

10. Mappings for generic template

Generic data is read to any template user wants and it is mandatory to set target folder, datasourceid and unique values which are used for identifying data between customers Entra Directory and Efecte solution.

• Target template - Select a template to define attribute mappings
• Target folder - Select a folder from a list of folders. The list is narrowed down to match compatibility with selected Template.

• Data Source Type mapping - optional. If it is set, it writes connectors type to that attribute.
• Task Id mapping - Task id number is written to this attribute.
• Set value to datacard fo object deleted from source system - This functionality is activated by setting checkbox on. When someobject that was previously read from 3rd party system to solution is deleted from 3rd party system (meaning this task query doesn't return it anymore). This scheduled task notices thatis was deleted and marks that datacard selected attribute with value you want. This can be for example used to set Status attribute to Deleted (as shown in below example screenshot). This functionality functions only for task type Full not for Incremental.

• Attribute mappings
  1. External attribute - which attribute from the directory is mapped to Efecte
  2. Local attribute - to which attribute in Efecte directory attribute is mapped to.
• It is possible to set additional attributes, which are read from user accounts in directory, by choosing New attribute

11. Save task

Save provisioning task from the Save button. If some required attributes are missing the save button is displayed as grey and it will display what is missing from the settings.

You have now configured scheduled-based connector task for Entra ID data read

• You can now wait until task is started based on scheduling or
• Run task manually - by clicking the button task is configured to be scheduled to start immediately. Usually for test runs or if you don't want to change the schedule settings, but want to run the task now.   

Example of manual task run starting message:

If task is executed manually (run task) or it is run according to scheduling, task status can be reviewed from View history.

Event task is used when writing data towards customers Azure / Entra ID. These Provisioning Engine capabilities for accounts, groups and permissions are available only for Matrix42 IGA solution and IGA license is required if these are used. 

All configuration related to Provisioning Engine and event-based provisioning task are configured in Matrix42 Core, Pro and IGA platform.

1. Open the Efecte Platform configuration view (a gear symbol).
2. Open connectors view
3. Choose connector, which will use the event task
4. Select  “new task” under correct connector

4. Fill in task details

• Task name - Give name name for the task, it will be displayed in connectors view.
  • It is good practice to name a task in a way that describes its purpose for example [Template name]:[Activity] IGA Service request:Verify user
• Task usage indicated that is the task used for reading data or writing data. Can be changed afterwards, but it's not recommended if event task is in use. It will break workflows.
• Mappings type depends what type of information is read from the directory, identity mappings selections are displayed based on this setting.
  • Identity and access rights - are used when user account and group information is read from the directory
  • Single (identity only) - is used when only user account information is read from the directory
  • Single (access right only) - is used when only group information is read from the directory
  • Generic (one template) - is used when generic information is read from the directory. Usually some other data than user or group information. 

Warning about changing task usage or mappings type when event task in use:

5. Fill in security information 

This information is needed if user creation process in workflow is attached to the task.

• Password for first login - Default password that is the same for all users,random password is generated in workflow,and it's usually unique.
  • Default password / type in the box below
    • Default password - Type default password that is same for all users and matches to directory requirements for the password. Note that number of characters doesn't represent actual length of the password
    • It is not recommended to use same default password for all new accounts in production environment
  • Random password / generate in the workflow
    • Generated password 

Fill in filtering details

• Import users parameter - Additional Graph API query filter applied when Users are being extracted.
• Import groups parameter - Additional Graph API query filter applied when Groups are being extracted. More info about filters in chapter Graph API filters & testing
• Microsoft Entra query - Graph API query filter applied when Generic objects are being extracted. More info about filters in chapter Graph API filters & testing
• Query headers - Custom headers added to final query during Users / Groups extraction.
   More info about filters in chapter Graph API filters & testing
• Date Attribute formatter - used to format dates, when provisioning date type attribute to target system. You can select format from list or add your own custom format. Right side field shows example of formatted date.
• DateTime Attribute formatter - used to format datetimes, when provisioning datetime type attribute to target system. You can select format from list or add your own custom format. Right side field shows example of formatted datetime.

6. Define identity mappings

• Target template - Select a template to define attribute mappings
• Target folder - Select a folder from a list of folders. The list is narrowed down to match compatibility with selected Template.
• Attribute mappings
  1. External attribute - which attribute from the directory/system is mapped
  2. Local attribute - to which attribute in template attribute is mapped to
• Add new attribute -  It is possible to set additional attributes, which are read from user accounts in Entra Directory, by choosing New attribute button.

7. Define access right mappings

• Target template - Select a template to define access rights mappings
• Target folder - Select a folder from a list of folders. The list is narrowed down to match compatibility with selected Template.
• Attribute mappings
  1. External attribute - which attribute from the directory/system is mapped
  2. Local attribute - to which attribute in template attribute is mapped to
• Add new attribute -  It is possible to set additional attributes, which are read from groups in Entra Directory, by choosing New attribute button.

8. Define generic mappings

• Target template - Select a template to define attribute mappings
• Target folder - Select a folder from a list of folders. The list is narrowed down to match compatibility with selected Template.
• Attribute mappings
  1. External attribute - which attribute from the directory/system is mapped
  2. Local attribute - to which attribute in template attribute is mapped to
• Add new attribute -  It is possible to set additional attributes, which are read from Azure / Entra Directory, by choosing New attribute button.

8. Save provisioning task from “save” button

If any mandatory information is missing, you are not able to save the task and save button will show missing information. 

9. The next step is to configure the workflow Orchestration node to use this event-based task. From workflow engine in Platform, it is possible to execute provisioning activities towards customer directory services. This means that any of the available orchestration nodes activity can be run at any point of the workflow.

Workflow references are shown in the connector overview page:

Note: Versions older than 2025.2 doesn't sync authentication tasks to Secure Access (ESA), so in those environments don't create authentication task according to this guidance, instead,configure authentication directly using Secure Access (ESA) Admin portal. Follow Efecte Secure Access configuration instructions according to required authentication method.

Authentication task is needed when customers Entra ID is used for authenticating users to customers Efecte solutions. 

There are two options to create a new authentication task. Option one is to copy existing provisioning task into authentication task, if authentication method is using same settings. Option two is to create new authentication task. 

Option 1: Create new Authentication task from provisioning task

1. Open the Administration area (gear symbol) 
2. Choose Connectors tab, copy desired task from Clone button

3. Give name for the new Authentication task and change task usage to be Authentication

4. Fill in the required fields and save the task
 

Option 2: Create new Authentication task

1. Open the Administration area (gear symbol) 
2. Choose Connectors module
3. Choose Authentication tab
4. Choose connector and Create New Task

5. Give name to your authentication task
6. Select task usage to be authentication
7. Define filters for users 
8. Define filter for groups

9. Select Auth protocol for the authentication - SAML2 or OpenID

10. Select Authentication realm. 

• Realm for which authentication configuration will be created in ESA

11. Save task and run ESA Sync

• Syncing information will automatically fulfill configuration in Efecte Secure Access

Filtering users

Filter name: Import Users Parameter
This filter is set to import user, based on entered parameters (like for example $filter=startswith givenName, 'J'). There can be several parameters, which are used together.

Examples

The following example finds users who have an email that ends with “@efecte.com"

The following example finds users who are in a department that starts with the word “IT-Service" 

The following example finds users who have a display name that starts with the word “TEST”

The following example finds users who are not in company called Efecte

The following example finds user that are not in Active Directory but are members in Entra tenant

The following example finds user who have an email  tuija.itasalmi@efecte.com

The following example finds users which has 'standard' authentication type in extension attribute extension_824667ba11b6468baf6ac13ac3c62c81_AuthenticationType and accounts are titled as internal or external in extension attribute extension_824667ba11b6468baf6ac13ac3c62c81_AccountType

The following example finds users which has mail

The following example finds users that are enabled

Filtering groups 

Filter name: Import Groups Parameter
This filter is set to import groups based on the entered parameters. For example: $filter=startswith groupName, ‘E’. Note that one filter can use several parameters at once.
 

Examples

The following example finds groups that are security groups

The following example finds groups with displayname that starts with the word “Efecte”

The following example finds groups that are created and synced from Active Directory

Excluded Groups

For Azure-based tasks, put Object IDs of the groups to exclude (separated by newlines). 

Filtering Users based on group-membership

Filter name: Import Groups Parameter
This filter is set to import users based on the group-membership. For Azure-based tasks, put Object IDs of the Groups memberships to include or exclude (separated by newlines)  

Filtering based on single users

Filter name: Excluded Users

With this filter it is possible to exclude specific users from the import. For Entra use ObjectGUIDs of the Groups to exclude (separated by newlines). 

More information about MS Graph API and filters can be found from https://docs.microsoft.com/en-us/graph/aad-advanced-queries?tabs=http .

How to test EPE Azure queries

If you want to test Azure queries without running EPE go to URL https://developer.microsoft.com/en-us/graph/graph-explorer 

This testing tool uses exactly the same rules as EPE. If something works here, it also works in EPE and vice versa.

For example how to test if onPremisesExtensionAttribute syntax works in EPE:

You can configure scheduled task to read data with query, and subqueries which are related to resultset returned by main query.

In this example deviceManagement/managedDevices is main query, and it has 2 subqueries. Subqueries are done for all devices, which main query returned.

When you have set those subqueries, you can use those in mappings to fetch data returned by subqueries. For example like this:
 

When you read attribute from subquery, it has it's own format. First you need to have subquery as a prefix, then dot (.) and then attribute name you want to read. 

As an example, let's check this mapping more detailed:
/deviceManagement/managedDevices/{id}/windowsProtectionState.deviceState

prefix(same as subquery): /deviceManagement/managedDevices/{id}/windowsProtectionState

dot: .

suffix as attribute name from subquery resultset: deviceState

That subquery mapping reads (in this example) from all main query resulted devices windowsProtectionState object, and from there it reads deviceState attribute value.

Subtables support added for 2025.2 version

You can read attributes from tables using this syntax:
deviceManagement/detectedApps/{id}/deviceActionResults.0.actionName
Examples (read data from deviceActionResults subquery resultsets first table and from that table it reads actionName, actionState and lastUpdatedDateTime attributes to separate ESM attributes:

Restrictions in 2025.1 version

Multilevel subqueries are not supported

Subqueries support only one level of subqueries, meaning you can't directly create for example these type of subqueries where you have more than 1 variable in {}: 

/deviceManagement/detectedApps/{detectedAppId}/managedDevices/{managedDeviceId}/users/{userId}/managedDevices 

Subtables are not supported

Fetching data from subtables are not supported, meaning you can't for example read actionName from this API call: 

deviceManagement/managedDevices/{id}

Only one subquery per task is supported

If you use more than one subquery, data might be mixed between subqueries.

Restrictions in 2025.2 version

Multilevel subqueries are not supported

Subqueries support only one level of subqueries, meaning you can't directly create for example these type of subqueries where you have more than 1 variable in {}: 

/deviceManagement/detectedApps/{detectedAppId}/managedDevices/{managedDeviceId}/users/{userId}/managedDevices 

Only one subquery per task is supported

If you use more than one subquery, data might be mixed between subqueries.

Restrictions in 2025.3 version

Multilevel subqueries are not supported

Subqueries support only one level of subqueries, meaning you can't directly create for example these type of subqueries where you have more than 1 variable in {}: 

/deviceManagement/detectedApps/{detectedAppId}/managedDevices/{managedDeviceId}/users/{userId}/managedDevices 

With Generic REST call -action, you can make various calls to Azure and Entra ID through Microsoft Graph API. Here are couple of examples of those possibilities, but not limited to only these.

Set extensionAttributes (1-15) to Entra ID account.

Generate json body in workflow script node (modify script to match your requirements), in example workflow below, this script is in “EXT Generate ExtensionAttributes payload” node:

import json

_source = this.get("source")

# EXT users extension attributes, ordered from portal
if "Self-service portal" in _source:
  # set values to variables
  _extAttr1 = this.get("iga_id")
  _extAttr4 = "EXT"
  _extAttr9 = str(this.get("work_unit"))
  _extAttr10 = "100"
  _extAttr15 = this.get("microsoft_license")

  _payload_dict = {
    "onPremisesExtensionAttributes": {
        "extensionAttribute1": _extAttr1,
        "extensionAttribute4": _extAttr4,
        "extensionAttribute9": _extAttr9,
        "extensionAttribute10": _extAttr10,
        "extensionAttribute15": _extAttr15
    }
}

  # format to json and set to extattributesEntra attribute
  _payload = json.dumps(_payload_dict, indent=4)
  this.set("extattributesEntra", _payload)

Create Orchestration node for Microsoft Graph API datasource and Generic REST call activity.

Set Action to PATCH, rest url to /users/$objectGUID$ and in body utilize extattributesEntra attribute value you created on previous step with syntax $extattributesEntra$.

Empty specific/listed User attributes on Entra ID

With this kind of Orchestration node, you can empty certain attribute values from one user at a time from Entra ID. 

Target user is given to REST URL as datacard attribute parameter after the api endpoint /user/.

Remember to use Action=PATCH to empty/remove certain attribute values from user object on Entra ID.

This example is removing/emptying almost all extensionattributes, and on top of those also companyName, department, employeeType, jobTitle, mobilePhone and officeLocation.

Activate / Deactive User 

In the illustration above admins choose the correct Microsoft Azure AD “Target” and are able to view the Identity Mappings which are configured for selected Azure tasks. In this orchestration view admins are not allowed to change any mappings, those are presented only as a visual aid. If any changes to the mappings are needed, those needs must be execute in the Provisioning task configuration view. 

Inside this same node, administrators are able to choose the action what they are prefer to use “Activate” or “Deactivate”. ‘Activate/Deactivate’ functionality here refers to setting 'accountEnabled’ true if the account is enabled; otherwise, false.

Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions. 

Add User to Group

In the illustration above, the Person attribute configuration should point to the template where the orchestration node finds the user’s data (usually IGA account). The Role attribute needs to be configured to define where the orchestration node finds the available roles (directory groups where the user should be removed). There might be single or multiple attribute groups configured in a “Role attribute”. The list of available registered directory Tasks is fetched from the EPE-master. 

It is required to select the directory Task, because the Efecte Provisioning Engine orchestration node will use identity and access rights fields mapping to know, under which attribute code, the user’s and directory group distinguished names are stored. 

Person attribute expects an attribute containing users Entra ID accounts id.

Exception handling:

• The result of a node will be in the “Completed” state only in the case when all user’s group memberships will be updated successfully. In the case when, for example, the user will be successfully removed from 5 out of 6 groups then the result of a node will be in the “Exception” state.
• Hence the mapping for distinguishedName JSON field, for both Identity and Access Right is required. If mapping won’t be found then the orchestration node will result in an “Exception” state.
• The attempt to remove a user from a group which they do not belong will end as a failure.
• The attempt to add a user to a group to which he already belongs will end as a failure.
• Details about successfully/unsuccessful updated user’s group membership can be found in logs.
• Provisioning and group membership exceptions are optional properties on this workflow node. Admins can configure this properties in use where exceptions can be written if any exceptions exists during the provisioning actions.

Create user
 

In the illustration above, the Identity Attribute Mappings are populated from Provisioning tasks. Admins choose the correct Directory “Target” and are able to view the Identity Mappings which are configured for selected directory tasks. In this orchestration view admins are not allowed to change any mappings, those are presented as a visual aid. If any changes to the mappings are needed, those needs must be execute in the Provisioning task configuration view. 

The creating new user orchestration node read attributes from Data Cards in question and executes API call to Azure. It is important to be sure, that Identity Mapping, being used in Create User orchestration node, contains at least three additional Azure AD mappings: for “displayName”, "mailNickname" and “userPrincipalName” attributes. Note: if those three mappings are missing on a given configuration, it will not be presented on a dropdown.

Creating new user activity notes:

• There are two ways to create the password for a new user for their first login.
  • Define “Default” password in the Provisioning Task -configuration view
    • That password will only be used by users, when they login into the system for the first time
  • Generating random password in the workflow and select into which attribute on Identity Mapping data-card it was written to
  • In both cases the first time password “pwdLastSet” value is set to zero (0) to force a user to change their password after the first login
  • Possibility to choose if the password must change at the first login or not. Administrators can make the selection for this directly from the workflow User Creation orchestration node.
• There are different ways to provide password for the first login for the end-user. Depending on customers needs it is possible to use workflow functionalities to send the password directly to the end user via email or sms. Another option is to send the password for first login to the manager, who will provide it for the end-user. EPE’s Orchestration node itself DO NOT provide that functionality, it needs to be defined elsewhere.
• Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions. 

Create Group

In the illustration above, the Access Rights Attribute Mappings are populated from Provisioning tasks. Admins choose the correct Azure Directory “Target” and are able to view the Access Rights Mappings which are configured for selected Azure tasks. In this orchestration view admins are not allowed to change any mappings, those are presented as a visual aid. If any changes to the mappings are needed, those needs must be execute in the Provisioning task configuration view. 

The creating new user orchestration node read attributes from Data Cards in question and execute API command to Entra Directory. 

It is important to be sure, that Access Rights Mapping, being used in Create Group orchestration node, contains at least four additional Azure AD mappings: for “displayName”, “mailEnabled”, “mailNickname” and “securityEnabled” attributes. 

Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions.


Delete Group
 

In the illustration above administrators can choose the correct Azure Directory “Target”. The delete group orchestration node read attributes from Data Cards in question and execute API command to Azure Directory. 

For Azure Active Directory-based configurations, 'Role group attribute' should contain group’s ObjectGUID.

Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions.
 

Delete User

In the illustration above administrators can choose the correct Azure AD “Target”. The delete user orchestration node read attributes from Data Cards in question and execute API command to Entra Directory.

Person attribute expects an attribute containing users Entra ID accounts id.

Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions.

Remove User from Group

In the illustration above administrators can choose the correct Azure AD “Target”. The remove user from group orchestration node read attributes from Data Cards in question and execute API command to Entra Directory.

For Azure Active Directory-based configurations, 'Person Attribute' and ‘Role attribute’ should contain User's ObjectGUID value.

Exception handling:

• The result of a node will be in the “Completed” state only in the case when all user’s group memberships will be updated successfully. In the case when, for example, the user will be successfully removed from 5 out of 6 groups then the result of a node will be in the “Exception” state.
• The attempt to remove a user from a group which they do not belong will end as a failure.
• Details about successfully/unsuccessful updated user’s group membership can be found in logs.
• Provisioning and group membership exceptions are optional properties on this workflow node. Admins can configure this properties in use where exceptions can be written if any exceptions exists during the provisioning actions.
   

Reset User Password

In the illustration above administrators can choose the correct Azure Directory “Target”. The Reset user password orchestration node read attributes from Data Cards in question and execute API command to Azure Directory. The Person and Password attributes should point to the template where the orchestration node finds the user’s data.  

From the EPE version 2022.3 forward we have implemented possibility to choose if the password must change at the first login or not. Administrators can make the selection for this directly from the workflow Reset User password orchestration node.

Person attribute expects an attribute containing users Entra ID accounts id.

Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions.

Update group
 

In the illustration above, the Access Rights Attribute Mappings are populated from Provisioning tasks. Admins choose the correct Azure Directory “Target” and are able to view the Access Rights Mappings which are configured for selected Azure tasks. 

In this orchestration view admins are not allowed to change any mappings, those are presented only as a visual aid. If any changes to the mappings are needed, those needs must be execute in the Provisioning task configuration view. 

The update group orchestration node read attributes from Data Cards in question and execute API call to Azure.

Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions.

Update User
 

In the illustration above, the Identity Attribute Mappings are populated from Provisioning tasks. Admins choose the correct Azure Directory “Target” and are able to view the Identity Mappings which are configured for selected Azure tasks. In this orchestration view admins are not allowed to change any mappings, those are presented only as a visual aid. If any changes to the mappings are needed, those needs must be execute in the Provisioning task configuration view. 

The update user orchestration node read attributes from Data Cards in question and execute API call to Azure AD.

User password update is not supported on this orchestration activity.

Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions. 

Verify Group

In the illustration above, the Access Rights Attribute Mappings are populated from the Provisioning tasks. Administrators choose the correct Azure Directory from “Target” and are able to view what Access Rights Mappings are configured for the selected Azure task. In this orchestration view you are not allowed to change any mappings, those are presented only as a visual aid. If there are needs to change the attribute mappings, those attributes must be defined in the provisioning task configuration view, in order them to be changed in the orchestration node. 

Within the Access Rights Mappings admins panel, admins are able to provide “IF” expression, which will form a API Call to verify if the group exists. It’s possible to select as many attributes from the Data Card as needed to confirm the uniqueness of a group. When an action takes place, those attributes will be read from the Data Card in question and will be compared to the appropriate Azure attributes according to the “Target*“ Azure Directory configuration. Admins can also choose to use “equal” or “not equal” to corresponding Azure attribute by changing the “IF” expression. The “Save result*” field is used to define where the successful API call results are saved, “true” if group was found or “false” otherwise. 

Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions.

Verify Group Membership

In the illustration above, the Identity Attribute Mappings are populated from the Provisioning tasks. Administrators choose the correct Azure Directory from “Target” and are able to view what Identity Mappings are configured for the selected Azure task. In this orchestration view you are not allowed to change any mappings, those are presented only as a visual aid. If there are needs to change the attribute mappings, those attributes must be defined in the provisioning task configuration view, in order them to be changed in the orchestration node. 

The “Save result*” field is used to define where the successful API call results are saved, “true” if user was found or “false” otherwise. 

Person attribute expects an attribute containing users Entra ID accounts id.

Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions. 

 Verify User

In the illustration above, the Identity Attribute Mappings are populated from the Provisioning tasks. Administrators choose the correct Azure Directory from “Target” and are able to view what Identity Mappings are configured for the selected Azure task. In this orchestration view you are not allowed to change any mappings, those are presented only as a visual aid. If there are needs to change the attribute mappings, those attributes must be defined in the provisioning task configuration view, in order them to be changed in the orchestration node. 

Within the Identity Mappings admins panel, admins are able to provide “IF” expression, which will form and API call to verify if the user exists. It’s possible to select as many attributes from the Person Data Card as needed to confirm the uniqueness of a user. When an action takes place, those attributes will be read from the Data Card in question and will be compared to the appropriate Azure attributes according to the “Target*“ Azure configuration. Admins can also choose to use “equal” or “not equal” to corresponding Azure attribute by changing the “IF” expression. The “Save result*” field is used to define where the successful API call results are saved, “true” if user was found or “false” otherwise. 

Key point to understand this node's mechanics is - while forming IF expression, admin needs to use Template's attributes, but in fact, values read from them, will be translated (mapped) to proper Azure Directory attributes, according to Identity Mapping configuration and will be passed to Azure Directory as a search query. 

Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions. 

Create Custom Object

Since 2022.2 Efecte Provisioning Engine (EPE) introduces new workflow activity "Create custom object". For example devices, contacts and applications can be now created with EPE towards Azure AD. Note this action is IGA licensed. This means that Custom object creation can be used in IGA installations. 

In the illustration above, the Identity Attribute Mappings are populated from the Provisioning tasks. Administrators choose the correct Azure Directory from “Target” and are able to view what Identity Mappings are configured for the selected Azure task. In this orchestration view you are not allowed to change any mappings, those are presented only as a visual aid. If there are needs to change the attribute mappings, those attributes must be defined in the provisioning task configuration view, in order them to be changed in the orchestration node. 

Custom object class defines what object EPE is creating. In this example EPE is creating contacts. 

Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions. 

Update Custom Object

Since 2023.1 Efecte Provisioning Engine (EPE) introduces new workflow activity "Update custom object". For example devices, contacts and applications can be now updated with EPE towards Azure AD. Note this action is IGA licensed. This means that Custom object creation can be used in IGA installations. 

In the illustration above, the Identity Attribute Mappings are populated from the Provisioning tasks. Administrators choose the correct Azure Directory from “Target” and are able to view what Identity Mappings are configured for the selected Azure task. In this orchestration view you are not allowed to change any mappings, those are presented only as a visual aid. If there are needs to change the attribute mappings, those attributes must be defined in the provisioning task configuration view, in order them to be changed in the orchestration node. 

Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions. 

Delete Custom Object

Since 2023.1 Efecte Provisioning Engine (EPE) introduces new workflow activity "Delete custom object". For example devices, contacts and applications can be now deleted with EPE towards Azure AD. Note this action is IGA licensed. This means that Custom object creation can be used in IGA installations. 

In the illustration above, the Object name attribute defines what object EPE is deleting. In this example EPE is deleting contacts. 

Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions. 

Read user data

Since 2022.2 Efecte Provisioning Engine (EPE) introduces new workflow activity “Read User's data”. Info can be updated behind reference for example IGA account data can be updated from Identity storage. 

In the illustration above, person attribute is used for updating right account information from directory to ESM. 

Person attribute expects an attribute containing users Entra ID accounts id.

Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions. 
 

Run provisioning task

This activity is used when all information from the directory is immediately needed back. 

In the illustration above administrators can choose the correct Directory “Target”. Run provisioning task orchestration node read attributes from Azure Directory to IGA Accounts. 

Requirements for the "Target" EPEtask are:

• Task must be of type "Schedulable task" not event-based
• Workflow's Template must be the same as Identity mapping Template
• Task must be scheduled at some time - it marks a task to be "enabled" then
• Mappings must be distinct, no duplicated mappings in the task

In this orchestration view you are not allowed to change any mappings, those are presented only as a visual aid. If there are needs to change the attribute mappings, those attributes must be defined in the provisioning task configuration view, in order them to be changed in the orchestration node. 

Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions.

Generic REST call

Add Orchestration node to your workflow and configure following things.

Name - set descriptive name

Description - set descriptive description

Orchestrate - select Provisioning Engine

Data Source - select Microsoft Graph API

Activity - select Generic REST call

Target - select your event-based task (you can use same task for many orchestration nodes)

Action - select action based on REST API you are calling (check API documentation for correct action). Supported actions are: POST, PUT, PATCH, DELETE and GET

REST URL - api endpoint you are calling. This can be full url or suffix of the url. If you use suffix, actual url to callwill be concatenated using all these: connector host url + task query + Orchestration node url. You can usetemplate attribute variables similarly than in email node, using dollar syntax like: $attribute_code$ and $reference:attribute_code$. 

Note! If you have spaces or $ signs in your url, remember to url encode those. So $ is %24 space is %20
E.g. this url: users?%24count=true&$filter=userprincipalname eq 'test' is encoded this: users?$count=true&%24filter=userprincipalname%20eq%20'test'

Rest Body - json body for api call. Can be empty if API you are calling does not need body, you can also use {} if leaving body doesn't work with Microsoft. See body details from API documentation. You can use template attribute variables similarly than in email node, using dollar syntax like: $attribute_code$ and $reference:attribute_code$. 

For example in this body we have two variables: $firstname$ and $lastname$
{"name": {
   "givenName": "$firstname$",
   "familyName": “$lastname$”}}

In case you need to create complicated json body for API call, you can construct that full json first to somedatacard attribute. And then only have that attribute code in body, like this:$generated_json_body_attributecode$

import json

if onPremisesExtensionAttributes:
  _data = this.get("onPremisesExtensionAttributes")
  _obj = json.loads(_data)
  _value = _obj["extensionAttribute14"]
  this.set("extensionAttribute14code",_value)

Rest Response Attribute - resultset json of API call will be written to this attribute. Not all API's return any response json. See details from API documentation.

import json

if onPremisesExtensionAttributes:
  _data = this.get("onPremisesExtensionAttributes")
  _obj = json.loads(_data)
  _value = _obj["extensionAttribute14"]
  this.set("extensionAttribute14code",_value)

Provisioning exception - If there is an issue on REST API call, error will be written to this attribute.

Exception handling for Generic REST calls:

• Provisioning exception is an optional property on this workflow node. Admins can configure this property in use where exceptions can be written if any exceptions exists during the provisioning actions. 
• The result of a node will be in the “Completed” state if Microsoft Graph API http response code is 200 or over and under 400.
• Details about successfully/unsuccessful Microsoft Graph API calls can be found in logs.

In this chapter are described troubleshooting options,

• In case failure template is used, check correct data card
• Check scheduled task history from connector management
• Check Efecte Provisioning Engine logs
• Currently, EPE does not support mapping the same EntraID id attribute to multiple ESM attributes. However, the UI still allows this configuration, which can lead to errors.