Bria 4 Provisioning Guide Enterprise Deployments
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 © April 2014 CounterPath Corporation. All rights reserved. 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 Licenses ............................................................................................................................3 1.3 What Provisioning Does: Writing to Settings................................................
CounterPath Corporation ii
About this Manual This manual describes the mechanism of remote login/provisioning if you are implementing provisioning using your own provisioning server (rather than the CounterPath CCS). 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: • • • • Remote login controls access to the application; the softphone will not start until the user has logged in.
CounterPath Corporation 2
1 About Provisioning 1.1 Provisioning Functions Bria provisioning includes the following features: Login: Controlling access to the VoIP service through a remote login. License key provisioning: The ability to provide a license key remotely. See below. Feature provisioning: Updating the Bria configuration (changing the factory defaults). Bria can be configured differently for each user.
CounterPath Corporation Setting up your Service for the Licensing Server Periodically, Bria connects to CounterPath’s license server in order to verify that a valid license is being used. Therefore, at all times, Bria will need to have an internet connection. Bria connects to https://secure.counterpath.com via port 443; make sure your firewall allows this HTTPS traffic to this URL.
Bria 4 Provisioning Guide – Enterprise Deployments 1.4 The Mechanism of Remote Provisioning Each remote provisioning service involves an exchange between the login server and an individual Bria client. The exchange is performed over HTTP or HTTPS. 1.4.1 Servers You must deploy servers to handle the provisioning requests: • • • The “login server”: a server to handle login requests. This server is simply a web server that, at a minimum, can serve one plaintext or XML file.
CounterPath Corporation Your script must understand the names assigned to the macros. For example a URL of: https://mycustomloginserver.com/login.php?platform=$platform$&lic=$license$ might become this POST used to log in the user: https://mycustomloginserver.com/login.
Bria 4 Provisioning Guide – Enterprise Deployments 1.4.4 Data Format All the data included in the GET or POST response is in a specific format. This format is similar to that of Microsoft® Windows®.ini files.
CounterPath Corporation 8
2 Remote Login and Configuring 2.1 Credentials Required Login Credentials Login refers to the process of signing into the VoIP service via your login server. The Bria user must enter login credentials – login name and login password – in order to access Bria. Login credentials are written to the settings file only if the “Remember” boxes on the dialog are checked. Login credentials cannot be changed through provisioning.
CounterPath Corporation 2.2 Specifying the Login Server You must provide users with the URL of the provisioning server. The URL should include any scripts and macros you are using. The user enters this URL into the field on the Bria Login dialog. When Bria starts, the Login dialog appears with “Manually enter login server” specified in the Profile field. The user should enter the server URL and their login credentials and click Login.
Bria 4 Provisioning Guide – Enterprise Deployments 2.3 The Login Process The login server must be set up to handle the following procedure. 2.3.1 The Login Procedure Is Invoked The Login dialog is displayed. The user enters the required information and clicks Login.
CounterPath Corporation 2.3.2 Query Step Bria sends the data from the Login dialog. The data is encoded application/x-www-form-urlencoded. The data is sent to the login server (the server specified in feature:custom_login:server) in an HTTP POST. The value will be blank if the branded Login dialog does not include the corresponding field; this is not an error. For example a URL of https://mycustomloginserver.com/login.
Bria 4 Provisioning Guide – Enterprise Deployments 2.3.4 Response Step Response Step: Failure If there is a problem with any of the data, your server should return failure data in the following format: [DATA] Success=0 Failure=" " Response Step: Pass If your server can handle the request, it should return a success message and the account credentials. It can also return other settings that can be specified only at login.
CounterPath Corporation 2.3.5 License Key Verification by Bria Bria next takes one of these actions, depending on the response received from the server: If the response was a failure: The Login dialog appears again. The process goes back to “The Login Procedure Is Invoked” on page 11. If the response was a success: Bria checks if there is a license key in the response. • • • 14 If the response includes a key, Bria validates the key and then starts.
3 Updates and Upgrades Remote Updates You can configure Bria 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. Use CounterPath Upgrade Server The default behavior is to obtain upgrades from the CounterPath upgrade server. Whenever CounterPath puts a new executable on its upgrade server, each user’s Bria will automatically download the upgrade and an install prompt will appear.
CounterPath Corporation 3.2 Remote Update 3.2.1 Setting Up • • Set up Bria as described on page 15. Set up the update server to handle the procedure described below. 3.2.2 Timing of Update Checks Bria contacts the update server as follows: 1. Bria starts and the update timer starts using the value in config_check_initial_t_s. 2. When the update timer expires, Bria checks for and (if appropriate) performs an update. 3. The update timer is then restarted, but this time with the value in update_check_t1_s.
3.3 Remote Upgrade 3.3.1 Setting Up • • Set up Bria 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. Or you can skip the script and manually set up your upgrade server to simply provide a success response when an upgrade is available and a failure response at other times.
CounterPath Corporation Server Response The upgrade executable server must respond with the following: [DATA] Success=0 or [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 default is “0”. Bria handles the upgrade differently depending on this response; see below.
Bria 4 Provisioning Guide – Enterprise Deployments • • If the user declines, Bria will start the original version and will enter its timing cycle, displaying the download prompt again at the appropriate time. If the user declines with “do not ask me again”, Bria will start the original version and will not prompt to install again during the session. Bria starts the version installed most recently. The automatic check scenario will be initiated as described in the previous section.
CounterPath Corporation 20
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 passes in the username and password.
CounterPath Corporation B Macros Macro Description $acc_passwdn$ where n is an account. The password for the specified account (for deployments that support more than one 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 unique buildstamp. $computerid$ Unique ID for this computer.
