Provisioning CounterPath Bria Professional OEM EditionRetail Edition
CounterPath Corporation CounterPath Corporation. Suite 300, One Bentall Centre 505 Burrard Street Box 95 Vancouver BC V7X 1M3 Tel: 1.604.320.3344 sales@counterpath.com www.counterpath.com © September 2009 This document contains information proprietary to CounterPath Corporation, and shall not be used for engineering, design, procurement, or manufacture, in whole or in part, without the consent of CounterPath Corporation.
Contents 1 About Provisioning ....................................................................................................................3 1.1 Provisioning Functions .....................................................................................................3 1.2 What Provisioning Does: Writing to Settings...................................................................3 1.3 The Mechanism of Remote Provisioning .........................................................................
CounterPath Corporation 2
About this Manual This manual describes the mechanism of remote login/provisioning. It describes how to set up a server (or servers) for the remote login and optionally the remote provisioning, remote update and remote upgrade features of Bria Professional • • • • Remote login controls access to the application; the softphone will not start until the user has logged in. Remote provisioning lets you configure the softphone remotely.
CounterPath Corporation 2
Provisioning Bria Professional OEM Edition 1 About Provisioning 1.1 Provisioning Functions Provisioning of Bria Professional includes the following features: • • • • Controlling access to the VoIP service through a remote login. See page 9. The ability to provide a license key remotely. See page 9. Updating the Bria Professional configuration (changing the factory defaults). Bria Professional can be configured differently for each user. This feature is optional. See page 15.
CounterPath Corporation 1.2.2 Syntax of Settings Each setting has a fully qualified name: :: For example, proxies:proxy0:register. The syntax for setting values via provisioning is: ::=<“value”> For example, proxies:proxy0:domain=“domainA.com” • • • 4 The value of the variable must appear in double quotes. Always a string. True is represented by “true” or “1”. False is represented by “false” or “0”.
Provisioning Bria Professional OEM Edition 1.3 The Mechanism of Remote Provisioning Each remote provisioning service involves an exchange between the login server and an individual Bria Professional client. The exchange is performed over HTTP or HTTPS. 1.3.1 Servers You must deploy servers to handle the provisioning requests: • • • The “login server”: a server to handle login requests, if you decide to implement login.
CounterPath Corporation might become this POST used to log in the user: https://mycustomloginserver.com/login.php -------------------------------------------------------------------------------------Username=21187 Password=rosebud platform=win32 lic=d3874ihfd8t23975v1iu5182ruity3iusapor236u545uye0r9qwjj Note that “Username” and “Password” (with initial capitals) are always sent in a login POST; the URL does not have to include macros for this data.
Example [DATA] Success=1 [SETTINGS] proxies:proxy0:display_name="kokila" proxies:proxy0:enabled="1" proxies:proxy0:username="kpereira" proxies:proxy0:password="dfher43d89dhferuieo98375uy8” proxies:proxy0:domain="domainA.com" [DATA] This section contains the response to requests: Success=, a boolean. This data is required. Failure=, which is optional if the success is 0. For login, the string you enter here will be displayed in the Login dialog.
CounterPath Corporation 1.3.5 Example of an Implementation The hardware requirements of the login server depend on what the server will do. If it will have a complicated backend database and processing involved in order to retrieve the settings that are to be provisioned, then the server should be of higher processing capabilities. Regardless, the login server is simply a web server and it only needs to serve one file for provisioning; this file is in plaintext or XML format.
Provisioning Bria Professional OEM Edition 2 Login and Configuring 2.1 Credentials Required 2.1.1 Types of Credentials Login Credentials Login refers to the process of signing into the VoIP service. The Bria Professional user must enter login credentials – user name and password – in order to access to Bria Professional. Login credentials cannot be changed through provisioning.
CounterPath Corporation • The authorization user name is used only to register the account. It does not replace the account user name in identifying the user to the outside world. • If you use an authorization name, make sure it is different from the user name! 2.2 Specifying the Login Server You can identify the login server in one of these ways: • • Bria Professional discovers login server via DHCP. Users enter login server manually.
Provisioning Bria Professional OEM Edition 2.3 Login Server Fallback Behavior Regardless of whether DHCP is being used or not, Bria Professional allows login to be skipped when the login server cannot be contacted (for example, it is temporarily offline). In these situations, Bria Professional displays the “Skip Login or Enter Server” version of the Login dialog. The user should press Skip to start Bria Professional without logging in.
CounterPath Corporation 2.4 The Login Process The login server must be set up to handle the following procedure. Step client GUI client your Server proxy User enters login credentials on Login dialog box Query Login credentials Verification Perform any verification, including license verification success and account credentials Response Local verification Client verifies license key Register using account credentials Login Procedure Is Invoked The Login dialog box is displayed.
Provisioning Bria Professional OEM Edition might become this POST used to log in the user: https://mycustomloginserver.com/login.php -------------------------------------------------------------------------------------Username=21187 Password=rosebud platform=win32 lic=d3874ihfd8t23975v1iu5182ruity3iusapor236u545uye0r9qwjj where: • • “Username” and “Password” (with initial capitals) are always sent in a login POST; the URL does not have to include macros for this data.
CounterPath Corporation where: • • • • success: this line is required. Settings: the username will be saved at shutdown. ##Memory##: the password will not be saved at shutdown. The response must end with a CRLF. Local Verification Bria Professional next takes one of these actions, depending on the response received from the server: • • 14 If the response was a failure, then the Login dialog apppears again. The process goes back to “Login Procedure Is Invoked” on page 12.
Provisioning Bria Professional OEM Edition 3 Updates and Upgrades Remote Updates You can configure Bria Professional to check with the update server at specified intervals for changes to the user’s settings. Remote Upgrades There are two ways to support upgrades to Bria Professional. Use CounterPath Upgrade Server The default behavior is to obtain upgrades from the CounterPath upgrade server.
CounterPath Corporation feature:auto_update update_check_t1_s See below for a description. Default is 86400 seconds (24 hours). Typically, leave the default. feature:auto_update timer_factor See below for a description. Default is 1.00 Timer Settings Remote upgrades and remote updates rely on four timers in the user’s settings. The timers control how frequently Bria Professional contacts the update and upgrade executable servers. All values are in seconds.
Provisioning Bria Professional OEM Edition 3.2 Remote Update 3.2.1 Setting Up • • Set up Bria Professional as described on page 15. Set up the update server to handle the procedure described below. 3.2.2 How Remote Update Is Performed Assuming that the timers are not all set to zero, this procedure runs “in the background” for as long as Bria Professional is running. 1.
CounterPath Corporation 3.3 Remote Upgrade 3.3.1 Setting Up • • Set up Bria Professional as described on page 15. Set up an upgrade server as follows: • You can use a script to include logic that determines a given deployment needs an upgrade. See below for an example. Obtain the sample upgrade script from CounterPath and modify it to suit your needs.
Provisioning Bria Professional OEM Edition [DATA] Success=1 Mandatory=1 version=60000 url=https://executableupgradeserver.com/newversion.exe where: • Success: 1=true (there is an upgrade) or 0=false (there is no upgrade). • Mandatory: 1=true. This response is optional; the deafult is “0”. Bria Professional handles the upgrade differently depending on this response; see below. • version: identifies a build stamp set by Bria Professional during build time.
CounterPath Corporation 20
Provisioning Bria Professional OEM Edition A Script Samples Contact CounterPath to obtain sample scripts. These sample scripts, written in PHP, are intended to illustrate a possible implementation. They are not intended to be used without modification. You should write scripts suitable to your environment, in an appropriate scripting language. login.php Custom login script. Bria Professional passes in the username and password.
CounterPath Corporation B Macros Macro Description $acc_passwdn$ where n is an account. The password for the specified SIP account (for deployments that support more than one SIP account). Value Stored as a setting. $acc_usern$ where n is an account. The username for the specified SIP account (for deployments that support more than one SIP account). Stored as a setting. $build$ The last five digits of the executable name.
23
CounterPath Corporation 24
