> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt
> Use this file to discover all available pages before exploring further.
# LDAP/Active Directory
> Configures and manages LDAP and Active Directory connections. You can access corporate directories with SSL/TLS protected connections and pool management
## Overview
Centralizes Connection definitions, making the same LDAP access information reusable across all Integration Flow and Connector steps
Manages SSL/TLS and certificate requirements with enum-based policies, ensuring consistency in authentication processes
Narrows directory queries with Search Scope and customFilter fields, limiting unnecessary traffic and unauthorized attribute access
Enables sharing the same connection at the project or management console level through Environment selection and Move to Global feature
When an LDAP connection is requested from within an Integration Flow or Connector, the system reads the configured connection parameters
Gateway keeps LDAP sessions ready in the pool; opens a new connection if no suitable session exists for the selected environment
Binds to the target directory by performing certificate verification according to Username/password or requireCertificateType field
Search/query operations are executed over LDAP protocol according to searchScope and customFilter values
When the operation completes, the connection returns to the pool and waits for subsequent requests
In case of connection error, timeout, or authentication error, the result is written to deployment logs and a detailed message is shown to the user
Managing LDAP-based user authentication in Integration Flow steps through a single connection
Querying self-service portal or management console users from Active Directory/LDAP directory
Reading membership attributes to create group-based or organizational unit (OU) based authorization rules
Connecting to internal directories with certificate requirements via LDAPS to perform SSL/TLS audit
## Technical Features and Capabilities
Options are determined with EnumLdapRequireCertificateType as NOT\_REQUIRED, REQUIRED\_CN, or REQUIRED\_AN\_PN; when REQUIRED\_AN\_PN is selected, the certificateId field becomes mandatory.
LDAP queries are refined with EnumSearchScope (OBJECT, ONE\_LEVEL, SUBTREE) and customFilter combination.
Environment variables can be selected for Server Address, Username, Password, and Base DN fields to use hidden values.
Ability to define separate connection parameters for each environment (Development, Test, Production).
Activating or deactivating the Connection (enable/disable toggle). In passive state, the connection cannot be used but its configuration is preserved.
LDAP connection within a project can be moved to the management project via Move to Global action, making it available across all projects.
When pulling the certificate list, the revoked flag is checked, and revoked certificates are placed in a separate warning list.
After save or Test Connection operations, the deploymentResult dialog opens showing bind/log details.
Ability to validate connection parameters before saving via "Test Connection" button.
Exporting Connection configuration as a ZIP file. Importing to different environments (Development, Test, Production). Version control and backup capability.
Monitoring connection health, pool status, and performance metrics.
## Connection Parameters
**Description:** Connection name (must be unique)\
**Example Value:** `Production_LDAP`\
**Notes:** Should not start with space, special characters should not be used
**Description:** URI or host information of the LDAP server\
**Example Value:** `ldaps://directory.example.com:636`\
**Notes:** Can be selected with environment variable
**Description:** Determines certificate verification policy\
**Example Value:** REQUIRED\_CN\
**Notes:** If REQUIRED\_AN\_PN is selected, certificateId becomes mandatory
**Description:** Query depth (EnumSearchScope)\
**Example Value:** SUBTREE\
**Notes:** One of OBJECT, ONE\_LEVEL, or SUBTREE values is selected
**Description:** Distinguished name where searches will start\
**Example Value:** `ou=Users,dc=corp,dc=local`\
**Notes:** Environment variable can be used; cannot be left empty for validation
**Description:** Opens SSL/TLS channel for LDAPS communication\
**Default Value:** false\
**Recommended Value:** true (in Production environment)
**Description:** Service account to be used for bind operation\
**Default Value:** (Empty)\
**Recommended Value:** svc\_ldap\_reader or environment variable
**Description:** Password of bind account or secret reference\
**Default Value:** (Empty)\
**Recommended Value:** Secret Manager variable
**Description:** Additional LDAP filter expression\
**Default Value:** (Empty)\
**Recommended Value:** LDAP filter expression
**Description:** Identity of the certificate in Secret Manager\
**Default Value:** (Empty)\
**Recommended Value:** UUID (mandatory when REQUIRED\_AN\_PN is selected)
### Timeout and Connection Pool Parameters
**Description:** Maximum time to connect to LDAP server\
**Default:** 10000\
**Min:** 2000 | **Max:** 60000\
**Unit:** milliseconds
**Description:** Wait time for search/bind response\
**Default:** 30000\
**Min:** 5000 | **Max:** 120000\
**Unit:** milliseconds
**Description:** Maximum connections to keep open simultaneously\
**Default:** 20\
**Min:** 1 | **Max:** 50\
**Unit:** count
**Description:** Wait between failed bind attempts\
**Default:** 2000\
**Min:** 500 | **Max:** 10000\
**Unit:** milliseconds
## Usage Scenarios
**Situation:** Portal users log in via LDAP\
**Solution:** Server Address=ldaps\://auth.corp:636, Use SSL=true, Require Certificate Type=REQUIRED\_CN\
**Expected Behavior:** Users are verified with TLS-protected bind
**Situation:** Integration Flow needs to fetch users belonging to specific groups\
**Solution:** Group filter with Custom Filter\
**Expected Behavior:** Flow lists only relevant members
**Situation:** Admin page should share global LDAP definition\
**Solution:** Move to Global is executed, selectedEnvironmentId=manager\
**Expected Behavior:** Management console uses the same connection
**Situation:** Passwords are stored in Secret Manager\
**Solution:** Username and Password environment variable\
**Expected Behavior:** No need to update connection when password changes
**Situation:** Mutual TLS is required with internal PKI\
**Solution:** Require Certificate Type=REQUIRED\_AN\_PN, Certificate Id=UUID\
**Expected Behavior:** Bind is rejected without certificate verification
**Situation:** Hundreds of search calls per minute\
**Solution:** Pool Size=30, Connection Timeout=5000\
**Expected Behavior:** Connections are reused thanks to pool
## Connection Configuration
### Creating New LDAP Pool Connection
#### Configuration Steps
* Go to **Connection → LDAP Pool Connection** section from the left menu.
* Click the **\[+ Create]** button at the top right.
* The new LDAP Pool Connection creation form opens.
**Setting Enable Status (Active Status):**
* Find the **Enable Status** toggle at the top of the form.
* Set the toggle to **Active** position (active by default).
* If you want to make the Connection passive, set the toggle to **Passive** position.
* Passive connections cannot be used in Integration Flows but their configurations are preserved.
**Name - Mandatory Field:**
* Enter a unique connection name in the **Name** field.
* Name examples: `Production_LDAP`, `Test_LDAPConnection`, `Dev_LDAP_Auth`
* Name rules:
* Should not start with space
* Special characters should not be used (recommended: letters, numbers, underscore)
* Maximum 255 characters
* System automatically checks as you type:
* Green checkmark: Name is available
* Red X mark: Name already exists, choose a different name
**Description - Optional:**
* Enter a text describing the purpose of the connection in the **Description** field.
* Example descriptions:
* "Portal LDAP access"
* "Production environment Active Directory connection"
* "Dummy LDAP connection for test environment"
* There is a maximum 1000 character limit.
* This field can be left empty.
In the action button area at the top of the page, you can use the **\[\<> Variable]** button to select dynamic values, and with global variables, you can manage connection parameters with variable-based values instead of fixed values. For detailed information, review the [Dynamic Variables](/en/concepts/core-concepts/dynamic-variables) page.
* Find the **Environment** dropdown menu.
* Open the dropdown menu and select one of the following options:
* **Development**: For development environment
* **Test**: For test environment
* **Production**: For production environment
* Different connection parameters can be defined for each environment.
* Environment selection determines in which environment the connection will be active.
* Test Connection button remains disabled until environment is selected.
**Server Address - Mandatory:**
* Enter the LDAP server address in the **Server Address** field.
* Format: `ldaps://directory.example.com:636` or `ldap://directory.example.com:389`
* You can select environment variable
* Port 636 is used for LDAPS, port 389 for LDAP.
**Search Scope - Mandatory:**
* Select from the **Search Scope** dropdown menu:
* **OBJECT**: Searches only a single entry
* **ONE\_LEVEL**: Searches the first level of the specified OU
* **SUBTREE**: Searches entries in the entire subtree
* Select according to performance requirements.
**Base DN - Mandatory:**
* Enter the distinguished name where searches will start in the **Base DN** field.
* Example: `ou=Users,dc=corp,dc=local`
* Environment variable can be used
* Cannot be left empty for validation.
**Custom Filter - Optional:**
* Enter additional LDAP filter expression in the **Custom Filter** field.
* Example LDAP filter expression
* This field can be left empty.
**Require Certificate Type - Mandatory:**
* Select from the **Require Certificate Type** dropdown menu:
* **NOT\_REQUIRED**: Certificate verification not required
* **REQUIRED\_CN**: Common Name verification required
* **REQUIRED\_AN\_PN**: Alternative Name or Principal Name verification required
* When REQUIRED\_AN\_PN is selected, Certificate Id becomes mandatory.
**Certificate Id - Mandatory when REQUIRED\_AN\_PN is selected:**
* When **Require Certificate Type** REQUIRED\_AN\_PN is selected, the **Certificate Id** field becomes visible.
* Select the certificate from Secret Manager.
* Certificate ID is entered in UUID format.
**Use SSL - Optional:**
* Find the **Use SSL** checkbox.
* Check the checkbox for LDAPS communication.
* Should be set to true in Production environment.
**Username - Optional:**
* Enter the service account to be used for bind operation in the **Username** field.
* Example: `svc_ldap_reader`
* You can select environment variable
* This field can be left empty (anonymous bind).
**Password - Mandatory if Username is filled:**
* If **Username** is filled, the **Password** field becomes visible.
* Enter the password of the bind account.
* Secret Manager variable is recommended
* Password will appear masked for security reasons.
**Connection Timeout:**
* Enter the maximum time to connect to LDAP server in the **Connection Timeout** field.
* Default: 10000 milliseconds (10 seconds)
* Minimum: 2000, Maximum: 60000 milliseconds
**Request Timeout:**
* Enter the wait time for search/bind response in the **Request Timeout** field.
* Default: 30000 milliseconds (30 seconds)
* Minimum: 5000, Maximum: 120000 milliseconds
**Pool Size:**
* Enter the maximum number of connections to keep open simultaneously in the **Pool Size** field.
* Default: 20
* Minimum: 1, Maximum: 50
* Increase Pool Size value if traffic increases.
* Warning: Values higher than necessary may strain the target LDAP server.
**Bind Retry Interval:**
* Enter the wait time between failed bind attempts in the **Bind Retry Interval** field.
* Default: 2000 milliseconds
* Minimum: 500, Maximum: 10000 milliseconds
**Username/Password Security:**
* Link Username/password fields to secret manager variables.
* This way, there is no need to update the connection when the password changes.
**SSL/TLS Settings:**
* Keep SSL/TLS field mandatory in Production environment.
* Check the Use SSL checkbox.
* Use port 636 for LDAPS.
**Certificate Management:**
* Update the connection during certificate renewals.
* Update Certificate Id with the new certificate.
* Verify by running Test Connection.
* Find the **\[Test Connection]** button at the bottom of the form or at the top right corner.
* Button remains disabled until environment is selected.
* Click the button.
* System tests connection parameters:
* Connection is established to LDAP server
* Authentication is performed (if Username/Password is filled)
* Certificate verification is performed (if Require Certificate Type is active)
* Bind operation is tested
* Test result:
* **Successful**: Green confirmation message is displayed, such as "Connection test successful"
* **Failed**: Red error message is displayed, error details are shown
* Remember that overlay is shown during test for critical fields using environment variables.
* In case of error:
* Read the error message
* Check relevant parameters (Server Address, Base DN, Username, Password)
* Check firewall and network settings
* Check LDAP server health
* Fix parameters and test again until test is successful.
* Make sure all mandatory fields are filled.
* Verify that Test connection is successful (recommended).
* Click the **\[Save and Deploy]** button at the top right corner of the form.
* System saves the connection and deploys it to the selected environment.
* After successful save:
* You are redirected to the connection list page
* New connection appears in the list
* Connection becomes **Enabled** status
* Becomes available for use in Integration Flow and Connector steps
**Checklist (Before Saving):**
* Name field is unique and valid
* Server Address is filled
* Search Scope is selected
* Base DN is filled
* Require Certificate Type is selected
* Certificate Id is filled if REQUIRED\_AN\_PN is selected
* Environment is selected
* Test Connection is successful (recommended)
* All mandatory fields are filled
**Result:**
* Connection is successfully created and saved
* Becomes active in the selected environment
* Connection selection can be made in Integration Flow and Connector steps
* Is displayed and can be managed in the connection list
Connection successfully created! You can now use it in Integration Flow and Connector steps.
### Deleting Connection
Select **⋮ → Delete** from the row end menu or click the **\[Delete]** button on the connection detail page
**Check Before Deleting:** It may be used in Integration Flow or Connector steps. If necessary, assign an alternative connection. Take a backup with **Export** before deleting
Use **Disable** option instead of deleting. Connection becomes passive but is not deleted. Can be reactivated when needed
### Exporting/Importing Connection
In this step, users can export (export) existing connections for backup, moving to different environments, or sharing purposes, or import (import) a previously exported connection again. This operation is used to maintain data integrity in version control, transition between test and production environments, or inter-team sharing processes.
Select **⋮ → Export** from the action menu. ZIP file is automatically downloaded.
Click the **\[Export]** button on the connection detail page. ZIP file is downloaded.
Format: `Date-connection-LDAP Pool Connection-export.zip`\
Example: `13 Nov 2025-connection-Production_LDAP-export.zip`
* Connection JSON file
* Metadata information
* Dependency information (e.g., certificates, key store)
* Backup
* Moving between environments (Test → Prod)
* Versioning
* Team or project-based sharing
* Click the **\[Import LDAP Pool Connection]** button on the main list.
* Select the downloaded ZIP file.
* System checks: Is format valid? Is there a name conflict? Are dependencies available?
* Then click the **\[Import]** button.
**Scenario 1: Name Conflict** → Overwrite the old connection or create with a new name.
**Scenario 2: Missing Dependencies** → Create missing certificates or key stores first or exclude them during import.
### Connection Usage Areas
**Steps:**
1. Create the connection.
2. Verify the connection with **Test Connection**.
3. Save and activate with **Save and Deploy**.
4. Make sure the connection is in **Enabled** status
Connection is selected in steps like "LDAP Lookup", "Attribute Enrichment". The same connection can be shared by multiple Flows; Warning: changes affect all Flows
Scheduled jobs can perform directory queries at certain intervals. When the job is redeployed, current connection parameters are automatically used
Connection Test result is displayed in the deployment dialog. Bind DN and error codes are quickly read during troubleshooting
## Best Practices
**Bad:** Binding with domain admin account.\
**Good:** Creating a read-only service account.\
**Best:** Defining OU-based limited privilege service accounts and planning password rotation
**Bad:** Continuing to use expired certificates.\
**Good:** Manually tracking certificate expiration dates.\
**Best:** Setting up automatic alerts with Secret Manager and event log, renewing REQUIRED\_AN\_PN connections in advance
**Bad:** Selecting SUBTREE for every query.\
**Good:** Using ONE\_LEVEL for OU-based queries.\
**Best:** Determining scope according to usage scenario and reducing unnecessary attribute reads
**Bad:** Writing fixed username and passwords to the form.\
**Good:** Hiding with environment variable.\
**Best:** Feeding variables from Secret Manager and auditing access logs
**Bad:** Using the same connection parameters in all environments.\
**Good:** Creating separate connections for each environment.\
**Best:** Managing all environments in a single connection using Environment option, only changing environment during inter-environment transitions
**Bad:** Saving and deploying connection without testing.\
**Good:** Verifying with Test Connection before saving.\
**Best:** Testing after every parameter change, performing full integration test in test environment before moving to production
Warning: Do not leave Use SSL closed in Production environment; otherwise credentials are transmitted in plain text
When you move Connection to Global, make sure only authorized users can edit, otherwise all projects are affected
Do not log sensitive data; prevent data leakage by keeping Test Connection overlay closed
Store sensitive information such as username and password using environment variable or secret manager. Do not hardcode credentials in code or configuration files. Periodically update passwords
Always enable SSL/TLS in Production environment. Use self-signed certificates only in development environment. Track certificate expiration dates and renew on time
Allow only authorized users to change Connection configuration. Store connection change logs. Apply change approval process for critical connections
**Why to avoid:** Directory opens to all users, access traces are not kept.\
**Alternative:** Bind with read-only service account
**Why to avoid:** Performance decreases in large directories.\
**Alternative:** Select ONE\_LEVEL or OBJECT scope, narrow with customFilter
**Why to avoid:** Becomes vulnerable to man-in-the-middle attacks.\
**Alternative:** Set Require Certificate Type field to REQUIRED\_CN or REQUIRED\_AN\_PN according to corporate policy
**Why to avoid:** Test data can be written to production system, real users can be affected, security risk occurs.\
**Alternative:** Create separate connections for each environment, use environment parameter, separate connection names by adding prefix according to environment (Test\_, Prod\_)
**Why to avoid:** Connection constantly times out in network delays, Integration steps fail.\
**Alternative:** Adjust timeout values according to real usage scenarios, measure network latency and determine timeouts accordingly
**Why to avoid:** New connection is opened for every request, performance decreases, resource consumption increases, target system load increases.\
**Alternative:** Activate connection pool, adjust pool size according to traffic volume, set up pool monitoring
**Recommendation:** Use ONE\_LEVEL instead of SUBTREE, narrow OUs with customFilter.\
**Impact:** Number of entries sent to LDAP server decreases, response time shortens
**Recommendation:** Provide variables through Secret Manager cache.\
**Impact:** Parameter read time decreases, overlay is less visible for Test Connection
**Recommendation:** Schedule certificate renewals to coincide with maintenance window, deploy new certificateId in advance.\
**Impact:** Your security level is maintained without experiencing LDAPS interruption
**Recommendation:** Adjust pool size according to peak traffic (recommended: concurrent request count × 1.5), set idle connection timeouts, perform pool health check.\
**Impact:** Connection opening cost decreases by 80%, response times decrease, resource usage is optimized
**Recommendation:** Measure real network latency, adjust timeout values accordingly, avoid very low or very high timeouts.\
**Impact:** Unnecessary waits are prevented, fast fail-over is provided, user experience improves
**Recommendation:** Monitor connection pool usage, track timeout rates, perform connection health check, set up alerting.\
**Impact:** Problems are detected proactively, performance bottlenecks are identified early, downtime decreases
## Troubleshooting
searchScope may be too narrow, customFilter may be wrong, or Base DN may be incorrect.
Try again by setting Scope value to SUBTREE.
Remove custom filter and test.
Verify Base DN with directory administrator.
Wrong requireCertificateType may be selected, certificate may be in revoked list, or CertificateId may not be current.
Check certificate status in Secret Manager.
Import new certificate if necessary.
Update RequireCertificateType value according to rule.
Network delay, target system responding slowly, or timeout value may be too low.
Check network connectivity.
Check target system health.
Increase timeout values.
Review connection logs.
Wrong username/password, expired credentials, or authorization problem may exist.
Verify credentials.
Check that user is active in target system.
Check that necessary permissions are granted.
Check SSL/TLS certificates.
Pool size may be too low, connection leak may exist, or traffic may be too high.
Increase pool size.
Check that connections are properly closed.
Set idle connection timeouts.
Monitor connection usage metrics.
Different connection may be selected in Integration/Connector step, step may be misconfigured, or Flow/Job may not be redeployed.
Check that Connection's enable toggle is active.
Verify that correct connection is selected in Integration Flow.
Redeploy Connection.
Redeploy Integration Flow or Job.
Check Gateway logs.
## Frequently Asked Questions (FAQ)
A single connection only takes one Base DN; you need to create separate connections for different OUs or define alternative steps within Flow.
If Server Address, Username, Password, or Base DN starts with a variable, values are resolved at deployment time; Test Connection enters overlay because it cannot see the real value.
OBJECT searches only a single entry, ONE\_LEVEL searches the first level of the specified OU, SUBTREE searches entries in the entire subtree; selection is made according to performance requirements.
Renew the certificate via Secret Manager or select a different certificateId; bind is blocked with revoked certificates according to requireCertificateType setting.
Separate values are stored for each environment; when you change the environment, the form is updated with relevant values and only the selected environment is affected after Save and Deploy.
Yes, the same connection can be used in multiple Integration Flow or Connector steps. This provides centralized management and guarantees configuration consistency. However, changes made to the connection will affect all usage locations, so care should be taken.
Using connection pool is not mandatory but strongly recommended in high-traffic systems. Reusing existing connections instead of opening new connections for every request significantly improves performance.
Yes, it is recommended to create separate connections for each environment. Alternatively, you can manage all environments within a single connection using the environment parameter. This approach provides easier management and less error risk.
Several reasons may exist:
1. Connection enable toggle may be passive
2. A different connection may be selected in Integration step
3. Connection may not be deployed
4. Integration Flow may not have been redeployed yet