SIP mappings

Introduction

The SIP mapping feature provides a way for defining, obtaining and updating SIP identities (sip-mapping) associated to a system resource. Supported resources are users and groups. This feature plays a key role on the SIP integration. It can identify the originator endpoints on the SIP network when they come from the system, and can identify resources on the system based on a SIP R-URI. With this feature, currently individual users and groups could be identified on the SIP network, but it opens the ability to establish multiple politics for SIP assignation.

This feature is implemented in two sippo-server services: “SIP mappings” (sipmappings) and “SIP identity pool (sipidentitypool).

Concept

A SIP mapping presents the equivalence between a SIP identity (user@domain) and a system resource (typically an user). By having this equivalence, we can route incoming SIP INVITE methods to a specific resource and replace the system identity when a system invite is being routed to the SIP network.

  • System resource: Currently the service supports user and usersgroup as assignable resources, where a user is a single platform user and a user group is a reachable element that involves multiple participants as a ringing group.

  • SIP mapping owner: System resource that owns a SIP mapping.

  • SIP identity: a pair of a SIP username and its associated password. Please do not confuse this SIP username (eg: alice@corporate-pbx.com) with the system username (eg: wac-user:alice_ID)

The following image summarizes the concept of a SIP mapping as a group of a user/usergroup and a SIP identity:

_images/sipmapping_1.png

SIP mapping assignment

Manual

Admins can assign/edit/remove a mapping to a resource at any time by using the REST API endpoint:

  • Create a SIP mapping identifying the owner and the SIP identity to use. POST /sipMappings

  • Update a SIP mapping. Changing both ownership and/or SIP identity. PUT /sipMappings

  • Obtain the SIP mapping for a given owner. GET /sipMappings

  • Remove a SIP mapping entry. DELETE /sipMappings

When a new sip-mapping is created, the service validates if the resource exists before. An error will be thrown if the resource already exists. In addition, one and only one sip-mapping can be associated to a given user. When a user leaves the system, the system will also remove its associated sip-mapping (if any)

Automatic (pool-based)

Since version v4.4, Quobis wac can automatically assign SIP mappings to system resources by using the “SIP identity pool” service. The assignment is done from selecting SIP identities from a pool, so the admin does not need to assign SIP mappings manually via the REST-API. This pool can be populated via the the REST API by using the /sipIdentitiesPool endpoint. There is one pool per domain and each pool can have as many entries as needed. The available fields for each entry are:

Parameters of a SIP identities pool entry

Parameter

Type

Value

“username”

string

Username of the SIP identity. Do NOT confuse with the wac user name.

“password”

string

Password of the SIP identity for the “username” user

“targetDomain”

string

This SIP identity can only be assigned to a user of this “targetDomain” domain

“available”

boolean

This field indicates if this entry is in user or not.

This is how the automatic assignment works:

  • When a user logs into the system:

    • A SIP mapping from the pool is given to him/her if he/she does not have a associated SIP mapping. In case that the user already has a SIP mapping, nothing happens and the pool remains untoched.

    • Once a SIP mapping is associated to a given user, it’s not removed from the pool but marked as “not available” (the “available” field is set to “false”).

    • The assignment process works with a FIFO scheme: the first available entry in the pool is the one selected for assignment.

    • In case that there are no available SIP mappings in the pool, an error message is thrown and no assignment is done.

  • When a user is removed from the system, two things happen:

    • If the user has a SIP mapping, it is removed from the system as well by the SIP mapping services (this happens even when the service “SIP identity pool” is not running)

    • It that SIP mapping exists in the pool, it’s marked as “available” (but it’s not removed, so it can be reused later on)

If the “Sip Identities Pool” service is not activated, no SIP mapping is assigned to the user after a successful login. In any case, the administrator can decide to manually assign a SIP mapping via the REST API at any time.

Let’s explain the process with an example. Let’s suppose that we have a system with two user domains (domain_1 and domain_2) and that have the SIP identity pool populated like this:

Initial state of the SIP identities pool

Username

Password

Domain

Available

0034986111222@sip-pbx.com

changeme!please

domain_1

false

0034986111333@sip-pbx.com

changeme!now

domain_2

false

0034986111444@sip-pbx.com

changeme!hurryup

domain_2

true

0034986111555@sip-pbx.com

changeme!soon

domain_2

true

In this situation, imagine that a new user “alice@domain_2.com” logs into the system. As Alice has no associated SIP mapping, the SIP identity pool service gives her the first available SIP identity from the pool (the one with username “0034986111444@sip-pbx.com”) and the status of the SIP identities pool changes to:

State of the SIP identities pool after Alice’s login

Username

Password

Domain

Available

0034986111222@sip-pbx.com

changeme!please

domain_1

false

0034986111333@sip-pbx.com

changeme!now

domain_2

false

0034986111444@sip-pbx.com

changeme!hurryup

domain_2

false <——–

0034986111555@sip-pbx.com

changeme!soon

domain_2

true

If we perform a GET query to the /sipMappings endpoint passing alice@domain_2.com as the “ownerUri” parameter, we’ll get this answer:

{
  "username": "0034986111444@sip-pbx.com",
  "password": "changeme!hurryup"
}

Some considerations to take into account when using this “SIP identity pool” service are:

  • The pool does not contain any entry after the initial setup, so it needs to be populated via the REST API.

  • Please note that the service does not check for duplicate entries. That means that it’s up to the applications to check if a entry already exists before creating a new one in order to avoid duplicates and other conflicts.

  • Please note that the service does not perform a sanity check on the username or password fields. It’s up to the administrator to make sure that the fields are correctly created (for example, the “username” parameters must be a valid SIP URI username like “alice@corporate-pbx.com”).

  • Please note that the service does not check that a SIP mapping is already in use when assigning it to a user. It’s up to the administrator to make sure that SIP mappings are not duplicated.

  • Please note that, in case an entry in the pool is updated or deleted via the REST API, no actions will be made if these credentials are assigned to an user.

Service configuration

In order to enable the SIP mappings service, you have to add the configuration block [sipmappings] to the config/wac.ini file. This service accepts two parameters, both used to configure the format of the dynamical mappings generated to the anonymous users, as explained in the service description.

  • dynamicMappingPrefix: Prefix used for anonymous SIP identities.

  • dynamicMappingDomain: Domain used for anonymous SIP identities.

[sipmappings]
dynamicMappingPrefix = <PREFIX>
dynamicMappingDomain = <DOMAIN>

An an example, the following configuration option configures the system to assign to an anonymous user with the id: abc, the following SIP identity: anonymous-abc@anonymous-domain

[sipmappings]
dynamicMappingPrefix = anonymous-
dynamicMappingDomain = anonymous-domain

In order to activate it the automatic assignment service using the pool, the configuration block [sipidentitiespool] needs to be included into the config/wac.ini file (no extra configuration parameters are needed):

[sipidentitiespool]

Internal services interaction

Other internal services can reach SipMappings using the Message Broker. For instance, when the Trunk service (sippo-server.trunk) requires to identify a system resource, it sends a message to SipMappings service in order to obtain the given resource.

Note

If sippoAS.sippo-server.UsersGroup is not enabled this service will reject any request that try to obtain the sip-mapping of a usersgroup.

User service also can take advantage of this service. Under request, this server can map anonymous users with SIP identities that are dynamically generated under request. A mapping for an anonymous user will follow this format:

dynamicMappingPrefix + userId + @ + dynamicMappingDomain

Where dynamicMappingPrefix and dynamicMappingDomain are both configurable parameters as explained above.

Log messages

  • info: Trying to add mapping with data: ${mappingData}. A sip-mapping is trying to be created.

  • info: Trying to get mapping for owner: ${owner}. A sip-mapping is trying to be obtained to identify its owner.

  • info: Trying to update mapping with data ${data}. A sip-mapping is trying to be updated.

  • info: Trying to get owner by its mapping username: ${username}. The owner of a sip-mapping is trying to be identified by its username.