LDAP Authentication/SSO

note

This feature is only available in the enterprise version.

LDAP SSO (Single Sign-On)

LDAP authentication/SSO feature allows Mosquitto MQTT Platform users to authenticate into the application using their corporate directory information service (LDAP) such as Active Directory. This allows for Platform's interoperability with existing user pfofiles within the organisation.

This feature can be configured by specifying several environment variables detailed in the configuration section below.

Terminology

• Directory service (or directory information service) - A hierarchical database system that stores and organizes information about network resources, users, and other objects in a centralized location.
• Active Directory - Microsoft's implementation of the active directory service commonly used in corporate organisations. Other implementations are: OpenLDAP, 389 Directory Serverm Apache Directory Server etc.
• LDAP (Lightweight Directory Access Protocol) - A protocol for accessing and managing directory information services. It facilitates a unified access to user information for enabling single sign-on (SSO) capabilities across different applications. In this documentation the name of the protocol is used interchangably with directory information service.
• DN - Distinguished Name. It is a string that uniquely identifies an entry (such as a user, group, or other objects) in the LDAP directory hierarchy. An example of a DN would be: CN=John Doe,OU=Users,DC=example,DC=com.
• LDAP record (or LDAP entry) - a record in the directory service database that holds a collection of information about an entity such as user, network resource etc. Each entry contains a distinguished name (DN), a set of attriiibutes, and a one or more object classes that define what attributes are required and allowed for that entry.

Configuration

Before configuring LDAP SSO, you should first know what is being used as a primary identifier of a LDAP user in your system. By default a full distinguished name is assumed to be an identifier but for ease of use many organisations define a unique LDAP record attribute such as mail (email) and use it to uniquely identify a user. This identifier is what's being accepted by the username field on the login and sign up pages of the Platform. If you are not using full DN as an identifer, then a separate administrative user with search privileges as well as a filter criteria have to be supplied to be able to perform search requests on the directory service. These search requests are used to find a corresponding user record's DN when binding user to the directory service. More details are explained below.

It's recommended (but not required) to start with a clean Platform that doesn't have any users. You can delete mosquitto-enterprise.sqlite3 file to achieve this and restart the platform. The file is stored in the data directory which depends on your installation, but in Docker environments it's usually called data, while for an RPM-package it's located under var/opt/cedalo/mosquitto-platform. You can also manually delete your users as an administrator or by signing in one user at a time and navigating to Settings -> Delete account. A crucial point is to make sure you don't have any existing Platform users that use the same email as LDAP users you want to add (in case emails are the primary identifiers of your LDAP users).

Now that you have identified a unique attribute to be used as a username, to configure the LDAP SSO feature you have to:

• Add ldap to the comma separated list of authentication providers specified in AUTH_PROVIDERS environement variable.

• Specify AUTH_LDAP_URL to set a URI of the LDAP server. It must include a protocol, port, and path (if any). For instance, ldap://ldap.example.com:389.

• Specify LDAP usernames, DNs, or emails that you want to register in Mosquitto Platform as a comma separated list in the AUTH_CUSTOM_ALLOWED_SIGNUP_EMAILS environemnt varaible. Example: testuser@myorg.com,testuser2@myorg.com.

• Set AUTH_LDAP_SEARCH_BASE_DN to define a search base, i.e. a DN starting from which a search for users will be performed. Example: dc=example,dc=org.

• If you are using something such as an email instead of a full user DN as username in your systems, then you will need an administrative user to bind to LDAP and find a corresponding user record. Specify credentials to use when binding administrative user to the LDAP server using the following entironment varaibles: AUTH_LDAP_ADMIN_DN (distinguished name of the admin user) and AUTH_LDAP_ADMIN_PASSWORD (a plain text password) or AUTH_LDAP_ADMIN_PASSWORD_FILE_PATH (a full path to a plain text file with the password). An example value for AUTH_LDAP_ADMIN_DN can be: cn=admin,dc=example,dc=org.

• After specifying all the required environment variables, you can start Mosquitto Platform and open it in your browser. If you don't have any users you will be greeted with a Setup screen where you can enter your LDAP credentials to create an admin user and sign in. In case you already have users in the platform, you will have to login using an admin account.

• After you are signed in as an admin, you can click on the top-right menu and choose "Admin board".

• Navigate to "User management" and create new users specifying LDAP as a user type.

• You can also choose to make some users admins in "Administrators" section on the left-hand side.

• After users were created, they can be used to login to the Platform by entering LDAP credentials.

You can optionally specify the following variables:

• AUTH_LDAP_FILTER. The filter criteria of the user search as specified in RFC4515. To specify username of the application (usernmae field from login and sign up pages) put %u into the filter string. Example: (cn=%u). This is needed if you are using a certain LDAP record's attribute such as an email instead of its full DN to identify a user.
• AUTH_LDAP_SCOPE. Scope of the user search. User search is performed on the LDAP server. Possible values are base - search only the search base (AUTH_LDAP_SEARCH_BASE_DN) entry. one - search only the immediate children of the search base entry. sub - search the search base entry as well as all its subordinates to any depth. children - don't search the search base entry but serach its subordinates to any depth. Default value: sub.
• AUTH_LDAP_DEREFERENCE_ALIASES. LDAP alias dereferencing policy as specified in 4.5.1.3 subsection of RFC4511. Possible values are: never - don't dereference aliases. always - dereference aliases both in searching and in locating the base object of the search. search - dereference aliases only when searching subordinates. find - dereference aliases only in locating the base object of the search. The always and find policies are applicable when aliases may be present in the search base object itself (AUTH_LDAP_SEARCH_BASE_DN). Conversly, if aliases are present in subordinates of the serach base object, use always or search. Default: never.

To define optoinal SSL options for ldaps protocol, SSL must also be supported by the LDAP server. Note that the typical port for the LDAP secure connection is 636, so AUTH_LDAP_URL might also need to be changed when using SSL:

• AUTH_LDAP_SSL_REJECT_UNAUTHORIZED - to specify whether to reject connections to LDAP servers that provide TLS certificates not trusted by the client (Mosquitto Platform). To set a particular custom certificate as trusted you will need to set AUTH_LDAP_SSL_CA (or AUTH_LDAP_SSL_CA_FILE_PATH) to a certificate of the certificates authority (CA) that issued this particular certificate of interest.

• AUTH_LDAP_SSL_CA or AUTH_LDAP_SSL_CA_FILE_PATH - to specify a plaintext or a full file path to a custom certificate of the certificate authority that issued the LDAP server's certificate in PEM foramt.

• AUTH_LDAP_SSL_CERT or AUTH_LDAP_SSL_CERT_FILE_PATH- to specify a plaintext or a full file path to a client certificate which belongs to the application (Mosquitto Platform) and is acknowledged by the identity provider. Certificate in PEM format base 64 encoded.

• AUTH_LDAP_SSL_KEY or AUTH_LDAP_SSL_KEY_FILE_PATH - to specify a plaintext or a full file path to a private key of the client certificate which belongs to the application (Mosquitto Platform) in PEM format

• AUTH_LDAP_INFER_NAME - whether to try to extract user's first name and last name from the username field. This extraction will remove everything after the @ symbol in the username field and look for a seperator such as ., -, , or _. If a separator is found, the first part of the string before it becomes user's first name and second part - their last name. ou can set this varaible to 1 to enbale the inference. If this variable is not set or first and last name could not be extracted, you will be able to set them in user settings.

Note that when using LDAP authentication, the values in AUTH_CUSTOM_ALLOWED_SIGNUP_EMAILS should match the LDAP record's attribute you're using as a unique identifier for user authentication. As discussed in the beginning of this section, this may not necessarily be the full DN. The only requirements to such an attribute is that it should uniquely identify a user entry and be searchable with a filter criteria in AUTH_LDAP_FILTER. However, if you are actually using DNs, you must use double quotes around each DN and single quotes around the entire environment variable value. For example: AUTH_CUSTOM_ALLOWED_SIGNUP_EMAILS='"CN=John Doe,OU=Users,DC=example,DC=com","CN=Tom Second,OU=Users,DC=example,DC=com"' Additinally, note that in case of using full DNs you will be specifying them as usernames when signing up and logging into Mosquitto Platform and you don't have to specify an admin user credentials in this case. Admin user is used to search for a record and find it's DN. So, if you are using DNs, the user will be bound to LDAP directly without requiring a search step. Note that using DNs directly is not recommended as not only are they complex as they capture a hierarchical structure of the directory service but they may alsoee change when modifications to the user record are made (e.g. organisation changes).

To debug LDAP authentication flow:

• Set AUTH_CUSTOM_DEBUG environement variable to 1

Limitations

SASL authenticaton mechanisms are currently not supported.