Skip to main content

​
Overview

Centralized Management

Centralizes Connection definitions, making the same LDAP access information reusable across all Integration Flow and Connector steps

SSL/TLS Management

Manages SSL/TLS and certificate requirements with enum-based policies, ensuring consistency in authentication processes

Query Optimization

Narrows directory queries with Search Scope and customFilter fields, limiting unnecessary traffic and unauthorized attribute access

Sharing Feature

Enables sharing the same connection at the project or management console level through Environment selection and Move to Global feature

Connection Initiation

When an LDAP connection is requested from within an Integration Flow or Connector, the system reads the configured connection parameters

Connection Pool Management

Gateway keeps LDAP sessions ready in the pool; opens a new connection if no suitable session exists for the selected environment

Authentication

Binds to the target directory by performing certificate verification according to Username/password or requireCertificateType field

Data Communication

Search/query operations are executed over LDAP protocol according to searchScope and customFilter values

Connection Management

When the operation completes, the connection returns to the pool and waits for subsequent requests

Error Management

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

Authentication

Managing LDAP-based user authentication in Integration Flow steps through a single connection

User Querying

Querying self-service portal or management console users from Active Directory/LDAP directory

Authorization

Reading membership attributes to create group-based or organizational unit (OU) based authorization rules

SSL/TLS Audit

Connecting to internal directories with certificate requirements via LDAPS to perform SSL/TLS audit

​
Technical Features and Capabilities

Certificate Requirement Policies

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.

Search Scope and Filtering

LDAP queries are refined with EnumSearchScope (OBJECT, ONE_LEVEL, SUBTREE) and customFilter combination.

Environment Variable Support

Environment variables can be selected for Server Address, Username, Password, and Base DN fields to use hidden values.

Environment-Based Configuration

Ability to define separate connection parameters for each environment (Development, Test, Production).

Enable/Disable Control

Activating or deactivating the Connection (enable/disable toggle). In passive state, the connection cannot be used but its configuration is preserved.

Move to Global Sharing

LDAP connection within a project can be moved to the management project via Move to Global action, making it available across all projects.

Revoked Certificate Separation

When pulling the certificate list, the revoked flag is checked, and revoked certificates are placed in a separate warning list.

Deployment Result Monitoring

After save or Test Connection operations, the deploymentResult dialog opens showing bind/log details.

Connection Test Feature

Ability to validate connection parameters before saving via “Test Connection” button.

Export/Import Feature

Exporting Connection configuration as a ZIP file. Importing to different environments (Development, Test, Production). Version control and backup capability.

Connection Monitoring

Monitoring connection health, pool status, and performance metrics.

​
Connection Parameters

Name

Description: Connection name (must be unique)
Example Value: Production_LDAP
Notes: Should not start with space, special characters should not be used

Server Address

Description: URI or host information of the LDAP server
Example Value: ldaps://directory.example.com:636
Notes: Can be selected with environment variable

Require Certificate Type

Description: Determines certificate verification policy
Example Value: REQUIRED_CN
Notes: If REQUIRED_AN_PN is selected, certificateId becomes mandatory

Search Scope

Description: Query depth (EnumSearchScope)
Example Value: SUBTREE
Notes: One of OBJECT, ONE_LEVEL, or SUBTREE values is selected

Base DN

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

Use SSL

Description: Opens SSL/TLS channel for LDAPS communication
Default Value: false
Recommended Value: true (in Production environment)

Username

Description: Service account to be used for bind operation
Default Value: (Empty)
Recommended Value: svc_ldap_reader or environment variable

Password

Description: Password of bind account or secret reference
Default Value: (Empty)
Recommended Value: Secret Manager variable

Custom Filter

Description: Additional LDAP filter expression
Default Value: (Empty)
Recommended Value: LDAP filter expression

Certificate Id

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

Connection Timeout

Description: Maximum time to connect to LDAP server
Default: 10000
Min: 2000 | Max: 60000
Unit: milliseconds

Request Timeout

Description: Wait time for search/bind response
Default: 30000
Min: 5000 | Max: 120000
Unit: milliseconds

Pool Size

Description: Maximum connections to keep open simultaneously
Default: 20
Min: 1 | Max: 50
Unit: count

Bind Retry Interval

Description: Wait between failed bind attempts
Default: 2000
Min: 500 | Max: 10000
Unit: milliseconds

​
Usage Scenarios

Single Authentication

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

Group-Based Authorization Control

Situation: Integration Flow needs to fetch users belonging to specific groups
Solution: Group filter with Custom Filter
Expected Behavior: Flow lists only relevant members

Management Console Integration

Situation: Admin page should share global LDAP definition
Solution: Move to Global is executed, selectedEnvironmentId=manager
Expected Behavior: Management console uses the same connection

Service Account Rotation

Situation: Passwords are stored in Secret Manager
Solution: Username and Password environment variable
Expected Behavior: No need to update connection when password changes

Certificate Required Environment

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

High Traffic Queries

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

Image 2024 9 9 15 35 35 Pn

​
Configuration Steps

1

Navigating to Creation Page

  • 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.
2

Entering Basic Information

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.
3

Environment Selection

  • 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.
4

LDAP Specific Parameters - Section 1

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.
5

LDAP Specific Parameters - Section 2

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.
6

Timeout and Connection Pool Settings

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
7

Security and Authentication Settings

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.
8

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.
9

Saving and Deploying

  • 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

Deletion Process

Select ⋮ → Delete from the row end menu or click the [Delete] button on the connection detail page

Deletion Tips

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

Alternative: Deactivate

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.

Method 1

Select ⋮ → Export from the action menu. ZIP file is automatically downloaded.

Method 2

Click the [Export] button on the connection detail page. ZIP file is downloaded.

File Format

Format: Date-connection-LDAP Pool Connection-export.zip
Example: 13 Nov 2025-connection-Production_LDAP-export.zip

ZIP Contents

  • Connection JSON file
  • Metadata information
  • Dependency information (e.g., certificates, key store)

Usage Areas

  • Backup
  • Moving between environments (Test → Prod)
  • Versioning
  • Team or project-based sharing

Import Steps

  • 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.

Import Scenarios

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

Creating and Activating Connection

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

Usage in Integration / Connector Steps

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 Job Usage

Scheduled jobs can perform directory queries at certain intervals. When the job is redeployed, current connection parameters are automatically used

Test Purpose Usage

Connection Test result is displayed in the deployment dialog. Bind DN and error codes are quickly read during troubleshooting

​
Best Practices

Service Account Management

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

Certificate Lifecycle

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

Search Scope Selection

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

Environment Variable Usage

Bad: Writing fixed username and passwords to the form.
Good: Hiding with environment variable.
Best: Feeding variables from Secret Manager and auditing access logs

Environment Management

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

Connection Test

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

LDAPS Requirement

Warning: Do not leave Use SSL closed in Production environment; otherwise credentials are transmitted in plain text

RBAC and Move to Global

When you move Connection to Global, make sure only authorized users can edit, otherwise all projects are affected

Environment Variable Monitoring

Do not log sensitive data; prevent data leakage by keeping Test Connection overlay closed

Credential Management

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

SSL/TLS Usage

Always enable SSL/TLS in Production environment. Use self-signed certificates only in development environment. Track certificate expiration dates and renew on time

Access Control

Allow only authorized users to change Connection configuration. Store connection change logs. Apply change approval process for critical connections

Using Anonymous Bind

Why to avoid: Directory opens to all users, access traces are not kept.
Alternative: Bind with read-only service account

Unnecessary SUBTREE Queries

Why to avoid: Performance decreases in large directories.
Alternative: Select ONE_LEVEL or OBJECT scope, narrow with customFilter

Disabling Certificate Control

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

Using Production Connection in Test Environment

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_)

Very Low Timeout Values

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

Not Using Connection Pool

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

Search Scope Optimization

Recommendation: Use ONE_LEVEL instead of SUBTREE, narrow OUs with customFilter.
Impact: Number of entries sent to LDAP server decreases, response time shortens

Environment Variable Cache

Recommendation: Provide variables through Secret Manager cache.
Impact: Parameter read time decreases, overlay is less visible for Test Connection

Certificate Rotation Plan

Recommendation: Schedule certificate renewals to coincide with maintenance window, deploy new certificateId in advance.
Impact: Your security level is maintained without experiencing LDAPS interruption

Connection Pool Optimization

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

Timeout Values Optimization

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

Connection Monitoring

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.
1

Scope Value

Try again by setting Scope value to SUBTREE.
2

Custom Filter

Remove custom filter and test.
3

Base DN Verification

Verify Base DN with directory administrator.
Wrong requireCertificateType may be selected, certificate may be in revoked list, or CertificateId may not be current.
1

Certificate Status

Check certificate status in Secret Manager.
2

Certificate Import

Import new certificate if necessary.
3

RequireCertificateType

Update RequireCertificateType value according to rule.
Network delay, target system responding slowly, or timeout value may be too low.
1

Network Check

Check network connectivity.
2

System Health

Check target system health.
3

Timeout Settings

Increase timeout values.
4

Log Review

Review connection logs.
Wrong username/password, expired credentials, or authorization problem may exist.
1

Credentials

Verify credentials.
2

User Status

Check that user is active in target system.
3

Authorization Check

Check that necessary permissions are granted.
4

Certificate Check

Check SSL/TLS certificates.
Pool size may be too low, connection leak may exist, or traffic may be too high.
1

Pool Size

Increase pool size.
2

Connection Check

Check that connections are properly closed.
3

Idle Timeout

Set idle connection timeouts.
4

Metric Monitoring

Monitor connection usage metrics.
Different connection may be selected in Integration/Connector step, step may be misconfigured, or Flow/Job may not be redeployed.
1

Enable Toggle

Check that Connection’s enable toggle is active.
2

Connection Selection

Verify that correct connection is selected in Integration Flow.
3

Connection Deploy

Redeploy Connection.
4

Flow/Job Deploy

Redeploy Integration Flow or Job.
5

Log Check

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