Microsoft Entra ID Connector

The Java-based Microsoft Entra ID connector integrates with the Identity Java Connector Integration Framework, using the Microsoft Graph API for secure communication and management of Microsoft Entra ID resources.

Overview

The connector operates via the Microsoft Graph API at https://graph.microsoft.com, authorized by OAuth at https://login.microsoftonline.com/TenantID/oauth2/token. It is implemented in the class EntraIDConnector within net.atos.dirx.dxi.connector.azure, supporting add, modify, delete, and search operations, translating requests/responses to SPMLv1 format. All communication is secured via SSL/TLS.

Prerequisites

  • Based on Microsoft Graph API v1.0 (functionality is limited to this version).

  • It uses OAuth 2.0 with Application Secret for authentication.

  • Supports user, group/teams, role and subscribedSku objects.

  • Navigation properties memberOf, manager and owner are handled as objectId values.

  • Only one valid Microsoft Entra ID license (subscribed sku) is supported.

Nested group assignment is not supported.

Configuration

Configuration is provided via XML, either as standard properties (attributes of <connection>) or non-standard properties (<property> sub-elements).

Table 1. Standard Properties
Property Type Description

server

String

Required. This property provides information about the host name or IP address of the Graph API endpoint.

Example: graph.microsoft.com

ssl

Boolean

Required. This value enables SSL/TLS authentication of a Graph API server and secures the communication line.

user

String

Required. This property is the Application ID that identifies DirX Identity as a Graph API client. This ID is also bound to the Application Secret used as a password and is used for OAuth service.

Example: abcd1234-5678-efgh-ijkl-9876mnopqrst

password

String

Required. The password is used as a symmetric key for communication between the Microsoft Entra ID connector and an OAuth service.

Example: ABCDEFGHIJKL_1234567890_MNOPQRSTUVWXYZ

type

String

Required. This is the Directory Type

Example: Microsoft 365
Table 2. Non-standard Properties
Property Type Description

authEndpoint

String

Required. This property is the full URL of the OAuth service. The URL format is https://OAuthServer/TenantID/OAuthPath.

Example: https://login.microsoftonline.com/12345678-9abc-def0-1234-56789abcdef0/oauth2/token

path

String

Required. This property provides the path to the latest Graph API Version and is also used for building endpoint URL. Use only valid values in the correct format. The default value is v1.0.

Example: https://graph.microsoft.com/v1.0/groups

proxyHost

String

(Optional). This property provides information about the host name or IP address of the HTTP proxy server. Do not use authenticated proxy servers. If the access to the proxy server requires authentication, deploy another local transparent proxy server that can access the authenticated one. Use only the local proxy server instead.

proxyPort

String

(Optional). This property provides information about the port number of the HTTP proxy server. Do not use authenticated proxy servers. See the description for proxyHost for more details
Sample Configuration
<connector className="net.atos.dirx.dxi.connector.azure.EntraIDConnector" name="TS" role="connector">
    <connection password="<password>" server="graph.microsoft.com" ssl="TRUE" type="EntraID" user="11111111-2222-3333-4444-555555555555">
         <property name="proxyHost" value="proxy"/>
         <property name="proxyPort" value="85"/>
         <property name="authEndpoint" value="https://login.microsoftonline.com/12345678-1234-1234-1234-123456789012/oauth2/token"/>
         <property name="path" value="v1.0"/>
    </connection>
</connector>

Managing Microsoft Entra ID Groups

Supported group types:

  • Microsoft 365 groups (Public, Private, HiddenMembership)

  • Microsoft 365 teams groups (Public, Private)

  • Security groups

See: https://docs.microsoft.com/en-us/graph/api/resources/groups-overview?view=graph-rest-1.0

  • Group Type cannot be changed after creation.

  • Do not change Group Type on imported groups in edit mode.

  • Mail-enabled security groups and distribution lists cannot be created via Graph API.

For migration info: https://docs.microsoft.com/en-us/microsoft-365/admin/manage/upgrade-distribution-lists?view=o365-worldwide

Security and Microsoft 365 groups

In DirX Identity you can manage these groups on Microsoft Entra ID

  • Security

  • Microsoft 365 — Public (Default)

  • Microsoft 365 — Private

  • Microsoft 365 — HiddenMembership

  • Microsoft 365 — Private Teams

  • Microsoft 365 — Public Teams

  • Mail-enabled security groups and distribution groups are read-only, they can’t be created through DirX Identity. They will only be displayed in the appropriated query folder

  • Changing the group type after creation is not supported

  • Creating teams from an existing group is not supported

For more information, see microsoft online documentation

Group Creation Properties

The following table lists the properties that are required when you create a group. Specify other writable properties as necessary for your group

Table 3. Required properties
Property Type Description

displayName

String

The name to display in the address book for the group. Maximum length: 256 characters. Required.

mailEnabled

Boolean

Set to true for mail-enabled groups. Required.

mailNickname

String

The mail alias for the group, unique for Microsoft 365 groups in the organization. The Maximum length is 64 characters. This property can contain only characters in the ASCII character set 0–127 except the following: @ () \ [] " ; : <> , SPACE. Required.

securityEnabled

Boolean

Set to true for security-enabled groups, including Microsoft 365 groups. Required.

NOTE: Groups created using the Microsoft Entra admin center or the Azure portal always have securityEnabled initially set to true.
Table 4. Optional properties
Property Type Description

description

String

Specify a description for the group. The maximum string length is 1024 characters.

owners

String[]

Collection that represents the group owners.

members

String[]

Collection that represents the group members.

visibility

String

Specify the visibility of a Microsoft 365 group. Possible values are:

Private: owner permission is needed to join the group. Non-members cannot view the contents of the group.

Public: anyone can join the group without needing owner permission. Anyone can view the contents of the group.

HiddenMembership: owner permission is needed to join the group. Non-members cannot view the contents of the group. Non-members cannot see the members of the group. Administrators (global, company, user, and (helpdesk) can view the membership of the group. The group appears in the global address book (GAL).

Empty: Interpreted as Public.

resourceProvisioningOptions

Any group that has a team has a resourceProvisioningOptions property that contains Team

groupTypes Options

Use the groupTypes property to control the type of group and its membership, as described in the Microsoft document:

Table 5. groupTypes property
Type of group Assigned membership Dynamic membership

Microsoft 365 (aka unified group)

["Unified"]

["Unified","DynamicMembership"]

Dynamic

[] (null)

["DynamicMembership"]
Microsoft Entra ID Connector does not support groupTypes=“DynamicMembership.”

Mapping groupType and dxrType

The following table shows the mapping between MS Graph API property groupType and DirX Identity property dxrType values for the supported Microsoft Entra ID groups.

Table 6. Mapping MS Entra ID to DXI
Type of group Attribute value (MS Entra ID) dxrType value (DXI)

Security Group

securityEnabled=true; mailEnabled=false

SecurityGroup

Microsoft 365 — Public

securityEnabled=true or false; mailEnabled=true; groupTypes=Unified; visibility=Public

MS365GroupPublic

Microsoft 365 — Private

securityEnabled=true or false; mailEnabled=true; groupTypes=Unified; visibility=Private

MS365GroupPrivate

Microsoft 365 — HiddenMembership

securityEnabled=false; mailEnabled=true; groupTypes=Unified; visibility=HiddenMembership

MS365GroupHiddenMembership

Microsoft 365 — Public Teams

securityEnabled=false; mailEnabled=true; groupTypes=Unified; visibility=Public; resourceProvisioningOptions=Team

MS365GroupPublicTeams

Microsoft 365 — Private Teams

securityEnabled=false; mailEnabled=true; groupTypes=Unified; visibility=Private; resourceProvisioningOptions=Team

MS365GroupPrivateTeams

Not supported groups (read-only)

Distribution Group

securityEnabled=false; mailEnabled=true; groupTypes=[]

DistributionGroup

Mail-Enabled Security Group

securityEnabled=true; mailEnabled=true; groupTypes=[]

MailEnabledSecurityGroup

Teams (Teams groups)

A team in Microsoft Teams is a collection of channel objects. A channel represents a topic, and therefore logical isolation of discussion, within a team.

The procedure for creating a team is the same as for Microsoft 365 groups with some additions.

  • Every team is associated with a Microsoft 365 group

  • When creating a new team, at least one owner needs to be assigned. This owner is also assigned as a member

  • Property resourceProvisioningOptions is set to Team

Resource provisioning options

resourceProvisioningOptions is a string collection that specifies the resources that are associated with the Microsoft 365 group.

Table 7. Supported values for this property
Supported values for resourceProvisioningOptions Description

Team

If set, the Microsoft 365 group is associated with a Teams team.

Filtering Entra-ID Objects

The Microsoft Entra ID connector supports filtering of accounts, groups, and roles channels via the Microsoft Graph $filter query parameter. Use DirX Identity Manager to set the filter in the respective channel. For example, you can define a filter to restrict synchronization to specific AD objects, as shown in the following dialog:

The following limitations apply

  • The Microsoft Graph API for Microsoft Entra ID objects does not support all filter operators.

  • The $filter query parameter does not support all Microsoft Entra ID object properties.

  • Not all Entra-ID object properties support filter queries.

  • In DirX Identity Manager, not all Microsoft Entra ID objects own the attributes defined in the attribute configuration file. Although you can select certain operators and attributes in the filter control, not all operators and attributes are supported.
For more information on Microsoft Graph query parameters, see the Microsoft document: https://docs.microsoft.com/en-us/graph/query-parameters

Using the $filter Parameter on User and Group Resources

You can use the $filter query parameter on user and group resource types to retrieve

  • A subset of a collection

  • Relationships, like members, memberOf, transitiveMembers, and transitiveMemberOf. For example, get all the security groups of which I am a member.

Example of Using the startswith $filter Parameter
HTTP GET https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName,'J')

The following table shows currently supported and unsupported Microsoft Graph logical operators for MS Entra ID user and group resources and how they correspond to DirX Identity and DirX DSML operators

Table 8. Logical Operators
Graph API MS Entra ID Resources (User, Group) DirX Identity Manager DirX DSML

equals (eq)

$filter=givenName eq ‘Max’

equals

<filter><dsml:equalityMatch name="givenName"><dsml:value>Smith</dsml:value>…

in (in)

unsupported

unsupported

unsupported

not equals (ne)

unsupported

not equals

<filter><dsml:not><dsml:equalityMatch name="givenName><dsml:value>Smith</dsml:value>…

greater than (gt)

unsupported

unsupported

unsupported

greater than or equals (ge)

$filter=createdDateTime ge 2020-08-01

greater than or equal to

<filter><greaterOrEqual name="givenName"><dsml:value>Smith</dsml:value>…​

less than (lt)

unsupported

unsupported

unsupported

less than or equals (le)

$filter= createdDateTime le 2014-08-01

less than or equal to

<filter><lessOrEqual name="givenName"><dsml:value>Smith</dsml:value>…​

unsupported

unsupported

contains

<filter><dsml:substrings name="givenName"><dsml:any>Smith</dsml:any>…​

startswith

$filter=startswith(givenName=‘Max’)

begin with

<filter><dsml:substrings name="givenName"><dsml:initial>Smith</dsml:initial>…​

unsupported

unsupported

ends with

<filter><dsml:substrings name="givenName"><dsml:final>Smith</dsml:final>…​

unsupported

unsupported

is present

<filter><dsml:present name="givenName"/></filter>

and()

$filter=startswith(givenName=‘Max’') and startswith(surName='Smith')

and

<filter><dsml:and>…

or()

$filter=startswith(givenName=‘Max’) or startswith(surName‘Smith’)

or

<filter><dsml:or>…

not()

unsupported

not

<filter><dsml:not>…

As shown in the table, the $filter operators ne, gt, lt, not aren’t supported for Microsoft Entra ID resources. The contains string operator is currently not supported on any Microsoft Graph resource.

Not every Microsoft Entra ID user and group object property supports filter query. Check the documentation for the resource to see which property is filterable

For more information about query parameters, see the Microsoft documentation at

In these documents, only the properties marked with Supports $filter are supported in Microsoft Graph API.

Using the $filter Parameter on directoryRole Resources

The directoryRole resource type represents a Microsoft Entra ID directory role (also called an administrator role).

Only the equality match filter operator is supported for this resource type.
…directoryRole?$filter=displayname eq ‘Helpdesk Administrator’
For more information on the directoryRole resource type, see the document: https://docs.microsoft.com/en-us/graph/api/resources/directoryrole?view=graph-rest-1.0

Escaping Single Quotes

For requests that use single quotes, if any parameter values also contain single quotes, they must be double escaped; otherwise, the request will fail due to invalid syntax.

Example of Escaping Single Quotes
HTTP GET https://graph.microsoft.com/v1.0/me/messages?$filter=subject eq 'let''s meet for lunch?'

The string value 'let's meet for lunch?' has the single quote escaped.

For more information on encoding query parameters, see the Microsoft document https://docs.microsoft.com/en-us/graph/query-parameters.

Paging

Paging for the Microsoft Entra ID connector is set to the following defaults in accounts, members, groups, plans and roles channels under the channel’s Export tab

  • pagedRead=true

  • timelimit=0

  • pageSize=100

Do not change these values for the Microsoft Entra ID connector