WebRTC API Authorization - ngmediaserver/NG-Media-Server GitHub Wiki
This document provides information on how to compute an authorization token for the RTC API.
With WebRTC calls, NG Media Server requests a valid authorization parameter in order to allow outgoing calls and registrations for incoming calls.
Softwares based on the RTC API must compute the authorization token. With Version 7, the computation can be performed either on the client side (Web Browser) or the server side (Application Server). With Version 6, it had to be performed on the server side.
Algorithm
The authorization parameter is computed as follows:
The authorization parameter uses a short term credentials algorithm based on the Username (credentialUsername),
the Password (credentialPassword), the data passed to NG Media SBC (data) and an expiry time (expiry):
data = token + LF + domain + LF + to + LF + toName + LF + from + LF + fromName + LF + subject + LF + uui + LF
expiry = time when the authorization must expire, expressed as the number of seconds elapsed since 00:00:00 UTC, January 1, 1970 (Unix timestamp)
temporaryUsername = expiry + ":" + credentialUsername
temporaryPassword = Base-64 encoding of HMAC-SHA1(data + temporaryUsername, credentialPassword)
authorization = temporaryPassword + ":" + temporaryUsername LF = the Line Feed character,
which is ASCII code #10 in decimal and #0A in hexadecimal,
which is represented as \n in many programming languages, including JavaScript, Python, C, Java, PHP, Perl, Go.
The Username (credentialUsername) and Password (credentialPassword) used must match those configured on the Back-End server
under BackEndUsername and BackEndPassword respectively (in the general dataset).
Sample Code
Sample source code is available in project WebRTC-API-Authorization.
Online test
An authorization token can be generated online: access the Administration UI of the NG Media Server, then go in the API menu (under Advanced), search the rtc_authorization resource and try it out ! See the API section for more details.
API
The REST API provides the rtc_authorization resource enabling to generate reference authorization token for test purposes.
This feature is designed to help developers validate that their implementation of the authorization token computation is valid. It is available only in developer mode. To enable the developer mode, in product.json, add the field "DeveloperMode": true and restart the NG Media Server service.
In production, the developer mode must be disabled and the authorization token must be computed by the software using the RTC API.
Documentation:
POST /rtc_authorization
Input parameters:
| Parameters | Type | Description |
|---|---|---|
| to, toName, from, fromName, domain, subject, uui | string | parameters of the makeCall or registerCall request |
| credentialUsername, credentialPassword | string | Username and Password of the User computing the authorization |
| credentialTimestamp | number | Time when the generation of the Authorization token was required, expressed as the number of seconds elapsed since 00:00:00 UTC, January 1, 1970 (Unix timestamp). When not provisioned by the client, the current server time is used. |
| credentialDelay | number | Delay before the expiry of the Authorization token (optional), expressed in seconds. When not provisioned by the client, zero is used. |
Output parameters:
| Parameter | Type | Description |
|---|---|---|
| authorization | string | the computed authorization token |
Authorization token validity period:
- At least a credentialTimestamp or a credentialDelay is required.
- Both parameters are used to compute the expiry of the authorization:
expiry = credentialTimestamp + credentialDelay - The credentialDelay should typically not be more than 15 seconds.
See the Online test section for a quick test.