Understanding Authentication


Authentication is the process of establishing association between an incoming call and an Account in the system. There are two basic methods for performing Authentication in the Softswitch: using secure SIP digest and using Authentication Rules. The two methods are described in detail below. Note that both methods can be combined together to provide advanced features (see DID assigning example below).

Sippy Softswitch uses the following authentication chain sequentially


  • When any call comes into the Softswitch, the very first place the system tries to find an acceptable authentication match is the DID Pool section  
  • If a match for the incoming call is not found in the DID's authentication rules, the System checks all available authentication rules under Accounts  
  • If there is no matched rule in the authentication rules of any Account, the system sends a "401 Unauthorized" response to the remote device with a "WWW-Authenticate" for the digest authentication   
  • If the remote end provides the correct credentials for the digest authentication, the system authenticates the call and proceeds with the authorization process.


Secure SIP Digest-based Authentication


For this type of authentication, a call is mapped into the Account by performing secure SIP digest authentication. In practice that means that the device or software that originates the call has a username and password configured and that those parameters are matched against the VoIP Login and VoIP Password parameters of all Accounts until a match is found.

Only this type of authentication allows a SIP device to register itself with the Softswitch, providing the requirements for receiving on-net calls.

The primary use of this Authentication method is to facilitate the connection of SIP phones and ATAs to the softswitch.


Rules-based Authentication


For this type of authentication, a call is mapped into the Account by matching four parameters of the incoming call against one or more Authentication Rules associated with the Account.  Below are the four parameters matched:

  • IP address of the device or server that originates the call
  • Calling Number / ANI (CLI)
  • Called Number / Destination Number (CLD)
  • Protocol (SIP, H.323, IAX2, Calling Card PIN)


The first three protocols check the match of incoming traffic to the parameter used in the rule.  The Calling Card PIN is used only when the IVR application is used, and the card number (PIN) is requested.

The system first checks the match of the number entered against the username/voip login of any Account in the system.  If no match is found, the Authentication Rules, Protocol, and Calling Card PIN are checked for the match.


In order for the call to match the rule, each of the four parameters of the call must match with the appropriate parameter of at least one Authentication Rule.  When one parameter or Rule is empty only the remaining parameters are matched against incoming calls (Protocol can never be empty)

For example:  The first rule will match any call originated from IP address 1.2.3.4, CLI 567890 and any CLD.  The second rule will match calls with CLD 123456789 and any CLI coming from any IP.


#Remote IP AddressIncoming CLI/ANIIncoming CLD/DNIS
11.2.3.4567890
2

123456789


Regular Expressions use:
  • Match any sequence of symbols in the whole number
Using a wildcard (*) in the Incoming CLI and Incoming CLD fields after the number, will result in prefix matching. 
For example the following modification of the first rule above will match any call originated from IP address 1.2.3.4 and any CLI starting with 567890 (e.g. 567890123).


#Remote IP Address

Incoming CLI/ANI

 Incoming CLD/DNIS
11.2.3.4567890*


Note: a wildcard can match the absence of symbols, so the 567890* rule will match 567890 CLI as well.


  • Match any symbol in any place of the number (starting from version 5.2)

This pattern can be set in the Incoming CLI and Incoming CLD fields by placing a question mark ('?') within the number.  The result will be number matching where the question mark matches any symbol in the incoming number.

For example: the rule below will match any call originated from IP address 1.2.3.4 and any CLI that starts with 567, is followed by any symbol, followed by 90 and any other symbol (e.g. 5678901 or 5670903).


#Remote IP Address

Incoming CLI/ANI

 Incoming CLD/DNIS
11.2.3.4567?90?

Note: the question mark CANNOT match the absence of a symbol, so the 567?90? rule will NOT match either 567890 or 567901 numbers.



Weight distribution for authentication rules (Sippy Softswitch v5.2 and before)


When performing the match against several concurrent Rules, the softswitch also calculates so-called weights for each matching Rule in order to determine the best match. The formula is as follows:


1. Matching IP address adds 1.0 to the resulting weight
2. Matching non-wildcard, CLD or CLI adds 1.5 to the resulting weight
3. Matching wildcard, CLD or CLI adds 1.0 to the resulting weight
4. For any matching wildcard, CLI or CLD the resulting weight is increased by the length of the matching part divided by 100
5. For any question mark, CLI or CLD, the resulting weight is decreased by 0.001 If a wildcard is present in the matching CLI or CLD, the question mark is considered a regular symbol to be added to the weight accordingly


For example, if a call from IP address 1.2.3.4, CLI 567890 and CLD 123456789 arrives, the weights would be calculated as follows:


#Remote IP AddressIncoming CLI/ANIIncoming CLD/DNISWeight
11.2.3.4567890
1.0+1.5=2.5
2

1234567891.5
31.2.3.4567890*
1.0+1.0+(6/100)=2.06
4
567?9*
1-0.001+0.05=1.049



Based on the example above, rule 1 would be selected as the best match. 

Note that if there are multiple rules with the same weight that can be considered "best" match, they will be rejected (due to ambiguity) if they use an Authentication rule; in this case, only Digest Authentication would be possible.  The error message "401 Unauthorized" is used when there is ambiguity.  


Typical Applications for Rules-based Authentication


Rules-based Authentication can accommodate different real-world scenarios.  Sample of scenarios and steps to implement them are listed below:

  • VoIP Peering.  Enter IP address of your peer’s softswitch into the Remote IP Address field
  • PSTN origination.  Enter IP address of the gateway into the Remote IP Address field.  If there are multiple gateways several rules with different IP addresses can be added
  • Assigning DID numbers.  DID (Direct Inward Dialing) can be implemented by combining secure SIP digest authentication with one or more Authentication Rules that contain the DID number (as CLD) from the originating gateway.  Optionally, the Remote IP Address can be used to only allow calls (considered DID calls) from a specific gateway.  It may be necessary to apply a Translation Rule to ensure proper routing of the call to the registered Account.


Accessing Authentication Rules


To access the Authentication Rules for a particular Account, navigate to the Account's menu, click on the Actions for specific Account.  Authentication Rules is an action relating to the Account.




Authentication Rules to block Individual Numbers

It is possible to manage this yourself, the method is as follows:


Adding a few numbers and maintaining a fairly simple list can be done manually by changing the Authentication Rules for the specific Account. This can be done PER NUMBER or by blocking an entire country/city (or carrier) code.


Example if you aimed to block calls going to CLI = 92321234567

  1. Create an Account with any Service Plan and Routing Group
  2. Add an Authentication Rule for the Account that uses CLI = 92321234567
    if you need to block calls based on NPA/NXX - you can also add a rule such as: 9232* whereby all calls to 9232 xxx xxxx are blocked

You can also manage Authentication Rules using the XML APIs - the support team can provide you details on the correct XML API syntax.


Note that calls dropped using the method above will show SIP error: "403 Auth Failed" and will not be written to the CDRs.  


While the solution works in limited numbers we do offer a Do Not Call List module that is far more effective for managing blocked calls.  You can read up more about this solution here. 


Changes made in Sippy 2020


In our Sippy 2020 release we have made some changes to added some attributes that are used to handle account authentication:

  • To domain (hostname in To: header of incoming INVITE)
  • From Domain (hostname in From: header of incoming INVITE)

In example below From domain would be 123abc.from.com

From: "Mr John Smith" <sip:123abc123-test@123abc.from.com:1036;user=some-id>;tag=43165asdgw3001


Lets introduce an order of preference for attributes:

  1. CLD
  2. CLI
  3. remote_ip
  4. To domain
  5. From domain

Rules to match the attributes.

  1. If there is a matching rule which contains a CLD then any other rules with empty CLD are skipped.
  2. Among the rules which passed the CLD check a rule which contains matching CLI beats any rule with empty CLI.
  3. And so on...

Phone number matching (CLI, CLD)

  1. If there is a matching rule which contains exact value then all rules with '*' or '?' chars in the value are skipped. If the winner is not determined, next step applies.
  2. If there is a matching rule which contains symbol '*' it is beaten by any rule that does not contain such symbol. Still remaining rules are passed to next step.
  3. Among two rules wins the rule which pattern has more non question mark characters.


Domain matching

  1. A domain can be either exact, e.g. 'domain.com' or can be a suffix match: '*.domain.com', there is no prefix matching for domains. 
  2. If there is a matching rule with an exact domain then all rules with suffix match are skipped.
  3. Among two rules with '*' symbol wins the longest rule

The suffix matching is literal (unlike DNS zone match). For example the rule '*.domain.com' matches the 'test.domain.com' but does not match 'domain.com'. The rule '*domain.com' matches both 'test.domain.com' and 'domain.com'. The domain part of a SIP URL is not analyzed and if it is in fact an IP address then it is used as is.

The new behavior added in our Sippy 2020 release also allows for legacy authentication attribute order to be respected.  There is a system configuration setting under "system/sip/authentication/attr_order" allowing for parameters:

  • "default" - equivalent to "cld,cli,remote_ip,to_domain,from_domain"
  • "old_style" - equivalent to "weight,to_domain,from_domain".


It is possible in Sippy 2020 versions and greater to be able to create custom order of these attributes.  If you are upgrading to 2020 your authentication methods will be set to "old_style".  At the present time this change must be handled by contacting our support team.


Additional Reading

- Understanding Number Translation - How to perform CLI/CLD Translations for prefix and number manipulation.

- Configuring your new Softswitch - Configuring Sippy to pass calls through Softswitch using Digest Authentication.

- Test Dialplan - Check the configuration of the system on how an incoming call is expected to be authenticated and routed within the system, with all charges applied.