9.2. Using Two-Factor Authentication for Users

Two-factor authentication (2FA) is a new experimental feature that helps to preserve security of a whole VoIP system even when security of a component is compromised. What sometimes happens is that PBX password leak in various ways and stolen passwords are used to make fraudulent calls that appear legitimate. The 2FA system allows to manage “shadow passwords” for SIP users. If a user’s account begins to show irregular patterns, identity of the user can be verified using this shadow password. The shadow password is a short string of digits (PIN) which is stored internally at the SBC in parallel to user’s SIP credentials.

The system works as follows. On his first attempt to make a call, a user is challenged to enroll by submitting a PIN code using DTMF. The user must remember the PIN code for future verification. Subsequent calls work as normally as long as the status of the user doesn’t change. The status can be changed manually from “ok” to “soft-limit” by administrator or an automated tool such as frafos Monitor. When a user attempts to initiate a call in the “soft-limit” status, he will be challenged to prove his identity using his PIN code. If the user fails to submit proper PIN code, his status will change to “hard-limit” and further calls will be blocked using an announcement. Otherwise the verification timestamp will be stored and the user will not be prompted anymore for some convenience period of time.

This basic scenario documented bellow is programmed using ABC rules and can be adjusted to the needs of a specific scenario.

9.2.1. Prerequisities

For the system to work, the following preparations must be made:

  • the ABC SBC must up and running in cloud configuration with a designated configuration master. This allows changes of user status to propagage to all attached SBCs.
  • An administrative account and password must be known for use by SBC to manipulate the user status. Ideally a special user is created for this purpose using “System ‣ Users ‣ Create User“ . In our examples bellow, we are assuming a user rpcuser with password rpcrpc.
  • the PIN database must be created. To create the database, use “Tables ‣ Add New Table“ on the configuration master. Make sure you choose 2FA as the table type.

Figure 1: Two factor authentication: Add a New PIN Table

  • a system is required to manipulate user status. This can be done manually by editing provisioned table, or by this-party tools using xml-rpc, or by deploying an extension to Frafos ABC Monitor. An example of XML-RPC use is shown bellow.
import xmlrpclib
import ssl
if hasattr(ssl, '_create_unverified_context'):
  ssl._create_default_https_context = ssl._create_unverified_context
# find IP address of config master: grep MASTER /etc/frafos/sbc-pullconf.conf
servernew = xmlrpclib.Server('https://rpcuser:rpcrpc@')
data = {"key_value":"sip:3@abc.com","status":"soft-limit","pin":"1111"};
print servernew.tables.insert_update_rule('twoFA',data);
  • a loopback CA bound to a loopback interface must be setup. The 2FA is running on a loopback interface so that multiple realms can use the same logic by forwarding traffic to loopback, and the 2FA logic doesn’t interfere with the actual realms rules. The following screenshots show how to set up the signaling interface, media interface and the actual CA. The interfaces must use systems physical “lo” interface. There must be also a realm to which the CA belongs.

Figure 2: Loopback signaling interface for two factor authentication


Figure 3: Loopback media interface for two factor authentication


Figure 4: Loopback Call Agent

9.2.2. Rules for Two Factor Authentication Processing

As mentioned bellow, the actual rules for two factor authentication processing will be tied to a loopback interface. This allows to share the rules for multiple Call Agents, in that the Call Agents forward relevant requests to the loopback interface. This is achieved by rewriting userpart of request URI to indicate the desired action and rewriting the hostpart to the loopback address

The following screnshot shows how the looopback rules are formed. They assume that userpart of request URI indicates what shall be done with INVITEs for the caller. Whether this is a requst from a new user who needs to be enrolled, or a user whose status shall be verified, or a user whose request shall be rejected using a voice announcement.


Figure 5: Loopback Rules

There are two actions: Two factor authentication which guides an existing user through a verification dialog. If the user types his proper PIN using DTMF, the action updates user’s verification timestamp and the user can continue using the service without further disruptions.

The other action, Two factor auth-enrollment, prompts a user to submit his PIN. The PIN is then later used to verify identity of the user.

The rule actions have a couple of paramters. The most important parameter is that of RPC URI – this is the address of configuration master and legitimate username and password. Both actions update the PIN databased based on their completion status. The audio filenames can be changed for a different user experience. RESTful URIs can be optionally used to notify external applications when a rule action finishes with success or failure.

9.2.3. Rules for User Disrimination Status

The more sophisticated part of the rules discriminates how to treat respective users. An example of such is shown in the following screenshot.

The very first rule retrieves user status from the curent database. The table attributes, such as PIN and status, are then available for processing as call variables.

The first condition selects users whose status is set to “hard-limit”. In that case, incoming INVITEs are forwarded to the loopback interface with “reject” in userpart of request URI, and rejected from there.

The next rule targets users for whom no records are available. Their INVITEs are forwarded to loopback for enrolment.

Subsequent condition try to determine, if user is in soft-limit status, and how recently he has verified his identity. If the last verification is too long ago (24 hours in this example), the INVITE is forwarded to the loopback interface for PIN verification.


Figure 6: User Discrimination in Two factor authentication Ruleset

If none of these conditions matched, rule processing continues “as usual”. That’s the case when user status is “ok” or if the user’s identity was verified recently.

9.2.4. Routing Rule to Connect Two Factor Authentication Processing and User Discrimination

There is one remaining piece to connect the user discrimination and 2FA processing rules: a routing rule. The user discrimination rules have already set loopback address in request URI and defined a variable “goto_loopback”. We still need to act upon these. This is fortunately easy to set up:


Figure 7: Two Factor Authentication Routing Rule

9.2.5. Scenario Modifications

The two-factor authentication scenario can be modified many different ways using the ABC rules. The period for which a user doesn’t have to re-validated may be extended or shortened. The IP address of a request can be checked against the IP address from which the identify was verified the last time ( last_verified_from_ip) – then a successful verification only validates calls from the same IP address. The way calls from a user in hard-limit status are declined can be changed. Note however, that the 2FA application is still in experimental status and untested scenarios may or may not work as expected.