Understanding Authentication


Authentication is the process of establishing association between an incoming call and an Account in the system. There are three basic methods for performing Authentication in the Softswitch: 
  • DID Pool
  • Authentication Rules of an Account
  • Secure SIP digest with credentials of an Account


The call authentication scenarios explained below are applicable for the calls within an Environment.


Sippy Softswitch uses the following authentication chain sequentially


  • When any call comes into the Softswitch, system tries to find an acceptable authentication match in 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 in consequent INVITE, the system authenticates the call and proceeds with the authorization process, otherwise another 401 response is sent


DID Pool Authentication rules

Matching DID is searched against Incoming DID-Incoming CLI-Vendor/Connection that are configured in the individual DID or DID range within DID Pool.

More information:

- Improvements to DID charging and authentication in Sippy Softswitch 2020

- DID Pool


Account Authentication Rules

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

  • Protocol - the incoming protocol call was sent within (SIP, IAX2, Calling Card PIN)
  • Remote IP Address - IP address of the device or server that originates the call
  • Incoming CLD/DNIS - Called Number / Destination Number (CLD)
  • Incoming CLI/ANI - Calling Number / ANI (CLI)
  • To domain - hostname in To: header of incoming INVITE
  • From Domain - hostname in From: header of incoming INVITE


In order for the call to match the rule, the match should be satisfied for all six parameters of at least one Authentication Rule. Protocol should be always specified, as well as at least one of the parameters above. When some parameters of a Rule are empty, only the remaining parameters are matched against incoming calls.


SIP and IAX2 are used to check whether the protocol of incoming traffic matches specific Authentication Rule.

Calling Card PIN option of the Protocol is used only in IVR application scenario, and the card number (PIN) is requested. The system first checks the match of the PIN 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.


Incoming CLD and Incoming CLI can be a number or a number with pattern/wildcard, e.g.

 

To/From Domain should be in a hostname format, e.g. for From Domain = 123abc.from.com the expected content of From header should be like: 

From: "Mr John Smith" <sip:[email protected]:1036;user=some-id>;tag=43165asdgw3001


Regular Expressions usage:

  • Match any sequence of symbols

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.


For To/From Domain 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.


  • Match any symbol in any place of the number

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.


Authentication attributes order

It's possible to specify a particular order of parameters that need to be checked upon call authentication. 

system_config setting "system/sip/authentication/attr_order" can have following parameters: cld,cli,remote_ip,to_domain,from_domain,weight,default,old_style with the special parameters as below:

  • "default" - setting for new installations since 2020.
  • "old_style" - Equivalent to "weight,to_domain,from_domain". Setting for existing systems since 2020.

Any combination could be used based on the purpose of Environment's usage. 

Default and weight are explained below.


Default

Equivalent to "cld,cli,remote_ip,to_domain,from_domain"

  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


In this example for the call that came from IP 1.2.3.4 with Incoming CLD = 123456789 and Incoming CLI = 567890 the second rule would be matched, CLD has higher order number, and first rule does not have matching CLD.

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

123456789


Weight

This is the legacy policy where softswitch calculates so-called weights for each matching Rule in order to determine the best match. The one with bigger weight is used for call authentication.

Weight operates with cld,cli,remote_ip parameters.


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


Calculation formula:

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 in CLD or CLI adds 1.0 to the resulting weight
4. For any matching wildcard in CLI or CLD the resulting weight is increased by the length of the matching part divided by 100
5. For any question mark in 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 (weight is increased by the length of the matching part divided by 100)


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) and the error message "401 Unauthorized" would be sent to Caller. In this case, only Digest Authentication would be possible. 


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.  While there is a separate feature called DID Pool, in some scenarios usage of Account's Authentication rules might be preferable. 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

It's possible to manage Authentication Rules via web UI or via XML API


To access the Authentication Rules for a particular Account, navigate to the Customers - My Customers - Accounts menu, click on the Actions for specific Account.


Authentication Rules to block Individual Numbers


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/carrier prefix code.


For example to block calls with 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

2.1 In order to block calls based on prefix NPA/NXX - a rule with CLI 9232* should be added to match any CLI that starts with 9232 - e,g, 92321234567 or 92325556667

3. In CLD Translation Rule add a rule to change the Called number so that it does not go through the Routing, e.g.:

s/^/blocked_/

The rule above would add a prefix blocked to any CLD, so that the call does not go through, e.g. CLD = 12061234567 would be changed to blocked_12061234567, thus "403 No Rate Found" error would be returned to Caller and recorded to CDRs. 


The scenario above might require adjustments in following cases:

* LRN is enabled on the Routing Group. A separate Routing Group could be created with LRN disabled and assigned to the Authentication Rule.

* CLD should be listed in CDRs at no change. CLD Translation Rule should be left intact, instead a new Tariff with no rates could be created and assigned to the Authentication Rule.


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. 


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.


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.

- Improvements to DID charging and authentication in Sippy Softswitch 2020

- DID Pool

- Do Not Call List (DNC, DNCL)

- XML-RPC API - Authentication Rules Management