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 user 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 wac-core 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
userandusersgroupas assignable resources, where auseris 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:
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 /sipMappingsUpdate a SIP mapping. Changing both ownership and/or SIP identity.
PUT /sipMappingsObtain the SIP mapping for a given owner.
GET /sipMappingsRemove a SIP mapping entry.
DELETE /sipMappings
When a new sip-mapping is created, the service validates if that sip-mapping exists before. An error will be thrown if this sip-mapping already exists. In addition, one and only one sip-mapping can be associated to a given user or userGroup.
When a user is deleted from the system, its associated sip-mapping is also deleted (if any).
There is a special case here regarding the anonymous users. This service also maps anonymous users with “anonymous SIP identities”, that are dynamically generated under request. A SIP mapping for an anonymous user will follow this format:
dynamicMappingPrefix + userId + @ + dynamicMappingDomain
Where dynamicMappingPrefix and dynamicMappingDomain are both configurable parameters as explained below in the configuration section.
Automatic (pool-based)
Note: this feature has been deprecated since version 5.8.
Since version v4.4, Quobis wac can automatically assign SIP mappings to system resources from a “pool” 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:
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:
Username |
Password |
Domain |
Available |
|---|---|---|---|
changeme!please |
domain_1 |
false |
|
changeme!now |
domain_2 |
false |
|
changeme!hurryup |
domain_2 |
true |
|
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:
Username |
Password |
Domain |
Available |
|---|---|---|---|
changeme!please |
domain_1 |
false |
|
changeme!now |
domain_2 |
false |
|
changeme!hurryup |
domain_2 |
false <——– |
|
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
SIP-mappings service
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:
[sipmappings]
dynamicMappingPrefix = anonymous-
dynamicMappingDomain = anonymous-domain
will configure the system to assign to an anonymous user with the id: abc, the following SIP identity: anonymous-abc@anonymous-domain
SIP-pools service
In order to activate 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.