ShoreTel Advanced Applications Web Utilities - Amazon Simple ...

INSTALLATION & USER GUIDE

ShoreTel Advanced Applications Web Utilities ShoreTel Advanced Applications

Introduction The ShoreTel Advanced Application Web Utilities provides ShoreTel User authentication and software license validation for web based (browser) applications such as “ShoreTel for Salesforce.com”. The application is installed on the ShoreTel Director (HQ) and requires some configuration in all ShoreTel servers (HQ and DVSs) which host ShoreTel users. Requirements:  ShoreTel Releases 13.X or 14.X.  ShoreTel Application Licensing Server

ShoreTel Advanced Applications Web Utilities

Version 1.4.4

Page 1 of 15

Table of Contents Introduction ................................................................................................................................ 1 Table of Contents ....................................................................................................................... 2 Overview .................................................................................................................................... 3 Installation Prerequisites ............................................................................................................ 3 Licensing ................................................................................................................................ 3 Create IIS Application Pool ..................................................................................................... 3 Installation .................................................................................................................................. 6 Configuration .............................................................................................................................. 9 Web Application Configuration................................................................................................ 9 ShoreTel Server Configuration ............................................................................................... 9 Web Utilities Configuration ................................................................................................... 11 Login Attempts .................................................................................................................. 12 Reverse Proxy Configuration ............................................................................................ 12 Error Messages ........................................................................................................................ 14 Application Log File .................................................................................................................. 14


Version 1.4.4

Page 2 of 15

Overview The ShoreTel Advanced Applications Web Utilities are used by web based applications (e.g., “ShoreTel for Salesforce.com”) to authenticate ShoreTel Users and for access control to applications. The ShoreTel Director (HQ) and DVS servers which host users must be configured to allow browsers to access these servers from web pages hosted by other severs. This type of web page access is called a “Cross-Domain” reference and requires IIS configuration to send additional HTML response headers (CORS) to allow access. The Web Utilities web application may be configured to operate using a reverse proxy server as documented in Appendix E of the ShoreTel Planning and Installation Guide. Since the reverse proxy has an official SSL certificate, it will be recognized by all browsers and allow the connection to operate in full HTTPS without warnings and without having to make any browser security setting changes (except IE 9). Additional information on browser configuration can be found in the ShoreTel for Salesforce.com Deployment Guide.

Installation Prerequisites Licensing The Application Licensing Server must be installed on the ShoreTel Headquarters (Director) server. The Application Licensing Server may be downloaded from the ShoreTel support website: http://support.shoretel.com/products/applications/. A license key is not needed for this application but keys are needed for other applications (e.g., ShoreTel for Salesforce.com) which depend on this application.

Create IIS Application Pool The Web Utilities application requires a dedicated IIS Application Pool. The following instructions are for IIS 7 (Windows 2008) and IIS 8 (Windows 2012) Start the Internet Information Services (IIS) Manager (i.e., Start ->inetmgr) and select “Application Pools” followed by “Add Application Pool”.


Version 1.4.4

Page 3 of 15

The Application Pool “Name” is “AAWebUtilities, “.NET Framework” is “v2.0…”, and “Managed pipleline mode” is “Classic”. Select “OK” followed by “Advanced Settings…”.


Version 1.4.4

Page 4 of 15

Set the “Enable 32-Bit Applications” to “True” and select the highlighted “Identity” button below to change the identity.


Version 1.4.4

Page 5 of 15

Change the “Built-in Account” to “NetworkService” followed by “OK” and “OK”.

Installation The application must be installed on the ShoreTel Director (HQ) server.  You should have received a zip file named “STAAWebUtil.X.Y.Z.zip”.  Unzip the file to a folder.  From the folder run the STAAWebUtilSetup.exe.  If you have not already installed the Microsoft .NET 3.5 runtime on the server you will be prompted to do so. If so, follow the prompts which should automatically download and install .NET from the Internet. Once this completes, continue with the install. Follow the install prompts:


Version 1.4.4

Page 6 of 15


Version 1.4.4

Page 7 of 15


Version 1.4.4

Page 8 of 15

Configuration Web Application Configuration Web applications (e.g., ShoreTel for Salesforce.com) which use the ShoreTel Advanced Applications Web Utilities must be configured with either the IP address or reverse proxy hostname:port for the ShoreTel Director (HQ) server. An IP address indicates the application will directly communicate with the HQ server while a hostname:port indicates a reverse proxy server is used to communicate with the HQ server. For example, the Salesforce.com Call Center definition must be configured with ShoreTel Director (HQ) server for the ShoreTel for Salesforce.com application.

ShoreTel Server Configuration All ShoreTel servers (HQ and DVSs) which host ShoreTel users must be configured to accept cross domain web requests using the following procedure. Start the IIS Manger by clicking Run and typing “inetmgr”. In tree view on the left side of the dialog, expand the following nodes: machine name (e.g., JMDIRECTOR), Sites, Default Web Site and then “sm_login”. In the center pane of the dialog, find and double-click on the “HTTP Response Headers” icon.


Version 1.4.4

Page 9 of 15

Click “Add…” to add a new http response header.

Enter “Access-Control-Allow-Origin” for the name, “*” for the value, the then press OK.


Version 1.4.4

Page 10 of 15

Verify the newly added response header and then close the IIS configuration application.

Web Utilities Configuration This section describes the configuration settings for the Web Utilities application. These settings are modified in IIS by double clicking on the “Application Settings” for the “STAAWebUtil” web application.


Version 1.4.4

Page 11 of 15

Login Attempts The configuration parameter for the number of login attempts is called “loginAttempts” and contains the default value of 3 as shown below. This value may be changed by selecting (highlighting) the “loginAttempts” line and then selecting “Edit…” which brings up the dialog to modify the value.

Reverse Proxy Configuration If a reverse proxy server is used, the application must be configured with the reverse proxy hostname and port for each ShoreTel server’s IP address. For example, to access the ShoreTel Director (HQ) server 10.0.0.1 using the reverse proxy hostname “pxy.myserver.com:5500”, you would select “Add…”, enter “10.0.0.1” for the “Name”, enter “pxy.myserver.com:5500” for the “Value”, and then select “OK” as shown below. Note: if the proxy routing rule references the ShoreTel HQ server using DNS (e.g. “pbx”), then you must configure this association by entering the DNS name (e.g.“pbx”) in the “Name” field and entering the reverse proxy hostname and port (e.g., “pxy.myserver.com:5500”) for the “Value” field.


Version 1.4.4

Page 12 of 15


Version 1.4.4

Page 13 of 15

Error Messages Listed below are error messages which may be returned to a User of a browser based application that leverages this software. The first two error messages may be corrected by the User while the last two errors must be corrected by the ShoreTel System Administrator.    

This version of Internet Explorer (IE) is not supported. The following browsers are supported: IE 9 (or greater), Chrome, Firefox, and Safari. Please enable or have your system adminstrator enable browser cookies for URL:. Please inform the ShoreTel System Administrator that the CORS configuration for the sm_login IIS web application on S nnn.nnn.nnn.nnn is missing or is incorrect. Please inform the ShoreTel System Administrator that ShoreTel server nnn.nnn.nnn.nnn is missing from the Advanced Applications Web Utilities reverse proxy configuration.

Application Log File By default, the application will write a log file containing informational and error messages. The logging feature allows more or less details to be logged by editing the logging XML file. As configured, the application will maintain a rolling history of up to 10 log files with a maximum of 2 Megabytes in each file. The application log files are named “AAWebUtil.log” and are stored in the installation folder (“C:\inetpub\wwwroot\STAAWebUtil\) in the Logs” subfolder. The XML file which controls the logging is named log4net.config. If you edit the file with (for example) notepad.exe, this shows the contents of the file: ShoreTel Advanced Applications Web Utilities

Version 1.4.4

Page 14 of 15

To change the level of detail logged, you would want to change the "level value" in the root section and save the changes. Changes to the log level do NOT require a service restart. The above screen shot shows the value. The valid values in order of increasingly detailed logging (each level includes lower levels) are as follows:  FATAL Only fatal errors are logged.  ERROR Errors are logged.  WARN Warnings are logged.  INFO Informational events are logged.  DEBUG All logging is enabled. Note: If UAC is enabled you must run Notepad as administrator (i.e., right click on Notepad and select “Run as administrator”) in order to save the updated “log4net.config” file.


Version 1.4.4

Page 15 of 15