LDAP Authentication/SSO

note

This feature is only available in the enterprise version.

LDAP single sign-on

Mosquitto Platform can authenticate users against a corporate directory over LDAP (for example Active Directory or OpenLDAP). After a successful LDAP login, the platform can map directory attributes such as group membership to project roles.

LDAP login cannot be combined with local username-and-password login. Do not list credentials together with ldap in AUTH_PROVIDERS.

Terminology

• Directory service is a hierarchical database of users, groups, and other objects.
• Active Directory is Microsoft's directory service. Other implementations include OpenLDAP, 389 Directory Server, and Apache Directory Server.
• LDAP (Lightweight Directory Access Protocol) is the protocol used to search and bind to a directory. This document uses “LDAP” for both the protocol and the directory service.
• DN (distinguished name) uniquely identifies an entry in the directory, for example CN=John Doe,OU=Users,DC=example,DC=com.
• LDAP entry is a directory record: a DN, object classes, and attributes.
• Bind is LDAP authentication: the client presents a DN and password.
• Search base is the DN from which user searches start.
• Claim in identity mapping is an LDAP attribute value (or a value synthesized from attributes) that a mapping rule can match.

Configure Mosquitto Platform

Complete these steps to enable LDAP login:

1. Decide which LDAP attribute is the unique user identifier (email, cn, or the full DN). That value is entered in the username field on login and signup.
2. Set AUTH_PROVIDERS and the required LDAP environment variables.
3. If the identifier is not a full DN, configure a search account and a user filter.
4. Start or restart Mosquitto Platform.
5. Provision users (first-user setup, allowlist signup, or Admin board).
6. Optionally, map LDAP groups or other attributes to project roles.

Start from a Platform instance that does not already have local users with the same emails (or other identifiers) as the LDAP users you will add. You can remove mosquitto-enterprise.sqlite3 from the data directory and restart, or delete accounts from Settings > Delete account. In Docker the data directory is usually data; for an RPM package it is under /var/opt/cedalo/mosquitto-platform.

Enable LDAP

Set AUTH_PROVIDERS to include ldap and omit credentials:

AUTH_PROVIDERS=ldap

If credentials is also listed, Mosquitto Platform disables the LDAP provider and logs a warning.

Required environment variables

Variable	Description
AUTH_PROVIDERS	Must include ldap and must not include credentials.
AUTH_LDAP_URL	LDAP server URI, including scheme and port. Example: ldap://ldap.example.com:389. Must start with ldap:// or ldaps://.
AUTH_LDAP_SEARCH_BASE_DN	DN from which user searches start. Example: dc=example,dc=org. Required even when usernames are full DNs.

Search account (when the username is not a DN)

If users log in with an email, cn, or another unique attribute rather than a full DN, Mosquitto Platform binds as a search account, finds the user's DN, then binds as that user to verify the password.

Variable	Description
AUTH_LDAP_ADMIN_DN	DN of the search account. Example: cn=admin,dc=example,dc=org.
AUTH_LDAP_ADMIN_PASSWORD	Password for that account.
AUTH_LDAP_ADMIN_PASSWORD_FILE_PATH	Full path to a file containing the password. Used if the inline password is unset.
AUTH_LDAP_FILTER	RFC 4515 search filter. Must contain %u, which is replaced by the escaped username. Example: (cn=%u) or (mail=%u).

If AUTH_LDAP_FILTER is unset, the default filter is (uid=%u).

If usernames are full DNs, omit the search account. Mosquitto Platform binds with the entered DN and password. Using DNs as usernames is not recommended: they are hard to type and can change when the directory tree is reorganized.

Optional environment variables

Variable	Description
AUTH_LDAP_SCOPE	Search scope: base, one, sub, or children. Default: sub.
AUTH_LDAP_DEREFERENCE_ALIASES	Alias policy from RFC 4511 §4.5.1.3: never, always, search, or find. Default: never. Use always or find if aliases may appear in the search base itself; use always or search if they appear in subordinates.
AUTH_LDAP_TIME_LIMIT	LDAP search time limit in seconds.
AUTH_LDAP_TIMEOUT	Client timeout in milliseconds.
AUTH_LDAP_CONNECT_TIMEOUT	Connect timeout in milliseconds.
AUTH_LDAP_INFER_NAME	When set, derive first and last name from the username (text before @, split on ., -, space, or _). Users can still edit names in settings.
AUTH_LDAP_DEFAULT_CLAIM_PATH	Default attribute path for identity-mapping rules that do not set a claim path. Default: groups. See Map attributes to project roles.

TLS (ldaps://). The typical port is 636. TLS options apply only when AUTH_LDAP_URL starts with ldaps://.

Variable	Description
AUTH_LDAP_SSL_REJECT_UNAUTHORIZED	0 or 1. When 1 (default for ldaps://), untrusted server certificates are rejected.
AUTH_LDAP_SSL_CA	CA certificate in PEM format that issued the LDAP server certificate.
AUTH_LDAP_SSL_CA_PATH	Full path to that CA certificate file.
AUTH_LDAP_SSL_CERT	Client certificate in PEM format, if the directory requires mutual TLS.
AUTH_LDAP_SSL_CERT_PATH	Full path to the client certificate.
AUTH_LDAP_SSL_KEY	Private key for the client certificate, PEM format.
AUTH_LDAP_SSL_KEY_PATH	Full path to the private key.

Inline certificate values are used when the corresponding *_PATH variable is unset.

User provisioning

AUTH_CUSTOM_ALLOWED_SIGNUP_EMAILS is a comma-separated allowlist of LDAP identifiers that may create a Platform account (setup or signup). Values must match the unique identifier used at login, which may be an email, another attribute, or a DN—not necessarily an email address.

Example for emails:

AUTH_CUSTOM_ALLOWED_SIGNUP_EMAILS=testuser@myorg.com,testuser2@myorg.com

For full DNs, quote each DN and wrap the whole value in single quotes:

AUTH_CUSTOM_ALLOWED_SIGNUP_EMAILS='"CN=John Doe,OU=Users,DC=example,DC=com","CN=Tom Second,OU=Users,DC=example,DC=com"'

After LDAP is enabled:

1. If the Platform has no users, the setup screen creates the first account from LDAP credentials. That first user becomes a root administrator.
2. An administrator can open Admin board > User management and create users with type LDAP.
3. Administrators can be granted in Admin board > Administrators.
4. Provisioned users sign in with their LDAP username and password.

An existing local account with the same identifier cannot be reused as an LDAP user.

Example

AUTH_PROVIDERS=ldap
AUTH_CUSTOM_ALLOWED_SIGNUP_EMAILS=testuser

AUTH_LDAP_URL=ldaps://ldap.example.com:636
AUTH_LDAP_SEARCH_BASE_DN=dc=example,dc=org
AUTH_LDAP_ADMIN_DN=cn=admin,dc=example,dc=org
AUTH_LDAP_ADMIN_PASSWORD_FILE_PATH=/run/secrets/ldap-admin-password
AUTH_LDAP_FILTER=(cn=%u)
AUTH_LDAP_SCOPE=sub
AUTH_LDAP_DEREFERENCE_ALIASES=never
AUTH_LDAP_SSL_REJECT_UNAUTHORIZED=1
AUTH_LDAP_DEFAULT_CLAIM_PATH=groups

Restart Mosquitto Platform after changing LDAP environment variables.

To log LDAP bind and search details, set AUTH_CUSTOM_DEBUG=1.

Configure the directory

The directory must allow Mosquitto Platform to:

• bind as the user (or as the search account, then as the user)
• search for the user under AUTH_LDAP_SEARCH_BASE_DN when a search account is configured
• read mapping attributes on the user entry after a successful bind

For identity mapping, the user entry must expose group membership as memberOf (Active Directory, or OpenLDAP with the memberOf overlay). Directories that only store members on the group object (uniqueMember, memberUid) do not populate memberOf on the user unless an overlay or equivalent is enabled.

If the search account can find the user but cannot read memberOf, Mosquitto Platform reads the entry again after binding as the user.

Map attributes to project roles

Project owners and project administrators can manage mappings in the Platform UI under Project settings > IdP Mapping. The page is shown on on-premise deployments when LDAP is enabled (or when another identity-mapping provider such as OIDC is configured).

The LDAP provider ID is ldap. Directory connection settings cannot be configured on this page; they come from environment variables.

Mappings are project-specific:

1. Select the LDAP provider.
2. Add one or more rules. Each rule contains:
   • Claim value regex: a regular expression matched against claim values.
   • Role: the project role granted by a match: Viewer, Editor, or Admin.
   • Claim path override: an optional path used instead of the LDAP default claim path.

The default claim path is displayed above the rule list. Leave the override empty to use that default.

LDAP claims

After a successful bind, Mosquitto Platform reads the user entry and builds claims from its attributes:

• Each requested attribute becomes a claim of the same name. Values are strings or arrays of strings.
• memberOf is always requested.
• Other attributes are requested automatically when they appear as a claim path on a stored LDAP mapping rule (for example department or ou).
• A synthetic groups claim is the CN of each memberOf DN. For example, CN=Platform Admins,OU=Groups,DC=example,DC=org becomes Platform Admins.

The default claim path is groups. Set AUTH_LDAP_DEFAULT_CLAIM_PATH=memberOf if rules should match full group DNs instead of CNs.

Examples:

Goal	Claim path	Example regex
Match a group CN	groups (or empty)	^Platform Admins$
Match a full group DN	memberOf	CN=Platform Admins,.*
Match another user attribute	department	^engineering$

Claim values and regular expressions

A claim can be either a string or an array of non-empty strings. Other value types do not match. A rule matches when its regular expression matches at least one value.

Regular expressions always match the complete claim value. For example:

• engineering matches only engineering.
• engineering-.* matches values such as engineering-eu.
• team-(reader|writer) matches either team-reader or team-writer.

The expression must not be empty or longer than 250 characters. Expressions that are excessively broad, susceptible to catastrophic backtracking, or use lookahead, lookbehind, or backreferences are rejected.

Rules with the same provider, project, claim path, and regular expression are duplicates and cannot be added, even if they specify different roles.

How roles are synchronized

Role mappings are evaluated after every successful LDAP sign-in:

1. Mosquitto Platform reads the user entry and builds claims as described above.
2. It evaluates all LDAP rules across all projects.
3. A matching rule adds a provider-managed project membership (mapped is ldap).
4. If several rules match the same project, the highest role wins: Admin, then Editor, then Viewer.
5. A changed match updates the provider-managed role. If no rule matches anymore, the provider-managed membership is removed.

Manually assigned project memberships (mapped is empty) are never changed or removed by LDAP mapping. A mapping does not replace a manual role, even when the mapping would grant a higher role.

Projects the user owns are not affected.

If group attributes cannot be read, the user can still sign in. Provider-managed LDAP memberships are then removed, so the user only keeps owned projects and manual memberships until a later login can read memberOf again.

Rule changes are applied when the affected user next signs in. Saving or deleting a rule does not immediately recalculate memberships for users who are already signed in. The mapping page does not provide a rule preview or test action.

Limitations

SASL authentication mechanisms are not supported.

Identity mapping is available on on-premise deployments only.

Identity mapping uses memberOf on the user entry (direct group membership). Nested Active Directory groups (tokenGroups) and OpenLDAP posixGroup / memberUid memberships are not resolved. OpenLDAP requires the memberOf overlay.

Active Directory users who belong to many groups may receive memberOf;range=0-1499 instead of memberOf. Those ranged results are not followed, so mapping may miss groups.

Using a full DN as the Platform username is supported but not recommended.