Skip to main content
Version: 4.3

Usage Manual

This page describes how the connector can be used and configured.

Prerequisites​

The connector requires network access (HTTPS) from the CMDBuild server to the following Microsoft endpoints:

  • https://login.microsoftonline.com, used to obtain the access token;
  • https://graph.microsoft.com, used to read the directory data through the Microsoft Graph v1.0 API.

Only the Microsoft Entra ID global (public) cloud is supported: the authority host and the Microsoft Graph endpoint are not configurable.

A Microsoft Entra ID application registration must be provided for each connector instance. The connector authenticates with the OAuth 2.0 client credentials flow (application-only access, client secret) and requires the following values:

  • Tenant ID
  • Client ID
  • Client secret

The application must be granted the following Microsoft Graph application permissions:

GroupMember.Read.All
User.Read.All

User.Read.All is used to list the users and their manager; GroupMember.Read.All is used to list the groups and their members. Group.Read.All can be granted instead of GroupMember.Read.All.

Service configuration​

Create an application registration in Microsoft Entra ID and add a client secret to it.

Grant the application the Microsoft Graph application permissions described in the previous section (User.Read.All and GroupMember.Read.All, or Group.Read.All instead of GroupMember.Read.All), then grant admin consent for them.

Record the Tenant ID, Client ID, and client secret, as these values are required in the connector instance configuration.

Connector dependencies​

The connector requires the installation of the Connector utils plugin version 2.0.8 or higher and CMDBuild version 4.3.0 or higher.

Configuration​

Plugin configuration​

The standard connector plugin configuration can be found here. This plugin has no additional configurations.

Instance configuration​

ConfigDefaultDescriptionNotes
Code*Unique name used to identify the connector instance.Used in executions, logs, notifications, and data source references.
Active*trueDefines whether the instance is included in connector batch executions.
Tenant ID*Identifier of the Microsoft Entra ID tenant from which data is retrieved.
Client ID*Application (client) ID of the Microsoft Entra ID application registration used by the connector.
Client secret*Client secret associated with the configured application registration.Stored as a password attribute.

Entities preview​

100%

The diagram provides a high-level overview of the entities extracted by the connector and the relationships between them.

The diagram uses the following conventions:

  • Orange containers represent CMDBuild superclasses. The entities contained within them belong to the corresponding superclass.

  • Blue boxes represent record types extracted by the connector. Each box is labeled using the format {Source Object Name} ({_type}), combining the object name used by the source service with the internal record type produced by the connector.

  • Blue boxes with a dashed border represent calculated entities. These records do not directly correspond to objects exposed by the source system but are generated during data processing to represent information that would otherwise be embedded within another record.

  • Arrows represent relationships between entities managed by the connector. The arrow points to the "many" side of the relationship, as indicated by its label (1 : N).

Below is a list of all the entities retrieved by the connector.

  • User (user)
  • Group (group)
  • Group member (groupmemberrelation)

Additional Information​

Synchronization to Application Classes​

The standard connector imports and maintains data within the CMDBuild standard classes and relationships, providing a consistent representation of the data.

As a separate and optional customization activity, organizations may define additional synchronization processes to populate application-specific classes from the imported infrastructure data. Through custom mappings and enrichment rules, connector resources can be associated with organization-specific business objects, services, assets, or other application entities.

This approach supports customer-specific business models, enrichment processes, and classification rules while preserving the standard infrastructure representation provided by the connector.

Known Limitations​

  • The connector operates in read-only mode.
  • Large environments may require increased execution time.
  • No real-time synchronization: data is updated only during scheduled runs.
  • The plugin is distributed under a Premium license model. Its usage is tied to an active support and maintenance agreement, which is subject to expiration and must be renewed to remain valid.

Deployment Guidelines​

Deployment of the connector includes the creation of standard CMDBuild classes and relationships corresponding to supported connector resource types. These structures provide the foundation for storing and organizing synchronized infrastructure information. The deployment process also includes configuration elements required for data visualization and the establishment of scheduled synchronization activities.

Following deployment, it is recommended to validate the configuration by executing an initial synchronization and reviewing the imported data.

Scheduling frequency should be selected according to the scale of the environment, expected rate of infrastructure change, and operational reporting requirements.