LDAP

The LDAP import agent for Elimity Insights queries your on-premise LDAP servers and uploads the results to your Elimity Insights server. You configure the LDAP connections, the queries to execute, the expected result schema and the connection with your Elimity Insights server. The import agent will then connect to your LDAP servers, execute the configured queries, transform the results to a format compatible with Elimity Insights and send the transformed data to your Elimity Insights server.

Installation

The import agent is available as a Docker image for Linux and Windows. Refer to the dedicated knowledge base article for all details about working with agents and gateways. Visit https://console.cloud.google.com/artifacts/docker/elimity-general/europe-west1/docker/ldap-import-agent to get a list of available image tags for this specific agent.

Generic usage

Running the import agent with the `-h` option prints a generic usage message:

$ docker run --rm europe-west1-docker.pkg.dev/elimity-general/docker/ldap-import-agent:<tag> -h
Usage of elimity-insights-client-ldap:
  -print-config-schema
      print a JSON schema definition for the configuration file and exit
  -print-data-model-export
      print a data model export file for creating a custom source in Elimity Insights and exit
  -print-example-config
      print an example JSON configuration and exit

Step-by-step deployment guide

The following sections will explain the different steps you'll need to take to deploy the LDAP agent for Elimity Insights.

1. Configuring the agent

To configure your import agent, mount a JSON configuration file at `/app/config/config.json` with the properties listed below. You can find an example in the attachments at the bottom of this page.

This example configuration will simply import all users and groups from an Active Directory server. You can leave the file mostly untouched if you want to try this standard import. Edit the following properties in this file to configure the import agent to your needs:

• `cronPattern`: optional CRON pattern describing when the import agent should run (refer to https://crontab.guru for example patterns); omit if you just want to run the agent once
• `entityTypes`: a list of configuration objects describing how to import entities of a specific type into Elimity Insights
  • `attributes`: a list of configuration objects describing how to import attributes of this entity type's entities
    • `attribute`: identifier of the attribute to read from the LDAP server 
    • `description`: description of the attribute type in Elimity Insights (*) 
    • `id`: unique identifier of the attribute type for which the agent should import assignments
    • `name`: human-readable name of the attribute type (*)
    • `syntax.type`: LDAP syntax of the attribute type, one of `boolean`, `enum`, `flag`, `generalizedTime`, `integer`, `interval`, `multiString`, `sid` or `string`
      • for attributes with syntax `enum`:
        • `syntax.default`: fallback value if none of the bitmasks match 
        • `syntax.options`: object mapping enum member names to bitmasks
      • for attributes with syntax `flag`:
        
        • `syntax.cmp`: boolean value to compare with the masking result
        • `syntax.mask`: the agent will check whether the attribute value matches this mask
      • for attributes with syntax `multiString`:
        • `syntax.delimiter`: delimiter to use for joining the attribute values into a single string
  • `icon`: icon of the entity type (*) 
  • `id`: unique identifier of the entity type for which the agent should import entities
  • `plural`: plural form of the entity type's name (*)
  • `searchRequests`: queries that the import agent should send to the configured LDAP server, each resulting entry corresponds to an entity of this type
    • `baseDn`: specifies the base of the subtree in which the search is to be constrained
    • `filter`: specifies criteria to use to identify which entries within the scope should be returned
    • `scope`: one of `base`, `oneLevel` or `subtree`
  • `singular`: singular form of the entity type's name (*)
• `insightsSourceId`, `insightsSourceToken`: you can leave these properties untouched for now, we'll come back to them later
• `insightsUrl`: URL of your Elimity Insights server
• `ldapUrl`: URL of your LDAP server, e.g. `ldap://my-host:389` or `ldaps://my-secure-host:636`
• `ldapUsername`: username for authentication with the LDAP server
• `ldapPassword`: password for authentication with the LDAP server
• `relationshipTypes`: a list of configuration objects describing how to import relationships between entities of two specific types into Elimity Insights
  • `from`: unique identifier of the entity type from which the relationships start
  • `to`: unique identifier of the entity type where the relationships end
  • `targetAttribute`: LDAP attribute to filter on when searching `to` entities (e.g. `memberOf` when searching relationships from users to groups)

Properties marked with a (*) do not affect the importing functionality, they are only necessary to generate a data model export file when running the import agent with the `-print-data-model-export` flag.

2. Creating a custom source in Elimity Insights

The import agent also includes some functionality to help you with creating a source in Elimity Insights. Assuming you correctly configured the properties marked with a (*) in the previous section, the following command will write a data model export file to `data-model-export.json`:

$ docker run -v ./config:/app/config --rm europe-west1-docker.pkg.dev/elimity-general/docker/ldap-import-agent:<tag> -print-data-model-export > data-model-export.json

You can now upload this file to Elimity Insights when creating a new custom source. Copy the resulting source's identifier and token to the `insightsSourceId` and `insightsSourceToken` properties in the agent's configuration file.

3. Deploying the agent

Having configured the agent and having created a source in Elimity Insights, you can now deploy the agent to regularly import data from your LDAP server and upload it to Elimity Insights. Since we distribute the agent as a Docker image, our recommendation for deployment is to use your cloud provider’s dedicated job execution platform (e.g. Google Cloud Run, Azure Container Apps, …). If that's not an option, you can also manually deploy the image on e.g. Windows Server. Refer to the dedicated knowledge base article about installing import agents for additional details.

4. Following up on the import

The import agent should start outputting some logs to indicate its progress, for a manual Windows Server deployment you can check these with `docker-compose logs ldap-import-agent`.