Setting Up TURN Shared Secrets on Synapse for WebRTC Calls

By 4FreeForums Editors · Published October 30, 2026 · Sources linked below

Configuring TURN Shared Secrets on Synapse for WebRTC Voice

Adding voice and video capability to community rooms allows members to interact in real time, but establishing direct peer-to-peer WebRTC connections often fails when users sit behind restrictive firewalls or residential network gateways. By integrating a dedicated relay daemon with your Matrix homeserver, you can bridge these connections securely without exposing private credentials directly to user clients.

Understanding the TURN REST API and Shared Secrets

According to the official Synapse documentation on configuring a TURN server, Synapse Matrix homeservers support integration with external relay services through the TURN server REST API. Instead of assigning individual, static account logins to every community member, the homeserver uses an ephemeral credential scheme.

Under this design, your homeserver and the relay daemon maintain a shared secret. When a client initiates a WebRTC voice or video session, Synapse generates short-lived authentication credentials valid strictly for that relay server. Common software daemons supported for this architecture include coturn and eturnal. This approach guarantees that community members receive dynamic relay access while keeping your backend authentication isolated.

Preparing Network Endpoints and Firewall Access

Before modifying homeserver configuration files, your relay server must satisfy foundational networking prerequisites. For TURN relaying to function properly, the relay service must reside on an endpoint or host that has a public IP address.

Hosting TURN services behind network address translation (NAT) introduces serious complications. While it is possible to forward ports if the NAT gateway possesses a public IP address, NAT topologies frequently cause connection failures and often do not work as expected. To maintain reliable audio traffic, verify that your firewall allows both TCP and UDP traffic to the standard TURN ports, 3478 and 5349. Additionally, administrators must permit incoming UDP traffic across the UDP relay ports so that active calls can transmit media streams unhindered.

Configuring Shared Secret Directives in Synapse

To enable the relay mechanism, update your homeserver configuration file with four essential configuration keys. As outlined in our Synapse Matrix homeserver profile, editing homeserver configuration directly requires maintaining precise YAML syntax:

turn_uris: Defines the network addresses and transport protocols that Matrix clients receive to access the relay.
turn_shared_secret: Holds the shared authentication passphrase established between Synapse and your TURN service.
turn_user_lifetime: Specifies credential validity duration in milliseconds, preventing stale tokens from remaining active indefinitely.
turn_allow_guests: Controls whether non-member guest accounts have permission to generate relay credentials for calls.

For unencrypted signaling listeners on default ports, the configuration block resembles the following layout:

turn_uris: [ "turn:turn.matrix.org?transport=udp", "turn:turn.matrix.org?transport=tcp" ] turn_shared_secret: "n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons" turn_user_lifetime: 86400000 turn_allow_guests: true

In this baseline example, turn_user_lifetime sets token longevity to 86400000 milliseconds, ensuring continuous communication without forcing frequent token renegotiations.

Applying Homeserver Changes and Reloading Clients

Once you finish updating the configuration parameters, restart the Synapse service to activate the new relay handlers. The appropriate restart method depends on your server environment:

If you run the homeserver with synctl, execute synctl restart. If synctl is not located on your system PATH, remember to activate your virtual environment beforehand.
If your system relies on systemd for service orchestration, issue the command systemctl restart matrix-synapse.service.

After restarting Synapse, instruct active community members to reload their client applications, or allow an hour for desktop and mobile clients to refresh their homeserver discovery settings automatically.

Testing Credentials and Relay Functionality

To verify that token exchange and packet relaying operate as intended, you can generate manual credentials and evaluate them against public WebRTC testing tools.

You can verify live homeserver responses by checking your browser network inspector during a call setup for the GET /_matrix/client/r0/voip/turnServer endpoint, which exposes the generated username and password. Alternatively, generate temporary testing credentials directly on your server host:

For eturnal installations, run the shell command eturnalctl credentials.
For coturn installations, calculate HMAC credentials with OpenSSL using your static secret:

secret=staticAuthSecretHere u=$((`date +%s` + 3600)):test p=$(echo -n $u | openssl dgst -hmac $secret -sha1 -binary | base64) echo -e "username: $u\npassword: $p"

Submit these credentials to the WebRTC sample tool hosted at https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/. If the daemon and firewall handle routing properly, the interactive results list will display at least one relay candidate entry. You can also evaluate overall configuration with the community tool at https://test.voip.librepush.net/, though this external tester is not fully reliable yet.

Troubleshooting WebRTC Call and Routing Failures

The standard symptom of a malfunctioning relay server occurs when calls between participants on differing networks ring successfully but freeze at the status message "call connecting". When diagnosing stalled calls, consult the official Configuring a Turn Server - Synapse guide for systematic diagnostic checks:

Disable TLS and DTLS listeners temporarily, leaving only unencrypted TCP and UDP transport enabled. This unencrypts only signaling negotiation; the underlying WebRTC voice and video media streams remain encrypted.
Google Chrome implementations may experience handshake issues when communicating with TURN endpoints publishing IPv6 addresses due to draft-ietf-rtcweb-ip-handling address behaviors. Strip AAAA DNS records from your TURN hostname so that clients connect purely over IPv4.
When routing through NAT gateways, confirm that ports 3478 and 5349 and all UDP relay ports forward correctly to the internal interface. If advertising both external IPv4 and IPv6 routes via the external-ip flag, verify that the NAT device forwards both address types to internal addresses, and verify that the relay server designates the NAT gateway as its default route.
Examine client-side negotiation logs by navigating to chrome://webrtc-internals/ in Chromium browsers or inspecting the Connection Log tab inside about:webrtc on Firefox.

For administrators managing high-traffic community infrastructure, balancing UDP throughput with general system stability is critical; review our guide on tracking resource exhaustion across forum layers to prevent relay traffic from degrading core web services.

Sources

Published October 30, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.