LDAP / Active Directory

LDAP (Lightweight Directory Access Protocol) provides direct integration with on-premise directory services. Use it to connect to Active Directory, OpenLDAP, FreeIPA, or any other LDAP-compliant directory server.

How It Works

1. A user clicks Sign in with {Provider Name} on the login page and enters their directory username and password.
2. MaestroHub connects to the LDAP server using one of two methods:
   • Search Bind (default): Binds with a service account, searches for the user by filter, then re-binds with the user's DN and password.
   • Direct Bind: Constructs the user's DN from a template and binds directly with their password.
3. If authentication succeeds, MaestroHub retrieves user attributes and group memberships from the directory.
4. A local user account is created or linked, roles are mapped from directory groups, and the user is logged in.

Configuration Reference

Connection Settings

Field	Type	Required	Default	Description
Host	Text	Yes	—	LDAP server hostname or IP address (e.g., ldap.company.com or 192.168.1.100). Do not include the protocol prefix.
Port	Number	No	389	LDAP port. Standard ports: 389 for LDAP, 636 for LDAPS. Automatically set to 636 when TLS is enabled and port is left at 389.
Base DN	Text	Yes	—	Base Distinguished Name for user searches (e.g., dc=company,dc=com). All user searches start from this point in the directory tree.

Authentication Method

Field	Type	Default	Description
Bind Method	Select	Search Bind	Search Bind (recommended): Uses a service account to find the user, then authenticates as the user. Works with any directory structure. Direct Bind: Constructs the user's DN from a template — faster but requires a predictable DN structure.

Search Bind Fields

Field	Type	Required	Description
Bind DN	Text	No	Distinguished Name of the service account (e.g., cn=ldap-service,ou=service-accounts,dc=company,dc=com). Leave empty for anonymous bind (if your server allows it).
Bind Password	Password	No	Password for the service account. Required if Bind DN is set.

Direct Bind Fields

Field	Type	Required	Description
User DN Template	Text	Yes	Template for constructing the user's DN. Use %s as a placeholder for the username (e.g., uid=%s,ou=users,dc=company,dc=com).

Search Settings

Field	Type	Default	Description
User Filter	Text	(uid=%s)	LDAP filter for finding user entries. %s is replaced with the username entered at login. For Active Directory, use (sAMAccountName=%s).
Search Scope	Select	Subtree	How deep to search from the Base DN. Base: only the Base DN entry. One Level: direct children of Base DN. Subtree (default): entire tree below Base DN.

Advanced Settings

TLS/SSL

Field	Type	Default	Description
Use STARTTLS	Switch	Off	Upgrade the plain LDAP connection to TLS after connecting (port 389). Use this for encrypted connections on the standard port.
Skip TLS Verification	Switch	Off	Skip certificate verification for TLS connections. Not recommended for production — use only for testing with self-signed certificates.

note

For LDAPS (TLS from connection start), set the port to 636 and enable STARTTLS. The connection will use TLS immediately.

Timeouts

Field	Type	Default	Range	Description
Connection Timeout	Number (seconds)	10	1–120	Maximum time to wait when establishing a connection to the LDAP server.
Request Timeout	Number (seconds)	30	1–300	Maximum time to wait for LDAP operations (search, bind) to complete.

Attribute Mapping

Map LDAP attributes to MaestroHub user fields. The defaults work with most standard LDAP schemas. Active Directory equivalents are noted where they differ.

Field	Default	AD Equivalent	Description
UID Attribute	entryUUID	objectGUID	Unique identifier attribute. Used to match directory users to local accounts across sessions.
Email Attribute	mail	mail	Email address attribute.
First Name Attribute	givenName	givenName	First name attribute.
Last Name Attribute	sn	sn	Last name (surname) attribute.
Display Name Attribute	displayName	displayName	Full display name attribute.
Member Of Attribute	memberOf	memberOf	Group membership attribute on user entries. Used for role mapping.

Group Settings

These optional fields support advanced group lookup when the memberOf attribute is not available on user entries.

Field	Default	Description
Group Base DN	—	Base DN for group searches, if different from the user Base DN.
Group Filter	—	LDAP filter for finding groups.
Group Member Attribute	member	Attribute on group entries that lists member DNs.

Role Mapping

Optionally map LDAP groups to MaestroHub roles.

Field	Type	Default	Description
Enable Role Mapping	Switch	Off	Activate role mapping for this provider.
Role Claim	Text	memberOf	The attribute containing group memberships. Defaults to memberOf. LDAP groups are automatically extracted — you usually don't need to change this.
Default Role	Select	Member	Role assigned when no mapping matches.
Strict Enrollment	Switch	Off	Block login if no specific mapping matches.
Mappings	Key → Value pairs	—	Map LDAP group DNs or names to MaestroHub roles (e.g., cn=Admins,ou=Groups,dc=company,dc=com → System.Admin).

Setup Guide

Step 1: Prepare the LDAP Server

Ensure you have:

• Server hostname and port — network accessibility from the MaestroHub server.
• Service account (for Search Bind) — a dedicated LDAP account with read access to user entries. Note its full DN and password.
• Base DN — the starting point in the directory tree where your users are located.
• User filter — know which attribute your users log in with (uid for standard LDAP, sAMAccountName for Active Directory).

Step 2: Create the Provider in MaestroHub

1. Go to Identity & Access → SSO Configuration.
2. Click Add Provider → LDAP / Active Directory.
3. Fill in:
   • Host and Port
   • Base DN
   • Bind Method — choose Search Bind or Direct Bind
   • Bind DN and Bind Password (for Search Bind)
   • User DN Template (for Direct Bind)
4. Adjust the User Filter if needed (e.g., (sAMAccountName=%s) for Active Directory).

Step 3: Test and Enable

1. Click Test Connection. MaestroHub connects to the LDAP server and performs a service account bind.
2. A success message confirms connectivity. If it fails, check the host, port, Bind DN, and password.
3. Save the provider.
4. The provider appears on the login page. Users see a username/password form when they select it.

Active Directory Quick Setup

For a typical Active Directory environment:

Field	Value
Host	ad.company.com
Port	389 (or 636 for LDAPS)
Base DN	dc=company,dc=com
Bind Method	Search Bind
Bind DN	cn=svc-maestrohub,ou=Service Accounts,dc=company,dc=com
User Filter	(sAMAccountName=%s)
UID Attribute	objectGUID
Use STARTTLS	On (recommended)

Login Experience

Unlike OIDC and SAML (which redirect to an external login page), LDAP authentication uses an inline login form directly on the MaestroHub login page:

1. The user selects their LDAP provider from a dropdown (if multiple are configured).
2. They enter their directory username and password.
3. MaestroHub authenticates against the LDAP server in the background.
4. On success, the user is logged in immediately without any redirect.

Troubleshooting

Problem	Solution
"Connection failed"	Verify the hostname, port, and network connectivity. Ensure the LDAP port is not blocked by a firewall. Test with 389 before trying 636.
"Bind failed"	Confirm the Bind DN and Bind Password are correct. The service account must have permission to search the user Base DN.
"User not found"	Check the Base DN and User Filter. Ensure the user exists under the Base DN and the filter matches their attributes. For AD, use (sAMAccountName=%s) not (uid=%s).
"Invalid credentials"	The user's password is incorrect, or the account is locked/disabled in the directory. Check the directory directly.
"TLS errors"	When using STARTTLS or LDAPS, ensure the server's certificate is valid. Use Skip TLS Verification only for testing with self-signed certificates.
"Timeout errors"	Increase the Connection Timeout and Request Timeout values. Check network latency to the LDAP server.
Users not getting correct roles	Verify the Member Of Attribute is populated on user entries. For AD, ensure group membership is replicated. Check that the group DNs in Mappings match exactly.
"Multiple users found"	The User Filter is matching more than one entry. Make the filter more specific (e.g., add (objectClass=person) to narrow results).