Freeze one failed sign-in and name the client path
Record one authorized occurrence with timestamp and timezone, FreePBX or PBXact release, operating-system baseline, Asterisk branch, Sangoma Phone build, installed desktop or browser path, entered host, user identity, network and exact symptom. Separate rejected credentials, a spinning or reloading login, certificate warning, connection timeout, successful login without registration and a later call failure.
Do not move between the installed client, direct browser client and a UCP launch while collecting evidence. Those paths can share a PBX identity without sharing storage, certificate handling, browser permission or session state.
Prove the selected build and PBX are in the documented support lane
Sangoma labels desktop 4.2.0 as the current Latest release in its public repository and states that it requires FreePBX or PBXact 15 or later. Newer 4.2.1, 4.3 and 4.4 entries are marked pre-release, unsupported and Switchvox-specific. Record the installed artifact and release channel rather than selecting the largest version number.
Confirm the PBX edition and release, Sangoma Connect entitlement, required module versions, PJSIP extension owner and service configuration. A downloaded client or reachable login page does not prove the user has a license, an assigned PJSIP identity or a supported server state.
Resolve the configured host and reach the RTAPI service
The desktop installation guide composes the Host from the PBX address and the Sangoma Phone Desktop Client Service secure port, documented as 6443 by default. The PBX port reference says that port can be changed in System Admin, while the external-connectivity note requires clients to reach the PBX RTAPI port. Capture the exact configured listener and address rather than assuming every system uses the default.
From the affected network, prove DNS result, route, TCP connection and the PBX listener separately. Preserve the firewall zone and source address. A timeout is not a credential failure, and an open TCP port is not proof that the intended TLS service or user session is working.
Keep certificate, HTTPS and WSS evidence separate from credentials
Sangoma documents a web-app login loop associated with self-signed-certificate warnings or a WSS connection problem. Inspect the presented certificate name, chain, validity period, browser trust result, secure-page load and WebSocket upgrade without bypassing validation or teaching users to ignore warnings. Confirm that the entered PBX name matches the certificate and that intermediate devices do not replace or block the protected connection.
A successful HTTPS page load does not prove the WSS session, and a successful WSS upgrade does not prove user authorization. Preserve response codes and the first failed boundary; do not weaken TLS, expose a broad port range or replace certificates merely because the client keeps reloading.
Trace user authorization, service response and session creation
The desktop login procedure requires Enable Sangoma Phone Login for the user and uses the User Management credentials associated with UCP. Verify the intended user, the enabled setting, assigned PJSIP extension, entitlement and module or service state before resetting a password. Then correlate one login request with the PBX-side response and session result.
Sangoma troubleshooting examples show server-side RTAPI or proxy failures returning a login error even when the client supplied a request. Capture only the minimum sanitized interval; logs can expose usernames, tokens, internal addresses and call data. A generic invalid-parameters or status-500 response is evidence of a failed server path, not proof that the typed password is wrong.
Correct the first divergence and test beyond sign-in
Correct only the first proven boundary: unsupported artifact, missing entitlement or module, wrong extension ownership, disabled user login, incorrect host or port, unreachable RTAPI service, certificate mismatch, failed WSS upgrade, service-side error or stale client session. Preserve the prior configuration and rollback path. Restart PBX or Asterisk services only under an approved window because active calls can be affected.
Retest desktop or browser sign-in, explicit sign-out and revocation, reconnect after sleep and network change, inbound and outbound calls, two-way audio, DTMF, hold, transfer and normal hangup where authorized. Successful login does not prove SIP registration, routing or media. No client, browser, PBX, account, module, license, certificate, service, packet, registration, endpoint, call, audio path, compatibility, availability or price was inspected or tested for this diagnostic.
Sources & applicability
Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.
- Sangoma Phone web app for FreePBX and PBXact ↗
- Sangoma softphone troubleshooting tips ↗
- Sangoma PBX platform port reference ↗
- Sangoma Phone desktop installation and login ↗
- Sangoma Phone external connection requirements ↗
- Sangoma Phone PBX setup guide ↗
- Sangoma desktop softphone release record ↗
Examples require adaptation to your topology. No live PBX or hardware testing is claimed.