DEV Community

Franz
Franz

Posted on

Connecting Uniface 10.4 to LDAP Servers: A Complete Guide 🔐

#uniface #ldap #enterprisedevelopment #legacysystems

This article was created with AI assistance to provide accurate technical documentation for the developer community.

If you're working with legacy enterprise systems, you've probably encountered the challenge of integrating directory services. Today, I'll walk you through the Uniface 10.4 LDAP Connector - a powerful tool that bridges the gap between your Uniface applications and enterprise directory services.

📚 Table of Contents

What is LDAP? 🤔

Before diving into the Uniface connector, let's understand what LDAP actually is.

LDAP (Lightweight Directory Access Protocol) is an industry-standard protocol used to access and manage directory information services over a network. Think of it as a specialized database optimized for read-heavy operations, storing information in a hierarchical tree structure.

Key Concepts:

📖 X.500 Standard: LDAP was originally designed as a lightweight alternative to the X.500 Directory Access Protocol (DAP). While X.500 required the heavy OSI protocol stack, LDAP runs directly over TCP/IP, making it much more practical for modern networks.

🌳 Hierarchical Structure: Data in LDAP is organized like a tree, with a root at the top and branches leading to individual entries (called "Distinguished Names" or DNs).

🔍 Common Operations: LDAP supports standard operations including:

  • Search: Query the directory for specific entries
  • Bind: Authenticate a user (verify credentials)
  • Add: Create new directory entries
  • Modify: Update existing entries
  • Delete: Remove entries from the directory

Why Use LDAP?

LDAP is perfect for centralized authentication in enterprise environments. Instead of managing user credentials separately in each application, you maintain a single source of truth. Applications like:

  • Jenkins 🛠️
  • Kubernetes ☸️
  • OpenVPN 🔒
  • Atlassian products (Jira, Confluence) 📊
  • Samba file servers 📁

...all commonly integrate with LDAP directories for user authentication.

Understanding the Uniface LDAP Connector 🔌

The Uniface LDAP connector (mnemonic: LDP) enables Uniface applications to communicate with LDAP servers seamlessly. This includes both standalone LDAP servers and X.500 Directory System Agents with an LDAP gateway.

Technical Specifications:

Specification Details
Connector Mnemonic LDP
Protocol Version LDAP V3
Windows Implementation Native LDAP (32-bit and 64-bit)
Unix/Linux Implementation OpenLDAP
Connection Types TCP (unencrypted) and TLS (encrypted)
Unicode Support Full Unicode range (independent of $DEF_CHARSET)

Important IPv6 Note 🌐

The LDP connector supports IPv6 through hostname resolution using DNS or the local hosts file. However, direct IPv6 address input is not yet available. This means you'll need to configure DNS entries or host file entries for IPv6-enabled LDAP servers rather than using literal IPv6 addresses.

Example:

# Instead of using literal IPv6 address
ldap://[2001:db8::1]:389  ❌

# Use hostname resolution
ldap://ldap-server.example.com:389  ✅
Enter fullscreen mode Exit fullscreen mode

Supported Features and Operations 🛠️

The Uniface LDAP connector provides comprehensive functionality within the limitations of the LDAP protocol:

Core Capabilities:

✅ Read Operations

  • Retrieve individual entries by Distinguished Name (DN)
  • Access specific attributes from directory entries
  • Handle multi-valued attributes

✅ Write Operations

  • Create new entries in the LDAP directory
  • Update existing entries (modify attributes)
  • Delete entries from the directory

✅ Search Operations

  • Execute complex search queries with filters
  • Search across subtrees or single levels
  • Return specific attributes or complete entries

✅ Connection Management

  • Establish secure connections using TLS
  • Authenticate using credentials stored in .asn files
  • Close connections gracefully

Configuration Through .asn Files 📝

All connection settings are stored in Uniface assignment files (.asn). This includes:

  • Server address and port: Where to connect
  • Base DN: The starting point in the directory tree
  • Authentication credentials: Username and password for binding
  • Connection parameters: Timeout values, SSL/TLS settings

Real-World Use Cases 💼

Let's explore practical scenarios where the Uniface LDAP connector shines:

1. Enterprise Single Sign-On (SSO)

Scenario: A large organization uses Uniface applications for business operations and needs centralized authentication.

; Example: Authenticate user against LDAP
operation AuthenticateUser
  parameters
    string vUsername
    string vPassword
  endparameters

  variables
    string vDN
    string vResult
  endvariables

  ; Build Distinguished Name
  vDN = "uid=%%vUsername%%,ou=users,dc=company,dc=org"

  ; Attempt LDAP bind
  activate "LDAP_AUTH".bind(vDN, vPassword)

  ; Check result
  if ($status = 0)
    putmess "Authentication successful"
  else
    putmess "Authentication failed"
  endif

end ; AuthenticateUser
Enter fullscreen mode Exit fullscreen mode

2. User Profile Synchronization

Scenario: Automatically sync user information from Active Directory to Uniface application entities.

; Example: Retrieve user details from LDAP
operation GetUserProfile
  parameters
    string vUsername
  endparameters

  variables
    string vEmail
    string vFullName
    string vDepartment
  endvariables

  ; Search for user
  retrieve LDAP_USER, 1
    where (LDAP_USER.UID = vUsername)

  if ($status = 0)
    ; Map LDAP attributes to variables
    vEmail = LDAP_USER.MAIL
    vFullName = LDAP_USER.CN
    vDepartment = LDAP_USER.DEPARTMENT
  endif

end ; GetUserProfile
Enter fullscreen mode Exit fullscreen mode

3. Dynamic Group Management

Scenario: Query LDAP groups to determine user permissions dynamically.

Real-world benefit: Instead of maintaining duplicate group memberships in your Uniface database, query LDAP at runtime to check if users belong to specific groups (e.g., "Administrators", "Finance_Staff", "ReadOnly_Users").

Configuration and Setup ⚙️

Here's how to configure the Uniface LDAP connector step by step:

Step 1: Configure the .asn File

Create or edit your assignment file with LDAP settings:

[DRIVER_SETTINGS]
; Define the LDAP connector
LDAP_DRIVER = LDP

[ENTITIES]
; Map your Uniface entities to LDAP structure
LDAP_USER = LDAP_DRIVER, ou=users,dc=company,dc=com
LDAP_GROUP = LDAP_DRIVER, ou=groups,dc=company,dc=com

[LDAP_DRIVER]
; Connection parameters
Server = ldap.company.com
Port = 389
; For TLS/SSL connection use port 636

; Base DN for searches
BaseDN = dc=company,dc=com

; Bind credentials (authentication)
BindDN = cn=uniface_service,ou=service_accounts,dc=company,dc=com
BindPassword = YourSecurePassword

; Connection options
Timeout = 30
Version = 3
Enter fullscreen mode Exit fullscreen mode

Step 2: Define Entity Keys

Each LDAP entity in your Uniface model needs a unique identifier:

[LDAP_USER]
; Define the key attribute
Key = uid

; Map Uniface fields to LDAP attributes
UID = uid
EMAIL = mail
FULL_NAME = cn
FIRST_NAME = givenName
LAST_NAME = sn
DEPARTMENT = ou
Enter fullscreen mode Exit fullscreen mode

Step 3: Enable TLS/SSL (Recommended) 🔒

For production environments, always use encrypted connections:

[LDAP_DRIVER]
Server = ldaps.company.com
Port = 636
SSL = yes
; or for STARTTLS on port 389
UseTLS = yes
Enter fullscreen mode Exit fullscreen mode

Security Best Practice: Never store credentials in plain text in production .asn files. Use environment variables or encrypted configuration management tools.

Step 4: Test the Connection 

; Test LDAP connectivity
operation TestLDAPConnection
  variables
    string vResult
  endvariables

  ; Attempt to open connection
  activate "LDAP_DRIVER".open

  if ($status = 0)
    putmess "LDAP connection successful!"
    activate "LDAP_DRIVER".close
  else
    putmess "Connection failed: %%$status%%"
  endif

end ; TestLDAPConnection
Enter fullscreen mode Exit fullscreen mode

Platform-Specific Considerations 🖥️

Linux/Unix Requirements

On Linux systems, the LDAP connector requires the OpenLDAP package to be installed:

Debian/Ubuntu:

sudo apt update
sudo apt install slapd ldap-utils libldap-2.4-2
Enter fullscreen mode Exit fullscreen mode

Red Hat/CentOS:

sudo yum install openldap openldap-clients openldap-servers
Enter fullscreen mode Exit fullscreen mode

SUSE/openSUSE:

sudo zypper install openldap2 openldap2-client
Enter fullscreen mode Exit fullscreen mode

⚠️ Important: Make sure you install the OpenLDAP version that is current for your operating system version. Outdated packages may have security vulnerabilities or compatibility issues.

Windows Considerations

Windows systems use the native LDAP implementation (Wldap32.dll), which is included with the operating system. No additional packages are required.

Active Directory Integration: When connecting to Microsoft Active Directory:

[AD_DRIVER]
Server = ad.company.local
Port = 389
; Use Windows domain format for bind DN
BindDN = COMPANY\\uniface_service
; or UPN format
BindDN = uniface_service@company.local
Enter fullscreen mode Exit fullscreen mode

Platform Independence ✨

One of LDAP's greatest strengths is its platform independence. Unlike Active Directory (which is Windows-centric), LDAP works seamlessly across:

  • Windows Server environments
  • Linux/Unix systems
  • macOS
  • Mixed heterogeneous networks

This makes the Uniface LDAP connector ideal for organizations with diverse infrastructure.

Best Practices and Common Issues 🎯

Security Best Practices 🔐

1. Always Use TLS/SSL

Never send credentials over unencrypted connections in production:

; ❌ Insecure
Port = 389
SSL = no

; ✅ Secure
Port = 636
SSL = yes
Enter fullscreen mode Exit fullscreen mode

2. Use Service Accounts

Create dedicated LDAP service accounts for Uniface applications with minimal required privileges:

# Example: Create restricted service account
dn: cn=uniface_service,ou=service_accounts,dc=company,dc=com
objectClass: inetOrgPerson
cn: uniface_service
sn: Service Account
userPassword: {SSHA}encrypted_hash_here
description: Uniface application authentication service
Enter fullscreen mode Exit fullscreen mode

3. Implement Connection Pooling

Reuse LDAP connections where possible to reduce overhead:

; Keep connection open for multiple operations
activate "LDAP_DRIVER".open

; Perform multiple operations...
; ... retrieve user 1
; ... retrieve user 2
; ... search groups

; Close when done
activate "LDAP_DRIVER".close
Enter fullscreen mode Exit fullscreen mode

Common Issues and Solutions 🔧

Issue 1: Authentication Failures

Symptoms: Bind operations fail with "Invalid credentials" error

Common Causes:

  • Incorrect BindDN format
  • Expired service account password
  • Insufficient permissions

Solution:

# Test credentials manually
ldapsearch -x -H ldap://server:389 \
  -D "cn=uniface_service,ou=service_accounts,dc=company,dc=com" \
  -W \
  -b "dc=company,dc=com" \
  "(objectClass=*)"
Enter fullscreen mode Exit fullscreen mode

Issue 2: Connection Timeouts

Symptoms: Operations hang or timeout

Common Causes:

  • Firewall blocking LDAP ports (389, 636)
  • Network latency
  • LDAP server overloaded

Solution:

; Increase timeout values
[LDAP_DRIVER]
Timeout = 60
NetworkTimeout = 30
Enter fullscreen mode Exit fullscreen mode

Issue 3: SSL/TLS Certificate Errors

Symptoms: "Certificate verification failed" errors

Common Causes:

  • Self-signed certificates not trusted
  • Expired certificates
  • Hostname mismatch

Solution:

# Add CA certificate to trusted store (Linux)
sudo cp ldap-ca-cert.pem /usr/local/share/ca-certificates/
sudo update-ca-certificates
Enter fullscreen mode Exit fullscreen mode

Issue 4: Character Encoding Problems

Symptoms: Special characters (ä, ö, ü, ß, é, ñ) displayed incorrectly

Solution: The Uniface LDAP connector uses Unicode exclusively. Ensure your .asn file specifies UTF-8 encoding:

[SETTINGS]
$NLS_ENCODING = UTF-8
Enter fullscreen mode Exit fullscreen mode

Issue 5: Performance Issues with Large Directories

Symptoms: Slow search operations

Solution: Use indexed attributes and implement pagination:

; Use paged results for large searches
operation SearchUsersWithPaging
  variables
    numeric vPageSize
    string vCookie
  endvariables

  vPageSize = 100

  ; Implement paging logic
  ; (pseudocode - actual implementation varies)

end ; SearchUsersWithPaging
Enter fullscreen mode Exit fullscreen mode

Testing and Debugging Tips 🔍

1. Use LDAP Browser Tools

Tools like Apache Directory Studio or JXplorer help you:

  • Visualize directory structure
  • Test search filters
  • Verify attribute names
  • Check permissions

2. Enable Verbose Logging

[SETTINGS]
$LDAP_DEBUG = 1
$TRACE = ALL
Enter fullscreen mode Exit fullscreen mode

3. Test with Command-Line Tools

# Test basic connectivity
ldapsearch -x -H ldap://server:389 -b "dc=company,dc=com"

# Test TLS
ldapsearch -x -H ldap://server:389 -ZZ -b "dc=company,dc=com"

# Test authentication
ldapsearch -x -H ldap://server:389 \
  -D "cn=user,dc=company,dc=com" \
  -W -b "dc=company,dc=com"
Enter fullscreen mode Exit fullscreen mode

Conclusion 🎉

The Uniface 10.4 LDAP Connector is a powerful integration tool that brings enterprise-grade directory services to your legacy applications. By understanding its capabilities and following best practices, you can:

✅ Implement centralized authentication

✅ Reduce administrative overhead

✅ Improve security posture

✅ Enable SSO capabilities

✅ Integrate seamlessly with existing infrastructure

Key Takeaways:

  1. LDAP is a protocol, not a product - it works across platforms
  2. X.500 compatibility means broad directory support
  3. TLS/SSL is mandatory for production environments
  4. IPv6 support requires DNS hostname resolution
  5. Platform-specific requirements vary (OpenLDAP on Linux, native on Windows)

Next Steps 🚀

  • Review your organization's LDAP directory structure
  • Install required OpenLDAP packages (Linux)
  • Configure your .asn file with connection parameters
  • Test authentication in a development environment
  • Implement proper error handling
  • Plan migration strategy for production

Resources 📚

Have you integrated Uniface with LDAP? Share your experiences, challenges, or tips in the comments below! 💬

Note: This guide is based on Uniface 10.4 documentation. Always refer to your specific version's documentation and consult with your system administrators before implementing changes in production environments.

Top comments (0)