Jitsi LDAP and Active Directory authentication

The choice is between two ways of making Prosody check room creators against an LDAP directory. On Debian or Ubuntu packages, the Jitsi handbook's LDAP guide has Prosody authenticate through saslauthd, the Cyrus SASL daemon, using the mod_auth_cyrus community module. In Docker, you enable ENABLE_AUTH and set AUTH_TYPE=ldap in the .env file, and the container configuration handles the wiring. Decide on the basis of how your team already deploys and operates Jitsi. The route that fits your change process and on-call model matters more than which one has fewer steps on the first day.

The Debian route depends on two things you must own. The first is a community module, which is not part of the core Jitsi packages, so you need to confirm that mod_auth_cyrus works with the Prosody version your distribution ships. The second is a set of host-level services: saslauthd must run on the same server, its configuration and socket permissions must be correct, and it has its own upgrade cycle. Each Prosody or operating system upgrade is a point where authentication can break without any change to Jitsi itself. Name who owns those host services and who gets paged when room creation fails.

The Docker route keeps the LDAP settings in one file. The variables that control the connection, including LDAP_URL, LDAP_BASE, LDAP_BINDDN and LDAP_FILTER, sit beside the rest of your deployment configuration, so they can be reviewed, versioned and compared between staging and production. The trade-off is that the bind credentials live in that same file, so it needs the same secret handling as other service passwords. Also check that the variable names in your image version match the handbook's Docker guide before you rely on them.

The handbook marks the LDAP guide as a first draft. It was tested on Debian 11 with OpenLDAP and on Ubuntu 24.04 with Active Directory. Debian 11 is older than the Debian 12 minimum in the Jitsi quick start, so if your hosts run Debian 12 or newer, the guide's test platform does not match yours. Before you pick a route, build a staging environment against your own directory, confirm mod_auth_cyrus compatibility with your Prosody version, and schedule test time for both a standard login and a failed login. Ask any implementation partner to state that testing time as a separate line in the written scope.

The most common Active Directory failure is the user search filter, so check it before anything else. The Jitsi handbook notes that LDAP filters default to uid=%u, which matches the uid attribute that OpenLDAP directories typically use for login names. Active Directory user objects usually do not carry a uid value for sign-in, so Samba and Active Directory deployments generally need (sAMAccountName=%U) in the LDAP_FILTER variable instead. Ask your directory team which attribute holds the name users type at sign-in, then test with one account from the group that should be allowed to create rooms. Confirm in the handbook how the placeholder is expanded in your Jitsi version, because the case and form of the name passed to the filter decide whether the lookup succeeds.

Three Docker variables control the transport, and each is a separate decision. LDAP_USE_TLS, LDAP_START_TLS and LDAP_TLS_CHECK_PEER govern whether the connection is encrypted from the first packet, whether a plain connection is upgraded with StartTLS, and whether the server certificate is verified. The LDAP_URL scheme and port must agree with the setting you choose, and the directory listener your Active Directory team exposes determines which combination is valid. Do not copy values from an example file or a forum post. Confirm each one against the listener the domain controllers actually offer, and record the chosen combination in your configuration documentation so that a later upgrade does not silently change it.

The peer check setting is where the trade-off is sharpest. If verification is switched off to get logins working, Jitsi may accept a directory server whose identity has never been validated, and users see a successful sign-in, so the weakness goes unnoticed. If verification is on and the directory presents a chain that the Jitsi host does not trust, every login fails, and the error often appears only in container or Prosody logs. The correct fix is to install the issuing certificate authority chain in the trust store that the Jitsi containers read, and to confirm that the name in LDAP_URL matches a name on the domain controller certificate. Test the chain from the Jitsi host with a TLS client tool before changing any Jitsi setting.

The directory trust and the public web certificate are separate decisions, and they should be documented separately. The Jitsi handbook says HTTPS with a proper domain certificate is necessary for working audio and video, and it warns that self-signed certificates cause problems, especially with mobile clients. Trusting your internal authority for LDAP does not make browsers trust the meeting site, and a public web certificate does nothing for the directory connection. For each one, record the signing authority, the host where the trust is installed, the owner responsible for renewal and the expiry process. Ask your PKI team to confirm both records before the first production sign-in test.

Before any user is told to sign in with directory credentials, the team should run a fixed test plan against the live login path and keep the results. The plan should start with a dedicated test organizational unit or group in the directory, populated with a small set of known accounts that cover the cases below. Using a test population keeps the checks repeatable, avoids locking out real staff during troubleshooting, and gives a reviewer a clear record of which accounts were used and what each one was expected to do.

Positive tests. A valid test account should sign in through the Jitsi login flow and be able to create a room. Confirm that the room opens, that the account is recognized as the room creator, and that the same result holds after the Prosody service restarts. Repeat the check for a second account drawn from a different branch of the directory tree, because a filter that works for one group can silently fail for another.

Negative tests. Wrong passwords, disabled accounts and accounts outside the search base should all be refused. The disabled-account case matters most in Active Directory, where a disabled user may still authenticate against some bind paths if the filter or bind account is set up loosely. Test an account that exists in the wider forest but sits outside LDAP_BASE, because a common misconfiguration returns a successful result for it. Record the exact error each case produces, and confirm that no room is created in any negative case.

TLS tests. Run the TLS checks from the Jitsi host itself, using the same LDAP_URL, certificate trust store, LDAP_USE_TLS, LDAP_TLS_CHECK_PEER and LDAP_START_TLS values that Prosody uses. Testing from an administrator workstation proves little, because the workstation may trust a different certificate chain. Confirm that the directory certificate validates against the expected name and that a deliberately wrong hostname or untrusted chain fails. The handbook's LDAP guide and Docker setup page describe these variables, and the team should confirm how their chosen Jitsi packaging applies them before relying on the results.

Rollback plan and change control. Before the first test run, save the previous configuration, whether that is the Prosody settings, the saslauthd configuration or the Docker .env values, so it can be restored exactly. Write down the steps to revert and who is authorized to run them. Keep the configuration files, the test account list, the commands run and the raw results under change control, with dates, versions and approvers. Security and compliance reviewers will ask for this evidence, and a documented rollback is what allows a failed change to be reversed without improvising under pressure.

For new installations, LDAP is often the wrong choice when your organization wants an identity provider to decide who can create a Jitsi room. The Jitsi handbook marks the older secure domain method, which uses a username and password at room creation, as deprecated for new installations. It recommends JWT token authentication instead, paired with a separate anonymous domain for guests. Before you commit to the LDAP route described in this topic, check whether that recommendation changes your design. An LDAP setup still ends with Prosody checking credentials against a directory, so the handbook's deprecation note is the first fact to put in front of your architecture review.

Three questions decide the route. First, does an identity provider already issue tokens for your users? If your organization already signs people in through an OpenID Connect or SAML provider, a token-based design reuses that sign-in and avoids creating a second place where passwords are checked. Second, do you want another application to decide when a meeting exists and who may enter it? JWT tokens let a portal, booking system or intranet issue a signed token for a specific room and user, which gives per-meeting control that a directory bind cannot express. Third, can your team support a Prosody module path? The LDAP guide relies on Cyrus SASL (saslauthd) and the mod_auth_cyrus community module, so someone must own those packages, their upgrades and the Prosody configuration that remains after each Jitsi release.

LDAP can still be the right choice when the directory is the system of record and the team wants room creators to use their existing directory accounts without a token service. Directory-first environments with OpenLDAP or Active Directory, a stable Prosody host and a small number of named hosts often fit this model well. In that case, confirm three things before build: the filter that matches your schema (uid=%u by default, or (sAMAccountName=%U) for Samba or Active Directory, as the handbook notes), the TLS settings your directory accepts, and who will test sign-in after each upgrade. Document those answers in the design record so the choice is reviewable.

If your organization is leaning toward tokens, the token-based route is covered on the separate Keycloak SSO page for Jitsi. That page explains how to place room creation behind Keycloak with OpenID Connect, including realm and client setup, Prosody token settings, wait-for-host behavior and the config.js SSO URLs. Plan the Keycloak work as its own project with its own owner, and do not treat it as a configuration tweak to an LDAP deployment. Moving from LDAP to tokens later means changing the Prosody authentication path, the guest domain and the way users reach the meeting, so it is cheaper to decide before the first production rooms exist.

Whichever route you choose, record the decision and the owner of each dependency. Ask your implementation partner or internal team to confirm which Jitsi release and Docker or Debian packaging you will run, because the authentication settings and file paths differ between them. Confirm with your identity team which directory or token issuer is authoritative, and with your security team how room creators will be removed when they leave. A short written comparison of the two routes, scored against the three questions above, gives reviewers a clear basis for approving LDAP or moving to JWT.