Creating a basic integration for LDAP users

The LDAP user load fetches user data from an LDAP directory server. This process not only retrieves essential user details but also provides insights into their permission levels within the server. With this visibility, managing and monitoring user activities within the LDAP environment becomes more streamlined and transparent.

Connect Oomnitza and LDAP in minutes

Get the information and insights that you need to reduce costs and the time that you spend on administration tasks such as:

• Configurable dashboards and list views of key user information, including the user name, email, and permissions.
• Configurable reports to share information about users with your colleagues and management such as corporate-wide reports that detail the distribution and status of the devices in your environment

Note on the LDAP basic integration

This integration is a local basic integration, which means that it needs to be managed on your local machine. You'll need to prepare your local environment beforehand, download the Oomnitza connector, update a configuration file, and push it to your Oomnitza instance. Finally, you'll need to manage the scheduling of your basic integration on your local machine (using tools such as Task Scheduler for example). 

Before you start

To stream asset data from LDAP to Oomnitza, you must complete these tasks:

1. Check your system requirements. See here. 
2. Download and install Python 3.8. See Installing the connector or our GitHub documentation for more information. Our documentation recommends creating a virtual environment. A virtual environment is created on top of an existing Python installation and may be isolated from the packages in the base environment, so only those explicitly installed in the virtual environment are available.

Download the source code for the Oomnitza connector

1. Log into Oomnitza.
2. Click Configuration > Integrations and click Block view
3. In the Basic section for User Integrations, click the Active Directory tile.
4. Download the source code and place it in a directory, such as C:\oomnitza_connector 

You can also download the source code on the Oomnitza Connector page on GitHub.

Installing the requirements

In the directory you created (C:\oomnitza_connector), install the required Python dependencies stored in the requirements.txt file using pip install -r requirements.txt

Tip
Run pip install --upgrade pip before installing and use the new version of pip

Generate the configuration file

In the same directory, runpython connector.py generate-ini to generate theconfig.inifile. For further information read the Connector Configs section in the Getting started document.

Tip
Run python connector.py --help to see all available command line options.

Edit the configuration file

You must modify the following sections in the configuration file:

• The Oomnitza section
• The LDAP section

Before you edit the configuration file, you must retrieve the following information:   

Your Oomnitza token which can be created in Configuration > Security > API tokens

Your LDAP details

1. Open the configuration file that you generated in edit mode.
2. In the Oomnitza section, enter the URL of your Oomnitza instance and enter the API token that you generated in Oomnitza. 
   

   Oomnitza configuration settings 
   [oomnitza]
url= https://<name_of_instance>.oomnitza.com 
api token = <my_Oomnitza_token> 

3. In the LDAP section, make the following changes:
   • Required
   • Set enable to True.
   • URL: The LDAP URL.  The format of the URL is as follows: ldap://servername:port. The standard default port for LDAP is 389.
   • Username. The LDAP username. Can be the common name of the user, for example, cn=John Doe
   • Password: The password of the user.
   • Base DN:  The domain, for example, dc=example belongs to the domain example.local
   • Protocol Version: The LDAP protocol version, defaults to 3.
   • Filter: Filters can be used to restrict the numbers of users or groups that are permitted to access an application. For example, (objectClass=*) will load all objects. See How to write LDAP search filters
     
   • Default Role: The numeric ID of the role which will be assigned to imported users.
   • Default Position: The default position that will be assigned to imported users, such as Admin or Employee.
   • Optional
   • Group DN: The user or group DN can be added onto the base DN, and will be used as the starting place to look for users and groups. If this value is defined, the base_dn is ignored
   • Groups DN = A list of groups to which the users belong. If this value is defined, the group_dn and base_dn are ignored.
   • Group Members Attribute= The name of the attribute in LDAP that links the record in the group with the group. Typically, this value is called "member".
   • Group Member Filter= The additional filter used to extract the details of the user in the group. Empty by default.
   • Page Criterium = To be used if LDAP does not support pagination.

   LDAP settings 
   [ldap]
   enable = True
   url = ldaps://ldap.com:389
   username = cn=read-only-admin,dc=example,dc=com
   password =
   base_dn = dc=example,dc=com
   group_dn =
   protocol_version = 3
   filter = (objectClass=*)
   default_role = 25
   default_position = Employee
   groups_dn = []
   group_members_attr = member
   group_member_filter =
   page_criterium=

4. You can delete all the other configurations you do not need from the list, i.e. Kace, LDAP etc.
5. Save your changes.

Mappings

You can define the mappings in the configuration file, as follows:

[ldap]
enable = False
url = ldaps://ldap.com:389
username = cn=read-only-admin,dc=example,dc=com
password =
base_dn = dc=example,dc=com
protocol_version = 3
filter = (objectClass=*)
default_role = 25
default_position = Employee
mapping.1234567* = {'source': "givenName"}
sync_field = 1234567*, EMAIL

Replace 1234567 with the ID of the Oomnitza field. You can find the External ID by navigating to Configuration > Data Model > Field Configuration > Users in your Oomnitza instance. Locate your field in the list. The ID is displayed in the Field Information tab.

Contact Support for more information.

Run the LDAP network devices connector

To upload the LDAP information to Oomnitza, run the connector.

Run the connector in test mode to ensure that the mapped information is uploaded to Oomnitza:

python connector.py upload ldap --testmode

When you are confident that you are uploading the information that you mapped, run the connector again in normal mode:

python connector.py upload ldap

Getting your results

1. Click Configuration > Integrations and click Block view
2. In the Basic section for User Integrations, click the Active Directory tile.
3. Click SYNC SESSIONS.
4. Go to the People page and review the information that is uploaded.

Schedule
To find out how to schedule the LDAP integration, contact Support or see Installing the connector

Unleash the power of Oomnitza

To get valuable actionable insights that help you manage your assets, learn how to:

• Configure dashboards for your assets
• Configure custom reports about your assets 

See Getting started.