Step-by-step deployment guide
1. Setting up an LDAP proxy
Each deployment of the Elimity Insights gateway for LDAP should communicate with an instance of the Elimity Insights LDAP proxy, as depicted in the diagram below:
The proxy simply relays connections to your LDAP server, the actual connection parameters (e.g. hostname, user, password) reside in gateway configuration. Refer to the documentation about our LDAP proxy for detailed setup instructions.
Note down your proxy's URL.
2. Configuring the gateway
The first step in setting up automatic imports via an LDAP gateway is configuring the gateway itself. As usual, please make sure your instance of Elimity Insights can reach the gateway and that the gateway can reach your LDAP proxy.
To configure your gateway, mount an HJSON configuration file at /app/config/config.hjson with the properties listed below. The following snippet provides a good starting point:
Edit the following properties in this file to configure the gateway to your needs:
jwtValidationAudiences
option[list[string]]
Audiences for JWT validation, defaults to ["gateway"]
jwtValidationBaseUrl
string
Expected Elimity Insights base URL for JWT validation, e.g. "https://example.elimity.com"
jwtValidationGatewayUrl
string
Expected gateway URL for JWT validation, e.g. "https://gateway.example.com"
jwtValidationIssuer
option[string]
Issuer for JWT validation, defaults to "https://auth.elimity.com/"
jwtValidationExpr
option[string]
Expr program implementing JWT custom claim validation, defaults to "claims.base_url == baseURL && claims.gateway_url == gatewayURL && claims.source_id == sourceID"
jwtValidationOptional
option[boolean]
Flag indicating whether JWT validation is optional, defaults to false
jwtValidationSourceId
string
Expected source id for JWT validation, e.g. "42"
ldapCaCertsData
option[string]
Optional PEM-encoded SSL certificates to override the LDAP proxy's trust store
ldapPassword
string
Password for LDAP simple bind
ldapProxyUrl
string
HTTP(S) URL of the proxy you set up in step 1
ldapServer
string
Hostname, IP or URL of the LDAP server you want to import from
ldapUser
string
User for LDAP simple bind
JWT validation
We highly recommend requiring JWT validation to secure your gateway. Please read our official documentation about the following topics to understand how Elimity Insights authenticates to gateways via OAuth2:
Our SaaS customers can simply set the jwtValidationBaseUrl, jwtValidationGatewayUrl and jwtValidationSourceId configuration options, which provides the following security guarantees:
Only requests coming from the configured Elimity Insights are allowed
Only requests targeting the configured gateway URL are allowed
Only requests for importing the configured source are allowed
On-premise customers should additionally set the jwtValidationAudiences, jwtValidationIssuer and jwtValidationExpr configuration options. Alternatively you can also set jwtValidationOptional to true and perform authentication in a proxy instead.
3. Deploying the gateway
Since we distribute the gateway 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. Creating a custom source in Elimity Insights
To set up automatic imports via the LDAP gateway we need to create a custom source in Elimity Insights itself first. If you're unsure about the data model then we recommend to start with just a single entity type. You can simply extend the data model later on.
5. Enabling automatic imports
Having created the new custom source, you can now navigate to its detail page in Elimity Insights and open the 'CONFIG' tab. Click the 'EDIT' button and enter your gateway's URL and the desired CRON schedule. For Elimity Insights server versions matching >=3.46.0, set the SDK version to 1. Also add the following configuration values:
entityTypes
JSON
JSON array describing how to import entities from your LDAP server; refer to the dedicated section below for more information
ignoreSearchResultReferences
JSON
JSON boolean indicating whether to ignore search result references instead of failing the import when receiving them from the LDAP server, defaults to false
relationshipTypes
JSON
JSON array describing how to import relationships from your LDAP server; refer to the dedicated section below for more information
Entity types
For each item in the entityTypes configuration value, the gateway will perform searches in your LDAP server, convert the results into entities and send those to Elimity Insights. Refer to the snippet below as a starting point:
More specifically, the entityTypes configuration value should be a JSON array of objects, where each object should have the following properties:
attributes
list[object]
Describes how to import attributes of the entity type's entities
attributes[].assignedExpr
option[string]
Expr program to determine whether the attribute is assigned, defaults to "true"; refer to the dedicated section below for more information
attributes[].id
string
Unique identifier of the attribute type for which the gateway should import assignments
attributes[].type
string
Data type of the attribute type, one of "boolean", "date", "dateTime", "number", "string" or "time"
attributes[].valueExpr
string
Expr program to determine the attribute assignment's value; refer to the dedicated section below for more information
extraSearchBases
option[list[string]]
Optional additional base DNs for LDAP search requests; defaults to []
id
string
Unique identifier of the entity type for which the gateway should import entities
nameExpr
string
Expr program to extract the entity name from an LDAP search result; refer to the dedicated section below for more information
searchBase
string
Base DN for the LDAP search request
searchFilter
string
Filter for the LDAP search request
Relationship types
For each item in the relationshipTypes configuration value, the gateway will iterate over all possible combinations of entities, creating relationships for those that match the configured predicate. Refer to the snippet below as a starting point:
More specifically, the relationshipTypes configuration value should be a JSON array of objects, where each object should have the following properties:
fromEntityTypeId
string
Unique identifier of the entity type from which the relationships start
expr
string
Expr program to determine whether the gateway should create a relationship for a given combination of entities; refer to the dedicated section below for more information
toEntityTypeId
string
Unique identifier of the entity type where the relationships end
Expr programs
Each of the attributes[].assignedExpr, attributes[].valueExpr and nameExpr properties in the entityTypes items must represent a valid Expr program for which Elimity Insights injects the following variables:
attributes
map[string]any
Map containing all attributes of the LDAP search result
dn
string
DN of the LDAP search result
For the expr property in relationshipTypes items we inject from and to variables instead, these have their own attributes and dn fields as described above.
The programs for attributes[].assignedExpr and nameExpr in entityTypes items should have result types bool and string respectively. For attributes[].valueExpr, the expected result type depends on attributes[].type:
"boolean"
bool
"date", "dateTime", "time"
int64 (Unix time)
"number"
float64
"string"
string
Programs for expr in relationshipTypes items should have result type bool.
The value type for entries in the attributes map depends on the LDAP attribute's syntax, the table below lists some examples:
Boolean
bool
Integer
int64
Directory String
string
Generalized Time
time.Time
Additionally, if the LDAP attribute type is multi-valued, then Elimity Insights injects an array of values instead of a single one.
Last updated