Jitsi and Matrix integration

Prosody makes the membership decision, not the web app or the conference focus. When Matrix user verification is enabled through the Prosody Auth Matrix User Verification module, Prosody sends the Matrix token from a joining participant to the endpoint set in MATRIX_UVS_URL. The module checks that the token was issued by the issuer named in MATRIX_UVS_ISSUER, and it authenticates its own call to the service with MATRIX_UVS_AUTH_TOKEN. Prosody only admits the participant if the service confirms the Matrix identity and the room membership that the conference depends on. Because the check runs in Prosody, the security of the join depends on three values being correct and on the service being reachable from the Prosody container.

The exact request and response behavior is the part you must verify before you rely on it. This page does not set out the HTTP methods, request fields, headers, or the response that signals a valid member, and those details can change between releases of the module and the Docker guide. Read the Docker guide for the Matrix user verification settings in the release you deploy, then read the documentation for your verification service to confirm what it accepts and returns. Ask the team that runs the service for a sample request and response from a member, a non-member, and an expired or malformed token, and keep those samples with your deployment records.

The hybrid_matrix_token auth type accepts both Matrix tokens and JWT tokens. A Matrix-only setup restricts entry to people whose Matrix identity passes the verification check, so room membership on your homeserver controls who joins. A hybrid setup adds a second path: a participant who presents a valid JWT can join without going through the Matrix check. That changes the access model. You need to decide who is allowed to issue JWTs for your deployment, whether guests from a portal or an external system should receive them, and whether those participants should be restricted in some other way. Treat the hybrid choice as a change to your membership policy, not only as a configuration option.

Plan the checks and the failure behavior before users depend on the integration. Test four cases with the exact settings you intend to run: a room member, a user outside the room, a token from an unexpected issuer, and a request made while the verification service is down. Confirm that the MATRIX_UVS_ISSUER value matches the issuer your Matrix stack actually emits, and confirm that a failed verification call denies the join rather than admitting the participant. Record who owns MATRIX_UVS_AUTH_TOKEN, where it is stored, and how it is rotated, since a leaked or expired value will either block legitimate members or expose the verification endpoint.

The first decision is which identity source decides who may enter a room. Matrix user verification alone fits an organization whose intended participants all hold accounts on the Matrix homeserver that backs the room. In this model, the Prosody server asks the Matrix user verification service, configured through MATRIX_UVS_URL, MATRIX_UVS_ISSUER and MATRIX_UVS_AUTH_TOKEN, whether a participant is a valid Matrix user, and room membership then governs access. Before you choose this path, confirm with your homeserver team that every participant has an account on that server and that the verification endpoint is reachable from the Prosody container.

The hybrid_matrix_token type supports both Matrix and JWT token authentication in one deployment. It becomes relevant when some participants, such as external guests, contractors or automated systems, need tokens from another system and cannot hold Matrix accounts. Each path brings its own trust boundary: a token issuer whose signing keys, claims and rotation you control, and a Matrix verification service that depends on your homeserver. Ask who issues the tokens, who maintains key rotation, and whether Matrix membership should still matter for people who arrive with a token. Confirm in the Docker guide how the hybrid mode decides which path applies to a join attempt before you promise guests access.

The Jitsi handbook recommends JWT token authentication and marks the older secure domain method, which relies on username and password room creation, as deprecated for new installations. JWT moves admission into a token that your identity system signs, so the server checks claims such as the room and the user's role before the participant joins. The handbook also recommends a separate anonymous domain for guests. Guests then join through a domain that carries no authenticated identity, which keeps rooms that require sign-in apart from open access. Confirm the exact configuration keys in the token authentication guide, and test both domains with a guest account and an authenticated account before you rely on the split.

MATRIX_LOBBY_BYPASS lets Matrix room members skip the Jitsi lobby. The convenience is clear: members of a standing team room join immediately, and no host has to admit each one. The cost is that anyone who passes the membership check also skips the moment when a host sees a name and decides. A reasonable approach is to enable bypass for internal rooms whose membership your organization already governs, and to keep lobby admission for rooms that external parties enter. Write down which rooms fall into each group, and check the behavior with a moderator and a non-member before go-live.

MATRIX_UVS_SYNC_POWER_LEVELS makes Matrix room moderators owners of the Prosody room. This ties Jitsi ownership to Matrix power levels, so a change in Matrix changes who can manage the Jitsi room. The decision is therefore an access decision as well as a convenience setting. Review which accounts hold high power levels in each Matrix room that maps to a Jitsi room, remove stale moderators on a set schedule, and confirm that your room owners understand that a Matrix role change also affects Jitsi.

The Matrix homeserver you run determines what the Jitsi integration can check against, so settle this choice before you edit the Jitsi .env file. Matrix.org's ecosystem page lists several homeserver implementations: Synapse, Dendrite, Conduit and its Rust forks Continuwuity and Tuwunel, and Element's commercial Synapse Pro. Synapse is the most widely documented of these, so most teams will compare against it first. Whichever server you choose, the Jitsi side depends on the Matrix user verification endpoint that MATRIX_UVS_URL points to. The homeserver and its version therefore belong in the Jitsi design from the start, and the team that runs the homeserver should sign off on that choice.

Synapse is developed by Element and distributed under AGPL-3.0, and Element sells commercial licenses for organizations that need terms beyond the AGPL. Confirm with your legal team whether running an AGPL-licensed server in your environment, including any modifications you make, creates obligations you must plan for, and whether a commercial license is needed. Licensing has also changed recently. On December 13, 2023, Element announced that future Synapse contributions would be licensed under AGPLv3 instead of Apache 2.0, that the repositories moved from matrix-org to element-hq on GitHub, and that contributors sign a CLA. If your engineers send patches upstream, the CLA terms apply to those contributions, and someone in your organization should review them before anyone signs.

Version floors constrain the database and runtime your platform team must build. Synapse 1.143.0 and later require PostgreSQL 14 or newer, and 1.142.0 and later require Python 3.10 or newer. Synapse documentation recommends PostgreSQL for production, with SQLite also supported, so a SQLite-based test homeserver may not match the database your production deployment uses. Check the upgrade notes for each version you plan to run. They also state that Synapse drops support for Python and PostgreSQL versions once those reach upstream end of life, so your database and host operating system lifecycles set the Synapse versions you can stay on.

Plan every homeserver upgrade with a rollback path that you have tested. The Synapse upgrade notes warn that rolling back can be difficult because database schema changes occur between releases. For this integration, a homeserver upgrade can change the behavior that the Jitsi verification depends on, and reverting the homeserver alone may not restore the earlier state. Take a database backup before each upgrade, record the exact Synapse and PostgreSQL versions in your change record, and schedule the upgrade in a window where room access can be checked afterward. Ask the homeserver operator which backups they will take and how long a restore takes in your environment.

Before go-live, confirm the verification integration against the homeserver and version you chose. The Jitsi Docker guide documents MATRIX_UVS_URL, MATRIX_UVS_ISSUER and MATRIX_UVS_AUTH_TOKEN, along with MATRIX_UVS_SYNC_POWER_LEVELS for moderators and the hybrid_matrix_token type for running Matrix and JWT together. Test with at least one room member, one non-member and one moderator, using the same homeserver version you will run in production. Record the results and repeat the test after every homeserver upgrade. The guide's settings are a starting point, but the endpoint behavior and token format come from your homeserver and its version, so confirm them there.

Test membership, moderator sync and lobby behavior against the access policy you agreed before any configuration was changed. The test cases should be written from that policy, not from what the configuration happens to do, because a test built from the configuration can only confirm the configuration. Before running anything, write down who may enter a conference, who may hold moderator rights, and who may skip the lobby, and map each of those statements to a test case with an expected result.

Build a dedicated Matrix test room with four accounts: one member, one non-member, one moderator and one guest. Use accounts that are clearly labeled as test users so they can be disabled afterward. For each account, attempt to join the Jitsi conference linked to the room and record the outcome. The member and moderator should be admitted under the rules your policy sets, the non-member should be refused, and the guest should follow whatever guest path you documented. Confirm the result from the Matrix user verification side as well, since the Prosody Auth Matrix User Verification module is the component making the decision. Do not rely only on what the browser displays.

Next, confirm the moderator sync. Set MATRIX_UVS_SYNC_POWER_LEVELS in the Docker .env file as your design specifies, then check that the Matrix moderator becomes the owner of the Prosody room. Verify this in the Prosody logs or with the administrative tools your deployment exposes, and confirm that a Matrix user without moderator power in the room does not gain owner status. Also confirm lobby behavior: members configured for MATRIX_LOBBY_BYPASS should join without waiting, and everyone else should wait in the lobby. Run this check for each role, because lobby bypass is the setting most often assumed to apply to moderators when it was only agreed for members.

Repeat the full test set after two events that commonly change behavior. The first is a Jitsi container restart, which confirms that the settings in .env persist and that the authentication path comes back in the same state. The second is a Matrix homeserver upgrade. If you run Synapse, read the upgrade notes for the release you are moving to before the test window, and confirm that the user verification endpoint still answers with the same token issuer and that room power levels were not altered by the upgrade. Schedule these retests before the change is approved for production, and ask your vendor or implementation partner to confirm any release-specific steps in writing.

For an internal review, keep a dated record for each run: the access policy version, the test account list with roles, the .env values in effect (with secrets redacted), the expected and observed result for every case, the Prosody log lines showing owner assignment, screenshots or screen recordings of lobby behavior, and the Matrix and Jitsi versions tested. Store the record where your change management process keeps other evidence. Record every failure and its fix, and rerun the affected cases afterward. This record shows reviewers what was tested and why, and it lets your team repeat the same plan after the next upgrade without rebuilding it.