BetterDesk/docs/features/GUEST_ACCESS_LINKS.md

Guest Access Links

Guest Access Links provide temporary Web Remote access without creating a BetterDesk Console account for the recipient.

Security model

• A link is an opaque, time-limited grant. The raw token is returned only when the link is created; the server stores only its hash.
• Every WebSocket upgrade must include the selected peer_id and a guest_session value. BetterDesk validates both the token and the peer allowlist before opening the bridge.
• The rendezvous bridge checks PunchHoleRequest and RequestRelay targets server-side. Changing the URL or sending a different protobuf target cannot escape the grant.
• TTL and revocation apply to active bridges. The panel closes locally revoked bridges immediately and periodically revalidates grants for revocations made by another panel process.
• max_uses is consumed atomically after the first valid session-opening protocol message. Failed upgrades do not consume a use.
• Guest session open/close events contain grant ID, peer, transport, source IP, duration and close reason. Tokens and passwords are never written to audit records.

For customer self-service, create a grant containing one peer. Existing operator-created grants may still contain multiple peers, but each individual WebSocket remains bound to one selected peer.

Password-less access

The organization peer vault (#367) encrypts unattended passwords at rest and is available to authorized operators. Guest grants do not contain passwords and public guest endpoints never return vault plaintext.

The current RustDesk Web Remote protocol performs the password challenge and hash calculation in the browser. Therefore, simply attaching a vault reference to a grant would either expose the password to the browser or require a protocol-aware proxy that terminates part of the end-to-end handshake. The second option needs a separate design and security review before it can be enabled for customer links.

Until that design is approved, guests must complete the normal target-device password or approval handshake.

Issuing links with a restricted API identity

The guest_issuer role has only:

• device.view
• guest.create

Use device and organization scoping to restrict which peer IDs the issuer may select. It does not grant general device.connect or Console administration.

The panel endpoints are:

• POST /api/guest/access-links
• GET /api/guest/access-links
• DELETE /api/guest/access-links/:id

Troubleshooting 403 responses

Check the response from the panel's GET /api/guest/access-links/peers?token=... first. It must return valid: true. Then verify:

1. The link has not expired or been revoked.
2. The URL still contains the complete token.
3. The selected peer is in peer_ids.
4. The panel can reach the Go API and has the current API key.
5. For split-container or reverse-proxy deployments, PANEL_SIGNAL_PROXY_CIDRS contains the panel-to-signal source network.

The WebSocket URLs generated by the current client include guest, peer_id, and guest_session on both rendezvous and relay connections.