LDAP Authentication

The LDAP Authentication connector integrates the Maverics Orchestrator with LDAP-based directory services — enabling user authentication via LDAP bind operations. For attribute-only lookups without authentication, see LDAP Attribute Provider. For Microsoft Active Directory environments, see the dedicated Active Directory connector.

Console terminology: In the Maverics Console, this section is called Identity Fabric. The YAML configuration uses the connectors key to define identity provider integrations.

Overview

The LDAP Authentication connector supports both LDAP and LDAPS (LDAP over TLS) protocols for secure directory integration. It authenticates end users via LDAP bind operations against the directory. For attribute-only lookups without authentication, see the LDAP Attribute Provider.

Use Cases

Legacy app SSO with on-premises directories — Extend single sign-on to applications that authenticate against LDAP directories, without rewriting the application or migrating users out of the directory
IdP consolidation for LDAP-dependent apps — Route authentication through the Orchestrator so LDAP-bound applications can participate in a unified authentication layer, reducing the need for standalone LDAP integrations per app
Hybrid identity bridge — Combine LDAP bind authentication with cloud IdP sessions so users in on-premises directories can access both legacy and modern applications through a single login experience
Combined authentication and attribute retrieval — Authenticate users and retrieve directory attributes (group memberships, email, department) in a single connector for header injection or policy evaluation

Setup

Console UI
Configuration

To create an LDAP Authentication connector in the Maverics Console:

Navigate to Identity Fabric in the Console sidebar.
Click Create and select LDAP Authentication.
Enter a Name for the connector.
Enter the URL of the LDAP server (e.g., ldaps://ldap.example.com:636).
Enter the Service Account Username (bind DN used to connect to the server).
Enter the Service Account Password.
Enter the Base DN for LDAP searches (e.g., dc=example,dc=com).
Enter the Username Search Key — the attribute used to filter on during query and bind operations (e.g., uid for OpenLDAP, sAMAccountName for AD).
Optionally select an Authentication Search Scope from the dropdown to control the search depth.
Optionally set a Login URL for a custom endpoint for posting user credentials. If unset, the form submits to a default location of /.ldap-login.
Optionally set a CA Path for the certificate authority when using self-signed certificates.
Click Save.

maverics.yaml

connectors:
  - name: ldap
    type: ldap
    url:
      - "ldaps://ldap.example.com:636"
    serviceAccountUsername: "cn=admin,dc=example,dc=com"
    serviceAccountPassword: <vault.ldap_password>
    baseDN: "dc=example,dc=com"
    usernameSearchKey: uid
    enableAuthentication: true
    userAttributes:
      - cn
      - email
      - memberOf
    attributeMapping:
      email: mail
      name: cn
    tls: ldap-tls

Configuration Reference

Key	Type	Required	Description
`name`	string	Yes	Unique connector identifier referenced by app policies and attribute providers
`type`	string	Yes	Must be `ldap`
`url`	string[]	Yes	LDAP server URLs — supports `ldap://` (port 389) and `ldaps://` (port 636); multiple URLs enable failover
`serviceAccountUsername`	string	Yes	Bind DN for the service account (e.g., `cn=admin,dc=example,dc=com`)
`serviceAccountPassword`	string	Yes	Service account password — use secret reference syntax `<namespace.key>`
`baseDN`	string	Yes	Base DN for LDAP searches (e.g., `dc=example,dc=com`)
`usernameSearchKey`	string	No	LDAP attribute used for username lookup (e.g., `uid` for OpenLDAP, `sAMAccountName` for AD)
`userRDNKey`	string	No	Relative Distinguished Name key for user entries
`enableAuthentication`	boolean	No	Enable LDAP bind authentication for end users
`loginUrl`	string	No	URL for the LDAP login form
`authenticationSearchScope`	string	No	LDAP search scope for authentication queries
`userAttributes`	string[]	No	LDAP attributes to retrieve during searches (e.g., `["cn", "mail", "memberOf"]`)
`objectClasses`	string[]	No	Object classes for the LDAP search filter (e.g., `["inetOrgPerson"]`)
`attributeMapping`	map	No	Map Orchestrator attribute names to LDAP attribute names (e.g., `email: "mail"`)
`attributeDelimiter`	string	No	Delimiter for multi-valued LDAP attributes (default: `","`)
`customLogin.templateFile`	string	No	Path to a custom HTML login form template
`tls`	string	No	Named TLS profile for LDAP connection
`healthCheck`	object	No	Health check monitoring configuration (see Identity Fabric Configuration Reference)

For the complete connector field reference including health check details, see Identity Fabric Configuration Reference.

The LDAP connector supports attributeMapping to translate between LDAP attribute names and Orchestrator attribute names. For example, mapping email: "mail" allows you to reference the attribute as ldap.email in header templates and policy rules, even though the LDAP directory stores it as mail. OIDC-based connectors do not have this field — they use claims directly from the OIDC token.

Troubleshooting

Test LDAP connectivity from the Orchestrator host — Use ldapsearch or a similar tool to verify the Orchestrator can reach the LDAP server on the configured port. Network firewalls or DNS issues are common causes of connection failures.
Verify the service account has read permissions on the baseDN — The bind DN specified in serviceAccountUsername must have sufficient permissions to search the baseDN subtree and read the attributes listed in userAttributes.
For LDAPS, ensure the TLS profile includes the correct CA certificate — If the LDAP server uses a private CA, the TLS profile referenced by the tls field must include the CA certificate via caFile. Self-signed certificates require insecureSkipVerify: true (not recommended for production).
Check attribute names in mapping — LDAP attribute names are case-insensitive in the protocol but must match the directory schema. Common sources of confusion: mail vs email, cn vs commonName, sAMAccountName vs uid.

LDAP Attribute Provider

LDAP attribute lookups without authentication

Active Directory

LDAP-based connector optimized for Active Directory environments

Identity Fabric

Overview of all identity providers

Continuity

IdP failover connector

Console Administration

Orchestration

Overview

Use Cases

Setup

Configuration Reference

Troubleshooting

LDAP Attribute Provider

Active Directory

Identity Fabric

Continuity

Console Administration

Orchestration

​Overview

​Use Cases

​Setup

​Configuration Reference

​Troubleshooting

​Related Pages

LDAP Attribute Provider

Active Directory

Identity Fabric

Continuity

Overview

Use Cases

Setup

Configuration Reference

Troubleshooting

Related Pages