Microsoft 365 Connector

The Java-based Microsoft 365 connector runs inside the Identity Java Connector Integration Framework. It communicates using the Microsoft Graph API on the common URL https://graph.microsoft.com via common HTTP protocol. The operations are authorized by a dedicated OAuth server available on the common URL https://login.microsoftonline.com/TenantID/oauth2/token.

The connector is implemented in the class Office365Connector in the package net.atos.dirx.dxi.connector.azure.

The connector implements the common methods for the DirX Identity Connector API: add, modify, delete, and search.

The operations are simply converted to the Graph API requests. The corresponding responses are again translated to SPMLv1 responses.

The Microsoft Graph API is a Representational State Transfer (REST)-ful service comprised of endpoints that are accessed using standard HTTP requests. The connector uses JavaScript Object Notation (JSON) content types for requests and responses.

The connector communicates using SSL/TLS only.

Prerequisites

The connector is based on Microsoft Graph API version 1.0. The connector functionality is limited by the functionality of the Graph API version in use. The functionality with other Graph API versions cannot be guaranteed.

The connector appends a JSON Web Token (JWT) in the Authorization header of the request. This token is acquired by making a request to the OAuth endpoint and providing valid credentials. The connector supports the use of the OAuth 2.0 service only using a valid symmetric key (Application Secret).

The connector supports common Microsoft 365 user objects (common attributes and navigation properties memberOf and manager), Microsoft 365 group objects (common attributes only), Microsoft 365 role objects (common attributes only) and Microsoft 365 subscribedSku objects (common attributes).

The user navigation properties memberOf and manager can be written or read only as common objectId values (for example, 0ab8ac77-b07a-46ce-a3f6-42a03c5bed6b).

The connector can handle only one valid license for Microsoft 365 (subscribed sku).

The connector does not support nested group assignment. Nested group assignments cannot be read or written.

Configuration

The connector receives its configuration from the Connector Framework in a format that is specified there and reflects an XML document. Note that DirX Identity Manager presents configuration options in a more convenient way. For example, bind credentials and service addresses are typically collected from appropriate LDAP entries found by selecting the appropriate connected directory and bind profile.

This section discusses the configuration options based on the XML format. These options are either specified attributes in the XML schema of the element <connection> (referred to as standard properties) or specified as <property> subelements of the <connection> element (referred to as non-standard properties).

The connector evaluates the following standard properties:

server: required. This property provides information about the host name or IP address of the Graph API endpoint. An example is graph.microsoft.com.

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

user: 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. An example is 76c6e05b-d989-43a9-ab30-6f6a9a765c71.

password: required. The password is used as a symmetric key for communication between the Microsoft 365 connector and an OAuth service. An example is 6n2VHFRryIyXlrYCelROtAEJBeiKhhtpwBiX/vp9yO0=.

type: required. This is the Directory Type, for example, Microsoft 365.

The Microsoft 365 connector evaluates the following non-standard properties beneath the <connection> element:

authEndpoint: required. This property is the full URL of the OAuth service. The URL format is https://OAuthServer/TenantID/OAuthPath. An example value is https://login.microsoftonline.com/10ff036f-b6ae-462d-82cb-a7cad3b876c3/oauth2/token.

path: 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. An example is https://graph.microsoft.com/v1.0/groups.

proxyHost: 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: 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.

Here is a sample configuration using some of the properties described here:

<connector className="net.atos.dirx.dxi.connector.azure.Office365Connector" name="TS" role="connector">
    <connection password="ZEbMo0Uh/7tbYwUb89HUZ9bLNHABcJ9ELNHfUqsmQCo=" server="graph.microsoft.com" ssl="TRUE" type="Office 365" user="def623cc-bac4-41ab-88ca-bea388941262">
         <property name="proxyHost" value="proxy-emea.my-it-solutions.net"/>
         <property name="proxyPort" value="84"/>
         <property name="authEndpoint" value="https://login.microsoftonline.com/10ff036f-b6ae-462d-82cb-a7cad3b876c3/oauth2/token">
         </property>
         <property name="path" value="v1.0"/>
    </connection>
</connector>

Creating Azure AD Groups

The following Microsoft Azure AD groups can be created/managed via the Microsoft365 connector using the Microsoft Graph API:

  • Microsoft 365 groups (Public, Private, HiddenMembership)

  • Security groups

For more information about these groups, see the document:

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

You can use DirX Identity Manager to create these groups on Microsoft Azure AD. For example:

Creating a Group in DirX Identity Manager
Figure 1. Creating a Group in DirX Identity Manager

Note the following limitations:

  • Group Type cannot be changed after group creation.

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

Mail-enabled security groups and distribution lists can’t be created through the Microsoft Graph API. Microsoft recommends migrating them to Microsoft 365 Groups to achieve the Graph API functionality. For more information, see the document:

https://docs.microsoft.com/en-us/microsoft-365/admin/manage/upgrade-distribution-lists?redirectSourcePath=%252fde-de%252foffice%252f787d7a75-e201-46f3-a242-f698162ff09f&view=o365-worldwide

For details about Microsoft Graph API, refer to the following Microsoft documents:

Graph REST API Reference: https://docs.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0

Working with users in Microsoft Graph: https://docs.microsoft.com/en-us/graph/api/resources/users?view=graph-rest-1.0

Working with groups in Microsoft Graph: https://docs.microsoft.com/en-us/graph/api/resources/groups-overview?view=graph-rest-1.0

Properties Request Body for Creating Groups

The following group resource properties are required when creating a group:

  • displayName - a string that specifies the name to display in the address book for the group. This property is required.

  • mailEnabled - a boolean value that is set to true for mail-enabled groups.

  • mailNickname - a string that specifies the mail alias for the group. Maximum string length is 64 characters.

  • securityEnabled - a boolean value that is set to true for security-enabled groups, including Microsoft 365 groups.

Groups created using the Microsoft Azure portal always have securityEnabled initially set to true.

The following optional group resource properties can also be used when creating a group:

  • description - a string that specifies a description for the group. The maximum string length is 1024 characters.

  • owners - a string collection that represents the group owners at creation time.

  • members - a string collection that represents the group members at creation time.

  • visibility - a string that specifies the visibility of an 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.

For more information about the group resource type, see https://docs.microsoft.com/en-us/graph/api/resources/group?view=graph-rest-1.0.

For more information about required and optional properties of a create group request body, see: https://docs.microsoft.com/en-us/graph/api/group-post-groups?view=graph-rest-1.0&tabs=http.

groupTypes Property Options

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

https://docs.microsoft.com/en-us/graph/api/group-post-groups?view=graph-rest-1.0&tabs=http

Microsoft 365 Connector does not support groupTypes=“DynamicMembership”.

DirX Identity dxrType Values

The following table shows the DirX Identity dxrType values for the supported Azure AD groups:

Group Type Attribute Values dxrType Value

Security Group

securityEnabled=true; mailEnabled=false

securityGroup

Microsoft 365 - Public

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

officeGroupPublic

Microsoft 365 - Private

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

officeGroupPrivate

Microsoft 365 - HiddenMembership

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

officeGroupHiddenMembership

Filtering Azure AD Objects

The Microsoft 365 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:

Setting a Filter for an Azure AD Object in DirX Identity Manager
Figure 2. Setting a Filter for an Azure AD Object in DirX Identity Manager

The following limitations apply:

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

  • The $filter query parameter does not support all AD object properties.

  • Not all AD object properties support filter queries.

  • In DirX Identity Manager, not all AD 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.

The following example uses the startswith $filter query function to find users whose display name starts with the letter “J”:

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 Azure AD user and group resources and how they correspond to DirX Identity and DirX DSML operators:

Graph API Azure AD 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

is 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

is 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’)

begins 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 (and)

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

and

<filter><dsml:and>…

or (or)

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

or

<filter><dsml:or>…

not (not)

unsupported

not

<filter><dsml:not>…

As shown in the table, the $filter operators ne, gt, lt and not are not supported for Azure AD resources. The contains string operator is currently not supported on any Microsoft Graph resource. For more information about about query parameters, see the Microsoft documentation at https://docs.microsoft.com/en-us/graph/query-parameters.

Not every Azure AD user and group object property supports filter query. Check the documentation for the resource to see which property is filterable:

User resource: https://docs.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0

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

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 an Azure AD directory role (also called an administrator role).

Only the equality match filter operator is supported for this resource type. For example:

…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.

In the following example, the string value let''s meet for lunch? has the single quote escaped:

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

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 365 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 365 connector.

Here is an example:

Microsoft 365 Connector Paging Defaults
Figure 3. Microsoft 365 Connector Paging Defaults