Subtitle: Unlock the power of Directory Services in your Uniface applications with the 10.4 LDAP Connector.
In the world of enterprise development, applications rarely live in isolation. They need to talk to other systems, and one of the most common requirements is authentication and user management. This is where LDAP comes in.
If you are a Uniface developer working with version 10.4, you have a powerful tool at your disposal: the Uniface LDAP Connector.
In this guide, we will break down exactly how to configure, use, and troubleshoot this connector, with a special deep dive into the addbase option. Whether you are a veteran dealing with legacy systems or a modern developer integrating new directories, this guide is for you! 🚀
1. What is LDAP? (A Quick Refresher) 📚
Before we dive into the code, let's clarify a few terms for those who might be new to this specific domain.
- LDAP (Lightweight Directory Access Protocol): Think of LDAP as a highly optimized, digital phonebook. It is a protocol used to access and manage distributed directory information services over an IP network. It's "Lightweight" because it was designed as a simpler alternative to the older, heavier X.500 standard.
- X.500: This was the original "granddaddy" of directory standards. It was comprehensive but very complex and heavy on network resources. LDAP kept the directory structure of X.500 but streamlined the way we talk to it.
- IPv6: You might see references to this in networking docs. It stands for "Internet Protocol version 6." It's the modern address system for the internet, replacing the older IPv4. Uniface and modern LDAP servers fully support IPv6, ensuring your application is future-proof.
In simple terms: If your company uses Microsoft Active Directory (AD) or OpenLDAP to store user passwords and emails, you use LDAP to talk to it.
2. The Uniface LDAP Connector 🔌
Uniface doesn't treat LDAP like a weird external service; it treats it like a database.
This is the magic of the Uniface architecture. You define an Entity (table) in your model, map it to an LDAP Object Class (like person or organizationalUnit), and use standard Uniface ProcScript commands (retrieve, store, delete) to manipulate data.
Key Capabilities:
- ✅ Authentication: Verify user credentials (bind).
- ✅ CRUD Operations: Create, Read, Update, and Delete directory entries.
- ✅ SSL/TLS Support: Secure your connection (essential for production).
- ✅ Hierarchy Management: Navigate the tree structure of a directory.
3. Configuration and Setup ⚙️
The connection behavior is controlled by the USYS$LDP_PARAMS setting in your assignment file (usually .asn). You configure this in the [DRIVER_SETTINGS] section.
The Assignment File Syntax
[DRIVER_SETTINGS]
USYS$LDP_PARAMS = addbase=on, searchscope=sub, identifier case=lower, logon timeout=10
Options Reference
| Option | Description | Recommended Value |
|---|---|---|
addbase |
(See Deep Dive below) Controls automatic DN concatenation. | on |
identifier case |
Determines if field names are case-sensitive. | lower |
logon timeout |
How long (in seconds) to wait for the server to accept a login. | 10 |
nulldefault |
Controls if empty fields are saved as NULL or empty strings. |
N |
searchscope |
Defines how deep the search goes (base, one, or sub). |
sub |
stepsize |
Controls batch fetching size. Higher values = better performance. | 50 |
tls server validation |
Checks if the server's certificate is valid. | on |
4. Deep Dive: The addbase Option 🕵️♂️
One of the most useful (but often misunderstood) settings in the LDAP driver is addbase.
What does it do?
The addbase option controls whether Uniface automatically appends the Base DN (Distinguished Name) defined in your path to the names you use in your ProcScript code.
-
addbase=on(Default/Recommended): Uniface saves you typing. You only need to provide the "Relative" Distinguished Name (RDN). -
addbase=off: You are in full control but must provide the full Distinguished Name for every operation.
Example in Action
Imagine your Base DN is dc=example,dc=com and you want to search for a user named jdoe inside the users container.
With addbase=on:
; You write cleaner code:
read (U_NAME = "cn=jdoe,ou=users")
; Uniface actually sends this to the server:
; "cn=jdoe,ou=users,dc=example,dc=com"
With addbase=off:
; You must write the full path every time:
read (U_NAME = "cn=jdoe,ou=users,dc=example,dc=com")
When should you turn it OFF?
You might want to set addbase=off if your application needs to access objects strictly outside of your defined Base DN, or if you are dynamically constructing complex DNs that might not follow the standard hierarchy of your main tree. For 95% of use cases, keeping it on reduces bugs and makes code more readable.
5. Practical Use Cases & Code Examples 💻
Scenario A: User Login (Authentication)
Instead of writing complex API calls, you simply try to "log on" to the LDAP path.
; Trigger: Detail Button (Login)
variables
string vUsername, vPassword
endvariables
vUsername = FIELD_USER
vPassword = FIELD_PASS
; Format: $logon(Path, Username, Password)
$logon("LDAP_PATH", vUsername, vPassword)
if ($status < 0)
message/error "Login Failed! Check credentials."
else
message/info "Welcome, %%vUsername! 🔓"
endif
Scenario B: Searching for a User
Assume you have modeled an entity named INETORGPERSON.
; Trigger: Read
read
if ($status < 0)
message/info "No users found."
endif
; Note: With addbase=on, the search is automatically
; restricted to your Base DN subtree.
6. Platform-Specific Notes & Troubleshooting 🚧
Linux vs. Windows 🐧🪟
- Windows: Uses the built-in Windows Secure Channel (Schannel). It usually "just works" if your machine trusts the domain controller.
- Unix/Linux: You often need to explicitly point to your certificate bundle using the
tls ca fileoption.- Example:
USYS$LDP_PARAMS = tls ca file=/etc/ssl/certs/ca-bundle.crt
- Example:
Common Pitfalls
- "Table not found": Your Uniface Entity name must match the LDAP Object Class exactly.
- Slow Searches: If
addbase=onandsearchscope=subare set on the root of a massive directory, you might timeout. Try narrowing your Base DN in the path definition (e.g.,ou=london,dc=company,dc=com). - Connection Refused: Check firewall rules and ensure IPv6 isn't blocking you if your server is configured for IPv4 only.
7. Conclusion ✅
The Uniface 10.4 LDAP connector bridges the gap between your sturdy legacy logic and modern directory services. By correctly utilizing options like addbase, you can write cleaner, more maintainable code that integrates seamlessly with enterprise identity systems.
Go ahead and integrate that directory! Happy coding! 👩💻👨💻
Transparency Note: This article was created with AI assistance to help structure technical documentation effectively.
Top comments (0)