Jitsi and Keycloak SSO integration

Token authentication in the Jitsi handbook depends on three parties agreeing on one signed token: the browser, Keycloak and Prosody. The browser starts the flow by sending the user to Keycloak's OpenID Connect authorization endpoint with a PKCE code challenge. The handbook's config.js sets tokenAuthUrl to that realm endpoint, along with tokenLogoutUrl and tokenAuthInline. After the user signs in, Keycloak redirects the browser back to the static sso.html page served by the Jitsi web app, which hands the token back to the Jitsi client. Before you build anything, map this path on a whiteboard so every hop has a named owner.

The signed token is presented when the user creates a room. Prosody, the XMPP server that manages conferences, does not trust the token on its own. It checks the token's signature against keys it fetches from the realm's OpenID Connect certs endpoint, which the handbook configures through cache_keys_url, and it runs with authentication set to "token". Keys are fetched and cached, so the Jitsi server needs a working network route to Keycloak and a certificate chain it trusts. Confirm the exact certs URL, the hostname Prosody resolves and the TLS trust store on the Jitsi host before testing sign-in.

Token-related settings live in different places depending on the install method. On a Debian or Ubuntu install, the handbook installs the jitsi-meet-tokens package, which writes app_id, app_secret and authentication = "token" into the Prosody configuration and enables token_verification on the conference MUC. Review what the package generates instead of assuming the defaults match your realm. On Docker, the handbook's settings sit in the .env file that feeds the containers. Confirm which variables your guide version uses for token mode, and where the cache_keys_url value ends up inside the Prosody container, because the containers run with read-only filesystems.

Each component should have exactly one owner, because most failed sign-ins come from a value that changed on one side only. The identity team owns the Keycloak realm, the client and its redirect URIs, which must match the sso.html path exactly. The Jitsi operators own the Prosody and jitsi-meet-tokens settings, and the Docker operator owns the .env file. Whoever maintains the web deployment owns config.js and sso.html. Write these owners into your runbook, along with the rule that any change to a realm key, client or URL requires a matching change on the Jitsi side.

Test the path before users depend on it. After a test sign-in, inspect the token's issuer and audience and compare them with what Prosody expects. Then try to create a room with no token and with an expired or altered token, and confirm that room creation is refused. Repeat the test after any Keycloak or Jitsi upgrade, because a change to the realm endpoint or key set affects the verification step even when the browser flow still appears to work.

Wait-for-host and the anonymous domain decide who can start a meeting and who has to wait for someone else to start it. The handbook's Keycloak guide enables the wait_for_host module together with persistent_lobby. Under that model, authenticated users who sign in through Keycloak can create rooms, while other participants join from the anonymous domain and wait until a host arrives. Settle this policy before anyone edits the Prosody settings or config.js. The same settings apply to internal staff, partners, patients or customers, so the organization should first decide which groups must be able to start a meeting and which groups only attend.

Guests who open a link before a host is present are the case to test first. The handbook describes these participants as waiting for a host rather than entering an active conference, so the first test is to open a meeting link as an unauthenticated guest with no host in the room and confirm that the guest is held in the waiting state. Then have an authenticated host join and confirm that the waiting guest proceeds. Repeat the test from a browser and from a mobile client, because the reader's experience can differ by client. Record exactly what the guest sees in your build instead of assuming the handbook's wording describes the screen.

Rejoin behavior and the persistent lobby setting need their own tests. Confirm what happens when the host leaves a meeting, whether the room stays open for guests already waiting, and what happens when the host returns through the same link. Then toggle persistent_lobby in a staging environment and repeat the same sequence, so you can see which behavior depends on that setting. Ask your Keycloak and Jitsi administrators to document the exact sequence, including what happens to guests who joined the lobby before the host left. Treat these results as the baseline for user guidance, and retest after each Prosody or Jitsi Meet upgrade.

The main trade-off is between strict host-only room creation and meetings that external participants must start. Host-only creation keeps control with your authenticated staff and limits who can open rooms on your domain. The cost is that an external party cannot begin a meeting unless a staff member is already signed in and present, which affects client calls, patient visits and partner reviews that run outside business hours. Loosening creation rights for external participants solves the scheduling problem but requires a separate identity route or accepting room creation with less control. Make this decision with the business owners and your security and compliance leads, record it in the configuration plan, and only then set wait_for_host and the anonymous domain behavior.

Before anyone outside the pilot group relies on Keycloak sign-in for Jitsi, run a fixed set of test cases that prove each access rule works in the deployed system, not only in the configuration files. The first case is the signed-in path: sign in as a user from the Keycloak realm, open the meeting domain and create a room. The room should open with that user as host. Repeat the test with a second authenticated account so you confirm that token claims, not a shared browser session, decide who is the moderator. Next, test the refusal cases, which matter more than the happy path. Attempt room creation with no token at all and confirm the request is refused and the room is not created. Then join as a guest from the anonymous domain while no host is present and confirm the wait-for-host behavior holds the guest in the lobby. Once an authenticated host arrives, confirm the guest is admitted. Record the exact sequence of timestamps and states so the result can be compared after any configuration change.

Test the token boundaries directly. Present a token issued by an expired session or by a realm other than the one Prosody trusts, and confirm the conference is rejected. Check that the cache_keys_url in Prosody points at the expected realm certs endpoint, because a mismatch there can make a valid token fail or an unrelated token pass. Also sign out from Keycloak and then from Jitsi, and confirm the tokenLogoutUrl in config.js sends the browser where you intend. Confirm with your own identity team how long a Keycloak session stays valid after sign-out, since that window is set in Keycloak, not in Jitsi. Run the same cases from the mobile clients your handbook covers and from at least one browser that your staff use. Certificate problems tend to appear first on mobile, so use a certificate chain that matches production and do not substitute a self-signed certificate for the test. If a mobile client fails while desktop browsers pass, treat that as a blocking finding for the SSO path rather than a client quirk.

Keep the evidence in a form an auditor or internal reviewer can follow. Store the test cases with their preconditions, expected results, actual results, tester and date. Keep the Prosody log lines and web server access and error logs covering each test window, and note which log entries correspond to which case. Record the versions of the Keycloak realm and client settings, the Prosody token configuration, the config.js SSO settings and the Jitsi package or container image used. Confirm the exact Keycloak and Jitsi versions with your own environment, because the release numbers you test against must match the ones you deploy. Finally, decide who signs off. The platform owner should own the configuration evidence, the identity team should own the realm and session results, and a security reviewer should confirm that the refusal cases were executed and not assumed. Re-run the full set after upgrades to Keycloak, Jitsi or the web server, and after any change to realm keys or client secrets.