WebRTC uTURN Networking Guide

This page covers the network configuration needed to connect a WebRTC client to a uTURN instance running on Eyevinn Open Source Cloud. If you are looking for how to create a uTURN instance, see Service: uTURN.

What uTURN exposes

A uTURN instance provides two distinct endpoints:

Endpoint Protocol URL / Address
HTTPS admin TCP 443 https://{instance}-srperens-uturn.{tenantId}.auto.{env}.osaas.io
STUN / TURN relay UDP 3478 Same hostname, port 3478 UDP

The HTTPS URL is what the OSC dashboard and describe-service-instance return. The UDP relay endpoint uses the same DNS hostname on port 3478 — no separate host to look up.

{instance} is the name you chose when creating the instance. {tenantId} is your OSC tenant identifier (visible in the dashboard URL). {env} is the environment where the instance is provisioned.

Region affinity

OSC runs on two infrastructure regions:

Region DNS suffix Notes
Linode (primary prod) auto.prod.osaas.io Default for new instances
Elastx (prod-se) auto.prod-se.osaas.io Sweden region

The two DNS suffixes resolve to different public IP addresses. A WebRTC client must use the suffix that matches the region where the instance is deployed. Using the wrong suffix causes the STUN/TURN exchange to reach the wrong IP, and the relay will not be found.

You can confirm which region your instance is on from the URL shown in the OSC dashboard or returned by describe-service-instance.

ICE server configuration

Use the Realm and Users values returned by describe-service-instance to build the ICE server config passed to RTCPeerConnection.

// Values from describe-service-instance:
//   url  -> "https://myrelay-srperens-uturn.myorg.auto.prod.osaas.io"
//   Realm -> "myrealm"
//   Users -> "alice:secretpass"

const turnHost = 'myrelay-srperens-uturn.myorg.auto.prod.osaas.io';

const peerConnection = new RTCPeerConnection({
  iceServers: [
    {
      urls: [
        `stun:${turnHost}:3478`,
        `turn:${turnHost}:3478`
      ],
      username: 'alice',
      credential: 'secretpass'
    }
  ]
});

The urls array includes both a stun: entry (for NAT traversal without relay) and a turn: entry (for relay when direct connection fails). Both point at the same host and port.

If you configured multiple users in the Users field (separated by commas or multiple field entries), use any one pair of username:credential values — each entry grants full relay access.

Troubleshooting

TURN relay not working, ICE fails

Port 3478 UDP must be reachable outbound from the client's network. Many corporate firewalls block non-standard UDP ports. Check that port 3478 UDP is allowed outbound on the client side. You can test reachability with:

# Send a STUN binding request (requires stun-client or similar tool)
stun myrelay-srperens-uturn.myorg.auto.prod.osaas.io:3478

Wrong region / connection drops after relay is selected

Confirm the DNS suffix in your turnHost string matches the region shown in the OSC dashboard. If you copied the hostname from an API response without checking the suffix, the host may resolve to the wrong region.

Authentication fails (401 Unauthorized)

Verify the username and credential values exactly match what you set in the Users field when creating the instance. The Realm value must also match if your WebRTC stack sends it in the TURN authentication exchange. Check the Realm field from describe-service-instance and confirm it matches what your client expects.

Resources