Skip to main content
Matrix42 Self-Service Help Center

Azure Active Directory Data Provider

Overview

The Azure Active Directory Data Provider is designed for establishing the integration between Digital Workspace Platform and Azure AD server.

On this page, you may find data filtering conditions and advanced settings of the Azure Active Directory Data Provider.

Go to the Administration application → Integration → Data Providers → Azure Active Directory → click Edit → open Settings view.

Settings and Filters

This section contains a number of settings grouped as follows:

010 Connector Configuration-Settings-New condition.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 Azure AD 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 Azure AD 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.

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 Azure Active Directory Graph API:

    • Equals
    • Starts With.

    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 Azure Active Directory to the ESM will not be marked as deleted.  Also, no "new" deleted objects will be imported to Azure Active Directory 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".

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 Azure Active Directory 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 Azure Active Directory 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: Azure Active Directory and on-premises Active Directory.

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

Added attributes are also available for filtering:

aad_user_filter.png

See also: Microsoft Azure AD 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, Azure AD must have configured synchronization to retrieve these attributes, and the attributes are retrieved by import only if they are available on Azure AD.

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 Azure AD 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.

 

Azure AD 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 Azure Active Directory server. The gateway collects the data on the Azure AD server and sends it to Digital Workspace Platform.

1 - Activating the Azure Active Directory Data Provider

The Azure AD import can be triggered in several ways in Digital Workspace Platform:

  • Manually run Azure AD 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 Azure AD 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 Azure Active Directory Data Provider launches the Directory Domain Services workflow. It is a server workflow that is run in Matrix42 Digital Workspace Platform.

3 - Launching the Azure AD 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 Azure AD Collect Data command.

4 - Retrieving Azure AD Objects

The Azure AD 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 Azure AD 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 Azure AD users that are currently active.
  • Group.xml contains all Azure AD groups that are currently active.
  • DeletedAccount.xml is relevant for partial import and contains users that have been deleted on an Azure AD server since the last import.
  • DeletedGroups.xml is relevant for partial import and contains groups that have been deleted on an Azure AD server since the last import.
  • Membership.xml contains the relations between Azure AD groups and their members. 

5 - Passing Azure AD 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 Azure AD 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 Azure AD 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 Azure AD 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 Azure AD 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 Azure AD server. It uses the Members.xml file as a data source.
  • AD: Update Deleted Accounts
    If some Azure AD 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 Azure AD 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 Azure AD 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.

Azure AD Data Provider Attribute Mapping

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

Users

Rules

  • Account attributes including state are imported from Azure Active Directory
  • The corresponding Person is created for every Account that is imported from Azure Active Directory (except the case when AD and Azure AD are connected with AD 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 Azure Active Directory
  • Person attributes are never updated during Import if the Person already exists
  • Person attributes are not synchronized back to the Azure Active Directory

Account

Mapping
SPSAccountClassAD.Sid = sid

or

(SPSAccountClassBase.NBAccountName = sAMAccountName AND Domain)

where Domain:

SPSAccountClassAD.Domain = @DomainId
Attributes
Name Azure AD 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 Azure AD 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 Azure Active Directory

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 Azure AD 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 Azure AD Attributes

Name

Azure AD

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