Skip to main content
Matrix42 Self-Service Help Center

Microsoft Entra ID Data Provider

  1. Last updated
  2. Save as PDF

Overview

The Microsoft Entra ID Data Provider is designed for establishing the integration between Digital Workspace Platform and Microsoft Entra ID server.

On this page, you may find data filtering conditions and advanced settings of the Microsoft Entra ID Data Provider.

Go to the Administration application → Integration → Data Providers → Microsoft Entra ID / Microsoft 365 → click Edit → open Settings view.

Settings and Filters

This section contains a number of settings grouped as follows:

operator1.png

operator2.png

Domain

Use the single selection button to select the domain for which the integration should be established.

Import Users

Indicates whether users will be imported.

User Filter

If User Filter is active you can specify a collection of conditions based on a list of supported properties for filtering to retrieve just a subset of a collection.

Supported properties

Description

Account Enabled

 true if the account is enabled; otherwise, false. This property is required when a user is created.

City

 The city in which the user is located.

Country

 The country/region in which the user is located; for example, “US” or “UK”.

Department

 The name of the department where the user works.

State

 The state or province in the user's address. 

Country Code

A two-letter country code (ISO standard 3166). Required for users that will be assigned licenses due to legal requirements

to check for availability of services in countries. Examples include: "US", "JP", and "GB".

Display Name

The name displayed in the address book for the user.

Usually, this is a combination of the user's first name, middle name, and last name.

This property is required when a user is created and it cannot be cleared during updates.

Employee ID

 The employee identifier assigned to the user by the organization.

First Name

 The given name (first name) of the user.

Last Name

 The user's surname (family name or last name).

When the Last Name is not defined, the user's Display Name is used for filling Last Name (all parts after the first name are split with whitespace and added as the last name).

Job Title

 The user’s job title.

Mail

 The SMTP address for the user, for example, "jeff@contoso.onmicrosoft.com".

Mail Nickname

 The mail alias for the user. This property must be specified when a user is created.

On-Premises Immutable ID

This property is used to associate an on-premises Active Directory user account to their Microsoft Entra ID user object.

This property must be specified when creating a new user account in the Graph if you are using a federated domain for the user’s userPrincipalName (UPN) property.

The $ and _ characters cannot be used when specifying this property.

Other Mails

 A list of additional email addresses for the user; for example: ["bob@contoso.com", "Robert@fabrikam.com"] 

Proxy Addresses

For example: ["SMTP: bob@contoso.com", "smtp: bob@sales.contoso.com"]

User Principal Name (UPN)

The User Principal Name (UPN) of the user.

The UPN is an Internet-style login name for the user based on the Internet Standard RFC 822.

By convention, this should map to the user's email name. 

User Type

 A string value that can be used to classify user types in your directory, such as “Member” and “Guest”.

Import Groups

Indicates whether groups will be imported.

Group Filter

If Group Filter is active you can specify a collection of conditions based on a list of supported properties for filtering to retrieve just a subset of a collection.

Supported properties

Description

Display Name

 The display name for the group. This property is required when a group is created and cannot be cleared during updates.

Group Types

Specifies the group type and its membership.

Available since DWP v.12.0.2.

Since the group types are defined by Microsoft, the only available operator is 'equals' with the following values:

  • Microsoft 365:  the group is a Microsoft Office 365 group if the collection from AAD contains Unified;
  • Security: the group is defined as Security group if the collection returns not Unified;

AAD_groupTypes.png

The groupType values are stored in Microsoft Entra ID Custom Filter Data Definition.

Mail

 The SMTP address for the group.

Mail Nickname

 The mail alias for the group, unique in the organization. This property must be specified when a group is created.

On-Premises Last Sync DateTime

 Indicates the last time at which the group was synced with the on-premises directory. The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 would look like this: '2014-01-01T00:00:00Z'

On-Premises Sync Enabled
  • true if this group is synced from an on-premises directory; 
  • false if this group was originally synced from an on-premises directory but is no longer synced; 
  • null if this object has never been synced from an on-premises directory (default).

Proxy Addresses

 Email addresses for the group that lead to the same group mailbox. For example: ["SMTP: bob@contoso.com", "smtp: bob@sales.contoso.com"]. 

Security Enabled

 Specifies whether the group is a security group.


To customize the filtering properties of Users and Groups, a new Data Definition called Entra ID Filter Property was introduced. To extend the existing properties list with a new property, you can add a new property that is not currently in the list and will be used for filtering.  The list of all available properties, that could be added, you can check here. 

Go to the Administration application → Schema → Data Definitions → Pickups → Entra ID Filter Property → click Edit → open Data tab

schema.png

In Data tab the list of existing properties for filtering data will be displayed.  Click add.pngto add new properties to list.

filter property.png

Is Nullable column -  indicates that the property is nullable and filterable using null. Two new operators, Is Set and Is Not Set, will become available in the operators list if the  Is Nullable checkbox is checked.

Display String column - Internally used filter properties name.

Supported Conditions Operators  column - Operators that will be available for the current attribute: 

  • 1 - Equals
  • 2 - Not Equals
  • 4 - Lower Than Or Equals
  • 6 - Greater Than Or Equals
  • 8 -  Starts With
  • 9 - Ends With
  • 10 - In
  • 11 - Not In

Object Type column - define two types of objects available for filtering:

  • 2 - Users
  • 3 - Groups

Filter conditions

To add a filter condition, follow these steps:

  • Click Add Condition.
  • Select the property you'd like to filter.
  • Select an operator.

    The following operators are supported by Microsoft Graph API:

    • Equals
    • Not Equals
    • Starts With
    • Ends With
    • Lower Than or Equals
    • Grater Than or Equals
    • In
    • Not In
    • Is Set
    • Not Set

    The filter conditions can be combined by using the following logical operators:

    • AND
    • OR

    Creating groups of conditions is supported as well.

    Only one kind of logical operator can be defined on each level

Known limitations

If "OR" operator is used at least once within the filter then the conditions count should not exceed 15. The validation message will be displayed in the UI.

Do not process deleted objects

This checkbox has the following options:

  • not selected (default): deleted objects are processed and synchronized;
  • selected: in this case already imported objects from Microsoft Entra ID to the ESM will not be marked as deleted.  Also, no "new" deleted objects will be imported to Microsoft Entra ID and will not be updated.
    do not process deleted objects.png

Starting from DWP v.11.0.2 the "Skip Import Deleted Objects" property has been renamed to "Do not process deleted objects".

Pay attention that processing of deleted object is applied to 30 days old entries max, and in case you may want to delete entries in DWP that were deleted in  Microsoft Entra ID later than 30 days ago - you will need to do that manually.

Additional Import Attributes

Users and Groups Import

Additional attributes can be specified for Users and Groups Import starting from DWP 10.0 Update 3.

Additional Import Attributes

Additional Import Attributes section is available when at least one type of import is enabled: Import Users or Import Groups.

additional_import_settings1.png

To configure the additional attributes you want to import, in the Settings section of the Data Provider configuration, fill out the following fields:

  • Extension Application (client) ID:
    • Same Application ID: by default, the configuration uses the same Application (client) ID that is specified in the General section.
    • Other Application ID: if the additional attributes are available in the other tenant, clear the Extension Application ID is the same as the Application (client) ID checkbox and specify the Extension Application (client) ID in the corresponding field;
  • User Attribute Names (Separated by Commas): enumerate necessary attributes. Please note that attribute names are case-sensitive;
  • Group Attribute Names (Separated by Commas): enumerate necessary attributes. Please note that attribute names are case-sensitive;

Update the import definition for User import accordingly, in order to correctly save the values from extended attributes in the database

For cases when both Microsoft Entra ID and on-premises Active Directory are used as import sources, Additional Import Attributes must be configured the same way in both configurations of these connectors:

  1. Configure Additional Import Attributes in Microsoft Entra ID connector configuration;
  2. Configure Additional Import Attributes in on-premises Active Directory connector configuration;
  3. Update the import definition accordingly, in order to correctly save the custom values in the database;
  4. Run import from both sources: Microsoft Entra ID and on-premises Active Directory.

Otherwise, if the Additional Import Attributes are configured only for Microsoft Entra ID, the on-premises Active Directory import fails.

Added attributes are also available for filtering:

aad_user_filter.png

See also: Microsoft Entra Connect Sync Directory extensions.

On-Premise Extension Attributes

Starting from DWP v.11.0.1 it is possible to import an additional type of extension attributes. Before configuring DWP, Microsoft Entra ID must have configured synchronization to retrieve these attributes, and the attributes are retrieved by import only if they are available on Microsoft Entra ID.

On-premises extension attributes are available only for Import Users only:

onpemises_attribures_2.png

This property returns an array of fifteen on-premises extension attribute properties that have reserved names, for instance: onPremisesExtensionAttribute1, onPremisesExtensionAttribute2, etc. 

Individual extension attribute can not be retrieved, as all 15 attributes are stored as a single object and are retrieved all together. 

When enabled, on-premises extension attributes are also available for filtering:

onprem_attr1.png

After import, the Account.xml will display the on-premises extension attributes as follows:

<onPremises_extensionAttribute1>value1</onPremises_extensionAttribute1>
<onPremises_extensionAttribute2>value2</onPremises_extensionAttribute2>
<onPremises_extensionAttribute3>value3</onPremises_extensionAttribute3>
<onPremises_extensionAttribute4>value4</onPremises_extensionAttribute4>
<onPremises_extensionAttribute5>value5</onPremises_extensionAttribute5>
<onPremises_extensionAttribute6>value6</onPremises_extensionAttribute6>
<onPremises_extensionAttribute7>value7</onPremises_extensionAttribute7>
<onPremises_extensionAttribute8>value8</onPremises_extensionAttribute8>
<onPremises_extensionAttribute9>value9</onPremises_extensionAttribute9>
<onPremises_extensionAttribute10>value10</onPremises_extensionAttribute10>
<onPremises_extensionAttribute11>value11</onPremises_extensionAttribute11>
<onPremises_extensionAttribute12>value12</onPremises_extensionAttribute12>
<onPremises_extensionAttribute13>value13</onPremises_extensionAttribute13>
<onPremises_extensionAttribute14>value14</onPremises_extensionAttribute14>
<onPremises_extensionAttribute15>value15</onPremises_extensionAttribute15>

See also: Microsoft Entra ID onPremisesExtensionAttributes resource type.

Limitations 

It is not possible to import navigation properties and related objects (e.g. manager field) even as custom attributes as currently it is not supported by Microsoft. For more details see Microsoft documentation.

 

Microsoft Entra ID Data Provider flow

As a rule, Digital Workspace Platform cannot access corporate networks and collect their data. Therefore, the Data Gateway service is installed within the corporate network that is managed by an Microsoft Entra ID server. The gateway collects the data on the Microsoft Entra ID server and sends it to Digital Workspace Platform.

1 - Activating the Microsoft Entra ID Data Provider

The Microsoft Entra ID import can be triggered in several ways in Digital Workspace Platform:

  • Manually run Microsoft Entra ID connector data import with the Activate action available in Administration application → Integration → Data Providers → Active Directory. It retrieves all data available at the configured remote Microsoft Entra ID server(s).
  • Scheduled: configured AD Connector engine activation runs the import and triggers the Active Directory Data Provider according to the specified import schedule.

2 - Launching the Directory Domain Services Server Workflow

The Microsoft Entra ID Data Provider launches the Directory Domain Services workflow. It is a server workflow that is run in Matrix42 Digital Workspace Platform.

3 - Launching the Microsoft Entra ID Collect Data Command

The Directory Domain Services workflow creates jobs according to the specified configurations of the Data Provider. The Data Provider configurations contain the information on the target domain and stipulate the conditions of import. When the Data Gateway finds the jobs, it starts the Microsoft Entra ID Collect Data command.

4 - Retrieving Microsoft Entra ID Objects

The Microsoft Entra ID Collect Data command is run on the Data Gateway server and therefore it can access the network data. Based on settings in the Data Provider configuration, the command activity collects data on Microsoft Entra ID objects and saves it as a package of XML files. A separate XML file is created for each imported object and for each type of deleted objects. If the import is configured for accounts, or groups, the command activity generates the following list of files:

  • Account.xml contains all Microsoft Entra ID users that are currently active.
  • Group.xml contains all Microsoft Entra ID groups that are currently active.
  • DeletedAccount.xml is relevant for partial import and contains users that have been deleted on an Microsoft Entra ID server since the last import.
  • DeletedGroups.xml is relevant for partial import and contains groups that have been deleted on an Microsoft Entra ID server since the last import.
  • Membership.xml contains the relations between Microsoft Entra ID groups and their members. 

5 - Passing Microsoft Entra ID Objects to Digital Workspace Platform

The Data Gateway passes XML files to the Directory Domain Services workflow in Digital Workspace Platform.

6 - Creating and Updating Objects Based on Imported Data

The Directory Domain Services workflow executes import definitions for each imported object. It uses the XML files as the data source to either update Digital Workspace Platform objects with new values from Microsoft Entra ID objects or create new objects in Digital Workspace Platform.

The following import definitions are executed:

  • AD: Import Accounts
    The import definition updates the existing accounts and creates new ones based on active users on an Microsoft Entra ID server. It uses the Account.xml file as a data source.
  • AD: Import Groups
    The import definition updates existing groups and creates new ones based on active groups on an Microsoft Entra ID server. It uses the Group.xml file as a data source.
  • AD: Import Persons
    The import definition updates existing persons and creates new ones based on active users on an Microsoft Entra ID server. It uses the Person.xml file as a data source.
  • AD: Membership
    The import definition updates group membership for accounts, groups based on data from an Microsoft Entra ID server. It uses the Members.xml file as a data source.
  • AD: Update Deleted Accounts
    If some Microsoft Entra ID users have been deleted since the last import, this import definition changes the Status field value to Deleted for corresponding accounts in Matrix42 Digital Workspace Platform. It uses the DeletedAccount.xmlfile as a data source.
  • AD: Update Deleted Persons 
    If some Microsoft Entra ID users have been deleted since the last import, this import definition changes the Status field value to Deleted for corresponding persons in Matrix42 Digital Workspace Platform. It uses the DeletedAccount.xml file as a data source.
  • AD: Update Deleted Groups
    If some Microsoft Entra ID groups have been deleted since the last import, this import definition changes the Status field value to Deleted for corresponding groups in Matrix42 Digital Workspace Platform. It uses the DeletedGroups.xml file as a data source.

Microsoft Entra ID Data Provider Attribute Mapping

In this section, you may find all the necessary information for the advanced settings of the Microsoft Entra ID Data Provider, in particular import mapping rules and available attributes.

Users

Rules

  • Account attributes including state are imported from Microsoft Entra ID
  • The corresponding Person is created for every Account that is imported from Microsoft Entra ID (except the case when AD and Microsoft Entra ID are connected with Microsoft Entra Connect)
  • If the Account is already associated with an existing Person, the Person is not updated
  • Person attributes are set only in case when new Person is created during import from Microsoft Entra ID
  • Person attributes are never updated during Import if the Person already exists
  • Person attributes are not synchronized back to the Microsoft Entra ID

Account

Mapping
SPSAccountClassAD.Sid = sid

or

(SPSAccountClassBase.NBAccountName = sAMAccountName AND Domain)

where Domain:

SPSAccountClassAD.Domain = @DomainId
Attributes
Name Microsoft Entra ID Data Definition Attribute Note
State 512 NORMAL_ACCOUNT SPSCommonClassBase State  
Locked CASE WHEN accountEnabled = 'true' THEN 0 ELSE 1 END SPSAccountClassAD Locked  
Domain - SPSAccountClassAD Domain taken from Relation, @DomainID
Account Name

CASE WHEN userPrincipal
​Name IS NULL THEN onPremisesSamAccountName ELSE SubString(userPrincipal
​Name,0, PATINDEX(”%@%”, userPrincipalName)) END

 SPSAccountClassBase AccountName  
NETBIOS Name onPremisesSamAccountName SPSAccountClassBase NBAccountName  
Person - SPSAccountClassBase Owner taken from Relation
Federal State state SPSAccountClassBase FederalState  
Address streetAddress SPSAddressClassBase Street  
Country country SPSAddressClassBase Country  
Fax faxNumber SPSAddressClassBase Facsimile  
P.O. postalCode SPSAddressClassBase ZIP  
City city SPSAddressClassBase City  
Email mail SPSAddressClassBase eMail  
Sid id SPSAccountClassAD Sid  
Distinguished Name onPremisesDistinguishedName SPSAccountClassAD ADCN  
First Name givenName SPSAccountClassADUser FirstName  
Last Name surname SPSAccountClassADUser LastName  
Position jobTitle SPSAccountClassADUser Position  
Cell Phone mobilePhone SPSAccountClassADUser MobilePhone  
Office officeLocation SPSAccountClassADUser Office  
Department department SPSAccountClassADUser Department  
Company companyName SPSAccountClassADUser Company  

Person

Mapping
SPSUserClassLdap.Sid = sid
Attributes
Name Microsoft Entra ID Data Definition Attribute Note
Display Name displayName SPSUserClassBase DisplayName  
Federal State state SPSAddressClassBase State  
Address streetAddress SPSAddressClassBase Street  
Country country SPSAddressClassBase Country  
Fax faxNumber SPSUserClassBase Fax  
P.O. postalCode SPSAddressClassBase POBoxZIP  
City city SPSAddressClassBase City  
Email mail SPSAddressClassBase eMail  
Accounts id SPSUserClassBase Accounts Relation
Distinguished Name onPremisesDistinguishedName SPSUserClassLdap DistinguishedName  
First Name givenName SPSUserClassBase FirstName  
Last Name surname SPSUserClassBase LastName  
Position jobTitle SPSUserClassBase Position  
Cell Phone mobilePhone SPSUserClassBase MobilePhone  
Business Phone businessPhone SPSUserClassBase BusinessPhone  
Office officeLocation SPSUserClassBase Office  
Department department SPSUserClassBase Department  
Company companyName SPSUserClassBase Company  

Groups

Rules

  • All specified attributes including state are imported from Microsoft Entra ID

Mapping

(SPSSecurityGroupClassAD.Sid = sid AND Domain)

or

(SPSSecurityGroupClassAD.NT4Name = sAMAccountName AND Domain)

or

(SPSSecurityGroupClassAD.Name = name AND Domain)

Where Domain:

SPSSecurityGroupClassAD.Domain =@DomainId

Attributes

Name Microsoft Entra ID Data Definition Attribute Note
State 2080 SPSCommonClassBase State  
Domain - SPSSecurityGroupClassAD Domain Relation, @DomainID
Name displayName SPSSecurityGroupClassAD Name  
NETBIOS Name displayName SPSSecurityGroupClassAD NT4Name  
Group Type groupTypes.Contains("Unified") ? 16 : 48 SPSSecurityGroupClassAD GroupType  
Security Group CASE WHEN groupType & 32 = 32 THEN 1 ELSE 0 END SPSSecurityGroupClassAD IsSecurityGroup  
Sid id SPSSecurityGroupClassAD Sid  
Description description SPSSecurityGroupClassAD Description  

Common Microsoft Entra ID Attributes

Name

Microsoft Entra ID

AD

Data Definition

Attribute

Note
Last Sync Date - - SPSCommonClassLdap LastSyncDate Current date
Object GUID id objectGuid SPSCommonClassLdap ObjectGuid  
Deleted - - SPSCommonClassLdap Deleted 0 (False)
Synchronizable - - SPSCommonClassLdap Synchronizable @Synchronizable