Call authorization rules

When a call comes to PortaSIP, it has to be authenticated (to verify that it is coming from a legitimate customer or vendor), processed, and then delivered to its destination. Although this sounds simple and straightforward, there are many variations on how exactly it should be done. For example, when handling a call coming from a residential VoIP user, a different approach is used than when processing a call from a wholesale carrier.

There are different call authorization scenarios for PortaSIP to adapt to the requirements of various business models and, at the same time, to process different types of calls. One of the most important things is the type of authentication to be performed. For example, do we return a challenge to the SIP device and request digest authentication, or do we just take its IP address as the identity for authentication?

Thus PortaSIP’s call processing logic consists of call authorization rules. Each rule contains:

• Conditions to be evaluated against the parameters of incoming calls, to see whether the rule is applicable.
• A selected call authorization scenario.
• Additional parameters for that scenario.

The administrator can define conditions to satisfy each of the following parameters of a call request:

• IP address of the remote party. This can be an IP address or an IPv4 network prefix in CIDR notation (e.g., 192.168.99.0/24). Note that the "signaling" the address is used, e.g., the IP address from which PortaSIP receives the INVITE, not the information in the INVITE request itself, e.g., "Contact" or "From" headers. This condition is mandatory.
• The phone number of the calling party (CLI). Note that the phone number in the "From" header of the INVITE request is used.
• The called phone number (CLD). Note that the phone number in the Request-URI is used, not the number in the "To" header of the INVITE request.
• The user name translation rule. This is the Python regular expression that adjusts the user name that arrives in a call request to match the account ID in PortaBilling. The header from which PortaSIP retrieves the identity for translation is defined by the type of call authorization scenario (e.g., for authentication by CLI, the number will be taken from the From header.)

If the condition is empty, no verification is performed. If multiple conditions are listed, they must all satisfy the call request in order to apply this rule. For instance, if the remote IP condition says “1.2.3.4” and the CLD condition says “1234#”, the rule will be applied only if the call comes from IP address 1.2.3.4 and the destination phone number starts with 1234#.

When a SIP device sends a call initiation (INVITE) request, PortaSIP determines how to process the call by evaluating the conditions of the first call authorization rule against the parameters of the INVITE request. If the conditions do not satisfy the INVITE request, the conditions for the second rule are evaluated, etc. until a rule is found where all the conditions are met to satisfy the INVITE request.

PortaSIP tries to process the call with this rule. PortaSIP searches an appropriate SIP header (to obtain the identity for authentication) in the INVITE request. If the identity is found, then PortaSIP sends the authorization request to the billing engine with the obtained identity in the User-Name attribute. If the INVITE request doesn’t contain an appropriate SIP header or its value (meaning the required identity for authentication can’t be obtained), then PortaSIP proceeds to evaluate the rules until it finds another rule where all the conditions are met to satisfy the INVITE request. PortaSIP attempts to process the call with this rule. If the appropriate identity is obtained from the INVITE request then PortaSIP sends the authorization request to the billing engine with this identity in the User-Name attribute.

If no rules satisfy the conditions for a given INVITE request or the appropriate identity can’t be obtained from the INVITE request (for those that do satisfy the conditions) then the digest authentication is applied for the call.

Since rules thus work based on the "first match", the order in which they are arranged becomes very important. Normally, you would place more specific rules (e.g., "call comes from IP 5.6.7.8 and CLI starts with 44") at the top of the list, and more generic ones (e.g., "call comes from IP 5.6.7.8") at the bottom.

These include:

• Apply digest authentication (this is the default call authorization scenario).
• Use authentication by IP. The identity for authentication is the IP address of the gateway from which PortaSIP receives the INVITE request.
• Use authentication by CLI/CLD Tech-Prefix. The challenge here is to correctly determine the tech-prefix and find out where the actual phone number is, as unfortunately there are no clear rules for this. The default approach is to regard everything to the left of # (including # itself) as the tech-prefix, and all the remaining digits as the phone number. It is also possible to create your own pattern for matching a tech-prefix.
• Use authentication by CLI/CLD Tech-Prefix and IP. The default approach here is to use the identity for authentication that consists of everything to the left of the # symbol (including the # symbol) in the CLI/CLD, followed by the remote IP address prefixed with @ (e.g., 977#@122.255.109.2).
• Use authentication by CLI/CLD.
• CLI (PAI if no CLI). The identity for authentication is the phone number of the party calling (CLI). If the CLI is not specified, the identity for authentication contains the value from the PAI header.
• CLI (RPID if no CLI). This method is similar to the previous one, except that the identity for authentication is taken from the RPID header if the CLI is not specified.
• Use authentication by PAI.
• PAI and IP – the identity for authentication contains the value from the PAI and the IP address from which PortaSIP receives the INVITE.
• Use authentication by RPID.
• Use authentication by PSU. The identity for authentication is taken from the P-Served-User header. If the P-Served-User header is missing, the authorization fails. This scenario applies to the call authorization condition in which the IP address of the remote gateway is evaluated.
• Use authentication by Trunk Group ID (tgrp). The identity for authentication is the value from the "tgrp" part of the "Contact" header.
• Use authentication by PCI (P-Charge-Info). The identity for authentication is the number from the P-Charge-Info header and the IP address prefixed with @ (e.g., a call from IP address 122.255.109.2 with the P-Charge-Info header <sip:+12349874567@example.com> will be authorized as +12349874567@122.255.109.2).
• Remote IP. The identity for authentication is an IP address taken from a custom Remoteip SIP header. Note that this IP address is used "as is," without validation.

When you create an account with the ID, which contains an IP address, the system automatically creates a call authorization rule to apply IP-based authorization for calls, arriving from this IP address – so you do not have to perform this extra step. Also, when you create a VoIP from vendor connection without assigning a vendor account to IP (so authentication by IP address is assumed), a call authorization rule will be automatically created for you.

These autogenerated rules are displayed on the Autogenerated panel, so you can easily distinguish them from the manually added rules.

Please consult the Call authorization section for more details.

Precedence of rules displayed on separate panels

The precedence of rules displayed on separate panels is the following:

1. First, PortaSIP searches for a manually added rule that matches the remote IP address.
2. If no matching rule is found, PortaSIP searches for an autogenerated rule for accounts that match the remote IP address.
3. If the previous two searches haven’t provided any matching rules, then PortaSIP searches for an autogenerated rule for connections that match the remote IP address.
4. If no matching rule is found up until now, then PortaSIP searches for an autogenerated rule for nodes that match the remote IP address.
5. If PortaSIP still hasn’t found a rule, digest authentication will be applied.

So when PortaSIP finds the first matching rule (providing the required identity for authentication has been obtained from the INVITE request), it passes the part used for authentication to PortaBilling in the User-Name attribute and waits for a response.