Console terminology: In the Maverics Console, the combination of applications,
policies, headers, and connector bindings is managed through User Flows. In
YAML, these elements are configured directly within each app’s configuration block
under
apps[].policies[].Prerequisites
Before configuring the LDAP Provider, ensure you have:- Service Extension development capability — You need to write Go-based Service Extensions that implement the LDAP operation handlers:
authenticateSEfor bind operations,searchSEfor search queries, and optionallygetHashedCredentialsSEfor NTLM. See Service Extensions reference. - Downstream application LDAP requirements — You must know what your LDAP-dependent application expects: which LDAP operations it performs (bind, search, compare), what base DNs it queries, which attributes it expects in search results (e.g.,
cn,sAMAccountName,memberOf), and what bind method it uses (simple bind or SASL/NTLM). - Attribute source systems — You must have identity attribute data available in systems the Orchestrator can query during LDAP operations. These sources — cloud IdPs (Azure AD, Okta), databases, APIs, directories — provide the data that the Service Extensions translate into LDAP responses.
- A running Maverics Orchestrator — Follow the Quick Start guide or installation reference if not yet installed.
Use Cases
- Virtualizing cloud IdP as LDAP directory — Present Azure AD, Okta, or PingFederate as an LDAP directory for applications that only know how to authenticate via LDAP bind operations.
- LDAP-dependent legacy app migration — Migrate legacy applications off on-premises Active Directory to cloud identity providers without changing the application’s LDAP configuration.
- Combining with HTTP Proxy for full legacy stack — Pair LDAP Provider with HTTP Proxy mode to modernize applications that depend on both LDAP lookups and header-based authentication.
- Directory consolidation — Present multiple identity sources as a single unified LDAP directory, consolidating user lookups across disparate systems.
How It Works
The LDAP Provider operation flow follows these steps:- LDAP client connects — An LDAP-dependent application (the LDAP client) connects to the Orchestrator’s LDAP endpoint via
ldap://orldaps://(TLS-encrypted). - Bind authentication — The client sends an LDAP bind request (simple bind with DN+password, or SASL/NTLM). The Orchestrator’s Service Extension handles credential validation — typically by translating the bind into an authentication request against a cloud identity provider.
- Root DSE discovery — The client reads the Root DSE entry to discover the directory’s capabilities, naming contexts, and supported features. The Orchestrator serves configured Root DSE attributes.
- Search operations — The client sends LDAP search requests (base DN, scope, filter, attributes). The Orchestrator’s search Service Extension translates these into queries against upstream identity sources and returns matching entries in LDAP format.
- Attribute translation — The Service Extension maps cloud IdP attributes (e.g., Azure AD user properties) into the LDAP attribute names and formats the client application expects (e.g.,
cn,sAMAccountName,memberOf). - Connection lifecycle — The Orchestrator manages connection timeouts (read/write deadlines) and handles multiple concurrent LDAP connections, each with its own bind state.
Key Concepts
Virtual Directory
The LDAP Provider is not a traditional LDAP server with its own data store. It is a virtual directory that translates LDAP protocol operations into queries against modern identity sources. The directory data comes from cloud IdPs, the LDAP protocol is just the interface.Service Extension-Driven
Unlike other Orchestrator modes that use declarative configuration for most operations, the LDAP Provider relies heavily on Service Extensions (Go code) for its core operations. TheauthenticateSE handles bind operations, the searchSE handles search queries, and the getHashedCredentialsSE handles NTLM credential lookups. This provides maximum flexibility for translating between LDAP semantics and cloud IdP APIs.
Authentication Methods
Two authentication methods are supported: simple bind (DN+password, the most common) and SASL with NTLM via GSS-SPNEGO (for Windows-integrated applications). Both methods require Service Extensions to implement the actual credential validation against upstream providers.Pairing with HTTP Proxy
The LDAP Provider is most commonly deployed alongside HTTP Proxy mode in a facade (or “sandwich”) pattern. The application sits between two Orchestrator roles: the HTTP Proxy handles browser-facing authentication while the LDAP Provider handles the application’s backend LDAP operations.
- A user requests a protected page. The Orchestrator (HTTP Proxy) intercepts and redirects the browser to a cloud IdP (Okta, Azure AD, Google, AWS, etc.) for authentication with modern MFA and policies.
- After successful authentication, the Orchestrator creates one-time credentials and delivers them to the downstream application using one of three methods:
- Header injection — The Orchestrator injects identity headers (e.g.,
SM_USER,X-Remote-User) into the proxied request. The application reads these headers directly. - Form-stuffing (upstream login) — The Orchestrator’s
loginSEService Extension POSTs one-time credentials to the application’s native login form, automating the “double login” problem. TheisLoggedInSEchecks whether the app session is already established. - Session/cookie — The Orchestrator stores credentials in the session, making them available to subsequent LDAP bind operations.
- Header injection — The Orchestrator injects identity headers (e.g.,
- The application sends an LDAP Bind request to the Orchestrator (LDAP Provider) to validate those credentials.
- The application sends LDAP Search requests to retrieve user attributes (e.g.,
cn,memberOf,sAMAccountName). - The Orchestrator translates the LDAP queries into lookups against the cloud IdP and returns the results in LDAP format. The user sees the requested page.
The diagram shows two Orchestrator roles, but these can be deployed as a single Orchestrator running both HTTP Proxy and LDAP Provider modes, two separate Orchestrator instances, or groups of Orchestrators for high-availability (HA) deployments.
No Apps Array
Unlike OIDC, SAML, and HTTP Proxy modes, the LDAP Provider does not useapps[] entries. All configuration lives under the ldapProvider top-level key. There is one virtual directory per Orchestrator instance.
Interface
- Console UI
- Configuration
In the Maverics Console, LDAP Provider settings are configured in the Deployment Settings dialog under the LDAP Provider section.Server Settings
Search
Authentication
| Field | Required | Description |
|---|---|---|
| Enable | Yes | Toggle to enable the LDAP Provider. The provider must be enabled for it to start. |
| Protocol | Yes | Dropdown to select the LDAP protocol: ldap:// (unencrypted) or ldaps:// (TLS-encrypted). |
| URI | Yes | LDAP listen address. Default port is 389 for ldap:// or 636 for ldaps://. |
| TLS Certificate | No | File path to the TLS certificate (used when protocol is ldaps://). |
| TLS Key File | No | File path to the TLS private key (used when protocol is ldaps://). |
| Field | Required | Description |
|---|---|---|
| Search Service Extension | No | Dropdown to select a Service Extension for handling LDAP search operations. |
| Field | Required | Description |
|---|---|---|
| Allow Anonymous | No | Toggle to allow anonymous LDAP bind operations. Off by default. |
| Enable Simple Auth | No | Toggle to enable simple bind authentication (DN + password). |
| Authentication Service Extension | No | Dropdown to select a Service Extension for simple bind authentication. Required when simple auth is enabled. |
The Console UI provides a subset of the full YAML configuration. Advanced settings such as SASL/NTLM authentication, Root DSE attributes, and read/write deadline timeouts are only available in YAML. See the Configuration tab for the complete reference.
Configuration Reference
TheldapProvider top-level key configures the virtual LDAP directory server. Unlike other modes, LDAP Provider does not use an apps[] entry — all configuration is at the provider level.
ldapProvider Fields
| Key | Type | Default | Required | Description |
|---|---|---|---|---|
ldapProvider.enabled | boolean | false | Yes | Enable the LDAP Provider |
ldapProvider.uri | string | — | Yes | LDAP listen URI — ldap:// for plain or ldaps:// for TLS (e.g., ldaps://0.0.0.0:636) |
ldapProvider.tls | string | — | Conditional | Named TLS profile — required when URI scheme is ldaps:// |
ldapProvider.readDeadline | string | — | No | Read I/O timeout (duration string, e.g., 5m, 30s) |
ldapProvider.writeDeadline | string | — | No | Write I/O timeout (duration string, e.g., 5m, 30s) |
ldapProvider.rootDSE.attributes | object | — | No | Custom Root DSE attributes exposed to LDAP clients (e.g., namingContexts) |
ldapProvider.search.searchSE | object | — | No | Service Extension for handling LDAP search operations |
ldapProvider.authentication.allowAnonymous | boolean | false | No | Allow anonymous LDAP bind operations |
ldapProvider.authentication.methods.simple.enabled | boolean | false | No | Enable simple bind authentication |
ldapProvider.authentication.methods.simple.authenticateSE | object | — | Conditional | Service Extension for simple bind authentication — required when simple auth is enabled |
ldapProvider.authentication.methods.sasl.enabled | boolean | false | No | Enable SASL authentication mechanisms |
ldapProvider.authentication.methods.sasl.mechanisms.gssspnego.enabled | boolean | false | No | Enable GSS-SPNEGO mechanism for Windows authentication |
ldapProvider.authentication.methods.sasl.mechanisms.gssspnego.ntlm.enabled | boolean | false | No | Enable NTLM authentication under GSS-SPNEGO |
ldapProvider.authentication.methods.sasl.mechanisms.gssspnego.ntlm.netbiosDomainName | string | — | Conditional | NetBIOS domain name for NTLM (required when NTLM enabled) |
ldapProvider.authentication.methods.sasl.mechanisms.gssspnego.ntlm.netbiosMachineName | string | — | Conditional | NetBIOS machine name for NTLM |
ldapProvider.authentication.methods.sasl.mechanisms.gssspnego.ntlm.getHashedCredentialsSE | object | — | Conditional | Service Extension for NTLM credential lookup — required when NTLM is enabled |
Root DSE
The Root DSE (DSA-Specific Entry) is the entry an LDAP client reads when connecting to discover directory capabilities. Custom attributes allow the virtual directory to present itself with the expected naming contexts and supported features.- Console UI
- Configuration
Root DSE attributes are configured via YAML only. The Console UI manages the core LDAP Provider settings (enable, protocol, URI, TLS, search SE, authentication) in the Deployment Settings dialog. See the Configuration tab for Root DSE attribute configuration.
Authentication Methods
The LDAP Provider supports two authentication methods: simple bind and SASL. Both are configured underldapProvider.authentication.methods.
Simple Bind
Simple bind authentication uses a DN and password to authenticate. TheauthenticateSE Service Extension handles the actual credential validation — typically by bridging the LDAP bind to an OIDC Resource Owner Password Credentials (ROPC) grant against an upstream identity provider.
- Console UI
- Configuration
Simple bind authentication Service Extension paths are configured via YAML only. In the Console, you enable simple auth and select the Service Extension from the dropdown in Deployment Settings. The YAML format shown here provides the same configuration with explicit file path and function name.
authenticateSE receives the bind DN and password, and returns a boolean indicating success or failure. This is the most common pattern for bridging LDAP authentication to modern identity providers.
simple.go
SASL / NTLM
SASL authentication supports the GSS-SPNEGO mechanism with NTLM. This enables Windows domain credential authentication, allowing Windows-integrated applications to authenticate against the virtual directory using native Windows credentials.| Key | Type | Description |
|---|---|---|
ntlm.enabled | boolean | Enable NTLM authentication |
ntlm.disableRequiring128bitEncryption | boolean | Disable the requirement for 128-bit encryption |
ntlm.netbiosDomainName | string | NetBIOS domain name (e.g., EXAMPLE) |
ntlm.netbiosMachineName | string | NetBIOS machine name (e.g., LDAPSERVER) |
ntlm.dnsDomainName | string | DNS domain name (e.g., example.com) |
ntlm.dnsForestName | string | DNS forest name (e.g., example.com) |
ntlm.dnsMachineName | string | DNS machine name (e.g., ldap.example.com) |
ntlm.getHashedCredentialsSE | object | Service Extension for NTLM credential hash lookup (required) |
- Console UI
- Configuration
SASL and NTLM authentication are configured via YAML only. These advanced authentication methods are not available in the Console UI.
gss_spnego_ntlm.go
Kerberos authentication under GSS-SPNEGO is defined in the schema but is not yet supported. Only NTLM is currently available as a SASL mechanism.
Search Handling
LDAP search operations are handled by thesearchSE Service Extension. This allows the virtual directory to translate LDAP search requests into queries against upstream identity sources.
- Console UI
- Configuration
Search Service Extension configuration follows the same pattern as the Console — in the Console, you select the Search Service Extension from the dropdown in Deployment Settings. The YAML format provides the explicit file path and function name.
search.go
Service Extension Hooks
The LDAP Provider relies on Service Extensions for its core operations. Service Extensions are Go source files referenced by file path and function name.| Hook | Location | Purpose |
|---|---|---|
authenticateSE | authentication.methods.simple.authenticateSE | Handles simple bind authentication — receives DN and password, returns success/failure |
searchSE | search.searchSE | Handles LDAP search operations — receives search parameters, returns matching entries |
getHashedCredentialsSE | authentication.methods.sasl.mechanisms.gssspnego.ntlm.getHashedCredentialsSE | Provides NTLM credential hashes for Windows authentication |
file and funcName fields to specify the Go source file and entry point function:
- Console UI
- Configuration
Service Extension file paths and function names are configured via YAML only. In the Console, Service Extensions are selected from dropdowns in the Deployment Settings dialog.
Related Integrations
The LDAP Provider mode works with all Identity Fabric connectors. The Orchestrator sources identity data from any upstream IdP and presents it as LDAP entries. These are the most commonly used pairings:Azure AD
Microsoft Entra ID as LDAP backend
Okta
Okta as LDAP backend
LDAP
LDAP directory as attribute source
Active Directory
AD as attribute source
- HTTP Proxy — Pair with HTTP Proxy mode for applications that need both LDAP directory access and header-based authentication
- Caches — Shared cache for facade deployments and directory lookup caching
Troubleshooting
LDAP bind fails with 'invalid credentials'
LDAP bind fails with 'invalid credentials'
Symptoms: The application receives LDAP error code 49 (
invalidCredentials) when attempting to bind.Causes:- The
authenticateSEService Extension is returning a failure response. - The upstream identity provider is rejecting the translated credentials.
- The ROPC (Resource Owner Password Credentials) grant type is not enabled on the upstream IdP application.
- Check the
authenticateSElogs for the specific upstream authentication error. - Verify the upstream identity provider supports the ROPC (password grant) flow and that it is enabled on the application registration.
- Confirm the client ID and client secret configured on the upstream connector are correct.
LDAP search returns empty results
LDAP search returns empty results
Symptoms: The application connects and binds successfully but LDAP search operations return no entries.Causes:
- The
searchSEService Extension is not matching the incoming search filter. - The upstream identity source query is returning empty results.
- The base DN in the search request does not match the directory’s naming contexts.
- Add logging in the
searchSEto inspect the incoming search parameters (base DN, scope, filter). - Verify the upstream data source contains entries that match the search criteria.
- Check that
rootDSE.attributes.namingContextsmatches the base DN the application queries.
TLS handshake failure on LDAPS
TLS handshake failure on LDAPS
Symptoms: The LDAP client cannot connect to the Orchestrator. Logs show “TLS handshake failed” or similar errors.Causes:
- The TLS certificate does not match the hostname the client connects to.
- The TLS certificate has expired.
- The client does not trust the certificate authority (CA) that signed the LDAP server certificate.
- Verify the TLS certificate’s Subject Alternative Names (SANs) cover the hostname the client uses to connect.
- Check the certificate expiry date and renew if needed.
- Ensure the LDAP client trusts the CA that signed the server certificate (install the CA certificate in the client’s trust store).
Connection timeout with no error
Connection timeout with no error
Symptoms: The LDAP client hangs and eventually times out without receiving an error response.Causes:
- A firewall is blocking the LDAP port (389 for
ldap://or 636 forldaps://). ldapProvider.enabledis not set totruein the Orchestrator configuration.- URI scheme mismatch — the client is connecting with
ldaps://but the Orchestrator is listening onldap://(or vice versa).
- Verify the Orchestrator is listening on the expected port (
ldap://defaults to 389,ldaps://defaults to 636). - Check firewall rules to confirm the LDAP port is open between the client and the Orchestrator.
- Confirm
ldapProvider.enabled: trueis set in the configuration.
Shared cache errors in facade deployment
Shared cache errors in facade deployment
Related Pages
HTTP Proxy
Protect applications with reverse proxy mode — often paired with LDAP Provider
Identity Fabric
Connect upstream identity providers to the Orchestrator
Architecture and Concepts
Understand how modes fit into the Orchestrator architecture
OIDC Provider
Configure the Orchestrator as an OpenID Connect authorization server