🔐 Mastering LDAP Integration in Uniface 10.4: The Native Way

This article was created with AI assistance, synthesizing official Rocket Uniface 10.4 documentation with practical implementation patterns.

Connecting legacy enterprise applications to modern directory services is a classic integration challenge. While many developers attempt to build complex wrappers or external call-outs, Uniface 10.4 provides a native LDAP Connector (LDP).

This connector is powerful because it allows you to treat a hierarchical Directory Service almost exactly like a relational database. This guide will show you how to configure and use it correctly using native ProcScript.

📚 What is LDAP? (For the Uninitiated)

Before we dive into code, let's clarify the terminology:

• LDAP (Lightweight Directory Access Protocol): Think of it as a specialized database optimized for reading data. Unlike a standard SQL database that balances reading and writing, LDAP is designed for scenarios where you write once (create a user) but read millions of times (verify a login).
• X.500: This is the "grandparent" standard. It defined the comprehensive model for directory services. LDAP was created as a lighter, more efficient way (via TCP/IP) to access X.500 directories. Uniface supports both pure LDAP and X.500 gateways.
• IPv6: The modern version of the Internet Protocol. The Uniface LDAP connector is fully compatible with IPv6 addresses (e.g., [2001:db8::1]), ensuring your application is future-proof.

🔌 The Uniface Approach: Driver, Not Service

A common misconception is that you "call" LDAP like a web service. In Uniface, you don't. You use the LDP driver.

This means you interact with LDAP using standard Uniface I/O commands:

• retrieve to search for users.
• open to authenticate.
• store to update attributes (if permissions allow).

🛠️ Step 1: Configuration (The ASN File)

The magic happens in the Assignment File (.asn). You need to define the driver and map a logical path to your LDAP server.

[SETTINGS]
; Load the LDAP driver (ensure the version matches your install, e.g., U3.0 or similar)
USYS$LDP = LDP

; Enable debug logging - crucial for seeing what happens under the hood!
LDAP_DEBUG = 1
LDAP_TIMEOUT = 10

[PATHS]
; Syntax: $PATH_NAME = LDP:ServerName:Port:BaseDN
; 'BaseDN' is the root folder where your search begins.
$AD_PROD = LDP:ad.company.com:389:DC=company,DC=com

; For SSL/TLS (LDAPS), typically use port 636
$AD_SECURE = LDP:ad.company.com:636:DC=company,DC=com

[ENTITIES]
; Map your Uniface entities to the logical path
USER.AD  = $AD_PROD
GROUP.AD = $AD_PROD

📝 Step 2: The Data Model

LDAP is hierarchical, but Uniface is relational. We bridge this gap by mapping:

1. LDAP Class ➡️ Uniface Entity
2. Distinguished Name (DN) ➡️ Primary Key

In your Uniface Model:

• Create an entity (e.g., USER)
• Create a field DN (String, approx C256) and mark it as the Primary Key.
• Create fields for attributes you want (e.g., CN, MAIL, TELEPHONENUMBER).

⚠️ Important: The field names in Uniface must match the LDAP attribute names (case-insensitive in Uniface, but usually lowercase in LDAP schema).

💻 Step 3: Practical Examples

Use Case A: User Authentication (The Login)

To check a password, we don't need a complex query. We simply try to open a connection using the specific user's credentials. If the server accepts the connection, the password is correct.

operation user_login
params
    string p_username : IN
    string p_password : IN
endparams

variables
    string v_connection_string
endvariables

    ; Construct the dynamic path string
    ; Syntax: LDP:Host:Port:BaseDN|Username|Password
    ; Note: Active Directory often requires 'domain\user' or 'user@domain'
    v_connection_string = "LDP:ad.company.com:389:DC=company,DC=com|%%p_username|%%p_password"

    ; Attempt to open the path
    ; The 'b' flag is best practice here to skip table verification checks
    open v_connection_string, "b"

    if ($status < 0)
        ; Connection refused (Wrong password, account locked, or server down)
        return -1
    endif

    ; Security Best Practice: Close the connection immediately!
    ; You don't want to keep a session open with the user's privileges.
    close v_connection_string

    return 1 ; Success
endoperation

Use Case B: Finding a User (The Search)

To find a user, use the standard retrieve command. Uniface translates your profile fields into an LDAP filter.

operation find_employee
params
    string p_search_name : IN
endparams

    clear/e "USER"

    ; Set the search profile
    ; This translates to an LDAP filter like (cn=Smith*)
    CN.USER = "%%p_search_name%%*"

    ; Execute the search
    retrieve/e "USER"

    if ($status < 0)
        message "Error or no data found: %%$status"
        return
    endif

    ; Loop through results
    setocc "USER", 1
    while ($status > 0)
        putmess "Found: %%CN.USER - %%MAIL.USER"
        setocc "USER", $orc + 1
    endwhile
endoperation

🐧 Platform Specifics: Linux vs. Windows

While the ProcScript code stays the same, the environment setup differs slightly.

Windows 🪟

• Certificates: The connector typically uses the Windows Certificate Store. If your organization uses a private CA for LDAPS, ensure the Root CA is installed in the Windows Trusted Root store.
• Authentication: Integration with Active Directory is usually seamless.

Linux 🐧

• Certificates: You must explicitly tell the driver where to find certificates if they aren't in the standard OpenSSL location. Add this to your .asn file:

[SETTINGS]
LDAP_CACERTFILE = /etc/pki/tls/certs/ca-bundle.crt
LDAP_CERTFILE   = /path/to/client-cert.pem
LDAP_KEYFILE    = /path/to/client-key.pem

⚡ Troubleshooting & Best Practices

1. "Table Not Found" (-13): This is the most common error. It usually means your Base DN is incorrect. If Uniface looks in OU=Sales but the user is in OU=IT, it won't find the "table" (object).
2. Performance: Never do a retrieve without setting a profile field (like CN or SAMACCOUNTNAME). An unbounded search attempts to download the entire directory, which will time out or crash your application.
3. Encoding: LDAP v3 uses UTF-8. Ensure your Uniface application handles Unicode correctly, otherwise, characters like é or ü in names will appear corrupted.
4. Read-Only Mindset: While store commands exist, AD permissions are complex. It is generally safer and easier to use Uniface for reading/authenticating and use specialized tools (or PowerShell scripts invoked by Uniface) for creating accounts.

🏁 Conclusion

The Uniface LDAP connector eliminates the need for external DLLs or Java wrappers. By understanding that LDAP is just another "database" to Uniface, you can use the standard commands you already know (open, retrieve) to build secure, integrated enterprise applications.

Happy coding! 🚀