Usage Manual
This page describes how the connector can be used and configured.
Prerequisites
- Network access from the CMDBuild server to the LDAP server, using the URL set in the instance configuration (for example
ldap://localhost:389). - The credentials of an account on the LDAP server, expressed as the Distinguished Name (DN) of the account (
principal) and its password (credentials). - The authentication method used to bind to the server (
none,simpleorsasl_mech; see Instance configuration). - The permissions listed below.
The account used by the connector must be allowed to perform the following operations:
Bind to the server with the configured authentication method
Search the entries under every Base DN set in the configured queries
Read the attributes of the entries returned by the queries
Use the paged results control (the connector requests the results in pages)
Connector dependencies
The connector requires the installation of the Connector utils plugin version 2.0.8 or higher and CMDBuild version 4.2.0 or higher.
Configuration
Plugin configuration
The standard connector plugin configuration can be found here.
In addition, the following plugin configuration is available:
| Config | Default | Description | Notes |
|---|---|---|---|
recordTypesValues | user,group,ou | The record types that can be selected in the configuration of the instance queries. | Comma-separated list. Only alphanumeric characters, underscore and hyphen are allowed in values. |
Instance configuration
Each LDAP server to read from is configured as an instance (LDAPConfig card).
| Config | Default | Description | Notes |
|---|---|---|---|
Code* | Unique code that identifies the instance. | ||
Active* | Whether the instance is read by the connector. | ||
Url* | URL of the LDAP server. | For example ldap://localhost:389. | |
Authentication | simple | The security authentication method used to bind to the server. | Accepted values: none (no authentication, anonymous access), simple (clear-text username and password), sasl_mech (space-separated list of SASL mechanism names, e.g. DIGEST-MD5 CRAM-MD5, GSSAPI). |
Principal* | The Distinguished Name (DN) of the account used to bind to the server. | ||
Credentials* | The password of the account. It is stored encrypted and decrypted by the connector. | ||
Referral | Ignore | How the LDAP referrals are handled. | Accepted values: Ignore, Follow, Throw. |
Page size | 500 | Number of records requested per page in the paged searches. | The same page size is used for every query of the instance. When empty or 0 the default is used. |
Queries* | The list of searches to execute on the server. | Managed through the Queries widget of the instance card. At least one query is required. See the table below. |
Queries
Each query represents a single search on the LDAP server and produces records of one record type. The queries are managed in the instance card through the Queries widget, which shows one tab per query.
| Config | Default | Description | Notes |
|---|---|---|---|
Query name | Query N | The name of the query. | If empty, a name is assigned automatically. |
Active | Whether the query is executed. | Only the active queries are executed. | |
Base DN* | The base DN of the search. | For example dc=example,dc=com. | |
Filter* | The LDAP search filter. | For example (objectClass=inetOrgPerson). | |
Returning attributes | The list of attributes to return. | Comma-separated list. When empty, all the attributes are returned. | |
Scope | Subtree | The scope of the search. | Accepted values: Object, One level, Subtree. |
Record type* | The type of the records obtained by the query. | One of the values set in the recordTypesValues plugin configuration. The standard import handles user (imported in LDAP User), group (LDAP Group) and ou (LDAP Organizational unit). | |
Key attribute | dn | The LDAP attribute whose value is used as the key of the record. | The key identifies the record within the instance. |
Notes | Free notes on the query. |
Entities preview
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.
The connector does not manage relationships between the entities.
Below is a list of all the entities retrieved by the connector.
- User (
user) - Group (
group) - OU (
ou)
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 Subscription 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.