Support for API-based Dynamic TURN Credentials (e.g., for Cloudflare TURN)

Currently, Synapse only supports TURN server authentication using a static turn_shared_secret. This works well for self-hosted TURN servers like coturn, but it is incompatible with many modern, managed TURN services such as Cloudflare TURN, Twilio Network Traversal, etc.

These services do not use a long-lived shared secret. Instead, they provide temporary, short-lived credentials (username and password) dynamically through a secure API call. This limitation prevents Synapse administrators from leveraging these powerful, globally distributed, and often more cost-effective TURN solutions, forcing them to self-host and maintain their own coturn instances.

Proposed Solution

I propose adding a new configuration method in homeserver.yaml to support fetching TURN credentials from a remote HTTP API endpoint.

When a client requests TURN credentials from the /_matrix/client/r0/voip/turnServer endpoint, Synapse could check for this new configuration. If present, it would perform an HTTP POST request to a specified URL.

The external API would be responsible for generating the short-lived credential and returning it in a JSON format that Synapse can then pass on to the client.

A potential configuration in homeserver.yaml might look like this:
YAML

turn_dynamic_credentials:
enabled: true
api_url: "https://my-auth-service.com/generate_turn_credentials"
api_method: "POST" # Defaults to POST
# Static headers to include, e.g., for authentication
api_headers:
Authorization: "Bearer MY_SECRET_API_KEY"
# Optional: Data to send in the request body. Placeholders could be used.
# api_body:
# user_id: "{user_id}"

The endpoint at api_url would then be expected to return a JSON response like:
JSON

{
"username": "1678901234:some_user",
"password": "some_temporary_password_from_api",
"uris": [
"turns:turn.cloudflare.com:443?transport=tcp",
"turn:turn.cloudflare.com:3478?transport=udp"
],
"ttl": 3600
}

Benefits of this feature

Access to Global, Low-Latency Networks: Allows federation with services like Cloudflare TURN, which uses an Anycast network to significantly reduce latency for VoIP calls between users in different geographical regions.
Reduced Operational Overhead: Administrators would no longer need to host, secure, monitor, and scale their own coturn servers.
Potential Cost Savings: Leverages the generous free tiers and competitive bandwidth pricing offered by these external services.
Enhanced Security: Utilizes a more modern, short-lived token authentication model, which is more secure than a static shared secret.
Increased Flexibility: Opens up Synapse to work with any TURN provider that can expose a simple API endpoint.

Thank you for considering this feature. I believe it would be a valuable addition for many homeserver administrators.