We are enhancing the security mechanism for sending data to callstats.io. We will continue to use origin URLs as a whitelisting mechanism, this limits data gathering to a particular domain (or subdomains). For WebRTC services (our customers) that desire more robust security, we are proposing an enhanced solution. The main effort in implementing the third party authentication proposal is that it requires the WebRTC service to develop a part of the security protocol, which mitigates the threats described in the basic authentication.
The proposed new authentication occurs between three parties.
WebRTC application service
This is an WebRTC application or service manages the signaling for its service, integrates with callstats.io, and contains information about its end-users
Clients run the WebRTC stack (e.g., send and receive media that they generated or forward media generated by other endpoints) and submit measurement data to callstats.io.
The client library is a piece of code that resides in the client and sends measurement data to a measurement service, callstats.io in this case. In the WebRTC case, an endpoint is any device along the IP route that handles the mediastream. Typically, these are clients used by the end-users, either a web browser or a native application that captures and renders the mediastream. However, it can also be a middlebox that either forwards media from one participant to another. The middlebox may for example transcode (Opus <-> G.711, or VP8 <-> H.264) or transrate it (switch between different media qualities or re-encode the media at a different rate).
In addition to sending measurement data, the client library sends conference state events, for example, a user joined, a user left, someone muted audio or paused video, conference created, conference stopped, etc.
Figure 2: Entities in the third-party authentication (all interactions over HTTPS).
Why not OAuth 2.0
In OAuth 2.0, there is an authentication flow named the “three-legged authentication”. It contains the following
- Consumer (entity that wants to access the user information)
- Resource owner (something that owns the user information)
- Service provider (someone that provides the requested user information)
Normally, the resource owner (e.g. a Twitter user) would access the consumer (e.g. an application that allows logging in using the Twitter credentials). The consumer redirects the resource owner to the service provider (e.g. Twitter). The resource owner authorizes the request (i.e., gives the consumer access to the resource owner’s data on the service provider’s service) and the service provider redirects the resource owner back to the consumer with the authorization information.
In our case, the resource is the ability to store measurement data for a particular userIDs at callstats.io and the resource owner is the WebRTC application service. To do this in OAuth2, would require a large number of round-trips and this will result in longer authorization latency (time to get to the final token that allows the user-agent to submit measurement data). Consequently, the long authorization latency is not advisable in situations where the conference failure time, i.e., conferenceID fails to set up (e.g., user fails to provide access to camera) may be shorter than the time to get a valid token (authorization latency) from callstats.io, and the user closes the tab, thus the failure event may go unreported.
To keep the number of RTTs short, we have chosen to not utilize the standard OAuth2, however, for the sake of simplicity the protocol utilizes OAuth2 terminology to explain the protocol interaction.
The WebRTC client (web or native application) receives an
__application_token__ associated to the
userID from the WebRTC application Service. The
application_token is sent to callstats.io during the authentication step. callstats.io sends the
application_token along with the
userID to the application service, which validates the
application_token request and sends a
__permission_token__ associated with the
userID back to callstats.io. Based on the PERMISSIONS in the
permission_token, callstats.io generates a
__data_token__ for the particular
userID and sends it back to the WebRTC client. The WebRTC client can then use the
data_token to submit conference events and measurement data.
The motivation for letting the WebRTC application service generate the
application_token is it to offer the flexibility of associating and validating a token for a particular
userID (or sessionID, conferenceID, etc) and not constrain it to a particular tuple of information.
Figure 3: Protocol interaction between different entities in the third-party authentication process.
1. fetchAppToken message (optional)
application_token is received by the WebRTC client from the WebRTC application service, this can be done on the first page load or requested explicitly by an REST API. Providing a REST API (e.g., fetchAppToken) is recommended, because it enables the WebRTC client to request a new
application_token if the authentication fails.
In the WebRTC application service, the
application_token is generally associated to the
userID. An WebRTC application service may specifically constrain the use of the application token to an HTTP session, for example. In case where the
userID is authorized to use the WebRTC service from several endpoints (web-browser, android/iOS application, etc), the WebRTC application service, depending on its design, may use the same or different token across endpoints. The association of the token to the
userID or an HTTP session is up to the discretion of the WebRTC application developer.
To summarize, the WebRTC client has an
application_token identifying a particular
2. Authenticate Transaction
The client sends the
application_token to callstats.io in the Authenticate message. Further, the response to the Authenticate message remains pending until the getPermissionToken transaction is complete.
3. getPermissionToken Transaction
callstats.io sends the
getPermissionToken message, which contains the
application_token to the WebRTC application service. Further callstats.io signs the
getPermissionToken message with its private key before sending it.
On receiving the
getPermissionToken message, the WebRTC application service verifies the message signature and validates if the
application_token is valid.
application_token is valid, the WebRTC application service sends back a signed
permission_token that contains a list of valid PERMISSIONS for that
application_token is invalid, callstats.io receives an error code, which it passes on to the WebRTC client.
4. Authenticate response
On receiving the response to the
getPermissionToken message, callstats.io verifies the signature of the Response message. If the response has a valid signature, callstats.io stores the PERMISSIONS indicated in the
permission_token for the associated
userID, and later uses the set of permissions to verify if the
userID is authorized to perform the requested action.
Meanwhile, callstats.io creates a
data_token for the associated
userID based on the
permission_token, and sends the
data_token to the WebRTC client. The
data_token, typically has a limited validity (fixed amount of time, or until the end of the current conferenceID).
If the application_token or the permission_token is invalid, callstats.io sends an error to the client, which restarts the process by getting a new
application_token from the WebRTC application.
On receiving the
data_token, the WebRTC client can use it to send new conference events (conference started, conference ended, etc) or measurement statistics (conference stats, bridge overall transport metrics, bridge overall health metrics).
On receiving the data submission messages, callstats.io verifies if the
data_token associated with the
userID is permitted to perform the action based on the PERMISSIONS indicated in the
permission_token. If the
data_token is invalid, callstats.io sends an error message, which restarts the authentication process. Alternatively, if the permission is invalid, i.e., if the
userID is attempting to perform an action that it is not permitted to perform, the application developer needs to
permission_token with the correct PERMISSIONS during the getPermissionToken transaction.
List of Permissions
A permission_token contains a list of permissions:
- Wildcard (*): all permissions are granted.
- CreateConference: can create a new conferenceID.
- TerminateConference: can end a conferenceID.
- SubmitBridgeEvent: can submit events as a middlebox.
- SubmitBridgeStats: can submit measurement data as a middlebox.
- SubmitConferenceEvent: can submit events as an
userIDat an endpoint.
- SubmitConferenceStats: can submit measurement data as an
userIDat an endpoint.
In some deployment scenarios, typically in MESH-based conferencing topologies, application developers may prefer granting all the conference call participants a wildcard permissions, i.e., anyone can create or end a conference, and send statistics. However, in topologies that have a centralized conference server, the application developer may prefer to limit the permission to create and terminate a conference to the centralized bridge (indicated by a unique
bridgeID), instead of every participant in the conference (each indicated by a
We wrote this page to gather feedback, please send your comments to