Step-by-step deployment guide
1. Configuring the agent
To configure your import agent, mount a JSON configuration file at /app/config/config.json with the properties listed below. Refer to the following attachment for a starting point:
This example configuration will simply mimic the import functionality of Elimity Insights' built-in connector for Active Directory. Edit the following properties in your file to configure the import agent to your needs:
cronPattern
string
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
list[object]
Describes how to import entities of a specific type into Elimity Insights
entityTypes[].attributes
list[object]
Describes how to import attributes of this entity type's entities
entityTypes[].attributes[].attribute
string
Identifier of the attribute to read from the LDAP server
entityTypes[].attributes[].id
string
Unique identifier of the attribute type for which the agent should import assignments
entityTypes[].attributes[].description*
string
Description of the attribute type
entityTypes[].attributes[].name*
string
Human-readable name of the attribute type
entityTypes[].attributes[].syntax
object
Describes how to parse the LDAP attribute
entityTypes[].attributes[].syntax.cmp
boolean
Value to compare with masking result; only applicable if syntax.type is "flag"
entityTypes[].attributes[].syntax.default
string
Fallback value if none of the configured bitmasks match; only applicable if syntax.type is "enum"
entityTypes[].attributes[].syntax.delimiter
string
Delimiter to use for joining the attribute values into a single string; only applicable if syntax.type is "multiString"
entityTypes[].attributes[].syntax.mask
number
Mask to apply before comparing with syntax.type.cmp; only applicable if syntax.type is "flag"
entityTypes[].attributes[].syntax.options
record[number]
Record mapping enum member names to bitmasks for matching; only applicable if syntax.type is "enum"
entityTypes[].attributes[].syntax.type
string
LDAP syntax for the attribute type, one of boolean, enum, flag, generalizedTime, integer, interval, multiString, sid or string
entityTypes[].icon*
string
Icon of the entity type
entityTypes[].id
string
Unique identifier of the entity type for which the agent should import entities
entityTypes[].plural*
string
Plural form of the entity type's name
entityTypes[].searchRequests
list[object]
Requests that the import agent should send to the configured LDAP server, each resulting entry corresponds to an entity of this type
entityTypes[].searchRequests[].baseDn
string
Specified the base of the subtree in which the search is to be constrained
entityTypes[].searchRequests[].filter
string
Specified criteria to identify which entries within the scope should be returned
entityTypes[].searchRequests[].scope
string
One of "base", "oneLevel" or "subtree"
entityTypes[].singular*
string
Singular form of the entity type's name
insightsSourceId
number
Elimity Insights source identifier; we'll create one in step 2
insightsSourceToken
string
Elimity Insights source token; we'll generate one in step 2
insightsUrl
string
URL of your Elimity Insights server
ldapUrl
string
URL of your LDAP server, e.g. ldap://my-host:389 or ldaps://my-secure-host:636
ldapUsername
string
Username for authentication with the LDAP server
ldapPassword
string
Password for authentication with the LDAP server
relationshipTypes
list[object]
Describes how to import relationships between entities of two specific types into Elimity Insights
relationshipTypes[].from
string
Unique identifier of the entity type from which the relationships start
relationshipTypes[].targetAttribute
string
LDAP attribute to filter on when searching to entities (e.g. "memberOf" when searching relationships from users to groups)
relationshipTypes[].to
string
Unique identifier of the entity type where the relationships end
*These properties 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 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 agent as explained in the previous step, the following command will write a data model export file to 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 a CaaS solution like Google Cloud Run or Azure Container Apps. If that's not an option, you can also manually deploy the image on e.g. Windows Server. Refer to our documentation about gateways and import agents for additional details.
4. Following up on the import
The import agent outputs logs to indicate its progress, for a manual Windows Server deployment you can check these with docker-compose logs.
Last updated