Issue a browser calling token restricted to chosen destinations

Voicescoped WebRTC access tokens

Mint a short-lived browser token and restrict what it is allowed to call.

tokenssecurity

The claim

A browser can place a call without an account, and without being able to dial anything you did not authorise. allowed_addresses on a guest token is the whole of its reach.

Why it holds

The browser chooses a key into a server-authored table. It cannot add an address, so the worst a visitor can do is pick another page’s desks. Every address behind any key is effectively public to every visitor.

How it works

The POST to /api/fabric/guests/tokens carries allowed_addresses, the only required field in the body.

client.fabric.tokens.create_guest_token(
    allowed_addresses=DESKS[page],
    expire_at=int(time.time()) + TOKEN_TTL_SECONDS,
)

The browser posts which page it is on, and the server ignores any address it sends. That distinction is the recipe. A value the browser supplies is a value the browser can change, so it may select from the table but never add to it. Keys are guessable, so treat every desk in the table as reachable from every page.

An unknown page mints nothing at all. A token with an empty list dials nothing, which looks exactly like a broken button and is harder to diagnose than a 404.

The documented maximum is ten addresses, and the code checks its own table against that rather than discovering it on a live request.

expire_at keeps the window short. A page reload mints another, so there is no reason for one to live long.

The response carries the minted token and nothing else. The project ID and API token stay on the server, which is the point of having a server in this flow at all.

Limitations

A guest token is bearer authority. Anyone with a copy has the reach of the visitor it was minted for, until it expires. That is what the short TTL is for.

The addresses are a static table here. Deciding them per visitor means authenticating the visitor, at which point a Subscriber token is the better fit.

What to change first

Add a desk to the DESKS table and give a page two entries instead of one. Keep allowed_addresses coming from that table: the moment it comes from the request body, the page can dial anything on your account.

python/app.py

"""Mint a guest token that can only dial what you list.

A Subscriber token belongs to a person and can reach whatever that person can.
A guest token belongs to nobody, and `allowed_addresses` is the whole of its
authority: a visitor holding one can dial the addresses on the list and nothing
else.

The list is built server-side from the page the visitor is on. It is never
taken from the request, because a value the browser supplies is a value the
browser can change.

Written against signalwire-sdk 3.0.1 (RestClient.fabric) and Flask.
"""
import os
import time

from dotenv import load_dotenv
from flask import Flask, jsonify, request
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

client = RestClient()

# What each page on the site is allowed to reach. The addresses live here,
# not in the browser.
DESKS = {
    "support": ["/public/support"],
    "sales": ["/public/sales"],
    # a page may offer a choice, within a list you decided
    "contact": ["/public/support", "/public/sales"],
}

# The documented ceiling for a guest token.
MAX_ADDRESSES = 10

# Short, because a page reload can mint another.
TOKEN_TTL_SECONDS = int(os.getenv("TOKEN_TTL_SECONDS", "900"))

app = Flask(__name__)


def guest_token_for(page):
    """A token whose reach is exactly the desks that page is allowed."""
    allowed = DESKS.get(page)
    if not allowed:
        raise KeyError(page)
    if len(allowed) > MAX_ADDRESSES:
        raise ValueError(f"{page}: {len(allowed)} addresses exceeds the "
                         f"documented maximum of {MAX_ADDRESSES}")
    return client.fabric.tokens.create_guest_token(
        allowed_addresses=allowed,
        expire_at=int(time.time()) + TOKEN_TTL_SECONDS,
    )


@app.post("/token")
def token():
    """The browser selects a key. It never supplies an address.

    A visitor can ask for any known page, so every desk in DESKS is reachable
    by anyone. What they cannot do is add an address that is not in the table.
    """
    page = (request.get_json(silent=True) or {}).get("page", "")
    try:
        minted = guest_token_for(page)
    except KeyError:
        return jsonify({"error": "unknown page"}), 404
    # only the token goes back: the project credentials stay here
    return jsonify({"token": minted.get("token")})


if __name__ == "__main__":
    app.run(port=int(os.getenv("PORT", "8080")))

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # add your credentials
python app.py

The browser side is call-from-a-browser, with this /token route in place of the subscriber one.

Verify it

No network, no account:

python verify.py          # from the recipe folder, not python/

With the HTTP layer replaced by a recorder, the verifier asserts:

one documented POST to /api/fabric/guests/tokens, checked against tools/openapi/rest.json
allowed_addresses is exactly the list for that page, and a page offering two desks gets both
the list is within the documented maximum, and an expiry is set
a request that also sends allowed_addresses and address changes nothing about what is minted
three kinds of unknown page return 404 and make no request at all
neither the API token nor the project ID appears in any response

Report an issue