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 plain LDAP and StartTLS, 636 for LDAPS. Selecting a transport-security mode swaps the port between those two standard values; any other port is left untouched. Check the field after switching modes if you had deliberately set 389 or 636.
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. Stored encrypted; once saved it is shown as ******** and never sent back to the browser.

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).

caution

Direct Bind authenticates as the user, so reading their attributes needs a separate connection. Set Bind DN and Bind Password as well, unless your directory allows anonymous read.

Without them MaestroHub can verify the password but cannot read anything else: the account is created with no email address, no name and no groups, so role mapping has nothing to match. Active Directory denies anonymous read by default.

About the Bind Password

The bind password is encrypted before it is written to the database and is never included in an API response. After you save a provider, the field shows ********.

• To keep the current password, leave the field showing ******** and save. Editing any other setting does not disturb it.
• To replace it, type the new password over the placeholder and save.
• To remove it, clear the field and save. The stored password is deleted.

Test Connection works on a saved provider without retyping the password: any field you leave masked is tested with the stored value.

The encryption key is created automatically on first start and kept in MaestroHub's secrets directory, alongside the persistent data volume. Back that directory up with your data: if the key is lost, saved bind passwords cannot be read back and you will need to re-enter the password for each provider.

Providers saved before this release still hold their bind password in clear text. They are converted automatically the next time MaestroHub starts, and keep working in the meantime.

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 LDAPS (implicit TLS)	Switch	Off	Encrypt the connection from the first byte, before any LDAP traffic. The standard port is 636.
Use StartTLS	Switch	Off	Connect in plain text on the standard LDAP port, then upgrade the connection to TLS. The standard port is 389.
Skip TLS Verification	Switch	Off	Skip certificate verification for TLS connections. Not recommended for production — use only for testing with self-signed certificates.

note

The two modes are mutually exclusive: turning one on turns the other off. Pick the one your directory offers — many directories serve LDAPS on 636, StartTLS on 389, or both.

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

Set these when your directory does not publish memberOf on user entries. That is the default state of OpenLDAP without the memberof overlay, 389 Directory Server without the MemberOf plug-in, and every RFC 2307 (posixGroup) directory. Active Directory always publishes memberOf, so these fields are optional there.

When Group Base DN is set, MaestroHub searches the group tree for groups that list the user as a member and adds them to whatever memberOf supplied. Nested groups — a group that is itself a member of another group — are resolved through the same search.

Field	Default	Description
Group Base DN	—	Base DN for group searches (e.g. ou=groups,dc=company,dc=com). Setting this turns on group-tree lookup and nested group resolution.
Group Filter	—	LDAP filter restricting which entries count as groups (e.g. (objectClass=groupOfNames)). Combined with the membership condition rather than replacing it.
Group Member Attribute	member	Attribute on group entries listing members. Use uniqueMember for groupOfUniqueNames, or memberUid for RFC 2307 posixGroup entries, which list bare login names rather than DNs.

note

Group lookup runs as the service account, so Bind DN and Bind Password must be set for it to work. Without them only memberOf is visible, and on a directory that does not publish it no groups are found at all.

Role Mapping

Optionally map LDAP groups to MaestroHub roles.

Field	Type	Default	Description
Enable Role Mapping	Switch	Off	Activate role mapping for this provider.
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 groups to MaestroHub roles (e.g., Admins → System.Admin).

LDAP providers have no Role Claim setting: group membership comes from the Member Of Attribute and the Group Settings search described above.

A mapping key may be either a group's full DN or its CN, and the match is exact — including case. Prefer the CN (Admins): it is short, and it is the form that does not depend on how your directory capitalises DN components. Active Directory returns CN=Admins,OU=Groups,DC=company,DC=com while OpenLDAP returns cn=admins,ou=groups,dc=example,dc=com, so a DN copied from the wrong console will not match.

Mapped roles are applied when the account is first created

Changing a mapping, or fixing group discovery, does not re-assign roles to users who have already logged in at least once. Their roles were set at first login and are not recomputed on subsequent logins.

So after correcting Group Settings on a provider whose users were already signing in, existing accounts keep whatever roles they had. Assign the roles to those users directly, or remove and let them be recreated on next login.

tip

If no user is receiving a mapped role, check Member Of Attribute and Group Settings first. On a directory that does not publish memberOf, role mapping has nothing to match until Group Base DN is set.

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 with StartTLS, or 636 with 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
Transport security	Use StartTLS on 389, or Use LDAPS on 636 — whichever your domain controllers serve

Active Directory publishes memberOf on user entries, so role mapping works without configuring Group Settings. Set Group Base DN if you also want nested groups (a group that is a member of another group) to resolve.

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.
Nobody gets a mapped role	Check whether your directory publishes memberOf on user entries (ldapsearch ... "(uid=someone)" memberOf). If it returns nothing, set Group Base DN, Group Filter and Group Member Attribute so groups are looked up from the group tree instead. Group lookup needs Bind DN and Bind Password. Note that this fixes future first logins — see the caution above about existing accounts.
Some users get roles, others don't	Check that the keys in Mappings match what the directory returns, including case. Either a group's full DN or its CN works.
A parent group never matches	Nested groups resolve only when Group Base DN is set.
A user is created with their login name in the email field	The directory published no readable mail attribute. With Direct Bind this usually means no service account is configured, so attributes cannot be read at all — set Bind DN and Bind Password, or point Email Attribute at an attribute your directory publishes.
"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).