Managing users

We are going the cover this section the basic actions to handle the users: create, list, modify and delete. All these actions here can be complemented with other actions available on the REST API.

Adding users

Create a user with a POST command using the users endpoint:

Note

Remember that you will need a valid authorization token to do any API REST action.

POST https://wac:8001/sapi/users HTTP/1.1
Authorization: Bearer ec3fe973ea047b6fd38228eb9f9b9661cbb5b0fdeac01ff23af1eef
Content-Type: application/json

{
   "domain": "quobis",
   "username": "alice",
   "email": "alice@demo.quobis.com",
   "role": "user",
   "capabilities": [],
   "mobilePhone": ["987654321"]
   "currentTimezone": "Europe/Madrid"
   "locale": "es-ES"
}

The following fields are available:

domain

As explained on previous section, in case it is left empty, the default domain will be included.

username

The username on the domain to be assigned to the user. If the user already exists the SippoAS will reject the user creation request.

role

Administrator, user or anonymous.

email

Context information of the user. An external email used to notify about meetings and other platform events that require the user attention.

mobilePhone []

Context information of the user. Array of external phone numbers to notify about meetings through SMS and other platform events that require the user attention.

capabilities []

Forced or pruned capabilities of the user. To limit or expand the functionalities available to this user. Check Users capabilities for extra information.

currentTimezone

Time zone of the user, it is used to set the right timezone hour used in meetings reminders. If no value is specified or the users.toml file does not exists, the default value of defaultTimezone in the conf/users.toml file in the wac-core will be used (by default the value is “Europe/Madrid”).

locale

Locale of the user, it is used to send the dates with the user country format. If no value is specified, or the users.toml file does not exists, the default value of defaultLocale in the conf/users.toml file in the wac-core will be used (by default the value is “es-ES”).

Check users created in the platform

You can check the users created or obtain a complete list of them using the GET command with the same endpoint:

GET https://wac:8001/sapi/users HTTP/1.1
Authorization: Bearer ec3fe973ea047b6fd38228eb9f9b9661cbb5b0fdeac01ff13af1eef
Content-Type: application/json

Also, it is possible to get a single user to get full details over it. The user must be identified using the UUID as parameter for the HTTP request:

GET https://wac:8001/sapi/users/57877673e8f15d347281734a HTTP/1.1
Authorization: Bearer ec3fe973ea047b6fd38228eb9f9b9661cbb5b0fdeac01ff13af1eef
Content-Type: application/json

Editing users

As administrator, you need to update users, change its domain, or its personal data (mail, phone, etc). To do it, simply execute a PUT command over the corresponding UUID of the user that you need to update:

PUT https://wac:8001/sapi/users/5788b1a8e8f15d3472817350 HTTP/1.1
Authorization: Bearer ec3fe973ea047b6fd38228eb9f9b9661cbb5b0fdeac01ff13af1eef
Content-Type: application/json

{
   "domain": "quobis",
   "username": "alice",
   "email": "imalice@demo.quobis.com",
   "role": "user",
   "capabilities": [],
   "mobilePhone": ['1111111'],
   "alias": "masterOfTheUniverse"
}

Delete users

To delete a user, simply use the DELETE command along with the UUID:

DELETE https://wac:8001/sapi/users/5788b1a8e8f15d3472817350 HTTP/1.1
Authorization: Bearer ec3fe973ea047b6fd38228eb9f9b9661cbb5b0fdeac01ff13af1eef
Content-Type: application/json

This action will simply remove the user entry on the system. In addition, if the SIP mapping service is being used, the SIP mapping associated to that user is removed and the sip mappings pool is marked as “available”, as explained in the SIP mappings section.

Warning

All other elements linked to this user, like credentials or any other element on the database not detailed above, will not be removed with this command.

Adding a password to an user - Basic credential

Any user will need an authorization token to log into the platform. The authorization tokens are defined as credentials. Also it is common to refer to it as a “password” the information that confirms that we have a legitimate user.

A credential is simply a authorization password. There are three kind of credentials on the system:

  • basic: Required for user authentication.

  • sip-mapping: Presents the equivalence between a SIP identity and a system resource. Required to identify the user at the SIP gateway when the user reaches the external SIP network. Refer to SIP mappings for a detailed description.

  • ims: Required to identify the user on a third-party SIPoWS gateway.

Note

The ims credentials are used only when a third party SIPoWS MS is used instead the default SFU provided by Quobis wac.

The classic old-school password is the basic credential, used by the applications to obtain a token. Be sure to create a basic credential for each user that uses the system. In this case, you will need to specify on the body of the request the UUID of the user to link with the credential:

POST https://wac:8001/sapi/credentials HTTP/1.1
Authorization: Bearer ec3fe973ea047b6fd38228eb9f9b9661cbb5b0fdeac01ff13af1eef
Content-Type: application/json

{
   "source": "wac",
   "type": "basic",
   "context": {},
   "domain": "quobis",
   "user": "5c4345a61f59a0026fa2929f",
   "data": {
      "password": "qa2"
   },
   "lease": 0
}

Adding SIP network access (SIP mapping)

In order to grant a user or usergroup to reach the SIP network, it is required to configure properly the SIP trunk and to add a sip-mapping to the resource. To do it, add the username of the resource on the SIP network. This will be used to identify the user or usergroup on the SIP network:

POST https://wac:8001/sapi/sipMappings/ HTTP/1.1
     Authorization: Bearer ec3fe973ea04739e1...12ec5adc8b323c83c0
     Content-Type: application/json

     {
     "ownerUri": "wac-user:aliceId",
        "credential": {
           "username": "205"
           "password": ""
        }
     }

The previous example will create a sip-mapping that will identify the user as “205” on the SIP network. Also, any call received on the SIP side with 205 as destination will be routed to the corresponding user (identified by its UUID wac-user:aliceId).

Adding SIPoWS credentials - IMS credentials

When the deployment includes a third party SIPoWS or vendor SIP gateway playing the Sippo MS role, it is required to add extra authentication information to the system users.

Consider it the login that must be done on the third-party element. Your user could be identified with a e-mail like username and a password, but these SIP gateways will need their own authentication framework. For example: you can be alice@quobis with pass MyB1rdDay, but you can have linked a SIP identity like alice@quobis.com with SIP authentication username 123@10.2.3.4 with a different password 23t6iyb3r5yliu. This link is made in the Quobis wac by using the IMS credentials. To do so, we will create the same request as we did for the basic password, but specifying the ims credential type:

POST https://wac:8001/sapi/credentials HTTP/1.1
Authorization: Bearer ec3fe973ea047b6fd38228eb9f9b9661cbb5b0fdeac01ff13af1eef
Content-Type: application/json
{
   "source": "wac",
   "type": "ims",
   "context": {},
   "domain": "quobis",
   "user": "586b6602ffc539dc7fc3261d",
   "data": {
      "username": "alice@quobiscom",
      "userauthname": "123@10.2.3.4",
      "password": "23t6iyb3r5yliu",
      "authserver": "wss://sipowsgw.quobis.com",
      "iceserver": [
         {
            "urls": "turn:158.61.103.18",
            "credential": "secret",
            "username": "alice"
         }
      ]
   },
   "lease": 0
}

This is the meaning of each field:

  • user: Required to link with the UUID of the Sippo user created previously.

  • data.username / userauthname / password: Authentication information for SIPoWS related authentication.

  • data.authserver: Address of the third party SIPoWS gateway.

  • data.iceserver: Address and authentication information of the third party TURN server in

    place to avoid NAT problems.

  • lease: Duration of the register. Value 0 will let the third party SIP gateway to define the expiration time.