GEMS Administration Guide

Product Version: 2.2 Last Updated: 8-Nov-16

BlackBerry DynamicsTM

©2016 BlackBerry Limited. Trademarks, including but not limited to BLACKBERRY, BES, EMBLEM Design, ATHOC, EMBLEM Design, ATHOC & Design and PURPLE GLOBE Design, GOOD, GOOD WORK, LOCK Design, MANYME, MOVIRTU, SECUSMART, SECUSMART & Design, SECUSUITE, SECUVOICE, VIRTUAL SIM PLATFORM, WATCHDOX and WORKLIFE are the trademarks or registered trademarks of BlackBerry Limited, its subsidiaries and/or affiliates, used under license, and the exclusive rights to such trademarks are expressly reserved. All other trademarks are the property of their respective owners. All other trademarks are the property of their respective owners. This documentation is provided "as is" and without condition, endorsement, guarantee, representation or warranty, or liability of any kind by BlackBerry Limited and its affiliated companies, all of which are expressly disclaimed to the maximum extent permitted by applicable law in your jurisdiction.

Good Work Product Guide

ii

Revision History Log begins 3-Aug-15 for GEMS 1.5 GA Date

Description

3-Aug-15

Initial GEMS 1.5 edition published (Rev 4.1)

5-Aug-15

Added respective HA and DR configuration guidance for each primary GEMS service

10-Aug-15

Added .NET Framework as a core requirement, regardless of whether Connect and Presence are configured; updated Appendix A checklists accordingly

17-Aug-15

18-Jul-15

20-Aug-15 21-Aug-15

l

Clarified "Enabling KCD on the GEMS Host" under "Configuring Kerberos Constrained Delegation (KCD) for GEMS-Docs"

l

Added clarification on service account naming restrictions

l

Updated Appendix A with corrections/clarification in accordance with field feedback

l

Caveat added to Appendix J, limiting its applicability to GEMS 1.3.x and earlier

l

Added "Configuring Docs for a Server Already Hosting GEMS" under "Upgrading"

l

Added "EWS Namespace Configuration" to PNS Prerequisites

l

Added UCMA 4.0 prerequisites to 4.11 in Appendix A - Connect and Presence

Amplified "Enabling KCD on the GEMS Host" to require OS privilege for GoodAdmin on all machines running GEMS Docs.

25-Aug-15 3-Sep-15 22-Sep-15

Added "Using the Docs Self-Service Web Console" under "Managing Repositories" l

Revised steps for creating a SPN for GEMS-Docs KCD

l

Revised "Enabling KCD on the GEMS Host"

Corrected SQL collation setting under "PNS Database Requirements" from Latin1_ General_CI_AS to SQL_Latin1_General_CP1_CI_AS and modified the screenshot to appropriately reflect the setting.

23-Sep-15

l

l

l

l

5-Oct-15

Based on valued field feedback, added clarifications under "Configuring Kerberos Constrained Delegation (KCD) for GEMS-Docs" to better differentiate the guidance pertinent to SharePoint as opposed to the steps required for File Shares Added clarification under "Presence Prerequisites" stating that a SQL database is not required for the Presence service Amended the set of disallowed characters in Docs Repository definitions for SharePoint and File Shares Added a note in "Understanding the GEMS-Connect Configuration File" stating that the minimum SESSION_TIMEOUT_SECS is 600, even if you put in 60 seconds or 1 second. This was done to mitigate stress related race conditions

Added a new bidirectional TCP port requirement for 61616 and/or 61617 (SSL), not blocked by any firewall, in "System and Network Requirements" under "GEMS Prerequisites: Core Requirements" to support clustering (ActiveMQ)

9-Oct-15

Added bidirectional port requirement for 61616 and 61617 to Appendix A checklists

26-Oct-15

Updated Appendix A with:

Installation and Configuration Guide

iii

Date

Description l

Revised list of supported SQL Server versions

l

.NET Framework version requirements

29-Oct-15

Removed SQL Server 2014 Express as a supported option

26-Oct-15

Updated for GEMS v2.0 release. The following new/enhanced services and supported features/functionality are being introduced in this release: Good Work: Secure/Multipurpose Internet Mail Extensions (S/MIME) Support (Phase 2); Push Notifications and Alerts updates; Good Docs: Box as a storage provider, support for Microsoft® Word editing (via Office Web Apps), Microsoft SQL-based auditing tools; bug fixes.

12-Feb-16

Updated for GEMS v2.1 release. New install media. Support for Jabber for Good Connect. Silent installer (unattended installation). Discontinue notifications when the Good container or app is removed from GC. Badge count kept consistent with Outlook unread-email count. Centralized configuration: saved GEMS Mail configuration in the database syncs to other nodes in the cluster.

18-Feb-16

Updated clickpaths/steps in Create Google Cloud Messaging API keys because Google changed their site again.

23-June-16

Support for Jabber Presence; support for specifying multiple Good Proxy in GEMS for failover; Exchange Information Rights Management (RMS) for mail; Active Directory Rights Management services for documents; Docs dynamic storage provider support (CMIS); support for Exchange 2016. Support for client certificate authentication for SMIME classification in Good Work (AD and LDAP). Refer to supplemental documentation for S/MIME PIN timeout for additional security; PKINIT and certificate sharing support. Refer to Good Work Product Guide for Rest service to configure Autodiscover URLs for both Exchange Web Service (EWS) and (Exchange ActiveSync) EAS endpoints, utilized by Good Work for Autodiscover configuration.

02-September-16

Updated for the server 2.2.20.20 server release. Refer to the release notes for the open issues resolved. Updates to this doc include noting that UCMA 3.0 is no longer readily available from Microsoft and Directory lookup is applicablee for Lync only.

Installation and Configuration Guide

iv

Table of Contents

Introducing Good Enterprise Mobility Server (GEMS)

1

What's New in GEMS

1

Architecture

2

GEMS Prerequisites

5

Upgrade Notes

5

Core Requirements

6

System and Network Requirements

6

Good Dynamics Requirements

9

Configuring the Java Runtime Environment

10

Setting Up a Windows Service Account for GEMS

11

Database Requirements

12

Push Notification Service (PNS) Prerequisites

13

Supported Exchange Versions

13

EWS Proxy Support

15

EWS Namespace Configuration

16

Create an Exchange Mailbox for the Service Account

17

Grant Application Impersonation Permission to the Service Account

17

Set Authentication for the EWS Protocol

17

Set Up Exchange Autodiscover

18

PNS Database Requirements

18

Connect Prerequisites for Lync

19

Microsoft Lync Server Requirements

20

Preparing the Lync Topology for GEMS

27

SSL Certificate Requirements for Lync and Presence

29

Database Requirements

36

Lync Presence Prerequisites

37

Jabber Server Requirements for Presence

37

Create an Application User

Good Enterprise Mobility Server™

37

v

Create a Dummy User

39

Certificates

39

Docs Service Prerequisites

40

Server Software and Operating System Requirements

40

Database Requirements

41

CMIS Requirements

41

Directory Lookup Service Prerequisites

41

Follow-Me Service Prerequisites

41

Certificate Lookup Service Prerequisites

42

Installing GEMS

42

Performing a Silent Install or Upgrade

43

Performing a GEMS Fresh Installation or Upgrade

43

Upgrading to GEMS Version 2.2

70

Upgrade steps using the installer

70

For environments with three or more servers

71

Configuring GEMS Core

72

Configuring GD in the GEMS Dashboard

72

Configuring Your Dashboard Administrators

74

Replacing the Auto-Generated Self-Signed SSL Certificate

75

Importing CA Certificates for GEMS

75

Enabling GEMS HTTP (Optional)

76

Dashboard Troubleshooting Facilities

77

Log Upload Credentials

78

Upload Logs

78

Upload GEMS statistics

79

Configuring GEMS Services

80

Configuring the Push Notification (Mail) Service

80

Enabling Exchange ActiveSync (EAS)

81

Configuring PNS (Mail) in the GEMS Dashboard

81

Configuring Good Control

91

Good Enterprise Mobility Server™

vi

Configuring GEMS-PNS for HA

94

Configuring GEMS-PNS for DR

94

Device Verification and Testing

95

Adjusting the Push Notification Cutoff Time

95

PNS Logging and Diagnostics

96

Configuring the Connect Service

101

Configuring Connect in the GEMS Dashboard

101

Configuring Good Control for Connect

115

Configuring GEMS-Connect for HA

123

Configuring GEMS-Connect for DR

123

Using Friendly Names for Certificates in Connect

124

Enabling SSL Support Via Good Proxy

126

Configuring Support for the Global Catalog

136

Configuring Windows Services

137

Connect Service Logging and Diagnostics

138

Configuring the Presence Service

140

Configuring Presence in the GEMS Dashboard (Lync)

140

Configuring Presence in the GEMS Dashboard (Jabber)

142

Configuring Good Control for Presence

143

Configuring GEMS-Presence for HA

145

Configuring GEMS-Presence for DR

146

Using Friendly Names for Certificates in Presence

147

Logging and Diagnostics

149

Global Catalog for GEMS Connect and/or GEMS Presence

149

Updating the Connect and Presence Services Using Lync Director

150

Configuring the Docs Service

151

Configuring Docs in the GEMS Dashboard

151

RMS restrictions

158

GEMS Docs deployment for AD-RMS support

159

Configuring Good Control for the Docs Service

159

Troubleshooting the Docs Service

163

Good Enterprise Mobility Server™

vii

Configuring GEMS-Docs for HA

163

Configuring GEMS-Docs for DR

164

Managing Repositories

165

Admin-Defined Shares

166

User-Defined Shares

171

User Repository Rights

174

Using the Docs Self-Service Web Console

176

Managing Storage Services

177

Windows Folder Redirection (Native)

179

Local Folder Synchronization – Offline Folders (Native)

181

Configuring Support for SharePoint Online/OneDrive for Business

183

SharePoint Online Authentication Setup

186

Troubleshooting SharePoint Issues

187

Configuring Office Web Apps Server (OWAS) for Docs Service Support

187

GEMS-Docs Service and Good Work Support for OWAS

187

OWAS Deployment

189

Troubleshooting

190

Configuring Kerberos Constrained Delegation (KCD) for GEMS-Docs

190

Finding the SharePoint Application Pool Identity and Port

192

Applying the GEMS Service Account to SharePoint in Active Directory

193

Adding KCD in Active Directory for SharePoint

194

Adding KCD for File Shares

197

Enabling KCD on the GEMS Host

198

Configuring Good Launcher

199

Verify Good Enterprise Services in Good Control

200

Adding GEMS to the Good Enterprise Services Entitlement App

201

Adding the GES Entitlement App to an App Group

204

Configuring the Certificate Lookup Service

204

Maintaining GEMS Cluster Identification in Good Control

205

Device Provisioning and Activation

Good Enterprise Mobility Server™

206

viii

Uninstalling GEMS

207

Removing a Single GEMS Instance

207

Removing a Connect Instance

209

Appendix A – Pre-Installation Checklists

210

Push Notifications

211

Connect and Presence

214

Docs

218

Appendix B – Importing/Configuring Certificates in the GEMS Java Keystore

221

Appendix C – Understanding the GEMS-Connect Configuration File

227

Appendix D – Fine-Tuning Your Java Memory Settings

230

Appendix E – IIS SSL Offloading

231

Appendix F – GEMS Windows Event Log Messages

237

Appendix G – File Types Supported by GEMS-Docs

241

Appendix H – Obtaining a Google Cloud Messaging API Key

243

Create Google Cloud Messaging API keys

243

Prerequisites

243

Steps

243

Installing Google Cloud Messaging API Keys Appendix I – Advanced Launcher Setup

243 244

Deploying Multiple GEMS

244

Configuring User Affinity

245

Additional Considerations

Troubleshooting Launcher Performance

245

246

Appendix J – Changing the GEMS Dashboard and Web Console Login

248

Appendix K – Migrating Your Good Share Database to GEMS-Docs

249

Client App Support Considerations

249

Migrating with Continued Support for Good Share

249

Migrating to Good Work Only

250

Noteworthy Feature Differences (GEMS-Docs versus Good Share)

250

Appendix L – Configuring AlwaysOn Support for SQL Server 2012

251

Good Enterprise Mobility Server™

ix

Setting Up SQL AlwaysOn

251

Testing Database Failover

256

Configuring Your GEMS Services Databases for AlwaysOn Availability

257

Glossary

Good Enterprise Mobility Server™

259

x

Introducing Good Enterprise Mobility Server (GEMS)

Introducing Good Enterprise Mobility Server (GEMS) Leveraging a services-based approach to integrated enterprise mobility, Good Enterprise Mobility Server (GEMS) consolidates the Good Connect and Good Mobile Messaging servers into modules on a standardized architecture. The integrated services offered by GEMS currently comprise Connect, Presence, Push Notifications, Docs, Follow-Me (for Good Launcher), Directory (GAL) Lookup, and Analytics. The Push Notifications Service (PNS) accepts push registration requests from hand-held mobile devices—iOS, Android etc.—and then communicates with Microsoft Exchange via its Exchange Web Services (EWS) protocol to monitor the user's enterprise mailbox for changes. The Connect service boosts user communication and collaboration with secure instant messaging, corporate directory lookup, and user presence from an easy-to-use interface on IT-provisioned mobile devices. The Presence service furnishes real-time presence status to third-party Good Dynamics applications—giving them a powerful add-in for mobile collaboration. The Docs service lets your mobile workers access, sync, and share documents natively via their enterprise file server, SharePoint, Box, and content management systems supporting CMIS, without the need for VPN software, firewall reconfiguration, or duplicate data stores. The Directory Lookup service gives users the ability to look up first name, last name, and picture from your organization's Global Address List (GAL) and display it within the Good Launcher. The Follow-Me service supports the Good Launcher on Good Work, and will soon be available on other GD apps like Good Connect and Good Access, keeping the Launcher in-sync across multiple devices. The Certificate Lookup service retrieves S/MIME digital certificates from the user's Active Directory account and matches the requested key usage. Only the recipient's public certificate is retrieved for matching. The Analytics service, currently in developer preview and initially comprising an App Usage module, provides traffic and usage metrics for evaluating the effectiveness and impact of the mobile app deployments comprising your GD-GEMS ecosystem—which apps are being used, by whom, for what, how frequently, and for how long. A browser-based administration console—called the GEMS Dashboard—gives you the flexibility to configure all server components and services after installation completes. GEMS Web Console, also browser-based, provides real-time monitoring and logging of device connectivity, traffic load and throughput in real time. "Services," in the context of Good Dynamics (GD), refer to concrete atomic business-level functionality that can be consumed by a plurality of GD Applications. Examples of this are "Look up this contact in the directory", "Subscribe to Presence for these contacts", "Save this file to SharePoint", and so forth. The Good Dynamics Services Framework allows client applications on an authenticated device to discover and utilize services by providing API publication, as well as life cycle and visibility management of services via the Good Developer Network (GDN).

What's New in GEMS New in this version:

Installation and Configuration Guide

1

Introducing Good Enterprise Mobility Server (GEMS)

Notifications l

l

Support for Exchange 2016 o

Notifications, Badge Count, VIP Notifications in Good Work

o

Conversation history in Good Connect

Notification localization support for Good Work [iOS]

SMIME l

Support for client certificate authentication for SMIME certificate lookup in Good Work (AD and LDAP)

Good Docs l

Access Microsoft® AD RMS protected files in Good Work

l

Support for CMIS enabled repositories in Good Work/Docs. Eg. EMC Documentum, Alfresco, HP Records Manager

Good Presence l

Support for Jabber Presence

GEMS Infrastructure l

Support for specifying multiple Good Proxy in GEMS for failover

l

Improved scalability for push notification service to support 10,000 users

Troubleshooting Page l

Pages adds the ability to automate periodic upload of GEMS statistics to the Good/Blackberry NOC. The information collected includes number of users assigned to the instance, name of instance, name of the cluster, version of GEMS, list of instances, feature set for instance, feature set for cluster, services installed, status of the instance, JVM Version, last restart time, system bugs, operating system, schema version, and system health. The mail service must be installed for much of this information to be retrieved. Refer to the Administrator's Guide for details.

Architecture At a high level, the GEMS architecture looks like this:

Installation and Configuration Guide

2

Introducing Good Enterprise Mobility Server (GEMS)

From this architectural view, the diagram does not show how the Good Work application connects to Exchange for accessing email. It does, however, show how each GEMS service is accessed by Good Work on end-user devices, which is the GEMS role—to expose secure device-facing services used by Good Work and make them available to other GD-powered apps, as well. These services currently include Push Registration, Follow-Me, Presence, Directory Lookup, and Docs. Communicating via the protocols shown, the feature modules of GEMS integrate with your backend systems of record using a shared SQL Server running multiple databases for Core/Email, Connect, and Docs. For High Availability (HA), GEMS is deployed as a cluster, with all of its device-facing services provided by all instances in the cluster and made available to client devices through the Good Dynamics (GD) infrastructure. Each GD-powered client app connects through a GP cluster deployed on-premise. Entitlement to use GEMS services is managed through Good Control. A slightly different view looks like this—again at a high level:

Installation and Configuration Guide

3

Introducing Good Enterprise Mobility Server (GEMS)

Another important point to note in the diagram above is that the GEMS-PNS service is utilizing the same database server as Good Control. The database server can be local to Good Control, as depicted, or remote. These diagrams and the balance of this document assume that necessary supporting infrastructure components like Microsoft Exchange, Microsoft Lync or Cisco Jabber, Active Directory, and Good Control/Good Proxy are present and configured to support existing enterprise network operations. This guide, therefore, restricts itself to step-by-step instructions and guidance for installing GEMS and its Connect, Presence, Docs, and Push Notification services. The overall process comprises: l

Preparing the service environment

l

Setting up a Windows service account

l

Installing GEMS

l

Configuring GEMS services

l

Provisioning and activating client devices

Before attempting installation, be sure to carefully read and confirm that you meet all of the listed requirements.

Installation and Configuration Guide

4

GEMS Prerequisites

GEMS Prerequisites Successful GEMS installation and configuration requires that a supporting infrastructure comprising necessary hardware and software components is already place. These prerequisites include: l

Core Requirements

l

Push Notifications Service (PNS) Requirements

l

Connect Requirements

l

Presence Requirements

l

Global Catalog for GEMS Connect and/or GEMS Presence

l

Docs Requirements

l

Directory Lookup Requirements

l

Follow-Me Requirements

l

Certificate Lookup Requirements

Based on the services you have chosen to deploy, only after verifying that each of the respective prerequisites are in place and operating properly should you begin the GEMS service installation and configuration procedures prescribed. Important: If you don’t install the required software or fail to configure the requirements correctly prior to beginning installation of GEMS, the server may fail or behave in an unexpected manner.

Upgrade Notes If you are upgrading from an earlier version of GEMS, please review the following information and then complete the steps below. If this is your first GEMS installation, skip the upgrade steps. 1. When upgrading to 1.6.x and above, administrators must provide their AD user credentials to login to the GEMS Dashboard. 2. When upgrading instances in a cluster, use the GEMS installer to upgrade each GEMS instance in turn. Refer to Upgrading to GEMS Version 2.2 3. For upgrade situations in which there are multiple GEMS instances pointing to a shared (common) database, new features will not be available until all GEMS instances have been upgraded. In a mixed-version environment, each GEMS instance will continue to function with the earlier version’s features. Running in a mixed-version environment for an extended period of time is not recommended. 4. Special characters are now disallowed in the GEMS service account name. Important: The account name is a different property than the account password, which excludes the use of ';', '@', '/' only, whereas the service account name excludes the use of all special characters.

Installation and Configuration Guide

5

GEMS Prerequisites

If you are upgrading from a GEMS version in which you included special characters in the service account name, you will need to change the service account name, omitting any special characters, before proceeding with GEMS upgrade.

Core Requirements Certain basic requirements must be satisfied, in place, and correctly functioning regardless of the service modules—PNS, Connect, or Presence—you are deploying. The core requirements include: l

System and Network Requirements

l

Good Dynamics Requirements

l

Configuring the Java Runtime Environment (JRE)

l

Setting Up a Windows Service Account for GEMS

l

Database Requirements

System and Network Requirements Verify that the designated GEMS machine and its associated environment meet the following (minimum) system and network requirements, bearing in mind that different services and combinations of services—Connect, Presence, and/or Mail—and their respective traffic and use patterns will strongly influence your actual requirements. Refer to the GEMS Deployment Planning Guide for additional scalability and sizing guidance, as well as high availability and disaster recovery recommendations.

Hardware1 l

4-core / 2.4 GHz CPU or higher

l

16 GB RAM

l

50 GB disk space

l

100 / 1000 Ethernet Card

Software The following Java versions are supported: l

Java 7 Update 79 (7u79) or higher Java 7 update for Microsoft Windows (64-bit)

l

Java 8 Update 65 (8u65) or higher update for Microsoft Windows (64-bit)

Operating System If you intend to use GEMS Connect in a Cisco Jabber environment, the following can be used:

1See GEMS Deployment Planning Guide for scalability and sizing guidelines for your specific enterprise traffic and use profile.

Installation and Configuration Guide

6

GEMS Prerequisites

l

Jabber 9 and 10 are supported

l

Microsoft Windows Server 2008 R2 or 2012 R2

If you intend to use GEMS Connect and/or Presence services in a Microsoft Lync environment, the following 64bit versions of Microsoft Windows Server can be used: For MS Lync 2010 Deployments use Windows Server in one of these 64-bit versions: l

2008 SP2 or R2

For MS Lync 2013 Deployments use Windows Server in one of these 64-bit versions: l

2008 R2

l

2012 R2

The minimum operating system for Lync 2013 implementations is based on the Microsoft Unified Communications Managed API (UCMA) version 4.0 requirements. Supported Microsoft Exchange versions include: l

Exchange 2010 SP 2 RU41

l

Exchange 2013

l

Exchange 2016

l

Microsoft O365

l

Hosted Exchange (2010 SP 1+)

Supported Microsoft Lync versions include: l

Lync 2010 (requires .NET 3.5 SP1 and .NET 4.5)

l

Lync 2013 (requires .NET 4.5 or 4.5.1)

Supported Browsers The GEMS Dashboard and the Docs Console are compatible with the following browsers: l

Internet Explorer (IE) 10 and IE 11; IE 9 is not supported

l

Firefox 32, 31, 30

l

Chrome 37.0.2062.120

Administration Rights l

User performing the installation must have local administrative privileges on the host machine

l

GEMS must be able to connect with Microsoft Exchange for PNS

l

GEMS must be in the same domain as the Microsoft Lync Server for Connect

1A plus sign ('+') indicates support for service packs and updates released subsequent to the core version.

Installation and Configuration Guide

7

GEMS Prerequisites

l

GEMS must be able to communicate with the enterprise’s Microsoft Active Directory

l

GEMS must have "logon as a service" right

l

Local antivirus software must be disabled during installation

l

Local Windows firewall must be disabled

Important: A Group Firewall Policy will cause the installer to fail its prerequisite checks, even if the local firewall is disabled.

Inbound TCP Ports (open and ready for GEMS; not blocked by any firewall) l

8080 from the Good Proxy (GP) server; or 8082, if SSL is required for inbound GP communications

l

8443 from the Good Proxy server for Push Notifications, Presence, and Docs; from Office Web Apps server for Docs

l

49555 from the Lync Server for the Connect Service

l

49777 from the Lync Server for the Presence Service

l

61616 TCP port to and from GEMS machines in the same cluster (bidirectional)

l

61617 TCP (SSL) to and from GEMS machines in the same cluster (bidirectional)

Important: To support clustering, GEMS employs ActiveMQ's enterprise features. By design, network port 61616 and 61617 (SSL) are used for inter-GEMS communication. Any firewall between GEMS nodes in the same cluster should have rules allowing bi-directional communication between GEMS nodes over port 61616 and/or 61617 (SSL).

Outbound TCP Ports (not blocked by any firewall) l

443 to Good NOC (gdweb.good.com)

l

443 to Microsoft Exchange

l

443 to Google Cloud Management (for Android Push Notification)

l

443 or 80 to Microsoft SharePoint

l

443 to Microsoft Office Web Apps Server (OWAS)

l

5061 to the Microsoft Lync Server

l

17080 to the Good Proxy server

l

17433 to the Good Proxy server1

l

1433 to the Microsoft SQL Server (default)

l

1434 UDP to the MS Lync database (for initial setup only)

1GEMS requires visibility of all Good Proxy servers (17080/17433), regardless of whether KCD is enabled or not, so that if one Good Proxy fails, GEMS can

communicate with the next Good Proxy in the cluster for authentication tokens, etc.

Installation and Configuration Guide

8

GEMS Prerequisites

l

8443 to the Cisco User Data Service

l

5222 to the Cisco Client Jabber XMPP Service

l

49152 – 57500 TCP: Random port in this range to the Lync database (for initial setup only)

l

61616 TCP port to and from GEMS machines in the same cluster (bidirectional)

l

61617 TCP (SSL) to and from GEMS machines in the same cluster (bidirectional)

Note: For installing Connect for Lync, if the Lync DB server is using a static port then open that port. The range of ports is necessary only when the Lync DB server is using dynamic ports. Important: Mobile devices must be able to connect to the Apple (APNS) and Google (GCM) messaging servers in order to properly receive push notifications from GEMS. If your wifi network restricts outbound access, please refer to the following articles and make sure the proper outbound ports are open for your mobile devices. Ports for APNS: https://support.apple.com/en-us/HT203609 Ports for GCM: https://developers.google.com/cloud-messaging/http

Internal Ports (used by GEMS): l

8080, 8082 for use by the Connect Server

l

8101 for SSH connectivity to GEMS

l

8443 for GEMS-PNS and Presence

l

8099 for use by the .NET Component Manager

l

8060 for use by the Lync Presence Provider (LPP)

TCP/IP Port Access to the Database l

1433 to the Microsoft SQL Server default

Good Dynamics Requirements The following minimum GD Server versions should be appropriately installed and configured according to the instructions in the GD Servers Installation Guide. l

Good Control (GC) Server 1.10.47.11

l

Good Proxy (GP) Server 1.10.47.2

For best performance results, the most current software version available is strongly recommended and is available from the Good Developer Network.

Installation and Configuration Guide

9

GEMS Prerequisites

Important: Your Good Dynamics Server(s) must be operating prior to installation of GEMS.

Configuring the Java Runtime Environment JRE 7u79 or later update for Windows x64 or JRE 8u65 or later update is integral to GEMS support of intranet applications and other e-business solutions that are the foundation of corporate computing. After installing the JRE, the JAVA_HOME system environment variable must be set. To set the JAVA_HOME system environment variable for GEMS: 1. First, edit the system environment variables: a. Select Computer from the Start menu, then click on System Properties. b. Click on the Advanced tab, then click the Environment Variables... button.

2. If the JAVA_HOME variable does not exist in the System variables list, click New and in the Variable name field, type JAVA_HOME. If the JAVA_HOME variable exists, click Edit. 3. In the Variable value field, type the full path to the Java install folder for the 64-bit JRE. For example, type C:\Program Files\Java\jre1.8.0_91. 4. Click OK. 5. In the System variables section, locate the Path variable, and click Edit. 6. In the Variable value field, append the JAVA_HOME variable, separated by a semi-colon. For example, add ;%JAVA_HOME%\bin. 7. Click OK.

Installation and Configuration Guide

10

GEMS Prerequisites

Setting Up a Windows Service Account for GEMS For the required service account, "GoodAdmin" is recommended. In fact, you can use the same Windows Service Account to install all GEMS service modules; e.g., [email protected]. Of utmost importance here is to make sure the service account ([email protected]) has the appropriate administrative privileges for all the GEMS service modules you plan to configure and deploy. Permissions for individual service modules may not require the same privilege level as others. Consequently, as you add services to GEMS, you will want to adjust the permissions accordingly. Important: If you use this same account for GEMS Connect and Presence, you will need to give "GoodAdmin" the RTCUniversalReadOnlyAdmins privilege.

Creating an Active Directory Account for GEMS Services Note: "Read Only Domain Controllers" (RODC) are a feature of Microsoft's Active Directory software. RODC AD servers are not supported for GEMS. GEMS supports only writable domain controllers. Set the following attributes for the Good-GEMS AD Account: l

The account name (UID, distinct from the account password) must be strictly alphanumeric; no special characters are allowed (exceptions: underscore (_) and hyphen (-); the recommended account name for GEMS is "GoodAdmin"

l

Account Password (distinct from the account name above ) must not contain these characters: ';', '@', '/' ^.

l

Password Expires option must be set to Never for this account.

l

This account (GoodAdmin) should be a member of local administrator group on the GEMS host machine.

Changing the GEMS Services Account Password If you later wish to change the GEMS services account password, you will need to do the following: 1. Log on to the GEMS server using the updated password. 2. Open Windows services. If the logon services for Good Technology Common Services is “local system,” no action is required. If the logon services for Good Technology Common Services is “service account,” update the password and click Apply. Restart the services. In the same way, update the Connect and Presence logon services passwords, and click Apply and restart the services for both. 3. Log on to the GEMS dashboard, 4. If “Use Windows Integrated Authentication” is unchecked under Mail > Exchange server, and the same service account is used, then update the password, run a test, and then save the configuration. 5. If the Connect and Presence services use the same service account, update that password and save the

Installation and Configuration Guide

11

GEMS Prerequisites

configuration.

Database Requirements The following versions of MS SQL Server are supported: l

SQL Server 2014 and 2014 SP1 (64-bit)

l

SQL Express 2014

l

SQL Server 2012 and 2012 SP1 (Standard/Enterprise)

l

SQL Server 2008 and 2008 R2 (Standard/Enterprise)

l

SQL Express 2008 R2 with Management Tools

If you have not yet installed a supported version of Microsoft SQL Server, please obtain one from the Microsoft Download Center. MS SQL Server 2008 R2 is recommended. For MS SQL Server 2008 R2 setup guidance, see SQL Server Setup. For test lab guidance on setting up SQL Server 2012 Enterprise Edition, click here. For SQL Server 2014, click here. To allow SQL Server Express to accept remote connections: 1. Login to the database server through Remote Desktop Connections. 2. Click Start > Programs > Microsoft SQL Server 2008/2012 >SQL Server Configuration Manager. 3. Select SQL Server Network Configuration, then double-click Protocols for SQLEXPRESS. 4. Right-click TCP/IP and select Properties, then scroll down to IPAll and make sure (a) TCP Dynamic Ports is blank and (b) TCP Port is set to 1433.

Installation and Configuration Guide

12

GEMS Prerequisites

5. Click OK.

Push Notification Service (PNS) Prerequisites GEMS-PNS requires a database, and that you set up a Windows Service Account for GEMS in support of your Exchange environment.

Supported Exchange Versions In general, EWS push notifications are sent (or pushed) by the server to a client-side web service via a callback address. Push notifications are ideally suited for tightly coupled clients like Good Work and other GEMSsupported apps to which the server has reliable access and the client is IP addressable. When GEMS-PNS is configured, EWS events are sent asynchronously from the mailbox server to the client. The GEMS version(s) listed in the following table are compatible with the Microsoft Exchange versions indicated. GEMS Version

Exchange Version

Supported

2.0 (in-cloud and on-premise) Exchange 2007 Exchange 2010 SP 2 RU 4

No +1

Yes

Exchange 2013+/2016

Yes

Microsoft O365

Yes

Hosted Exchange* (Exchange 2010 SP 1+)

Yes

1Plus sign indicates support for subsequent service packs and updates to the core version.

Installation and Configuration Guide

13

GEMS Prerequisites

GEMS Version

Exchange Version

1.5 (in-cloud and on-premise) Exchange 2007

Supported No

Exchange 2010 SP 2 RU 4 +

Yes

Exchange 2013+/2016

Yes

Microsoft O365

Yes

Hosted Exchange* (Exchange 2010 SP 1+)

Yes

1.4 (in-cloud and on-premise) Exchange 2007

No

Exchange 2010 SP 2 RU 4 +

Yes

Exchange 2013+/2016

Yes

Microsoft O365

Yes

Hosted Exchange* (Exchange 2010 SP 1+)

Yes

1.3 (in-cloud and on-premise) Exchange 2007

No

Exchange 2010 SP 1+

Yes

Exchange 2013+/2016

Yes

Microsoft O365

Yes

Hosted Exchange* (Exchange 2010 SP 1+)

Yes

1.2 (in-cloud and on-premise) Exchange 2007

No

Exchange 2010 SP 1+

Yes

Exchange 2013+/2016

Yes

Microsoft O365

Yes

Hosted Exchange* (Exchange 2010 SP 1+)

Yes * Certified Rackspace

If you are deploying GEMS in a mixed environment, wherein GEMS and Exchange are not co-located, there are additional requirements/prerequisites which may apply. These scenarios include: l

Cloud-based GEMS ð On-Premise Exchange a. You must expose EWS and Autodiscover from your on-premise Exchange to the Internet on port 443. b. Both Basic Authentication and Windows Authentication are supported for EWS and Autodiscover.

l

On-Premise GEMS ð Cloud-based Exchange a. You must expose EWS and Autodiscover from Cloud-based Exchange to On-Premise GEMS on port 443. b. Although both Basic Authentication and Windows Authentication are supported by GEMS, be advised that certain cloud vendors—for instance, O365 and Rackspace—only support Basic Authentication. Please check with your specific cloud vendor for details.

Installation and Configuration Guide

14

GEMS Prerequisites

l

On-Premise GEMS ð On-Premise and Cloud-based Exchange (i.e., Hybrid Exchange setup) a. You must expose EWS and Autodiscover from Cloud-based Exchange to On-Premise GEMS on port 443. b. Although both Basic Authentication and Windows Authentication are supported by GEMS, be advised that certain cloud vendors—for instance, O365 and Rackspace—only support Basic Authentication. Please check with your specific cloud vendor for details. c. A GoodAdmin mailbox must first be created on premise and then migrated to the cloud d. The GoodAdmin account must have Impersonation rights on both the On-Premise and O365 Exchange systems. For details, see KB4509.

For additional information on configuring EWS and Autodiscover for external access, refer to the pertinent Microsoft articles on TechNet: l

Configuring the Autodiscover Service for Internet Access

l

Configuring EWS for External Access

EWS Proxy Support Simply put, Exchange Web Services (EWS) lets client applications communicate with the Exchange server using SOAP messages sent by HTTP. Proxying occurs when a client access server (CAS) role sends traffic to another CAS role—two common situations being: l

CAS to CAS communication between two AD sites

l

CAS to CAS communication between Exchange 2010 and 2007 or 2003

More to the point, the following CAS protocols/services are proxy enabled: l

Exchange Web Services (EWS) and the availability service (part of EWS)

l

Exchange ActiveSync (EAS)

l

Outlook Web App (OWA) and Exchange Control Panel (ECP)

l

POP3 / IMAP

Proxy support is available for the GEMS versions indicated in the following implementations as defined below: GEMS Versions

Remote Endpoint

1.1

Proxy Support Transparent

Anonymous

Basic

NTLM

NOC

Yes

Yes

Yes

No

1.2, 1.3, 1.4, 1.5, 2.0

NOC

Yes

Yes

Yes

Yes

1.1, 1.2, 1.3, 1.4, 1.5, 2.0

Remote O365

Yes

No

No

No

1.1, 1.2, 1.3, 1.4, 1.5, 2.0

On-prem Exchange n/a

n/a

n/a

n/a

Proxy Support GEMS Versions

Remote Endpoint

Installation and Configuration Guide

Transparent

Anonymous

Basic

NTLM

15

GEMS Prerequisites

Proxy Support 1.1

NOC

Yes

Yes

Yes

No

1.2, 1.3, 1.4, 1.5, 2.0 NOC

Yes

Yes

Yes

Yes

1.1, 1.2, 1.3, 1.4, 1.5, Remote O365

Yes

No

No

No

n/a

n/a

n/a

n/a

2.0 1.1, 1.2, 1.3, 1.4, 1.5, On-prem Exchange 2.0

l

Transparent – also known as an intercepting proxy, inline proxy, or forced proxy, it intercepts normal communication at the network layer without requiring any special client configuration. GEMS doesn't need to be aware of the existence of a transparent proxy, which is normally located between the client and the Internet, with the proxy performing some of the functions of a gateway or router.

l

Anonymous – also known as an anonymizer, attempts to make activity on the Internet untraceable by acting as an intermediary and privacy shield between the client and the rest of the Internet. It accesses the Internet on the user's behalf, protecting personal information by hiding the client computer's identifying information.

l

Basic – is based on the model that a client must authenticate itself with a user name and password for each realm. The server services the request if it is resent with an Authorization header that includes a valid user name and password.

l

NTLM – challenges users who request content for proof of their credentials. The proxy then sends the proof of the user's credentials directly to the Windows domain controller to be validated. If the credentials are valid, the proxy serves the requested content and stores the credentials in the NTLM cache for future use. If the credentials are not valid, the proxy sends an authentication failed message to the user.

EWS Namespace Configuration If you have Exchange servers deployed in multiple Active Directory sites, a unique internal EWS URL must be configured for each site in order for GEMS Push Notifications to work properly. For example, assume there are two Active Directory sites and each site has two CAS servers, such that: Site 1: cas1, cas2 Site 2: cas3, cas4 In which case, at least two unique internal EWS URLs are needed—one for Site 1 and one for Site 2—so that the URLs look something like the following: Site1: https://site1cas.domain.com/EWS/Exchange.asmx Site2: https://site2cas.domain.com/EWS/Exchange.asmx It is also valid to configure a unique internal EWS URL for each CAS server.

Installation and Configuration Guide

16

GEMS Prerequisites

Before modifying the internal EWS URL for your CAS servers, however, first check which AD site the CAS servers are in and what the current internal EWS URL is set toby running the following from a CMD prompt on the Exchange server: nltest /dsgetdc:mydomain.com

The “DC Site Name” output parameter indicates the AD site. For more information on how to use the NLTEST command, please see KB19285. For information on how to check the internal EWS URL on a CAS server, see KB19280.

Create an Exchange Mailbox for the Service Account Using the Exchange Management Console or Exchange shell, create a mailbox for the GoodAdmin service account. If you are not familiar with how to create a mailbox on Exchange, please refer to the respective Microsoft Exchange resource for additional details and tutorials: l

Exchange Server 2010

l

Exchange Server 2013

Grant Application Impersonation Permission to the Service Account In order for the GEMS Push Notification service to monitor mailboxes for updates, the GEMS Push Notification service account (GoodAdmin), must have impersonation permissions. Execute the following Exchange Shell command to apply Application Impersonation permissions to the GoodAdmin service account: New-ManagementRoleAssignment -Name:GoodAppImpersonation -Role:ApplicationImpersonation -User:GoodAdmin

Important: Do not omit this step. For more information on how to restrict Application Impersonation rights to specific users, organizational units, or security groups, please see the MSDN article "How to: Configure impersonation."

Set Authentication for the EWS Protocol The GEMS Push Notification service supports Basic, NTLM and Windows Authentication when connecting with Exchange via EWS. Basic authentication is turned off by default on the Exchange server. Optionally, if Basic authentication is in fact desired, the command that follows can be used to update Exchange to use Basic authentication for EWS connectivity. Regardless of authentication method used on Exchange for EWS, however, no extra configuration is necessary for GEMS. Execute the following Exchange Shell command to configure Basic authentication for the EWS protocol on Exchange: Set-WebServicesVirtualDirectory -Identity "Contoso\EWS(Default Web Site)" -BasicAuthentication $true

Installation and Configuration Guide

17

GEMS Prerequisites

Note: Replace "Contoso\EWS (Default Web Site)" highlighted above in yellow with the proper identity for the EWS virtual directory. Be sure to enclose the string in quotes.

Set Up Exchange Autodiscover Ensure that your Exchange Autodiscover is setup correctly. This is very important! The Autodiscover feature in Exchange is often overlooked during setup but is an important factor in ensuring smooth day to day running of your Exchange environment. Its main function is to provide the mail client with all the configuration options it needs, sharing only the user's email address and password. This is particularly useful for remote users and smartphone users, who no longer have to enter advanced settings like server names and domains. It is also vital for the correct functioning of features such as Out Of Office and the Offline Address Book in Outlook. Use EWSEditor to test if there are any doubts. Note: Please reference KB5558 for additional details on using EWSEditor. Please see also "Exchange Autodiscover" by Jaap Wesselius (2010) for more helpful information on Exchange Autodiscover.

PNS Database Requirements You will need to create a (blank) SQL database for GEMS-PNS. The recommended name for this database is "GEMSDB." Important: Make sure the Collate property is set to CI (case insensitive). This is the default collation setting when you create a new database. If you are upgrading an existing database, you will want to check the collation setting to be sure.

Installation and Configuration Guide

18

GEMS Prerequisites

To check the case sensitivity of the GEMS PNS database, run this SQL query: SELECT DATABASEPROPERTYEX('dbname', 'Collation') Replace dbname with the name of your GEMS PNS database (i.e., GEMS-DB, then check the return value. If the value is: l

‘SQL_Latin1_General_CP1_CI_AS’, the database is case insensitive

l

‘SQL_Latin1_General_CP1_CS_AS’, the database is case sensitive.

To change the GEMS PNS case type to insensitive, use the following command: alter database [dbname] collate SQL_Latin1_General_CP1_CI_AS During installation, you will be prompted to specify the database server and SQL instance. When this information is entered, the GEMS installer will automatically create the schema required by GEMS PNS.

Connect Prerequisites for Lync (Note that the prerequisites discussed here do not apply to Cisco Jabber, when Jabber is selected during GEMS server installation for use with Good Connect.)

Installation and Configuration Guide

19

GEMS Prerequisites

Among the most important prerequisites for the Connect IM service is the availability of an established Microsoft Lync environment. These requirements comprise: l

MS Lync 2010 Requirements

l

MS Lync 2013 Requirements

l

Database Requirements

l

Preparing the Lync Topology for GEMS-Connect

l

SSL Certificate Requirements for Lync

l

Global Catalog for GEMS Connect and/or GEMS Presence

Microsoft Lync Server Requirements Antivirus software should be OFF for computers running GEMS with Connect-Presence. The respective GEMS prerequisites for Lync 2010 and Lync 2013 are included in the following topics: l

Microsoft Lync 2010 Requirements

l

Microsoft Lync 2013 Requirements

Note: Even if you're not using Lync, however, for planned deployments of GEMS-PNS running on Windows 2008 R2, you will need to install .NET Framework 4.5.

Microsoft Lync 2010 Requirements If you have deployed or are deploying Microsoft Lync 2010, the following components are required on the GEMS machine to properly support Lync connectivity and operations. Important: For GEMS support of Lync 2010, .NET Framework 3.5 SP1 and .NET Framework 4.5 must both be installed. Windows Management Framework 3.0/PowerShell 3.0 Built on the Microsoft .NET Framework, Windows PowerShell 3.0 is a command-line shell and scripting language designed for system admin and automation. Windows Server 2012 comes with PowerShell 3.0 already installed. Enable the Windows PowerShell 3.0 feature using Windows Server Manager. If you are using Windows 2008 R2 SP1, however, you must install Windows Management Framework 3.0, which includes Windows PowerShell 3.0. To install Windows Management Framework 3.0: 1. Go to Windows Management Framework 3.0. 2. Review the information on the web page, then click Download. 3. Select Windows6.1-KB2506143-x64.msu and click Next. 4. Close all Windows PowerShell windows.

Installation and Configuration Guide

20

GEMS Prerequisites

5. Uninstall any other version of Windows Management Framework 3.0. 6. Run the Windows6.1-KB2506143-x64.msu executable. 7. Open Windows PowerShell (x86) and run the following command to enable execution of remote-signed scripts: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

If you need to troubleshoot the installation, refer to the WMF 3.0 Release Notes. For more complete information about Windows Management Framework 3.0 and Windows PowerShell 3.0, visit the following Microsoft resources: l

Windows PowerShell Web site

l

Windows PowerShell Online Help

l

Windows PowerShell Blog

l

Windows PowerShell Software Development Kit (SDK)

l

Windows Management Framework 3.0 Compatibility Update

.NET Framework 3.5 SP1 Microsoft .NET Framework 3.5 SP1 is a cumulative update containing many new features that incrementally build upon .NET Framework 2.0, 3.0, 3.5, and includes .NET Framework 2.0 service pack 2 and .NET Framework 3.0 service pack 2 cumulative updates. Windows Server 2008 R2 comes with .NET Framework 3.5 SP1 already installed. Enable the .NET 3.5 Framework feature using Windows Server Manager. If you are using Windows Server 2008 SP2, however, you must install .NET Framework 3.5 SP1. Always make sure you have the latest service pack and critical updates for the version of Windows Server running on your machine. To look for recent Windows Server 2008 updates: Click the Start button, click All Programs, and then click Windows Update.

To install Microsoft .NET Framework 3.5 SP1: 1. Go to Microsoft .NET Framework 3.5 Service Pack 1 (Full Package). 2. Review the information on the web page, then click Download near the top of the page.

Installation and Configuration Guide

21

GEMS Prerequisites

3. When the download is complete, click Finish. If you prefer to download the bootstrapper, rather than the full package, go to .NET Framework 3.5 Service Pack 1 (Bootstrapper). For additional information about .NET Framework 3.5 SP1, visit the following Microsoft resources: l

.NET Framework 3.0 SP1 KB Article

l

.NET Framework 3.5 SP1 Update

.NET Framework 4.5 Microsoft .NET Framework 4.5 is a highly compatible, in-place update to .NET Framework 4. It includes significant language and framework enhancements, the blending of control flow in synchronous code, a responsive UI, and web app scalability. .NET Framework 4.5 adds substantial improvements to other functional areas such as ASP.NET, Managed Extensibility Framework, Windows Communication Foundation, Windows Workflow Foundation, and Windows Identity Foundation, in addition to delivering better performance, reliability, and security. Windows Server 2012 comes with .NET Framework 4.5 already installed. Enable the .NET 4.5 Framework feature using Windows Server Manager. If you are using Windows Server 2008 R2, however, you must install .NET Framework 4.5. Always make sure you have the latest service pack and critical updates for the version of Windows Server running on your machine. To look for recent Windows Server 2008 R2 updates: Click the Start button, click All Programs, and then click Windows Update.

To install Microsoft .NET Framework 4.5: 1. Go to the Microsoft .NET Framework 4.5. 2. Review the information on the web page, then click Download near the top of the page. 3. To install the software immediately, click Run. 4. To install the software later, click Save. Then, when you actually do the install, make sure the server machine is connected to the Internet. For additional information about .NET Framework 4.5, visit the following Microsoft resources:

Installation and Configuration Guide

22

GEMS Prerequisites

l

.NET Framework Developer Center

l

.NET Framework 4.5 Language Pack

64-bit UCMA 3.0 Runtime Microsoft’s Unified Communications Managed API (UCMA) 3.0 is a managed-code platform which developers use to build applications that provide access to and control over Microsoft Enhanced Presence information, instant messaging, telephone and video calls, and audio/video conferencing. Note: You must have elevated permissions to install UCMA 3.0 Runtime. A reboot is required to install and enable Windows Media Format after UCMA 3.0 Runtime setup is finished. To install the UCMA 3.0 Runtime: 1. Contact Microsoft for the runtime download. 2. Launch UcmaRuntimeSetup.exe from the download and accept the End-User License Agreement (EULA). The setup wizard will install all the necessary components. 3. Follow the onscreen instructions to complete the installation. The setup program installs English versions of the Speech Recognition and Text-to-Speech engines. The final screen of the installer provides a link that can be used to download additional engines for other languages. Included in the setup is an additional installer called OCSCore.msi that is also required for GEMS. Find OCSCore.msi by navigating to the following directory: C:\ProgramData\Microsoft\Lync Server\Deployment\cache\4.0.7577.0\Setup\OCSCore.msi By default, the ProgramData folder is hidden, so it might not appear in Windows Explorer. You can change this (unhide it) in folder settings. 4. Launch OCSCore.msi and use the default settings in the wizard. To ensure that you have the latest cumulative update from Microsoft and thereby avoid performance issues: 1. Open Windows Update in Control Panel. 2. In addition to installing any listed updates for Windows, click Find out more next to Get updates for other Microsoft products.

Installation and Configuration Guide

23

GEMS Prerequisites

3. Shortly, you'll receive the cumulative list of update patches. 4. Be sure to select Lync Server 2010 Core Components along with any UCMA 3.0 updates.

5. Verify that the latest update is now installed in Programs and Features. The required Lync Server 2010, Core Components version is 4.0.7577.230.

Microsoft Lync 2013 Requirements If you have deployed or are deploying Microsoft Lync 2013, the following components are required on the GEMS machine to properly support Lync connectivity and operations: Windows Management Framework 3.0/PowerShell 3.0 Built on the Microsoft .NET Framework, Windows PowerShell 3.0 is a command-line shell and scripting language designed for system admin and automation. Windows Server 2012 comes with PowerShell 3.0 already installed. Enable the Windows PowerShell 3.0 feature using Windows Server Manager. If you are using Windows 2008 R2 SP1, however, you must install Windows Management Framework 3.0, which includes Windows PowerShell 3.0.

Installation and Configuration Guide

24

GEMS Prerequisites

To install Windows Management Framework 3.0: 1. Go to Windows Management Framework 3.0. 2. Review the information on the web page, then click Download. 3. Select Windows6.1-KB2506143-x64.msu and click Next. 4. Close all Windows PowerShell windows. 5. Uninstall any other version of Windows Management Framework 3.0. 6. Run the Windows6.1-KB2506143-x64.msu executable. 7. Open Windows PowerShell (x86) and run the following command to enable execution of remote-signed scripts: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

If you need to troubleshoot the installation, refer to the WMF 3.0 Release Notes. For more complete information about Windows Management Framework 3.0 and Windows PowerShell 3.0, visit the following Microsoft resources: l

Windows PowerShell Web site

l

Windows PowerShell Online Help

l

Windows PowerShell Blog

l

Windows PowerShell Software Development Kit (SDK)

l

Windows Management Framework 3.0 Compatibility Update

.NET Framework 4.5 Microsoft .NET Framework 4.5 is a highly compatible, in-place update to .NET Framework 4. It includes significant language and framework enhancements, the blending of control flow in synchronous code, a responsive UI, and web app scalability. .NET Framework 4.5 adds substantial improvements to other functional areas such as ASP.NET, Managed Extensibility Framework, Windows Communication Foundation, Windows Workflow Foundation, and Windows Identity Foundation, in addition to delivering better performance, reliability, and security. Windows Server 2012 comes with .NET Framework 4.5 already installed. Enable the .NET 4.5 Framework feature using Windows Server Manager. If you are using Windows Server 2008 R2, however, you must install .NET Framework 4.5. Always make sure you have the latest service pack and critical updates for the version of Windows Server running on your machine. To look for recent Windows Server 2008 R2 updates: Click the Start button, click All Programs, and then click Windows Update.

Installation and Configuration Guide

25

GEMS Prerequisites

To install Microsoft .NET Framework 4.5: 1. Go to the Microsoft .NET Framework 4.5. 2. Review the information on the web page, then click Download near the top of the page. 3. To install the software immediately, click Run. 4. To install the software later, click Save. Then, when you actually do the install, make sure the server machine is connected to the Internet. For additional information about .NET Framework 4.5, visit the following Microsoft resources: l

.NET Framework Developer Center

l

.NET Framework 4.5 Language Pack

64-bit UCMA 4.0 Runtime Microsoft’s Unified Communications Managed API (UCMA) 4.0 is a managed-code platform which developers use to build applications that provide access to and control over Microsoft Enhanced Presence information, instant messaging, telephone and video calls, and audio/video conferencing. Note: You must have elevated permissions to install UCMA 4.0 Runtime. A reboot is required to install and enable Windows Media Format after UCMA 4.0 Runtime setup is finished. UCMA 4.0 requires Desktop Experience on Windows Server 2008 R2 SP1. Enable this feature using Windows Server Manager. UCMA 4.0 requires Media Foundation on Windows Server 2012. Enable this feature using Windows Server Manager. To install the UCMA 4.0 Runtime: 1. Go to Unified Communications Managed API 4.0 Runtime in the Microsoft Download Center and click Download. 2. Launch UcmaRuntimeSetup.exe and accept the End-User License Agreement (EULA). The setup wizard will install all the necessary components. 3. Follow the onscreen instructions to complete the installation.

Installation and Configuration Guide

26

GEMS Prerequisites

The setup program installs English versions of the Speech Recognition and Text-to-Speech engines. The final screen of the installer provides a link that can be used to download additional engines for other languages. Included in the setup is an additional installer called OCSCore.msi that is also required for GEMS. Find OCSCore.msi by navigating to the following directory: C:\ProgramData\Microsoft\Lync Server\Deployment\cache\5.0.8308.0\Setup\OCSCore.msi By default, the ProgramData folder is hidden, so it might not appear in Windows Explorer. You can change this (unhide it) in folder settings. 4. Launch OCSCore.msi and use the default settings in the wizard.

Preparing the Lync Topology for GEMS The Connect service and Lync Presence Provider (LPP) are Microsoft Lync trusted-UCMA applications. In order to establish trust with Microsoft Lync, you must first use the Lync Management Shell to complete the following: l

Create a trusted application pool.

l

Designate trusted applications for the use of the GEMS computer.

l

Create a trusted-computer entry for every GEMS in the environment.

l

Publish these changes to the Lync Topology.

l

Create a Trusted Endpoint for the GEMS-Presence Service.

Important: You must be a member of the RTCUniversalServerAdmins and Domain Admins security groups to provision and publish new applications in the Microsoft Lync Topology. If you have a designated Lync administrator within your organization, that person should perform all subsequent preparation steps for this procedure. You must complete the application provisioning process described in the following instructions: l

Preparing to install GEMS for the first time

l

Preparing subsequent GEMS machines

After updating the Lync topology, the Lync administrator must delegate RTCUniversalReadOnlyAdmins permission to the GEMS service account in order for the GEMS Dashboard to access the provisioning information during the GEMS configuration process.

Preparing the Initial GEMS Machine Preparations vary if the Lync Topology has already been set up for GEMS. Hence, the preparation instructions included here apply only if you are installing GEMS for the first time. If GEMS is already installed in your environment, see Preparing Additional GEMS Machines. Otherwise, when you create a trusted application pool for the installation of GEMS, you also create the trustedcomputer entry. Subsequent installations of GEMS machines do not require a new trusted application pool or

Installation and Configuration Guide

27

GEMS Prerequisites

designated trusted applications. Because these are merely added to the existing trusted application pool, you only need to create trusted application computers. To prepare your topology, you must: 1. Create a Trusted Application Pool. 2. Create a Trusted Application for GEMS Connect. 3. Publish changes to the Lync Topology. To accomplish these tasks, first launch the Lync Management Shell by selecting: Start > All Programs > Microsoft Lync Server [2010 or 2013] > Lync Management Shell. Next, enter the following commands (highlighted areas represent recommended values): PS> Get-CsSite

If your organization has more than one site in its topology, look up the appropriate siteId number and the corresponding registrar value and jot them down. You will need this information to create the application pool. PS> New-CsTrustedApplicationPool -Force -Identity "pool_gems.mycompany.com" -Registrar -RequiresReplication $false -Site -ComputerFqdn "FQDN of GEMS machine" PS> New-CsTrustedApplication -Force -ApplicationId "appid_connect.mycompany.com" -TrustedApplicationPoolFqdn "pool_gems.mycompany.com" -Port 49555 PS> New-CsTrustedApplication -Force -ApplicationId "appid_presence.mycompany.com" -TrustedApplicationPoolFqdn "pool_gems.mycompany.com" -Port 49777

Create the second application (appid_presence.mycompany.com) only if you are deploying the GEMS Presence service. PS> New-CsTrustedApplicationEndpoint -ApplicationId "appid_presence.mycompany.com" -TrustedApplicationPoolFqdn "pool_gems.mycompany.com" -SipAddress "sip:[email protected]"

Create an application endpoint only if you are deploying the GEMS Presence service. PS> Enable-CsTopology

This completes topology preparations for your initial GEMS machine. If you are deploying additional GEMS machines, see Prepping Additional GEMS Machines. If you are installing only one GEMS machine, proceed to Installing GEMS.

Preparing Additional GEMS Machines The instructions presented here apply only if you have already installed at least one GEMS. If you are installing GEMS for the first time, refer to the instructions in Preparing the Initial GEMS Machine Prepare your Lync Topology for additional GEMS machines by launching the Lync Management Shell via Start > All Programs > Microsoft Lync Server [2010 or 2013] > Lync Management Shell.

Installation and Configuration Guide

28

GEMS Prerequisites

Next, you need to create a trusted computer for the GEMS trusted application pool. To do so, enter the following command line: PS> New-CsTrustedApplicationComputer -Identity "" -Pool ""

If this GEMS host will be running the Presence service, you must also create an application endpoint. This is done with the following commands: PS> New-CsTrustedApplicationEndpoint -ApplicationId "appid_presence.mycompany.com" -TrustedApplicationPoolFqdn "pool_gems.mycompany.com" -SipAddress "sip:[email protected]" PS> Enable-CsTopology

With the Lync topology now prepped for the new GEMS, you may proceed to Installing GEMS after reviewing the section on creating/acquiring a valid SSL certificate.

Creating an Additional Trusted Application Pool One GEMS-Connect server can be associated with only one Trusted Application Pool. In a high availability or disaster recovery scenario, it is recommended that you create an additional trusted application pool in your Front-End HA/DR pool for your GEMS-Connect HA/DR instances. The steps for creating an additional trusted application pool are exactly the same as creating your first trusted application pool for GEMS-Connect with the exception that trusted application pool names must be unique. Therefore, if you named your first trusted application pool "pool1_gems.mycompany.com", then your second trusted application pool name must be different—i.e., "pool2_gems.mycompany.com".

SSL Certificate Requirements for Lync and Presence If your enterprise doesn’t already have one—or one designated for use by GEMS—you must obtain and install a digital certificate. Your enterprise can sign its own digital certificates, acting as its own certificate authority (CA), or you can submit a certificate request to a well-known, third-party CA. Although you can preinstall the root authority for your own CA on each user’s device, to forestall the continuous tedium and management, especially as new employees come and go, it makes sense to get an independent CA-validated certificate.

Mutual TLS (MTLS) Certificates Connect and LPP connections to Lync rely on mutual TLS (MTLS1) for mutual authentication. On an MTLS connection, the server originating a message and the server receiving it exchange certificates from a mutually trusted CA. The certificates prove the identity of each server to the other. In Lync Server 2010 deployments, certificates issued by the enterprise CA that are still in their validity period and not revoked by the issuing CA are automatically considered valid by all internal clients and servers because all members of an Active Directory domain trust the Enterprise CA in that domain. In federated scenarios, the issuing CA must be trusted by both federated partners. Each partner can use a different CA, if desired, so long as

1For more on TLS and MTLS for Lync Server 2010, see http://technet.microsoft.com/en-us/library/gg195752(v=ocs.14).aspx.

Installation and Configuration Guide

29

GEMS Prerequisites

that CA is also trusted by the other partner. This trust is most easily accomplished by the Edge Servers having the partner’s root CA certificate in their trusted root CAs, or by use of a third-party CA that is trusted by both parties. Hence, GEMS must form a mutual trust relationship for MTLS communications supporting its network server environment. Mutual trust requires a valid SSL certificate that meets the following criteria: l

The private certificate issued for GEMS by a trusted CA must be stored in the GEMS machine’s Console Root\Certificates local_host_name\Personal\Certificate folder.

l

The GEMS computer’s private certificate and the Lync Server’s internal computer certificate must both be trusted by root certificates in GEMS’s Console Root\Certificate local_host_name\Trusted Root Certification Authorities\Certificates folder.

l

Intermediate certificates for both the GEMS private certificate and the Lync Server’s internal computer certificate must be located in the GEMS Console Root\Certificates local_host_name\Trusted Root Certification Authorities\Certificates folder (similar to the one pictured next).

Important: The account used to run GEMS must have read access to the certificate store and the private key. You can assign read rights to the private key by right-clicking on the certificate. l

The Subject Name (SN) of the certificate must contain the Common Name (CN) for GEMS’s fully qualified domain name (FQDN), such that CN=server.subdomain.domain.tld.

l

The Subject Alternative Name (SAN) must contain the DNS for the trusted pool for the GEMS machine, as well as the GEMS machine FQDN. SANs let you protect multiple host names with a single SSL certificate.

l

The certificate must be signed by a CA that is mutually trusted by both the Lync Server and GEMS.

For more complete information regarding Microsoft Lync SSL certificate requirements, visit the MSDN Office Dev Center’s Lync page. For instructions on creating a certificate for GEMS, see Creating and Adding the GEMS SSL Certificate.

Installation and Configuration Guide

30

GEMS Prerequisites

Creating and Adding the GEMS SSL Certificate for Lync These certificate request procedures are based on a Windows Server 2012 certificate authority but will also work for earlier versions of Windows Server. Please make sure to execute the steps that follow on the Certificate Authority server. If you are deploying the Connect Service only, skip to Requesting a GEMS Certificate from a Local AD Certificate Authority. However, if you are deploying the GEMS Presence service, you will need a Subject Alternative Name (SAN) certificate. A SAN SSL Certificate, also known as Unified Communications SSL Certificate (UCC SSL), is mainly used by Microsoft Exchange 2007 (or newer) for Unified Messaging. This certificate allows multiple server or domain names to use the same secure SSL certificate, whereas a normal SSL Certificate protects only one FQDN. In a SAN certificate, several alternatives of common names can be placed in the Alternative Name field. Note: Any existing and appropriate SAN certificate, for example your Exchange SAN certificate, can be used to create a template, or you can create a new template from any existing template, which can then be used to create and configure the required certificate for a given service. The name of the template is often the only way to distinguish its purpose. The certificate common name (CN), friendly names, and other properties must be unique. This is important when deploying the final name of the issued certificate, which should always match the designated service name. For a quick primer on generating SSL certificates with subject alternative names, see TechNet's "How to generate a certificate with subject alternative names (SAN)." If you are configuring only for Connect (without Presence), skip to Requesting a GEMS Certificate from a Local AD Certificate Authority. Otherwise, continue with the guidance that follows for creating a SAN certificate template. Creating a SAN Certificate Template To create a SAN certificate template: 1. Open a CMD window and type MMC to open the MMC window. 2. Click File> Add/Remove Snap-in and then click Add > Certificate Templates. 3. In the center panel, right-click Computer, then Duplicate Template.

Installation and Configuration Guide

31

GEMS Prerequisites

4. In the General tab, change the name to Computer – SAN Cert, or something like it. Just be sure to make note of it for future reference.

5. In the Subject Name tab, select “Supply in the request”. 6. Click Apply, then click OK. To add the SAN Certificate Template to the CA In order for requesters to see the new template, it must first be added to the CA using the following steps: 1. Open the Certificate Authority utility and right-click on Certificate Templates. 2. Select New > Certificate Template to Issue.

3. Select the template that was created above in Creating a SAN Certificate Template.

Requesting a GEMS Certificate from a Local AD Certificate Authority Use the following procedure if you are requesting a certificate for the GEMS machine from a local AD certificate authority.

Installation and Configuration Guide

32

GEMS Prerequisites

On the GEMS machine: 1. Open a CMD window and type mmc. 2. Click File > Add/Remove Snap-In. 3. Select Add Certificate > Computer Account > Local computer. 4. Right-click Personal, then select Certificate (or Personal) > All Tasks > Request New Certificate.

5. Click Certificate Enrollment, then click Next and Next again.

6. If you are only deploying the GEMS Connect Service, choose a Computer certificate request template. Otherwise, choose the Computer-SAN Cert certificate request template. If there is no Computer SAN certificate request template, refer to Creating a SAN Certificate Template above.

Installation and Configuration Guide

33

GEMS Prerequisites

7. If you chose a regular Computer certificate request, click Enroll and you’re done. Otherwise, you will need to supply both the Common Name (CN) and the Subject Alternative Name (SAN). 8. If you choose a Computer-SAN Cert, you will need to supply both the Common Name (CN) and the Subject Alternative Name (SAN). Click on the More information is required... link to enter this information. 9. In the Certificate Properties popup: a. Under the Subject tab, change the Subject name Type to Common Name. b. For Value, enter the FQDN of the GEMS machine. c. Click Add. d. Change the Alternative name Type to DNS. e. Add two Values, one with the FQDN of the GEMS machine and the other with the FQDN of the GEMS Lync pool.

Installation and Configuration Guide

34

GEMS Prerequisites

f. Click Apply, then click OK. g. Click Enroll. After creating the certificate, make sure the Subject Name and Subject Alternative Name are correct. To do this, simply double-click on the certificate, then click the Details tab. Correctly reflecting the name you gave it or chose, the Subject Name should look something like this:

Installation and Configuration Guide

35

GEMS Prerequisites

And the Subject Alternative Name should look like this:

10. Right-click the certificate, then select All Tasks > Manage Private Keys. 11. Under the Security tab, add the service account and grant it read access to the certificate.

Database Requirements You will need to create a (blank) SQL database for GEMS-Connect. The recommended name for this database is "GEMS-CONNECT."

Installation and Configuration Guide

36

GEMS Prerequisites

During installation, you will be prompted to specify the database server and SQL instance. When this information is entered, the GEMS installer will automatically create the schema required by GEMS Connect.

Lync Presence Prerequisites Essentially, for Lync, the Presence service has the same predeployment requirements as the Connect service. The Presence service, however, does not require an SQL database. Please refer to the complete list of Connect Prerequisites. If you wish to configure GEMS Presence to use the Global Catalog for GEMS Connect and/or GEMS Presence , you will need to perform the following. Note that Good Presence is supported in Lync and Jabber environments. On the GEMS Presence host, edit the following configuration parameters in the LyncPresenceProviderService.exe.config file installed by default in the C:\Program Files\Good Technology\Good Enterprise Mobility Server\Good Presence folder: If the GEMS Presence service is already running, please restart the service for this change to take effect.

Jabber Server Requirements for Presence Antivirus software should be OFF for computers running GEMS with Connect-Presence.

Create an Application User This application user is a logical entity that represents a third-party application that can log into Cisco Unified CM IM and Presence. This admin user has the ability to log end users into Log into Cisco Unified CM IM and Presence Administration. To create this user do as following 1. Log into Cisco Unified CM IM and Presence Administration. 2. Navigate to User Management > Application User. 3. Select Add New button to create a new application user.

Installation and Configuration Guide

37

GEMS Prerequisites

4. Fill out User ID and Password.

5. Select the Add to Access Control Group button to pop up a List Access Control Groups window. 6. Select Admin-3rd Party API from the pop-up list and select Add Selected button to choose it.

7. Close and save.

Installation and Configuration Guide

38

GEMS Prerequisites

Create a Dummy User Use this dummy UDS user to log into Cisco Unified CM IM and Presence Administration as an end user and get presences of other LDAP end users. To create this user: 1. Log into Cisco Unified CM IM and Presence Administration. 2. Navigate to User Management > End User. 3. Select Add New button to create a new UDS end user. 4. Fill out User ID, Password, and Last name. 5. Enable this user for presence by selecting "Enable User for Unified CM IM and Presence (Configure IM and Presence in the associated UC Service Profile).

6. Close and save.

Certificates There are two required certificates: cup.der and tomcat.der. To get these certs: 1. Log into Cisco Unified CM IM and Presence Operating System Administration. 2. Navigate to Security > Certificate Management.

Installation and Configuration Guide

39

GEMS Prerequisites

3. Click Find. The list of certificates is displayed.

4. Click on the link cup.der and click Download. 5. Navigate back to the certificate list, then click on tomcat.der and click Download. 6. Import these certs into the Java keystore. (The import steps are the same as for Jabber Connect.)

Docs Service Prerequisites The Docs service requires its own SQL database like other GEMS services. And, while having many of the GEMS core requirements in common, it has additional dependencies not required by the other services. These include: l

Server Software and Operation System Requirements

l

Database Requirements

l

CMIS requirements

Server Software and Operating System Requirements In addition to core requirements for all GEMS services, the following prerequisites apply the Docs service:

Network Capabilities and Resources l

The GEMS host must be a domain member and have access to Active Directory

l

Network shares must be accessible from the server

l

SharePoint sites must be accessible from the server; supported SharePoint versions include:

l

o

2007/2010/2013

o

SharePoint Online

If KCD is not enabled, users using network shares must have Allow Logon Locally rights in the local security policy on the GEMS host.

Installation and Configuration Guide

40

GEMS Prerequisites

Database Requirements A blank SQL database is also required for a new installation of the GEMS-Docs Service in accordance with the supported SQL Server version specified under Core Requirements. The name of the database is arbitrary, but "GEMS-DOCS" is recommended. The installer will extend the schema during the installation process. If you are migrating an existing database from Good Share, see Appendix K.

CMIS Requirements Content Management Interoperability Services (CMIS) is an open standard that allows different content management systems to inter-operate over the Internet. The GEMS Docs service supports content management systems that support CMIS. Consult your vendor documentation to determine whether your system (such as Alfresco, Documentum, HP RM, IBM Filenet, etc.) is supported by CMIS and whether that support comes via AtomPub or Web Services. (If both are supported, we recommend using AtomPub.) You will need to know the binding URL for this support. For example, for Alfresco the CMIS support is via AtomPub and the binding URL is : http://ALFRESCOSERVER:PORT/alfresco/api/-default-/public/cmis/versions/1.0/atom. Note: Only Active Directory users are supported for CMIS. That is, the content management system must be hooked up to Active Directory for user authentication for GEMS Docs to support it.

Directory Lookup Service Prerequisites GEMS Directory Lookup requires a database, and that you set up a Windows Service Account for GEMS in support of your Exchange environment (see Supported Exchange Versions). In this regard, the prerequisites for this service are essentially identical to the Push Notification service, and include (see Note 1): l

Creating an Exchange Mailbox for the service account

l

Granting Application Impersonation permissions to the service account

l

Setting Authentication for the EWS protocol

l

Setting up Exchange Autodiscover

l

Setting up a SQL database

Note 1: Required unless already completed for PNS or another service, in which case the same service account Exchange environment settings should be used.

Follow-Me Service Prerequisites GEMS Follow-Me requires a database, and that you set up a Windows Service Account for GEMS in support of your Exchange environment (see Supported Exchange Versions). In this regard, the prerequisites for this service are essentially identical to the Push Notification service, and include):

Installation and Configuration Guide

41

Installing GEMS

l

Creating an Exchange Mailbox for the service account

l

Granting Application Impersonation permissions to the service account

l

Setting Authentication for the EWS protocol

l

Setting up Exchange Autodiscover

l

Setting up a SQL database

Note: Each of the above is required unless already completed for PNS or another service, in which case the same service account, Exchange environment settings, and EWS database can be shared.

Certificate Lookup Service Prerequisites GEMS Certificate Lookup requires a database, and that you set up a Windows Service Account for GEMS in support of your Exchange environment (see Supported Exchange Versions). In this regard, the prerequisites for this service are essentially identical to the Push Notification service, and include): l

Creating an Exchange Mailbox for the service account

l

Granting Application Impersonation permissions to the service account

l

Setting Authentication for the EWS protocol

l

Setting up Exchange Autodiscover

l

Setting up a SQL database

Note: Each of the above is required unless already completed for PNS or another service, in which case the same service account, Exchange environment settings, and EWS database can be shared.

Installing GEMS A successful GEMS installation hinges on all prerequisites for each service you are deploying being in place. These include, respectively: l

Core Prerequisites

l

PNS Prerequisites

l

Connect Prerequisites

l

Presence Prerequisites

l

Docs Prerequisites

l

Directory Lookup Prerequisites

l

Follow-Me Prerequisites

l

Certificate Lookup Prerequisites

It is strongly recommended that installation be done with the GEMS service account.

Installation and Configuration Guide

42

Installing GEMS

Important: Before proceeding, verify that you have created the blank databases specified for PNS, Connect, and Docs, respectively. Upon verifying that all prerequisites have been satisfied, download and unzip the GEMS installer package, then continue with the steps below.

Performing a Silent Install or Upgrade This release supports silent installation of the GEMS server, using the following command in the Command Prompt window: -i silent -f

A template response file GoodServerSetup.properties is provided, along with a silentInstall.bat file and the GEMS installer, in the installer zip file. The GoodServerSetup.properties file contains the variables and values of the inputs for each screen in the installer for fresh installation, along with instructions on how to edit the variables. The silentInstall.bat file is provided as a convenience to run the silent install command. You can enter Admin-user details, machine details , SQL server details, and other configuration specifics in this property file and then install the GEMS server in an unattended mode. Installation results are logged in the install log file folder (for example, C:\Users\alias\AppData\). This silent install feature also can be used to upgrade or repair/modify the server. A password can be specified as part of the command file.

Performing a GEMS Fresh Installation or Upgrade Follow the steps outlined below to install and configure a fresh GEMS installation: 1. Install all core GEMS prerequisites as outlined in the section titled Core Requirements. We require the Microsoft .Net 4.5 Framework. For more details regarding the installation of .Net 4.5, refer to the section titled .NET Framework 4.5. 2. If you are upgrading GEMS in a clustered environment, back up the GEMS cluster database before upgrading the GEMS servers. For upgrades to Version 2.2, refer to Upgrading to GEMS Version 2.2 Performing a Silent Install or Upgrade 3. To run the installation media, unpack the contents of the installation zip file and run GoodEnterpriseMobilityServerSetup..exe.

An introduction screen is displayed, for a fresh install or an upgrade or uninstall.

Installation and Configuration Guide

43

Installing GEMS

Installation and Configuration Guide

44

Installing GEMS

4. An introductory screen is displayed. Click Next.

5. Click on the “I accept the terms of the License Agreement” option to enable the “Next” button. Click Next. A “Select Services” screen is displayed. For a fresh install:

Installation and Configuration Guide

45

Installing GEMS

Installation and Configuration Guide

46

Installing GEMS

For an update:

Installation and Configuration Guide

47

Installing GEMS

6. With this new installer, you can select which GEMS services are to be installed. Check the desired services. If you are upgrading, Select Services shows the currently installed services. Uncheck a service to uninstall it. To add or modify a service after an upgrade, use the installer’s Modify/Repair option. If upgrading from version 1.5 or lower, the Connect options are available to upgrade from Microsoft Lync to Cisco Jabber. If the Connect or Docs database is not entered in the previous installation, the following message is shown for each missing database. If upgrading from version 2.0 or higher, the Connect service only shows the currently installed option. Changing Connect options is not allowed. To do so, use the installation media's Modify option to remove the service to be changed and then, in a separate operation, add the new service. No database was specified for service in previous installation. Please select the service if you want to upgrade it. For a fresh install, for Connect and Presence services using Microsoft Lync, the same “Microsoft Lync” option must be selected for both. Otherwise the following message will be displayed.

Installation and Configuration Guide

48

Installing GEMS

7. Click Next after dismissing any information screens. A prerequisites screen is displayed.

The Prerequisites for each service are listed in this table. The Next button will not be enabled unless all prerequisites display a green check. Unsatisfied prerequisites display a red X.

Installation and Configuration Guide

49

Installing GEMS

8. Click Next when the button is enabled. A Host Information screen is displayed. For a fresh install:

for an upgrade:

Installation and Configuration Guide

50

Installing GEMS

The current hostname and domain are displayed in the input fields. This information is used as the fully qualified domain name for the self-signed certificate. If upgrading and you want to keep the existing certificate, select the “Use Previously installed certificate”. If a different hostname or domain is entered, the following warning will be displayed.

Installation and Configuration Guide

51

Installing GEMS

9. Click Next after any information screens have been cleared. An installation location screen is displayed.

Installation and Configuration Guide

52

Installing GEMS

This screen is displayed only for Fresh and Upgrade installations. It will not be displayed for Modify or Repair installations. Specify a destination folder or accept the default. If an invalid drive letter is specified, the following message is displayed.

A similar error screen will be displayed if information is entered in an invalid format. 10. Click Next after any information screens have been cleared. A log location screen is displayed.

Installation and Configuration Guide

53

Installing GEMS

All GEMS logs will reside in the specified folder. This screen is only displayed for Fresh and Upgrade installations. It will not be displayed for Modify and Repair installations. Accept the default or enter a folder path. 11. Click Next. An Administrator information screen is displayed.

Installation and Configuration Guide

54

Installing GEMS

This screen is used to specify the “Log On As” account for “Good Technology Common Services” Windows service. Accept the default or enter your account information. If an incorrect login or password is entered, the following message is displayed.

12. Click Next after any information screens have been cleared. For upgrades, an AD User Credentials screen is displayed.

Installation and Configuration Guide

55

Installing GEMS

The Installer requires AD credentials to retrieve and preserve the configuration from the current GEMS installation. 13. Click Next when the screen is configured as desired. A Database Information screen for Core service is displayed.

Installation and Configuration Guide

56

Installing GEMS

You receive the Database Schema Upgrade Warning to back up the Core/Mail database if you have not already done so. Stop all GEMS nodes accessing this database if you have not alread done so. Refer to Upgrading to GEMS Version 2.2 for details. Enter connection information for the Good Enterprise Mobility Server Core service database. If Good Enterprise Mobility Server should be configured to use your Enterprise database, you can obtain connection information from your enterprise DBA. Enter the required information for the database and authentication type. There are separate screens in the Connect and Docs installers. Core and Mail share a database. The database information is validated by connecting to the database server and verifying that the database table exists. If the installer is unable to connect to the database or the database table does not exist, an error message is displayed.

Installation and Configuration Guide

57

Installing GEMS

Click Next after any information screens have been cleared. An Administrator Information screen for the Connect service is displayed.

Installation and Configuration Guide

58

Installing GEMS

This screen is used to specify the “Log On As” account for “Good Connect” Windows service. This screen is only displayed if the Connect service has been selected. 14. Click Next. A Database Information screen for the Connect service is displayed.

Installation and Configuration Guide

59

Installing GEMS

All input fields are similar to the Core Database Information screen. This screen is only displayed if the Connect service is selected. Specify authentication type, credentials, and connection type. If the database entered is same as Core/Mail database, the following message is displayed.

15. Click Next after any information screens have been cleared. An Administrator Information screen for the Presence service is displayed.

Installation and Configuration Guide

60

Installing GEMS

This screen is used to specify the “Log On As” account for “Good Presence” Windows service. This screen is only displayed if the Presence service is selected. Enter the appropriate login credentials. 16. Click Next. An Administrator Information screen for Connect service for Docs services is displayed.

Installation and Configuration Guide

61

Installing GEMS

This is the Database Information screen for Docs service. All input fields are similar to the Core Database Information screen. This screen is only displayed if the Docs service is selected. If no database name is entered, the following message is displayed.

17. Click Next after any information screens have been cleared. A Replace JCE Policy Files screen is displayed.

Installation and Configuration Guide

62

Installing GEMS

Select “Yes” to replace local_policy.jar and US_export_policy.jar in the \lib\security folder. The original files will be renamed by appending a “.orig” extension. This screen is displayed only for Fresh, Repair, and Upgrade installations. 18. Click Next. A Summary screen is displayed, showing the previously entered information.

Installation and Configuration Guide

63

Installing GEMS

Use the Previous button to back up and make any necessary corrections. 19. Click the “Install” button to start the installation. A progress screen is displayed.

Installation and Configuration Guide

64

Installing GEMS

Installation and Configuration Guide

65

Installing GEMS

Each selected service will run a sub-module installation sequentially.

Installation and Configuration Guide

66

Installing GEMS

Here, the Mail installer has successfully completed a fresh installation. This screen is displayed only if the Mail service is selected. Similar screens are displayed for each selected service, for fresh installs and upgrades. Good Enterprise Mobility Service needs to restart after the installation and configuration of GEMS core and selected services.

Installation and Configuration Guide

67

Installing GEMS

When the restart is complete, the following screen is displayed for upgrades and repairs:

Installation and Configuration Guide

68

Installing GEMS

Select Yes to use this server’s configuration, previously configured in the dashboard, as the master configuration for GEMS configuration synchronization between nodes in a GEMS cluster. If your installation includes only one node, select Yes. If you select No in an HA/cluster configuration, ensure that one node in the cluster has selected Yes. Once a node is installed with a Yes, any newer nodes will not require configuration via the dashboard. Note that the last node configured with a Yes will be used to populate the configuration in the database. 20. On the Install Complete dialog box, make sure that the Start GEMS services checkbox is selected. Click Done. If you clear the Start GEMS services checkbox, the GEMS installer stops the Good Technology Common Services. If a system restart is required for an upgrade, options at the bottom of the screen will allow you to specify an immediate restart or to defer the restart. Click the radio button labeled “Yes” if you want to restart or the radio button labeled “No” if don’t want to restart. Click on the “Done” button to launch the browser for the dashboard if not restarting. Note: If the GEMS Dashboard fails to launch automatically in your browser, open your browser and manually enter "https://localhost:8443/dashboard" in the address bar. HTTP access is allowed only from the localhost. Google's Chrome browser is recommended. 21. Login as a member of the local administrator group and you are taken to the GEMS Dashboard home page. Note: The Analytics service is a developer preview only and is not intended for production environments..

Installation and Configuration Guide

69

Installing GEMS

You're now ready to set your GEMS dashboard administrators based on Active Directory membership groups and then select a service to configure. The Mail service is required to run the Good Work mobile collaboration app. The Presence service furnishes the Lync Presence Provider (LPP) to Good Work and other Good Dynamics applications, while the Connect service provides both presence and instant messaging services on client devices provisioned with the Good Connect app (Lync only). The Docs service enables SharePoint and File Share access by Good Work clients. Analytics is an optional service currently in developer preview.

Upgrading to GEMS Version 2.2 In this release, the database schema has been updated to improve push notification scalability. For this reason, when upgrading in clustered environments, you will be required to halt all GEMS server services for the upgrade, providing downtime for the servers. Warn the end users as required before performing such an upgrade. You can use either of the following two options.

Upgrade steps using the installer You can use this option or Option Two. 1. Back up the GEMS cluster database before upgrading the GEMS servers. 2. Stop all GEMS server services except for the services of the server being upgraded first. 3. After the first server is upgraded, start the GEMS services on all the remaining servers. 4. Upgrade the remaining servers .

Installation and Configuration Guide

70

Installing GEMS

For environments with three or more servers You can use this option or Option One. To reduce server downtime, follow these steps: 1. Back up the GEMS cluster database before upgrading the GEMS servers. 2. Download the GoodEnterpriseMobilityServer.2.2.12.11.zip file and extract dbmanager-2.2.12-jar-withdependencies.jar from it. Copy the file to one of the GEMS servers onto a machine where Java is installed. 3. Stop all the servers in the cluster before running the tool. 4. Open the command-line tool as an administrator and navigate to the folder where you have copied the JAR file. Run the following command, to upgrade the Core database schema (replacing HOSTNAME, DATABASENAME, USERNAME, and PASSWORD with actual values). Note: The Core databases schema referenced in this step and the Mail database schema referenced in the following step are the same database schema. SQL authentication: java -jar dbmanager-2.2.12-jar-with-dependencies.jar -moduleName jsonstore dbType sqlserver -action upgrade -dbHost "HOSTNAME" -dbName "DATABASENAME" dbPort "" -integratedAuth false -userName "USERNAME" -password "PASSWORD" Windows authentication (need to log in to the Windows machine using credentials that have access to the database): java -jar dbmanager-2.2.12-jar-with-dependencies.jar -moduleName jsonstore dbType sqlserver -action upgrade -dbHost "HOSTNAME" -dbName "DATABASENAME" dbPort "" -integratedAuth true 5. Upgrade the Mail database schema using the following command (replacing HOSTNAME, DATABASENAME, USERNAME, and PASSWORD with actual values). SQL authentication: java -jar dbmanager-2.2.12-jar-with-dependencies.jar -moduleName pushnotify dbType sqlserver -action upgrade -dbHost "HOSTNAME" -dbName "DATABASENAME" dbPort "" -integratedAuth false -userName "USERNAME" -password "PASSWORD" Windows authentication (log in to the Windows machine using credentials that have access to the database): java -jar dbmanager-2.2.12-jar-with-dependencies.jar -moduleName pushnotify dbType sqlserver -action upgrade -dbHost "HOSTNAME" -dbName "DATABASENAME" dbPort "" -integratedAuth true 6. Restart all the servers in the cluster 7. Perform a rolling upgrade using the Installer.

Installation and Configuration Guide

71

Configuring GEMS Core

Configuring GEMS Core The first phase in the configuration process is to set up the server irrespective of the services you choose to put in place. This includes: l

Configuring GD in the GEMS Dashboard

l

Configuring Your GEMS Dashboard Administrators

l

Installing the GEMS SSL Certificate

l

Installing CA Certificates for GEMS

Configuring GD in the GEMS Dashboard Note: Your Good Dynamics servers must be operating before the Docs service can be configured for Good Dynamics. Your GEMS environment must be configured to trust the Root CA for the Good Proxy HTTPS configuration or implement the Karaf workaround. For more information, see Appendix B To configure your Good Dynamics server for GEMS: 1. On the GOOD ENTERPRISE MOBILITY SERVER DASHBOARD page, click GEMS Configuration.

A Settings page is displayed.

Installation and Configuration Guide

72

Configuring GEMS Core

2. Click on Good Dynamics.

3. Any Good Proxy servers that you have already defined are listed. Click Add Good Proxy if no proxy server has been defined yet. If you have more than one Good Proxy server, pick any one you wish to define. Autodiscover on that server will correctly identify the others. You can add mulitple proxies if they are available in your environment. You may wish to add more than one proxy to provide redundancy should the designated proxy be unavailable during GEMS startup, autodiscovery, and configuration.

4. To define a proxy server, enter a host name, proxy port number, and choose a protocol from the drop-down menu. 5. Use the Test button to verify the connection. 6. Click the Apply to other nodes in the GEMS cluster checkbox to cause this proxy information to be communicated to all GEMS servers in the cluster. 7. Click the Enforce the SLL Certificate validation checkbox if desired for use with HTTPS protocol. 8. Click Saveto record the setting.

Installation and Configuration Guide

73

Configuring GEMS Core

Configuring Your Dashboard Administrators GEMS Administrators are added via Active Directory groups. Groups in Active Directory are directory objects that reside within a domain and organizational unit container objects. Active Directory provides a set of default groups upon installation, and also gives you the option of creating groups. Adding a group of administrators to your GEMS settings gives the entire group GEMS Dashboard permissions. Remember that a group can be a single individual or many, and that you can add more than one group, but any group added must be part of your security groups. Group members can then login to the dashboard using their Active Directory credentials (UID/PWD/Domain). Users who are members of the Local Administrator group on the server will also be able to login. See Groups under Understanding Active Directory for more information on group creation and management. Otherwise, click GEMS Configuration under GEMS Systems Settings on the Dashboard home page to get started.

To add dashboard administrators: 1. Under SETTINGS, click Dashboard Administrators. 2. On the ACTIVE DIRECTORY page, click Add Group.

3. Provide the following information: a. Active Directory Group – the name of an existing enterprise AD Group. b. Dashboard Role – Currently, Admin is the only available dashboard role.

Installation and Configuration Guide

74

Configuring GEMS Core

c. Admin Role – Only Console is currently available.

4. Click Save. 5. Repeat from Step 2 above to add more groups.

Replacing the Auto-Generated Self-Signed SSL Certificate By default, GEMS is remotely accessible using the HTTPS protocol only. Consequently, during installation, a GEMS Java keystore is created named gems.jks and placed in \Good Enterprise Mobility Server\Good Server Distribution\gems-quickstart-\etc\keystores\. However, if you have a previously created self-signed certificate, then your existing certificate and certificate password are retained. The default password for the gems.jks keystore is "changeit." For instructions on importing certificates into the GEMS Java keystore, please see Appendix B. Note: Unless you import a publicly verifiable certificate into the GEMS Java keystore, please be aware of the following: 1. Access to the GEMS Dashboard from a browser will show an untrusted SSL certificate. 2. You must either upload the GEMS certificate to Good Control or you will need to disable SSL checking on the Good Work client (see "Adding the JSON Configuration for EAS" in the Good Work Product Guide).

Importing CA Certificates for GEMS By default, GEMS only knows about public CA certificates. If GEMS needs to communicate with a server that does not have a public CA certificate (Exchange, for instance), then you must import the non-public CA certificate into the GEMS host Java keystore. The list of servers to which GEMS may connect, includes: l

GEMS ð Exchange

l

GEMS ð ADFS

l

GEMS ð Good Proxy

Installation and Configuration Guide

75

Configuring GEMS Core

l

GEMS ð SharePoint

l

GEMS ð Office Web Apps Server (OWAS)

Within your environment, if GEMS needs to communicate with any of these servers, check to see whether these servers are using public CA certificates. If they are not using public CA certificates, then use the following procedure to add the non-public CA certificates into the GEMS Java keystore. To export the CA certificate from the server with which GEMS needs to communicate: 1. Make sure you have the JAVA bin directory correctly specified in your environment PATH. l

If necessary, confirm the version of JAVA that GEMS is using by complete the following steps: 1. In a command prompt, type set | findstr "JAVA_HOME". 2. Press Enter.

l

Verify the JAVA_HOME System variable is set to the correct JAVA bin directory. For instructions about setting the JAVA_HOME system variable, see Configuring the Java Runtime Environment.

2. Obtain a copy of your non-public CA certificate. If you are unclear on how to do this, check with the administrator of your Exchange, Good Proxy, or SharePoint servers. 3. On the GEMS host, make a backup of the Java keystore file. The default location of the Java keystore file is value_of_JAVA_HOME\lib\security\cacerts. For example: C:\Program Files\Java\jre1.8.0_91\lib\security\cacerts. 4. Copy your non-public CA certificate to the Java keystore directory in Step 3. 5. Open a DOS CMD and change directory to the Java keystore directory. For example, cd %java_ home%\lib\security. 6. Use the following command to import your non-public CA certificate into the Java keystore: keytool -importcert -trustcacerts -alias -file .cer -keystore cacerts

Be sure to (a) replace with the proper alias for your non-public certificate and (b) replace .cer with the file name of your non-public certificate. 7. Repeat Steps 2 through 6 for each non-public CA certificate. 8. Restart the Good Technology Common service from the Windows Service Manager.

Enabling GEMS HTTP (Optional) Recognizing the inherent security vulnerability that comes with standard HTTP connections, when necessary or desired, you can manually configure GEMS to use HTTP in test/POC environments using the following procedure. To enable GEMS HTTP: 1. On the GEMS host, locate the org.ops4j.pax.web.cfg file and open it in a text editor. Its default location is C:\Program Files\Good Technology\Good Enterprise Mobility Server\Good Server Distribution\gemsquickstart-\etc .

Installation and Configuration Guide

76

Configuring GEMS Core

2. Comment out the “org.ops4j.pax.web.listening.addresses=127.0.0.1” line by prefixing it with a “#” sign. It should look like this: #org.ops4j.pax.web.listening.addresses=127.0.0.1

3. Save the file. 4. Locate the jetty.xml file. Its default location is C:\Program Files\Good Technology\Good Enterprise Mobility Server\Good Server Distribution\gems-quickstart-\etc and open it in your text editor. 5. Find the following block of lines and delete the comment markers highlighted in yellow: 300000 2 false 8443 20000 5000 -->

6. Save the file. 7. Restart the Good Technology Common service.

Dashboard Troubleshooting Facilities The GEMS dashboard provides several aids for collecting troubleshooting data.

Installation and Configuration Guide

77

Configuring GEMS Core

Log Upload Credentials Use this option to enter the upload credentials that will give you permission to send logs and data directly to Good Support.

Enter the Good ID you use to log on to the Good Online Portal. These credentials will be used to upload logs under your organization's name for Good Support to review. that these credentials are not stored, and only used to ensure that this GEMS server is authorized for log uploads.

Upload Logs Use this option to send logs directly to Good Support. Mail and Docs services are supported.

Installation and Configuration Guide

78

Configuring GEMS Core

Enter the date range to be included. Click the

icon for ease of selection. Note that the time zone displayed is

that of the GEMS server and the dates chosen here would be used in reference to that time zone. Click Upload Logs to send the logs.

Upload GEMS statistics Use this option to enable/disable sending GEMS statistics to the Good/Blackberry NOC periodically.

Click the checkbox to allow this GEMS server to send diagnostics information to Good Support. By opting in, the GEMS server will send periodic updates to Blackberry about your GEMS deployments. The information collected includes: l

Number of users assigned to the instance*

l

Name of instance*

l

Name of the cluster

l

Version of GEMS

l

List of instances*

l

Feature set for instance*

l

Feature set for cluster*

l

Services installed, status of the instance*

l

JVM Version

l

Last restart time

l

System bugs

l

Operating system

Installation and Configuration Guide

79

Configuring GEMS Services

l

Schema version

l

System health

* The mail service must be installed for this information to be retrieved.. Enter the cluster name, domain name, and sampling interval (in minutes). The cluster name is used to update monitoring data for a GEMS cluster instance. Good support identifies all instances belonging to this cluster by the cluster information. The domain name is a network domain name. This is typically the domain name of the GEMS cluster-instance server's hostname. Ideally, this would be your organization domain name. Cluster Name and Domain Name identify a unique GEMS cluster instance. The default sampling interval is 30 minutes. We recommend leaving the sampling interval at its default value unless instructed to do otherwise by your authorized support representative. Click Save to save your changes.

Configuring GEMS Services As previously indicated, you can configure one or more services at any time in any order desired according to your organization's mobile user demand and deployment requirements. Once again, these services currently comprise: l

Push Notifications (Email)

l

Connect

l

Presence

l

Docs

l

Launcher

l

Certificate Lookup

Note: The Analytics service is currently an app developer's preview. In GEMS 2.1, administrators may safely omit configuration of this service. There is no impact on the other services.

Configuring the Push Notification (Mail) Service Configuring GEMS for PNS support of the Good Work app, which includes Mail, Contacts, and Calendar, entails: l

Enabling Exchange ActiveSync (EAS)

l

Configuring Mail in the GEMS Dashboard

l

Configuring Good Control

l

Configuring GEMS-PNS for High Availability

Installation and Configuration Guide

80

Configuring GEMS Services

Enabling Exchange ActiveSync (EAS) EAS is a protocol designed for the synchronization of email, contacts, calendar, tasks, and notes from the messaging server to the Good Work client. GEMS does not participate in EAS activity, but if EAS is not properly enabled, then GEMS cannot support Good Work clients with PNS. Consequently, if you plan to deploy the Good Work client to your users, please ensure that EAS is enabled on port 443 and that connections are permitted to the Good Proxy server. Note: By default, ActiveSync is enabled when you install the Client Access server role on the computer that's running Microsoft Exchange Server 2010, Exchange 2013, or 2016. For detailed guidance on Exchange EAS and how it works with Good apps, please refer to Good Work EAS Security Information and Guidance. For additional information on how to enable and manage EAS in your existing Exchange environment, see Microsoft's Exchange and IIS documentation.

Configuring PNS (Mail) in the GEMS Dashboard Important: The configuration sequence presented next must be strictly followed to avoid connectivity issues. Chiefly, it is critical that database configuration be completed prior to configuring Microsoft Exchange.

After clicking Mail under Good Services Configuration on the Dashboard home page, complete its service configuration in the following order: l

Database

l

Microsoft Exchange

l

Web Proxy

l

Android Push Notifications

l

Stop Notifications

l

User Directory Lookup

l

Certificate Directory Lookup

Installation and Configuration Guide

81

Configuring GEMS Services

Database In configuring your SQL database for GEMS-PNS, you have a choice of using either Windows Authentication or SQL Authentication for granting access to the database by GEMS. Make sure you have already set the “Good Technology Common” service to run as the service account in Windows Service Manager (SrvMan). After restarting the Good Technology Common service, perform the steps below for either Windows Authentication or SQL Authentication. To use Windows Authentication to access the database: 1. In the GOOD MAIL SERVICE CONFIGURATION page, click Database.

2. Enter the Server host name and instance name; i.e., \. 3. Enter the Database name. For example, GEMSDB. Note: If you are configuring the database for an AlwaysOn Availability Group, please see Appendix L. 4. Select Windows Authentication for the Authentication Type. 5. Click the Test button to verify connectivity with the database. 6. Click Save to commit your changes. 7. Finally (and critical to the configuration process), restart the Good Technology Common service in Windows Services Manager to allow these settings to take effect.

Installation and Configuration Guide

82

Configuring GEMS Services

To use SQL Authentication to access the database: 1. Select SQL Server Login as the Authentication Type. 2. Enter the SQL Server Username and Password. 3. Click the Test button to verify connectivity with the database. 4. Click Save to commit your changes. 5. Use the Windows Services Manager to locate the service named Good Technology Common service, then select Restart to allow these settings to take effect. Tip: After restart, check the table dbo.KeyValueRecord to verify that your SQL Server database is now being used by GEMS.

Microsoft Exchange 1. Returning to the GOOD MAIL SERVICE CONFIGURATION page, click Microsoft Exchange. 2. Enter the Domain, Username ("GoodAdmin" is recommended), and Password of the Windows Service Account. This account should have impersonation rights on Exchange.

Installation and Configuration Guide

83

Configuring GEMS Services

3. Enter a valid end-user email address to test connectivity using the Service Account and click Test. Note: If the service account is correctly configured and the test fails, it is generally the case that GEMS is attempting to communicate with an Exchange Server that is not using a trusted SSL Certificate. If your Exchange server is not set up to use a trusted SSL certificate, see Importing CA Certificates for GEMS. 4. Click Save to commit your changes. Database Connectivity Issues If GEMS is unable to connect to its Push Notification database, this usually means that the Mail > Microsoft Exchange configuration information was applied in the GEMS Dashboard before configuring the Mail > Database information. If you encounter this problem, use the following procedure to resolve the issue. From the GEMS Dashboard: 1. Restart the Good Technology Common service. 2. Make sure the information in Mail > Database is correct. 3. Repopulate the Mail > Exchange Server configuration, then test and save your changes.

Web Proxy Because APNS pushes are sent via the Good Network Operations Center (NOC), which resides outside of your enterprise network, a proxy may be needed to access the NOC.

Installation and Configuration Guide

84

Configuring GEMS Services

To configure a Web Proxy for GEMS-PNS: 1. Returning to the GOOD MAIL SERVICE CONFIGURATION page, click Web Proxy. 2. Enable the Use Web Proxy checkbox. 3. For Proxy Address, enter the FQDN of the web proxy. 4. Enter a Proxy Port. 5. Select a Proxy Server Authentication Type (or None) from the drop-list. If you choose Basic or NTLM authentication, enter recognized credentials (Username, Password) and, optionally, the Domain. 6. Check Use the same web proxy settings to connect to an externally hosted Exchange if you want to use this web proxy to communicate with a hosted Exchange (cloud deployed).

7. Click Test to confirm connection to the proxy server. 8. Click Save to commit your changes.

Android Push Notifications Google Cloud Messaging (GCM) must be configured to support Android Push Notifications. This requires a GCM sender ID and API key.

Installation and Configuration Guide

85

Configuring GEMS Services

To configure Android Push Notification: 1. On the dashboard's GOOD MAIL SERVICE CONFIGURATION page, click Android Push Notification.

Installation and Configuration Guide

86

Configuring GEMS Services

2. Fill in the fields for GCM Sender ID and API Key and click Save. Note: If a GCM API Key does not currently exist in Good Control, follow the guidance in Appendix H for obtaining a GCM API Key.

Stop Notifications By default, notifications are sent to a user's device and are regulated by a set of timers. The Stop Notifications feature allows you to stop notification for all devices associated with a particular user immediately. A user can resubscribe to notifications but only if the user is entitled to an app that can subscribe to notification services. To selectively stop push notifications for an individual user: 1. On the dashboard's GOOD MAIL SERVICE CONFIGURATION page, click Stop Notifications. 2. Enter the user's email address and click Save.

User Directory Lookup The User Directory Lookup service of GEMS allows client apps using the service to look up first name, last name, and the associated photo or avatar from your organization's Global Address List (GAL). A User ID Property Name is used to determine whether query results from various sources (EWS and LDAP) correspond to the same user and may therefore be consolidated into a single result.

Installation and Configuration Guide

87

Configuring GEMS Services

To configure the User Directory Lookup service: 1. On the dashboard's GOOD MAIL SERVICE CONFIGURATION page, click User Directory Lookup.

2. Enter the User ID Property Name, typically Alias, then check the box for Enable GAL Lookup or Enable LDAP Lookup or both.

3. If you select LDAP lookup because you have an LDAP server available, you can use it to validate digital certificate connections to the LDAP server. If you select LDAP lookup, a frame is opened on the page, in which you can enter the specifics of the LDAP operation.

Installation and Configuration Guide

88

Configuring GEMS Services

4. Enter the LDAP Server Name (ldap.DNS domain name) and port; enable SSL LDAP if desired (data will be tunneled through an SSL-encrypted connections. If desired, edit the LDAP User Name Query Template, which is used to search for a user by their user name. GEMS will replace the "{key}" with the user name when performing the query. The default template is (&(|(mail=*{key}*)(name=*{key}*)(displayName=*{key}*)(sAMAccountName=*{key}*) (givenName=*{key}*)(sn=*{key}*))(objectClass=user)(objectCategory=person)(! (userAccountControl:1.2.840.113556.1.4.803:=2))) 5. If desired, provide a base DN for the LDAP search. GEMS will try to find the base DN in the namingContexts attribute if this entry is not set. 6. Choose an authentication type (anonymous, basic, or certificate type). Certificate type is available if SSL LDAP is specified. If using a certificate, enter the keystore password and use Choose File to browse and select the desired file. 7. To test LDAP usage, enter a user name or email in User Search Key and click Test. 8. Click Save.

Certificate Directory Lookup The Certificate Directory Lookup service of GEMS retrieves S/MIME digital certificates from the user's Active Directory. These certificates are used to enable the email encryption and signature functionality in Good Work mobile apps. See the product guide supplemental Configuring S/MIME for Good Work for more on the device side of configuring and using S/MIME. To configure the Certificate Directory Lookup service in GEMS: On the dashboard's GOOD MAIL SERVICE CONFIGURATION page, click Certificate Directory Lookup.

Installation and Configuration Guide

89

Configuring GEMS Services

Opt to Include expired certificates in results by clicking its checkbox. Choose to Enable Contact Lookup, Enable GAL Lookup and/or Enable LDAP Lookup by activating the corresponding check box. Uncheck the box to disable a lookup.

If you select LDAP lookup because you have an LDAP server available, you can use it to validate digital certificate connections to the LDAP server. When you select LDAP lookup, a frame is opened on the page, in which you will need to configure the settings for the LDAP operation.

Enter the LDAP Server Name (ldap.DNS domain name) and port; enable SSL LDAP if desired (data will be tunneled through an SSL-encrypted connections. If desired, edit the LDAP User Name Query Template, which is used to search for a user by their user name. GEMS will replace the "{key}" with the user name when performing the query. The default template is

Installation and Configuration Guide

90

Configuring GEMS Services

(&(|(mail=*{key}*)(name=*{key}*)(displayName=*{key}*)(sAMAccountName=*{key}*) (givenName=*{key}*)(sn=*{key}*))(objectClass=user)(objectCategory=person)(! (userAccountControl:1.2.840.113556.1.4.803:=2))) If desired, provide a base DN for the LDAP search. GEMS will try to find the base DN in the namingContexts attribute if this entry is not set. Choose an authentication type (anonymous, basic, or certificate type). Certificate type is available if SSL LDAP is specified. If using a certificate, enter the keystore password and use Choose File to browse and select the desired file. To test LDAP usage, enter a user name or email in User Search Key and click Test. Click Save. Remember, you can always return to the GEMS Dashboard to adjust and fine-tune your settings or change them altogether. Next, you're ready to configure Good Control to support GEMS services.

Configuring Good Control A few basic configuration settings are necessary so that Good Control can properly support Good Work application users with GEMS services. These include: l

Configuring EAS for the Good Work app

l

Adding Applications and Users

l

Device Provisioning and Activation

Note: The Good Work application must be published in Good Control. For prerequisite details on setting up Good Control, see Good Dynamics Requirements. To learn how to add the application in Good Control, see "Registering a New Application" in the GC console's online help. With respect to GEMS, to complete configuration of PNS, please login to Good Control with full admin rights.

Configuring Exchange ActiveSync (EAS) for Good Work™ To allow your users to easily enroll in EAS when they activate their Good Work app, the app must be configured in Good Control to connect to EAS. This is accomplished from your Good Control console. Important: Before the Good Work app can be configured to use PNS, it must first be configured for EAS. There are two parts to this procedure: l

Whitelisting the EAS server(s) in Good Control

l

Adding the correct JSON configuration

If this has not already been accomplished, please see the Good Work Product Guide for the correct setup instructions.

Installation and Configuration Guide

91

Configuring GEMS Services

Adding Applications and Users in Good Control By default, every user is assigned to the “Everyone” group. If you plan to use the default, simply add the Good Work app to the Everyone Application Group. Refer to your Good Control online help utility and the Good Work Product Guide for guidance on adding applications like Good Work and Good Connect, along with adding new user accounts and modifying policies and permissions.

Whitelisting Your GEMS Host(s) in Good Control The GEMS host must be whitelisted in Good Control to enable proper communication between the Good Proxy server and GEMS. To whitelist GEMS in Good Control: 1. Open the Good Control console, then under POLICIES, click Connectivity Profiles, then under Base Profile, click Master Connection Profile. 2. Scroll down to ADDITIONAL SERVERS and click EDIT. 3. At the bottom of the list of servers, click ADD. 4. In the SERVERfield, add the FQDN of the GEMS machine and enter 8443 for the Port. Choose a primary GP cluster and a secondary GP cluster (if available), then click Add.

Installation and Configuration Guide

92

Configuring GEMS Services

5. White list additional GEMS hosts with GP Clusters by repeating from Step 3. 6. Click Save to record your changes.

Adding GEMS to the Good Work Application Server List The Good Work client checks the Good Work server list for available GEMS instances hosting the Presence service. Hence, the list must be populated with at least one GEMS machine configured for the Good Enterprise Services entitlement app. When multiple GEMS hosts are listed, you can use Good Work's Preferred Presence Server Configuration parameter to set up a presence affinity association (see Configuring Presence Affinity for Good Work). To add GEMS to the Good Work application server list: 1. Under APPS, click Manage Apps, search for or scroll down to Good Work and click it. 2. Click the GOOD DYNAMICS tab, then, in the Server section, click EDIT. 3. Enter the GEMS host FQDN in the Host Name field, then enter 8443 under Port.

Note: Unless you import a publicly verifiable certificate into the GEMS Java keystore, please be aware of the following: 1. Access to the GEMS Dashboard from a browser will show an untrusted SSL certificate. 2. You will need to upload the GEMS certificate to Good Control. 4. If you have additional GEMS hosts, configure them for the application in the same way, after clicking

to

add a new row. 5. Click Save to commit your changes.

Installation and Configuration Guide

93

Configuring GEMS Services

Configuring GEMS-PNS for HA High Availability for GEMS-PNS is based on clustering. When adding a new GEMS-PNS instance, you will need to: 1. Configure your new GEMS-PNS instance to use the existing database. 2. Configure your new GEMS-PNS instance to point to the same Good Proxy server. 3. Configure your new server host and port in the Good Control server list. The GEMS Push Notifications Service (PNS) supports high availability (HA) by adding additional servers running PNS. The GEMS instances hosting PNS that you designate to participate in HA must share the same database. To set up a HA GEMS-PNS host, simply provision an additional server and install GEMS-PNS. Using the same service account ("GoodAdmin") for all HA servers is strongly recommended. In the GEMS dashboard configuration on the HA server, be sure to point the HA server to the same database. From the Good Control console, add each HA server to the Good Work application server list in accordance with the instructions above for configuring the Good Work App with EAS.

Configuring GEMS-PNS for DR Recommended disaster recovery (DR) measures for GEMS-PNS are based on an active/cold standby clustering model. Before adding a GEMS-PNS instance for DR, you will need to: 1. Configure database replication for the GEMS-PNS database from your primary site to your DR site. SQL log shipping is recommended. Consult your database administrator for assistance. 2. Ensure that the appropriate network ports are open to allow the GEMS-PNS servers within your DR site to communicate with the database, Exchange, and Good Proxy servers in your DR and Primary site. When adding a new DR GEMS-PNS instance, you will need to: 1. Configure your DR GEMS-PNS instance to use the primary database in the cluster. 2. Configure your DR GEMS-PNS instance to use the primary Good Proxy server in the cluster. 3. Whitelist your DR GEMS-PNS server host and port in Good Control (see Whitelisting Your GEMS Host(s) in Good Control). 4. Configure your DR GEMS-PNS instance in Good Control for the Good Work App [see Adding GEMS to the Good Work Application Server List). Be sure to set the PRIORITY setting to Secondary or Tertiary. Important: After the DR GEMS-PNS instance is installed and configured, you will need to stop the Good Technology Common service. This places the DR GEMS-PNS instance in cold standby.

Installation and Configuration Guide

94

Configuring GEMS Services

In a DR situation in which you want to failover, you will need to: 1. Stop the Good Technology Common service on all your primary GEMS-PNS instances. 2. Failover your GEMS-PNS database on your database server (i.e., make the GEMS-PNS database in your DR site active). 3. Failover your DB FQDN DNS to your DR DB server. If this is not possible, see Step 5. 4. Start the Good Technology Common service on your DR GEMS-PNS instance. 5. If you were not able to do Step 3 (failover DB DNS), you will need to login to the GEMS Dashboard and update the GEMS-PNS DB information to point to your DR DB server, then restart the Good Technology Common service for the new DB settings to take effect. 6. If you also failed over your Good Proxy servers as part of this process, you will need to update the Good Proxy information in the GEMS dashboard for the GEMS-PNS service.

Device Verification and Testing The Good Work app is publicly available from the Apple App Store or the Google Play store. By default the app will only use HTTPS to communicate with GEMS when it registers for push notifications. If you haven’t already done so, download the Good Work app to your device. Upon launching the Good Work app for the first time, you will be prompted for an email address and a provisioning PIN. If you don’t have this information, refer to the previous section on device activation keys. Good Work will continue the provisioning process once the email address and PIN is entered correctly. Depending on the Good Control policy for the device, you may be prompted to create a password for the app. After the app password is set, you will be prompted for your enterprise email address and Active Directory password. If the system is not able to correlate your email address to an Exchange Active Sync (EAS) server, you will be prompted for a different EAS server and domain credentials. When everything is setup correctly, Good Work will automatically start synchronizing with Exchange and you will start to see mail, calendar and contact information in the app. If Good Presence is configured, you will also see presence information for each contact. To test from GEMS as to whether a device is actually connected, go to Push Channels and query GEMS. You can also query users by going to EWS Listener. If these tests fail or are inconclusive, investigate Autodiscover troubleshooting. Refer to Logging and Diagnostics for any additional issues encountered.

Adjusting the Push Notification Cutoff Time GEMS-PNS Mail notifications are downgraded to "no-details" if the device has not registered within a configurable amount of time. The default cutoff time is 12 hours (43200 seconds). Max value is 3 days (43200 * 6) or 259200 seconds.

Installation and Configuration Guide

95

Configuring GEMS Services

To change the mail push notification cutoff time: 1. Go to http://.com:8443/system/console/configMgr and login as administrator with the appropriate AD credentials. 2. Click OSGi, then select Configuration. 3. Scroll down to the Good Technology Email Push Coalescing section and locate the pushDowngradeCutoffSec parameter. 4. Increase or decrease the value (default = 43200) to the desired cutoff time in seconds.

PNS Logging and Diagnostics Helpful performance logs and diagnostic information for GEMS and the Push Notification Service can be found in the GEMS Web Console. To set/change the administrator's password see Changing the GEMS Web Console Password.

GEMS Web Console The GEMS Web Console provides advanced configuration and tuning options for GEMS. It should be used with care as it offers advanced maintenance capabilities intended for expert users of the system.

Installation and Configuration Guide

96

Configuring GEMS Services

To see the relevant logs in your browser: 1. Go to https://.com:8443/system/console/configMgr 2. Login as an administrator with the appropriate AD credentials. 3. Click on OSGi, then select Log Service. 4. Scroll the log activity. It's listed in chronological order. Note: A more robust and complete administration guide covering how to use the advanced features of the GEMS Web Console is scheduled for publication later this year.

Log File Location The actual log files are stored in the GEMS installation directory. Its default location is: C:\Program Files\Good Technology\Good Enterprise Mobility Server All log directories are relative to this path. The GEM Server Log can be found in: \Good Server Distribution\gems_quickstart-\data\log\

Autodiscover Override In certain environments, the system may not be able to dynamically retrieve the autodiscover endpoint URL. If this happens, the autodiscover endpoint URL will need to be set manually. Push notification failure and EWS Listener queries returning NULL are common symptoms.

Installation and Configuration Guide

97

Configuring GEMS Services

To set the override from the GEMS machine: 1. Login to the GEMS Web Console as an administrator. 2. Select OSGi > Configuration. 3. Scroll down to GEMS Autodiscover Configuration and click it.

6. Enter an Autodiscover override URL in the field provided. This typically takes the form "https://" + domain + "/autodiscover/autodiscover" + fileExtension. Ex.: https://mycas.mydomain/autodiscover/autodiscover.svc. The value of fileExtension depends on which Autodiscover access method is used, SOAP or POX. The SOAP service uses a ".svc" file extension; POX uses ".xml". Important: Because GEMS uses SOAP (Simple Object Access Protocol), you must use the .svc file extension.

Installation and Configuration Guide

98

Configuring GEMS Services

7. Click Save. 8. Restart the Good Technology Common service. To remove the override, return to the GEMS Autodiscover Configuration in the GEMS Web Console and remove the override URL, then save the configuration.

Detailed Notifications Cutoff Time After a configurable amount of time (12 hours by default) if Good Work has not been unlocked and actively used on a device, the GEMS Push Notification Service will remove details about individual email messages from Notifications that are displayed on the device. Message details in Notifications sent by the GEMS Push Notification Service will resume when Good Work is next unlocked and used on the device. To configure the detailed notifications cutoff time: 1. Open the GEMS Web Console in your browser (https://.com:8443/system/console/configMgr). 2. Login as administrator (the default uid/pwd is "admin"/"admin"). 3. Select OSGi > Configuration, then scroll down to Good Technology Email Push Coalescing and click it. 4. Increase/decrease the value of pushDowngradeCutoffSec in seconds. The default value is 43200 (in seconds) or 12 hours. The following conversion table is provided for convenience. Seconds

Hours

3600

1

43200

12

86400

24

Days

1

172800

2

259200

3

Checking EWS Listener and Push Channels GEMS provides diagnostic URLs to help you determine whether GEMS-PNS is working properly. However, these diagnostic URLs are not remotely accessible. They can only be accessed on the same machine on which GEMSPNS is running. Therefore, you must use "127.0.0.1" as the hostname in each of the URLs below. A quick way to check whether or not the Push Channels and EWS Listener are working is to query GEMS with the following URLs: Push Channels http://127.0.0.1:8181/pushnotify/pushchannels

Installation and Configuration Guide

99

Configuring GEMS Services

Sample Output: [{"registrationId":"[email protected]#3EFED82C-BE27-4A71-BF647F68424122B4","account":"[email protected]","pushToken":"8FAE82462C794005BFC90C7A4B654B523CDB2FCC59A922BDAFBAFD 30D2460614","bundleId": "com.good.gcs.g3.enterprise","ewsProfileId":"51","deviceType":"ios"}]

If the outputs are NULL ([]), check the log for the reasons why. If outputs are not found, then refer to the SSH console for additional detail. EWS Listener http://127.0.0.1:8181/ewslistener/user Sample Output: [{"connectionId":45946713,"email":"[email protected]","stage":"Streaming", "lastErrorTime":null,"status ":null}]

Using the first check, you will see a push channel registration if the device successfully connected to GEMS. Then, if your Exchange Configuration is set up properly you will see a streaming EWS Listener subscription. Note that in the diagnostic URLs above, the HTTP protocol is used. This is permissible for connections made to GEMS from same machine on which GEMS is running but not from remote clients. Occasionally, for evaluation or demonstration purposes, you may not yet have configured SSL for GEMS Core. In this situation, you can permit remote connections to GEMS via HTTP. Even when doing so, please note that traffic between the device and the Good Proxy remains protected over a secure channel. To do so, add the following line to the JSON configuration for Good Work in Good Control: "serverProtocol":"http",

For example: { "serverProtocol":"http", "disableSSLCertificateChecking":"true", "": { "EASDomain":"", "EASServer":"", "AutodiscoverURL":"https://autodiscover.mydomain.com/autodiscover/autodiscover.xml", "EASServerPort":"", "EASUseSSL":"true" } }

If using Autodiscover, replace the EASServer parameter above with AutodiscoverURL so that "EASServer":""

becomes "AutodiscoverURL":"https://autodiscover.good.com/autodiscover/autodiscover.xml"

See Enabling GEMS HTTP above; see also "Adding the JSON Configuration for EAS" in the Good Work Product Guide.

Installation and Configuration Guide

100

Configuring GEMS Services

Configuring the Connect Service The Connect service governs IM and presence capabilities of the Good Connect app. Configuring the GEMS Dashboard and Good Control are critical phases in the deployment of Good Connect. This entails: l

Configuring Connect in the GEMS Dashboard

l

Configuring Good Control for Connect

l

Enabling SSL via Good Proxy

l

Configuring support for the Global Catalog

Configuring Connect in the GEMS Dashboard Using Good Connect, employees can track coworker availability, initiate or receive an instant message, make a phone call, share and open file links in Good Share or send an email securely via Good for Enterprise™. Best of all, Good Connect lets you efficiently embrace BYOD programs without compromising corporate security or employee privacy.

Complete the configuration steps for the following components to set up the Connect service: l

Service Account

l

Database

l

Good Dynamics

l

Lync 2010 or Lync 2013 or Jabber

l

Microsoft Exchange (optional)

l

Web Proxy (optional)

Installation and Configuration Guide

101

Configuring GEMS Services

Click Connect in the dashboard's Good Services Configuration page to get started.

Configuring the Service Account Necessary components are grayed-out until you provide the correct Windows Service Account credentials for GEMS. which uses this information to securely connect to Microsoft Services like Active Directory, Lync, Exchange, and SQL Server. Make sure this service account has RTCUniversalReadOnlyAdmins rights. If an account has not yet been created, contact your Windows domain administrator to request an account.

Important: Be sure to stop the "Good Technology Connect" service in Windows Services Manager. To configure the Windows Service Account for GEMS: 1. Click Service Account to provide the GEMS Domain Service Account credentials. 2. Enter the service account Username and Password 3. Click Save.

Installation and Configuration Guide

102

Configuring GEMS Services

These credentials are not stored after the current browser session ends. If the credentials are valid, the service is connected and the links to the other components on the Good Connect Service Configuration page are activated.

Configuring the Database 1. In the Good Connect Service Configuration page click Database. 2. Enter the Server and Database name. For example, GEMS-Connect. Select the appropriate Authentication Type

When you choose Windows Authentication, the credentials for the Windows Service Account configured for the Good Connect Service are used. If you select SQL Server Login, you will then need to enter a valid Username and Password for the SQL Server database prescribed in the Prerequisites section of this guide. 4. Click Test to verify that a connection with the database can be made.

Installation and Configuration Guide

103

Configuring GEMS Services

If the test is successful, a confirmation is displayed at the top of the page in blue. If testing fails, check that System and Network Requirements, plus all Database Requirements, have been met. Correct as needed, then return to Step 1 above. 5. Click Save.

Configuring Good Dynamics Before continuing with this setup phase, make sure that your Good Dynamics servers—Good Connect and Good Proxy—are installed and operating. For details, see the Good Dynamics Server Installation Guide available on GDN. To configure GEMS connectivity with Good Dynamics: 1. In the Good Connect Service Configuration page (breadcrumb: Services > Connect), click Good Dynamics. 2. Next, in the Good Dynamics Server Configuration page, enter the Hostname and Port number of the Good Proxy server, then choose communication via HTTP or HTTPS. Important: To configure HTTPS you must upload the Good Proxy server's CA certificate to the GEMSConnect server’s Windows keystore. See Configuring GEMS-Connect to use SSL with Good Proxy for details.

Installation and Configuration Guide

104

Configuring GEMS Services

3. Click Test to verify that a connection to the Good Proxy server can be made. If the test is successful, a confirmation is displayed at the top of the page in blue. If testing fails, check that all System and Network Requirements, plus all Good Dynamics Requirements have been met. Correct as needed, then return to Step 1 above. 4. Click Save to record these settings. Next, follow the guidance for the Lync Server version deployed in your environment: Lync 2010 or Lync 2013.

Configuring Lync 2010 1. From the Good Connect Service Configuration page, click Lync 2010. The system will query the Lync server to verify that the appropriate GEMS Lync topology has been added. Allow a few moments for the query to complete.

Installation and Configuration Guide

105

Configuring GEMS Services

2. From the Application ID drop-down list, select the pool_gems. application id. If the list is empty, this means that either the GEMS Lync topology was not setup correctly or the service account does not have the proper permissions to query these settings. Refer to Microsoft Lync 2010 Requirements and correct your topology or permissions as needed. 3. Click Test to verify that a connection to the Lync 2010 Server can be made. If the test is successful, a confirmation is displayed at the top of the page in blue. It testing fails, check that all System and Network Requirements, plus all Microsoft Lync 2010 Requirements, have been met. Correct as needed, then return to Step 1 above. 4. Click Save to record these settings. The default location of the GEMS Connect Dashboard logs is: (a) \Good Enterprise Mobility Server\Good Component Manager\RunAsService\logs (b) \Good Enterprise Mobility Server\Good Component Manager\logs These are the log files you will want to check if issues arise with your Lync configuration.

Configuring Lync 2013 1. From the Good Connect Service Configuration page, click Lync 2013. The system will query the Lync server to verify that the appropriate GEMS Lync topology has been added. Allow a few moments for the query to complete.

Installation and Configuration Guide

106

Configuring GEMS Services

2. From the Application ID drop-down list, select the appid_connect. application id. If the list is empty, this means that either the GEMS Lync topology was not setup correctly or the service account does not have the proper permissions to query for these settings. Refer to Microsoft Lync 2013 Requirements and correct your topology or permissions as needed. 3. Click Test to verify that a connection to the Lync 2010 Server can be made. If the test is successful, a confirmation is displayed at the top of the page in blue. It testing fails, check that all System and Network Requirements, plus all Microsoft Lync 2013 Requirements, have been met. Correct as needed, then return to Step 1 above. 4. Click Save to record these settings. The default location of the GEMS Connect Dashboard logs is: (a) \Good Enterprise Mobility Server\Good Component Manager\RunAsService\logs (b) \Good Enterprise Mobility Server\Good Component Manager\logs These are the log files you will want to check if issues arise with your Lync configuration.

Configuring Jabber With GEMS installed, the initial configuration dashboard URL used will not match the self-signed certificate that was created. You can replace localhost with the FQDN that you specified during the installation, and bookmark this for future use.

Installation and Configuration Guide

107

Configuring GEMS Services

1. Login with the admin user account that has local admin privileges to configure the service.

2. Configure Jabber from the GEMS dashboard as follows: On the dashboard, click Connect.

Installation and Configuration Guide

108

Configuring GEMS Services

3. On the Connect Service Configuration page, click Service Account.

4. On the Domain Service Account screen, enter the name by which the Connect Service will be known on Windows. You must stop this service in Windows Services Manager before making configuration changes. For security reasons, the Good Enterprise Mobility Server will not store your Service Account credentials after the browser session. You will need to re-enter this Service Account every time you want to make further configuration changes. Enter Username and Password credentials for the account and click Save.

Installation and Configuration Guide

109

Configuring GEMS Services

5. Returning to the Good Connect Service Configuration screen, click Good Dynamics, to specify the Good Dynamics server configuraton to be used with Connect, as described in the Configuring Good Dynamics section. Do the same for Configuring the Database .

Installation and Configuration Guide

110

Configuring GEMS Services

6. On the Good Connect Service Configuration screen, click Jabber.

Configure the Jabber adapter using this screen. Enter the CUCM FQDN and port, CIMP FQDN and port, and full server domain name. (Jabber Connect uses CUCM LDAP only. It does not use directory lookup.) 7. From the Good Connect Service Configuration screen, click Web Proxy if desired, and configure the resulting screens as described in Configuring a Web Proxy . 8. With this configuration complete, start the “Good Technology Connect” service.

9. Connect policies applied to user devices must specify Jabber as the IM platform in use. To configure these polices, in the GC console go to Policy Sets > policy_name > APPS tab > App Specific Polices > Good Connect > Server Configuration and from the Platform dropdown, select Cisco Jabber.

Installation and Configuration Guide

111

Configuring GEMS Services

In addition to performing this step, you also need to configure the Good Connect GD application as described in the section titled Configuring Good Control for Connect

Configuring Microsoft Exchange Conversation History Enable this component connection only if you wish to access saved conversations from Microsoft Exchange. Bear in mind that before configuring conversation history for the Good Connect Service, you must first make sure that it is enabled on the enterprise Lync Server for which you are configuring Good Connect. As indicated on the Dashboard, consult your Microsoft Lync 2010 Administration Guide and Windows PowerShell Supplement. To configure GEMS to access Exchange conversation histories: 1. From the Good Connect Service Configuration page, click on Microsoft Exchange.

Installation and Configuration Guide

112

Configuring GEMS Services

2. Check Enable Conversation History.

3. Enter the URL for your Microsoft Exchange Server in the field provided. 4. Select the supported Exchange Server Type (version) from the drop-down list. 5. Enter the desired Server Write Interval in minutes. This determines the frequency with which each unique conversation will be sent to Exchange. 6. Click Test to verify that a connection to the Exchange Server can be made. If the test is successful, a confirmation is displayed at the top of the page in blue. If testing fails, check that System and Network Requirements, plus all Microsoft Lync Server Requirements, have been met. Correct as needed, then return to Step 1. 7. Click Save to record these settings.

Configuring a Web Proxy If your company uses a web proxy server to connect to the Internet, you must enter the required information necessary to enable a connection with the Good Connect Service. Skip this setup phase if your enterprise does not use a web proxy. To configure the GEMS Internet connection using a web proxy: 1. From the Good Connect Service Configuration page, click on Web Proxy.

Installation and Configuration Guide

113

Configuring GEMS Services

2. Check Use Web Proxy.

3. Enter Proxy Address and Proxy Port number. Both of these value should be exclusive to your organization. 4. Select a Proxy Authentication Type.

Basic authentication requires that a user name and password be supplied by the GEMS-Connect Service to authenticate a request. Digest authentication is more secure because it applies a hash function to the password before sending it over the network. If no authentication is required or desired, select None. If you choose an authentication type, the Connect Service Username and Password are automatically populated based on the Windows Domain Service Account you assigned to the Connect Service under Configuring Windows Services. 5. Next, you can specify the Domain, although this is not required. 6. Click Test to verify that connection to the Web Proxy can be made. If the test is successful, a confirmation is displayed at the top of the page in blue. If testing fails, check that you entered the correct Proxy Address in

Installation and Configuration Guide

114

Configuring GEMS Services

Step 3 above, and that all System and Network Requirements have been met. Correct as needed, then retry by clicking Test again. 7. Click Save to record these settings.

Restart the Good Technology Connect Service Now that GEMS is configured, you must restart the Good Technology Connect service in the Windows Services Manager in order for your changes to take effect.

Configuring Good Control for Connect Next, it’s important to associate deployed GEMS and the Good Connect Client within Good Control’s application management handler. This is required for each GEMS machine, individually and clustered. This configuration information dictates the available servers to which a Good Connect client may connect. Important: The Good Connect application must be published in Good Control. For prerequisite details on setting up Good Control, see Good Dynamics Requirements. To learn how to add the Good Control app, see "Registering a New Application" in the GC console's online help. To add server pool and IM platform information in Good Control: 1. In the navigator under APPS, click Manage Apps, then search for or scroll down to select Good Connect. 2. Under the ENTERPRISE tab, scroll down or search for Good Connect. 3. Click it to open, then click the GOOD DYNAMICS tab. 4. In the Server section, click EDIT.

5. For each GEMS machine deployed: a. Click the Add icon

.

b. In the new HOST NAME field, enter the FQDN of the Connect service host.

Installation and Configuration Guide

115

Configuring GEMS Services

c. In the PORTfield, enter the corresponding port (typically 8080). d. For each GEMS machine, enter the following information in the Configuration field: PLATFORM=LYNC SERVERS= Consult the Good Control online help utility for additional information. Next, you’re ready to list the approved GEMS hostnames and ports for client connections.

Defining Allowed Domains and Servers Allowed domains and servers within your enterprise network to which the Good Collaboration client apps can connect are defined in Good Control’s Client Connections option under SETTINGS. It is strongly recommended that you whitelist each individual GEMS. Here, the domain you are trying to configure is the one that allows GD connections to your Microsoft Exchange server and your host and port(s) for Connect IM. Whitelisting means that domains and servers on the list will be accepted, approved or recognized. It is the reverse of blacklisting—the practice of identifying those that are denied or unrecognized. To whitelist allowed domains and servers: 1. In the Good Control navigator, under POLICIES, click Client Connections, 2. Under Base Profile, click Master Connection Profile, then open the INFRASTRUCTURE tab and scroll down to Additional Servers.

Installation and Configuration Guide

116

Configuring GEMS Services

This is a list of specific servers with which all GD applications can connect. Add servers to this list instead of using the ALLOWED DOMAINS list if you want to restrict access so that GD applications can only connect to certain servers—like GEMS and Exchange—and not to every machine in a domain. To add an allowed server: 1. Click Edit, then at the bottom of the list click ADD. 2. Enter the SERVERfully qualified hostname and PORTin the respective fields.

3. Assign a primary and secondary GP cluster for the server, if applicable. Connections through GP servers in the primary cluster are attempted first, and if no responses are received, connections are attempted through GP servers in the secondary cluster. 4. Click Save. As indicated at the beginning of this topic, you can also whitelist or block domains. To remove a server or domain from the list: 1. Click the corresponding

.

2. Confirm delete, then click Save. 3. Click Save. To whitelist GEMS: 1. Follow the instructions above to add a server. 2. For Host Name, enter the FQDN of the GEMS-Connect server; for Port, use port 8080. 3. Make sure to save your changes. So, for example, your Connectivity Profile with GEMS-Presence and GEMS-Connect configured might look something like this:

Installation and Configuration Guide

117

Configuring GEMS Services

Setting Policy Governing Disclaimer Text Via Good Control, you can choose the option to display a Corporate Policy disclaimer at the top over every new conversation (IM) within each Connect Service client; for example: “Use of this service, a company IT asset, is subject to the proper conduct, secure use and handling policies found in the XYZ Employee Handbook.” To set or add a disclaimer via Good Control: 1. In the navigator under POLICIES, click Policy Sets, then select the policy set you want to govern Good Connect (e.g., "Default Policy"). 2. Click the APPS tab, then expand APP SPECIFIC POLICIES, scroll down to GOOD CONNECT and click it. 3. Open the Disclaimer tab. 4. Enable (check) the Display Disclaimer option. 5. Type or paste in your approved Disclaimer Text (250 characters max).

6. Click Update to save and display this disclaimer at the top of each new client conversation window.

Installation and Configuration Guide

118

Configuring GEMS Services

Establishing User Affinity In clustered environments, client affinity can be used to map a client to a GEMS machine for the duration of the client session. This makes it possible for a GEMS administrator to pin a user to a cluster of GEMS machines, instead of letting the system randomly assign this particular user to a server from a master list. To better understand how to use affinity assignments, consider the following example. XYZ Inc. has two Lync pools—a West Coast pool hosting users in XYZ’s West Coast offices, and an East Coast pool, which hosts users in the firm’s East Coast offices—so IT deploys a Connect server for each pool, while only setting up one Good Control and Good Proxy cluster, as pictured.

Unless affinity is configured, when Aaron Beard launches his Good Works client, Good Control sends a list of servers that includes both East Coast and West Coast servers and Aaron’s client randomly chooses which one with which to connect. Even though Aaron is a West Coast user, there’s a strong chance he’ll actually be served by the East Coast server. By contrast, when user affinity is enabled, it means Aaron will always connect to the West Coast server. To enable User Affinity for Connect: 1. In the navigator under POLICIES, click Policy Sets, and select the policy set corresponding to user affinity assignments you want to associate with Good Connect (e.g., "West Coast Users"). 2. Open the APPS tab, expand APP SPECIFIC POLICIES, and select GOOD CONNECT . 3. Click the Server Configuration tab. 4. Enter (type or paste) your Connect Server Hosts separated by commas in the following format: :,:,: Example: westcoast1.xyzcorp.com:8080,westcoast2.xyzcorp.com:8080,eastcoast1.xyzcorp.com:8080 5. Select a Platform (e.g., LYNC).

Installation and Configuration Guide

119

Configuring GEMS Services

6. Next, in the navigator under USERS, click Users and Groups. 7. Select the user(s) for whom you want to establish an affinity policy by marking the corresponding checkbox, then from the User Actions list box, select Edit User. 8. Then click Edit.

Installation and Configuration Guide

120

Configuring GEMS Services

9. From the Policy Set dropdown, assign the user to the appropriate policy set.

10. From the User Actions list box, select Refresh to confirm the change and update the user account.

Enabling/Disabling Conversation History Saving conversation histories on respective user devices in enabled by default in Good Control. The GEMS Connect Service supports the option to limit storing conversation histories of more than 40 messages on client devices. The decision to do so could be in support of standard enterprise security policy, to conserve physical storage availability on devices, or for any other reason. To configure the Conversation History option: 1. In the Good Control navigator under POLICIES, click Policy Sets, then select the policy set(s) governing Good Connect. 2. Click the APPS tab, then expand APP SPECIFIC POLICIES and scroll down to select GOOD CONNECT and click the Conversation History tab. 3. Click the Conversation History tab, then enable/disable Save more than 40 messages in a conversation history on the device. 4. Enable/disable the Purge chat messages older than property; then, if enabled, set the interval.

Installation and Configuration Guide

121

Configuring GEMS Services

5. Click Update.

Controlling Browser and Map Behavior GEMS supports the option to control whether or not the local device browser application is invoked when tapping on a Web page URL within a Good Work or Good Connect contact, conversation, or email, and if the device’s map application can be used when tapping an address. Both browser and map access are allowed by default in Good Control. To disable either browser or map access or both from Good Work or Good Connect : 1. In the navigator under POLICIES, click Policy Sets, then select the policy set governing the application you want to set; i.e., Good Connect or Good Work. 2. Open the APPS tab, expand APP SPECIFIC POLICY, then select the app (GOOD CONNECT or GOOD WORK . 3. Click the App Settings tab. 4. Disable (uncheck) either option or both, then click Update.

Here, it's important to remember that Good Control Policy Sets are assigned to provisioned devices running the application governed by the policy's permissions. When the app is activated by the user, a policy's permissions and restrictions are applied immediately.

Installation and Configuration Guide

122

Configuring GEMS Services

Configuring GEMS-Connect for HA ((Not supported for Connect using Cisco Jabber.) Like GEMS-PNS, high availability (HA) for GEMS-Connect is based on clustering. The GEMS-CONNECT service supports HA by adding additional GEMS servers running the GEMS-Connect service in a cluster. When adding a new GEMS-Connect instance for HA, you will need to: 1. Configure your new GEMS-Connect instance to use the existing database. 2. Configure your new GEMS-Connect instance to point to the same Good Proxy server. 3. Whitelist your new GEMS-Connect server host and port in Good Control. 4. Configure your new GEMS-Connect instance in Good Control for the Good Connect app. If you have GEMS-Connect user affinity configured, be sure to add the new GEMS-Connect instances to your affinity list as well.

Lync Front-End (FE) Pool Consideration If your Lync environment has more than one FE pool—especially if it’s a FE pool for HA—it is recommended that you create an additional Trusted Application Pool for your GEMS-Connect HA instances. The additional Trusted Application Pool should be created in your FE HA pool. For instance, let's assume you have FE Pool1 for general use and FE Pool2 for HA. In which case, you would create a Trusted Application Pool in FE Pool1 for your primary GEMS-Connect instances and a Trusted Application Pool in FE Pool2 for your GEMS-Connect HA instances. See Creating an Additional Trusted Application Pool above for details.

Configuring GEMS-Connect for DR Disaster Recovery (DR) for GEMS-CONNECT is based on an active/cold standby clustering model. (Not supported for Connect using Cisco Jabber.) Before adding a GEMS-Connect instance for DR, you will need to: 1. Evaluate your Lync Disaster Recovery strategy. If you have separate Front End (FE) pools for DR, it is recommended that you create a separate Trusted Application Pool for your GEMS-Connect instances. This separate Trusted Application Pool should be associated with the DR Front End pool. Associate all DR GEMS-Connect instances to this Trusted Application Pool. If you don’t have separate Front End pools for DR, then using a single Trusted Application Pool is fine, although you must make sure your Lync DR strategy properly preserves the Trusted Application Pool in event of a failover. 2. Ensure that the appropriate network ports are open to allow GEMS-Connect servers in your DR site to communicate with database, Lync, Lync DB, and Good Proxy servers in your DR and Primary site.

Installation and Configuration Guide

123

Configuring GEMS Services

When adding a new DR GEMS-Connect instance, you will need to: 1. Create a GEMS-Connect database on the DB server in the DR site. Use the schema files that came with the software to manually extend the schema. Only one database is needed for all DR GEMS-Connect instances. 2. Do not provide the name of the GEMS-Connect database during the DR GEMS-Connect installation. 3. After the installation, configure GEMS-Connect to use the database in the DR site. 4. Configure your DR GEMS-Connect instance to use the secondary Good Proxy server in the cluster. 5. Whitelist your DR GEMS-Connect server host and port in Good Control [see Defining Allowed Domains and Servers). 6. Configure your DR GEMS-Connect instance in Good Control for the Good Connect App (see Configuring Good Control for Connect). Be sure to set the PRIORITY setting to Secondary or Tertiary. Important: After the DR GEMS-Connect instance is installed and configure, you will need to stop the Good Technology Connect Service. This places the DR GEMS-Connect instance in cold standby. In a DR situation in which you want to failover, you will need to: 1. Stop the Good Technology Connect service on all your Primary GEMS-Connect instances. 2. Start the Good Technology Connect service on your DR GEMS-Connect instance.

Using Friendly Names for Certificates in Connect The friendly name of a certificate can be helpful when multiple certificates with a similar subject exist in a certificate store. Friendly names are properties in the X.509 certificate store that associate aliases with certificates so they can be easily identified. You can restrict certificates used for GEMS-Connect to a Friendly Name by: a. Creating and enrolling a certificate, if you don't already have one b. Changing the certificate Friendly Name and Description, and c. Setting the new certificate friendly name string value in the Good Connect Server configuration file (GoodConnectServer.exe.config). If you do not already have a certificate, you can create and verify a GEMS SSL Certificate for Lync by following the guidance under GEMS Prerequisites, above, for creating and adding the GEMS SSL certificate for Lync. To change the certificate Friendly Name and Description: 1. Open a command prompt and run mmc. 2. Select File > Add/Remove Snap-in. 3. Click Certificates, click Add, click Computer Account, then click Next. 4. Click Local Computer, click Finish, and then clickOK. 5. Select Certificates (Local Computer) > Personal > Certificates.

Installation and Configuration Guide

124

Configuring GEMS Services

6. Locate the certificate you want to change and double-click it.

7. Open the Details tab and select Show: , then click Edit Properties... 8. Enter a Friendly Name. 9. Enter a Description. 10. Click Apply, then OK to save your changes. 11. Click OK again, to exit the Certificate popup. You're now ready to set the certificate's new Friendly Name in the configuration file for the GEMS-Connect service.

Installation and Configuration Guide

125

Configuring GEMS Services

To update the Good Connect Server configuration file: 1. Open GoodConnectServer.exe.config in your favorite text editor. You can find the file in \Good Technology\Good Server\Good Connect Server\GoodConnectServer.exe.config.. 2. Add the following line (or change its value if it has already been added):

Note: The value for is case-sensitive. Enter it exactly as you see it from the certificate. 3. Save your changes. 4. Restart the Good Technology Connect service in the Windows Service Manager for this change to take effect.

Enabling SSL Support Via Good Proxy In the diagram below, the blue lines indicate the path to the GEMS machine from each Good Work client. Although SSL is disabled by default, GEMS can be configured to run securely using SSL/TLS (HTTPS) to communicate with clients through Good Proxy.

As discussed under prerequisites, GEMS requires a signed server SSL certificate from a third-party Certificate Authority (CA). The following step-by-step details will guide you in enabling SSL support via Good Proxy: l

Importing the CA-signed certificate to the GEMS machine

l

Binding the SSL certificate to the Connect SSL port

Installation and Configuration Guide

126

Configuring GEMS Services

l

Adding the certificate to the GEMS-Connect configuration file

l

Configuring Good Control to send requests over SSL

l

Configuring GEMS-Connect to use SSL with Good Proxy

l

Troubleshooting SSL certificate exceptions

Submitting the CSR to a Certificate Authority (CA) If you need to send the new CSR to a well-known third-party CA and purchase a certificate for your server, the third-party CA may also send you a file that contains the full certificate chain, including possible intermediate certificates. Well-known third-party CAs include: l

Symantec

l

Thawte

l

GeoTrust

l

GlobalSign

l

DigiCert

When the issued certificate is received, it is important that it be installed on the same server that generated the CSR. To do so, after the new certificate is issued, you must: l

Import the CA-signed SSL certificate to the GEMS machine

l

Bind the issued certificate to the GEMS machine's SSL port

l

Add the new certificate information to the GEMS configuration file

l

Upload the CA certificate to Good Control

l

Configure Good Control to send requests over SSL

Importing the Signed Certificate Installing the signed certificate is done on the GEMS machine with the GEMS service account. Thus, to install a well-known third-party CA-signed SSL certificate for GEMS, login with the Submitting the CSR to a Certificate Authority (CA) GEMS service account, and then:

Installation and Configuration Guide

127

Configuring GEMS Services

1. Click Start > Run, enter mmc, and click OK.

2. After the MMC launches, click File > Add/Remove Snap-in…

Installation and Configuration Guide

128

Configuring GEMS Services

3. Select Certificates in the left panel and click Add to move it into the right panel, then click OK.

4. Select the Computer account option and click Next.

5. Confirm that Local computer is selected and click Finish.

Installation and Configuration Guide

129

Configuring GEMS Services

6. Click OK to confirm Certificates in the Console Root.

7. Launch import of the trusted root certificate by expanding Certificates (Local Computer) in the panel on the left, then right-clicking Personal > All Tasks > Import.

8. Once the Certificate Import Wizard opens, click Next. 9. Specify the file you want to import; e.g., the certificate received after submitting a CSR to a well-known, thirdparty CA; and click Next. 10. Click Next to confirm placing the certificate in the Personal store, then click Finish to import the certificate.

Installation and Configuration Guide

130

Configuring GEMS Services

11. Click OK when informed that the import was successful.

Next, you’re ready to bind the certificate to the server.

Binding the SSL Certificate to the Connect SSL Port Before binding the certificate to the GEMS machine’s SSL port, you must first import the third-party CA-signed certificate to the GEMS machine. If import was successful, complete the binding exercise that follows here. Binding must be completed prior to configuring Good Control to use the new certificate. To bind the new certificate to the GEMS machine's SSL port: 1. Login to the GEMS machine with the correct service account. 2. In the MMC’s Certificate Snap-in, double-click the certificate, then click on Details to switch to that tab. 3. Change the Show value to Properties Only. 4. Click Thumbprint. 5. Copy the thumbprint value in the lower textbox.

6. Paste the copied thumbprint into a text editor and remove all the spaces, so that “80 82 41 2f …” becomes “0882412f…” 7. Copy this edited version of the thumbnail to the clipboard. 8. Check that a certificate is not already bound to port 8082 (e.g., a certificate has already been installed) by opening a command prompt as an administrator and entering the following command string: > netsh http show sslcert

Installation and Configuration Guide

131

Configuring GEMS Services

Note: if a certificate is already bound to port 8082, you will not be able to bind a new certificate until the existing one is deleted. You can delete the certificate bound to port 8082 by executing the following command: Netsh http delete sslcert ipport=0.0.0.0:8082 You should receive a confirmation that the deletion is complete. You can then add the new certificate. 9. Open a command prompt as an administrator and enter the following command string: > netsh http add sslcert ipport=0.0.0.0: certhash= appid={AD67330E-7F41-4722-83E2F6DF9687BC71}

replacing with the port number you want to use (e.g., 8082) and with the contents of the clipboard. The appid is an arbitrary GUID value. 10. Confirm the certificate binding by executing the following command: > netsh http show sslcert

If the certificate is properly bound, you’re ready to: l

Add the new certificate information to the GEMS configuration file

l

Configure Good Control to send requests over SSL

If binding fails, see Troubleshooting SSL Certificate Exceptions.

Modifying the GEMS-Connect Configuration File with the New Certificate Some important configuration file changes are necessary to allow Good Connect to use the new SSL certificate. Before continuing, however, it is recommended that you make a backup copy of the current Good Connect server configuration file. Next, for discussion purposes here, it is assumed that you have installed GEMS in the default directory location on the server. Adjust the drive:\path\ for your deployment as necessary. To modify the server configuration to use the correct SSL certificate, open C:\Program Files\Good Technology\Good Server\Good Connect\GoodConnectServer.exe.config and: a. Find this value is the configuration file:

b. Change it to this:

Note: Save your changes, then restart the Good Technology Connect service in the Windows Service Manager for these changes to take effect.

Installation and Configuration Guide

132

Configuring GEMS Services

Configuring Good Control to Send Requests over SSL There are only a couple of changes needed in the Good Control console to enable client SSL connections with GEMS. These configuration settings involve making sure that: l

Any server previously installed without SSL, including prior implementations of Good Connect and Connect Server, has its FQDN added and associated with the new SSL port. Previously installed non-SSL Good Connect Configuring GEMS-Connect to Use SSL with Good Proxy servers and Connect Service servers must be removed from Good Control.

l

The format and port information for servers listed in the configuration must be prepended with https:// and assigned to the new SSL port.

To change the necessary application server settings in Good Control (pictured below): 1. Open your Good Control console. 2. In the navigator under APPS, click Manage Apps. 3. Search for or scroll down to GOOD CONNECT, click it, and open the GOOD DYNAMICS tab. 4. In the Server section, click EDIT, then click

to add a server; click

to edit an existing server.

5. Under HOST NAME, enter the fully qualified domain name (FQDN) of each GEMS-Connect Server. 6. Under PORT, enter the SSL port; typically, 8080 or8082. 7. In the Configuration text box, prepend each listed FQDN with https:// and change its port assignment to the Connect SSL port; e.g., 8082.

To change user affinity-clustering: 1. Click on Policy Sets in the navigator, select the policy to modify and open the APPS tab. 2. Expand APP SPECIFIC POLICIES, scroll down and select GOOD CONNECT, then open the Server Configuration tab. 3. Change the port numbers in Connect Server Hosts to the new SSL port for GEMS.

Installation and Configuration Guide

133

Configuring GEMS Services

Configuring GEMS-Connect to Use SSL with Good Proxy By default, the Good Proxy server uses a certificate that is signed by the Good Control CA—a private CA—which means GEMS-Connect will not trust it by default. In order for GEMS-Connect to trust the Good Proxy server’s certificate, you must upload Good Control’s CA certificate to the GEMS-Connect server’s Windows keystore. Although there are a variety of ways to export the Good Control CA certificate, the easiest method is to use the Firefox browser. To export the Good Control CA certificate using Firefox: 1. Navigate to the Good Control URL from Firefox. 2. In the Firefox URL bar click on the lock icon (to the left of the URL address), then click More Information. 3. Click Security, then click View Certificate. 4. Open the Details tab and then expand the GC CA entry (should be the very first under Certificate Hierarchy). 5. Click Export.

Once you have the GC CA certificate, you must now import it into the Windows keystore.

Installation and Configuration Guide

134

Configuring GEMS Services

To import the certificate to the Windows keystore: 1. Open a Windows MMC and select File > Add/Remove Snap-in > Certificates. 2. Select Computer Account > Local computer > OK. 3. Expand Certificates > Trusted Root Certification Authorities > Certificates. 4. Right-click the Certificates folder, then select All Tasks > Import. 5. Select the GC CA certificate and import it. Now that the GC CA certificate is imported into the Windows keystore, go back to the GEMS Dashboard and navigate to Connect > Good Dynamics and configure HTTPS.

Upload the CA Certificate to Good Control If your certificate is signed with an internal certificate authority (i.e., private CA), you must upload the CA certificate to Good Control. Doing this allows the Good Connect client to trust your certificate. If you do not upload your private CA certificate to Good Control, Good Connect will not be able to connect to the GEMSConnect service. To upload your CA certificate to Good Control: 1. Obtain a copy of your CA certificate. Consult your certificate administrator if you do not have access to the CA certificate. 2. Login to Good Control as an administrator. 3. Under SETTINGS, click Certificates and open the SERVER CERTIFICATES tab. 4. Click

button to browse for the appropriate certificate and upload it.

5. Click Apply to save your changes. Upon uploading the certificate, Good Control automatically distributes it to all GD apps, including Good Connect.

Troubleshooting SSL Certificate Exceptions Despite meeting all of the SSL certificate requirements defined under Enabling SSL Support via Good Proxy, you may continue to get the following error: Description: The process was terminated due to an unhandled exception. Exception Info: Microsoft.Rtc.Internal.Sip.TLSException If so, the most likely explanation is that the SSL certificate was not created with the correct CSP and key spec. The KeySpec property sets or retrieves the type of key generated. Valid values are determined by the cryptographic service provider (CSP) in use, typically Microsoft RSA. To check the certificate’s CSP and KeySpec: 1. Open cmd/powershell on the GEMS machine and execute the following command: certutil.exe –v –store “my”

” > c:\temp\ssl.txt

Installation and Configuration Guide

135

Configuring GEMS Services

2. Open c:\temp\ssl.txt in a text editor and search for “CERT_KEY_PROV_INFO_PROP_ID.” The search should return the following: CERT_KEY_PROV_INFO_PROP_ID(2): Key Container = 9ad85141c0b791ad17f0687d00358b70_dd7675d5-867d-479c-90b0-cd24435fe903 Provider = Microsoft RSA SChannel Cryptographic Provider ProviderType = c Flags = 20 KeySpec = 1 -- AT_KEYEXCHANGE

If the values for Provider, ProviderType, and KeySpec are not exactly the same as those shown above, you will need to have the CA reissue a new SSL with appropriate provider and key spec values.

Configuring Support for the Global Catalog In a multi-domain Active Directory Domain Services (AD DS) forest, the global catalog provides a central repository of domain information for the forest by storing partial replicas of all domain directory partitions. These partial replicas are distributed by multimaster replication to all global catalog servers in a forest. In this way, the global catalog makes the directory structure within a forest transparent to users who perform a search. Without a global catalog server, this query would require a search of every domain in the forest. During an interactive domain logon, the domain controller authenticates the user by verifying the user’s identity, and also provides authorization data for the user’s access token by determining all groups of which the user is a member. Because the global catalog is the forest-wide location of the membership of all universal groups, access to a global catalog server is a requirement for authentication in a multidomain forest. A global catalog server is also required for Microsoft Exchange Server. To support Good collaboration suite users from multiple domains within the same forest, the following modifications using the Active Directory Schema MMC Snap-In will enable users to be accessed from the Global Catalog: 1. Click the Attributes folder in the snap-in. 2. In the right panel, scroll down to the desired attribute, right-click it, and then click Properties. 3. Click to select the Replicate this attribute to the Global Catalog check box. 4. Click OK. 5. Verify that the following attributes are published to the Global Catalog: l

msrt-primaryuseraddress

l

mail

l

telephoneNumber

l

displayname

l

title

l

mobile

l

givenName

Installation and Configuration Guide

136

Configuring GEMS Services

l

sn

l

sAMAccountName

l

msRTCSIP-UserEnabled

l

msRTCSIP-UserAddress

6. Edit the following configuration parameters in the GoodConnectServer.exe.config file installed by default in the C:\Program Files\Good Technology\Good Enterprise Mobility Server\Good Connect folder: Note: You must restart Good Technology Connect Service in the Windows Service Manager after updating the parameters.

Configuring Windows Services Good Connect Server is now listed in the Microsoft Windows Services UI. By opening it, you can review its current status.

If you select the Log On tab, you should see the Service Account user you entered for the Connect service the GEMS Dashboard.

Installation and Configuration Guide

137

Configuring GEMS Services

In order for Connect to run as another domain user, the following must be true: l

The alternate domain user must have access to the private key of the computer certificate. See Identifying/Acquiring a Valid SSL Certificate for details.

l

The alternate domain user must be enabled to “Log on as service” through the Local Security Policy tool.

To give your GEMS account Log on as service privileges: 1. Run the Local Security Policy admin tool on the Good Connect host. 2. Expand the Local Policies folder in the navigator on the left.

3. Select the User Rights Assignments folder to see a list of policies. 4. Double-click Log on as a service to add this policy to the Good Connect account.

Connect Service Logging and Diagnostics Server logs and performance information for the Connect Service can be found in the GEMS installation direction directory.

Log File Location The default GEMS host installation directory is: C:\Program Files\Good Technology\Good Enterprise Mobility Server All log directories are relative to this path. GEMS Connect Service Log \Good Connect\logs\Application-log_.txt

Installation and Configuration Guide

138

Configuring GEMS Services

Common Good Connect Issues The most common issues can be diagnosed by properly analyzing the appropriate log file when encountering IM or preference issues. For troubleshooting, entries like the following examples are generally the most revealing: Example 1 Log Entry: Failed to start GoodConnectServer: Microsoft.Rtc.Signaling.ConnectionFailureException: Unable to establish a connection. ---> System.Net.Sockets.SocketException: No such host is known.

Issue: The hostname value in the configuration file for the key OCS_SERVER does not exist or is not recognized as a valid server. Resolution: Correct the OCS_SERVER value in the configuration file. Example 2 Log Entry: DeregisterReason=None ResponseCode=480 ResponseText=Temporarily Unavailable Microsoft.Rtc.Signaling.RegisterException: The endpoint was unable to register. See the ErrorCode for specific reason.

Issue: The port number specified in OCS_PORT_TLS is not valid. Resolution: Correct OCS_PORT_TLS value in the configuration file. Example 3 Log Entry: ErrorCode=-2146233088 FailureReason=RemoteDisconnected LocalEndpoint=10.120.165.137:5060 RemoteEndpoint=10.120.167.109:55118 RemoteCertificate= Microsoft.Rtc.Signaling.TlsFailureException: Unknown error (0x80131500) --> Microsoft.Rtc.Internal.Sip.RemoteDisconnectedException: Remote disconnected while outgoing tls negotiation was in progress --> System.Net.Sockets.SocketException: An existing connection was forcibly closed by the remote host.

Issue: OCS_TRANSPORT was specified as TLS, however the port number provided was TCP. Resolution: Change the OCS_PORT_TLS to 5061. Example 4 Log Entry: Failed to start GoodConnectServer: Microsoft.Rtc.Signaling.ConnectionFailureException: Failed to listen on any address and port supplied.

Installation and Configuration Guide

139

Configuring GEMS Services

Issue: Port number specified for UCMA_APPLICATION_PORT in the configuration file is either blocked by a firewall or used by another application. Resolution: Unblock port if it is a firewall issue or choose another port number. Example 5 Log Entry: Failed to start GoodConnectServer: WCFGaslampServiceLibrary.OCSCertificateNotFoundException: Certificate not found.

Issue: The certificate's subjectName must contain the local host's FQDN and the private key for the cert must be enabled for the user which executes the GEMS software. Resolution: Enable private keys for this cert for the user running the GEMS machine.

Configuring the Presence Service Configuring the GEMS-Presence to support both Good Work and other third-party apps running on the Good Dynamics platform entails a few steps. These include: l

Configuring Presence in the GEMS Dashboard

l

Configuring Good Control for Presence

Configuring Presence in the GEMS Dashboard (Lync) The Presence service exposes the Lync Presence Provider (LPP) to third-party Good Dynamics applications. Setting up the Presence service is similar to configuring the Connect service. It can be reduced to the following four steps: a. Service Account: Enter the GEMS Service Account, but only after making sure this service account has RTCUniversalReadOnlyAdmins rights. Click Save to record these settings. b. Good Dynamics: Enter the Good Proxy Hostname. Use the Test button to test the connection. Click Save to record these settings. c. Settings: Default settings are typically sufficient. d. Lync 2010/2013 – After clicking on this setting, the system will dynamically query the Lync Server to see if the appropriate GEMS Lync topology has been added. It will typically take a few moments for the query to complete, so please be patient. For Application ID, select the Lync Presence Provider application ID, then select the corresponding Application Endpoint. If the listboxes are empty, this means that either the GEMS Lync topology was not setup correctly or the service account does not have the proper permissions to query these settings. To configure the Presence service for your environment: 1. Click Presence under Good Services Configuration.

Installation and Configuration Guide

140

Configuring GEMS Services

2. Complete Steps a thru d above, accessing each section from the GOOD PRESENCE SERVICE CONFIGURATION page, beginning with Service Account.

3. Use the Test button to test connectivity. 4. Click Save when done.

Additional resources for App Developers If you are a GD app developer seeking to incorporate the presence service in your apps, the following will be useful links: l

Good Presence Service API

l

Good Presence Sample app

Installation and Configuration Guide

141

Configuring GEMS Services

Configuring Presence in the GEMS Dashboard (Jabber) To configure the Presence service for your environment: 1. Tap Presence in the GEMS dashboard.

2. For Settings, use the default values. 3. Tap Jabber.

4. Enter the Jabber configuration information and click Save. (The Test button confirms that all fields are filled out, but not whether the entered information is correct or not.)

Installation and Configuration Guide

142

Configuring GEMS Services

Cisco Unified Communications Manager User Data Service (UDS) FQDN - ciscoUdsServer. The Cisco server that JPP needs to query the contact cards. Type is String. Example: cucm.g3.qa.com Cisco Unified Communications Manager User Data Service (UDS) port - ciscoUdsPort. The Cisco server port that JPP needs to use with ciscoUdsServer for querying the contact cards. Type is numeric. Example: 8443 Presence SIP domain: (e.g., office.domain.tld) - ciscoDomain. The domain that Cisco Jabber server belongs to. Type is String. Example: g3.qagood.com Cisco Unified Communications Manager Server User - udsUserUsername. This is the Cisco Jabber server user (not LDAP user). It is a dummy user that uses to get presences of subscribed contacts. Type is String. Example: dummy. Note: For multiple GEMS servers, this user must be the same. REST-based Client Configuration Web Service Endpoint - axisConfigUrl. The endpoint where the RESTbased Client Configuration Web Service is hosted. Type is String. Example: https://cimp.g3.qagood.com:8443/EPASSoap/service REST-based Presence Web Service Endpoint - presenceRestUrl. The URL where the REST-based Presence Web Service is hosted. Type is String. Example: https://cimp.g3.qagood.com:8083/presence-service Application Username - applicationUserUsername. The username of the application user. Type is String. Example: g3admin. Note: For multiple GEMS servers, this username must be different. Application Password - applicationUserPassword. The password of the application user. Type is String GEMS Presence Keystore File Location - keystoreFile. This is the keystore file that we have to import for JPP (please refer to Requirements for Jabber Presence to know what to import). This is an optional parameter, we import certs into default java keystore. 5. Restart the Good common service. Restart this service whenever a change is made tothe Jabber configuration settings on this page, or when performing a Repair with the installation media. Jabber Presence is configured in the GC console in the same way as Lync.

Configuring Good Control for Presence Presence is currently one of three services, along with Follow-Me and Directory Lookup, enabled through Good Control via the Good Enterprise Services entitlement app. You only have to add GEMS as the application server to GES entitlement once to enable all three services, rather than for each service individually. See Configuring Good Enterprise Services in Good Control for guidance. Note: You will only need to configure GEMS for services entitlement once to cover all three service; i.e., Presence, Follow-Me, and Directory Lookup. Otherwise, setting up the Presence service for Good Work involves: l

Adding GEMS to the Good Work Application Server List

l

Configuring Presence Affinity for the Good Work app

Installation and Configuration Guide

143

Configuring GEMS Services

Adding GEMS to the Good Work Application Server List The Good Work client checks the Good Work server list for available GEMS instances hosting the Presence service. Hence, the list must be populated with at least one GEMS machine configured for the Good Enterprise Services entitlement app. When multiple GEMS hosts are listed, you can use Good Work's Preferred Presence Server Configuration parameter to set up a presence affinity association (see Configuring Presence Affinity for Good Work). To add GEMS to the Good Work application server list: 1. Under APPS, click Manage Apps, search for or scroll down to Good Work and click it. 2. Click the GOOD DYNAMICS tab, then, in the Server section, click EDIT. 3. Enter the GEMS host FQDN in the Host Name field, then enter 8443 under Port.

Note: Unless you import a publicly verifiable certificate into the GEMS Java keystore, please be aware of the following: 1. Access to the GEMS Dashboard from a browser will show an untrusted SSL certificate. 2. You will need to upload the GEMS certificate to Good Control. 4. If you have additional GEMS hosts, configure them for the application in the same way, after clicking

to

add a new row. 5. Click Save to commit your changes.

Configuring Presence Affinity for Good Work Presence affinity for Good Work is configured in Good Control's Application Policies. Presence affinity is optional. Be aware, however, that once you set affinity, it takes precedence.

Installation and Configuration Guide

144

Configuring GEMS Services

Caution: When a distributed computer system is truly load balanced, each request is routed to a different server. This load balancing approach is diminished when server affinity techniques are applied. To set Presence Affinity for Good Work: 1. In the Good Control navigator under POLICIES, click Policy Sets. 2. Locate the policy you want to apply and click it. 3. Click the APPS tab, then expand APP SPECIFIC POLICIES. 4. Scroll down to GOOD WORK and click it. The App Settings tab should be open by default. If not, click it. 5. Scroll to PREFERRED PRESENCE SERVER CONFIGURATION. 6. In the Server Hosts field, enter in the FQDN of your GEMS host and a colon followed by port 8443. As desired, add more servers separated by a comma and no space.

7. Click Update. Repeat for every other policy that will govern Good Work Presence.

Configuring GEMS-Presence for HA The GEMS-Presence service supports high availability (HA) by adding additional GEMS servers running the GEMSpresence service. When adding a new GEMS-Presence instance for HA, you will need to: 1. Configure your new GEMS-Presence instance to point to the same Good Proxy server. 2. Whitelist your new GEMS-Presence server host and port in Good Control (see Defining Allowed Domains and Servers).

Installation and Configuration Guide

145

Configuring GEMS Services

3. Configure your new GEMS-Presence instance in Good Control for the Good Work App (see Adding GEMS to the Good Work Application Server List). 4. Configure your new GEMS-Presence instance in Good Control for the Good Enterprise Services Entitlement app see Adding GEMS to the Good Enterprise Services Entitlement App). If you have GEMS-Presence user affinity configured, be sure to add the new GEMS-PRESENCE instances to your affinity list as well.

Lync Front-End (FE) Pool Consideration If your Lync environment has more than one FE pool—especially if it’s a FE pool for HA—it is recommended that you create an additional Trusted Application Pool for your GEMS-Presence HA instances. The additional Trusted Application Pool should be created in your FE HA pool. For instance, let's assume you have FE Pool1 for general use and FE Pool2 for HA. In which case, you would create a Trusted Application Pool in FE Pool1 for your primary GEMS-Presence instances and a Trusted Application Pool in FE Pool2 for your GEMS-Presence HA instances. See Creating an Additional Trusted Application Pool above for details.

Configuring GEMS-Presence for DR Like for other GEMS services, disaster recovery (DR) for GEMS-Presence is based on an active/cold standby model. Before adding a GEMS-PRESENCE instance for DR, you will need to: 1. Evaluate your Lync Disaster Recovery strategy. If you have separate Front End (FE) pools for DR, it is recommended that you create a separate Trusted Application Pool for your GEMS-Presence instances. This separate Trusted Application Pool should be associated with the DR Front End pool. Associate all DR GEMS-Presence instances to this Trusted Application Pool. If you don’t have separate Front End pools for DR, using a single Trusted Application Pool is fine as long as you make sure your Lync DR strategy properly preserves the Trusted Application Pool in the event of a failover. Note: GEMS-Presence and GEMS-Connect can use the same Trusted Application Pool for DR. 2. Ensure that the appropriate network ports are open to allow GEMS-Presence servers in your DR site to communicate with database, Lync, Lync DB, and Good Proxy servers in your DR and Primary site. When adding a new DR GEMS-Presence instance, you will need to: 1. Configure your DR GEMS-Presence instance to use the secondary Good Proxy server in the cluster. 2. Whitelist your DR GEMS-Presence server host and port in Good Control (see Defining Allowed Domains and Servers).

Installation and Configuration Guide

146

Configuring GEMS Services

3. Configure your DR GEMS-Presence instance in Good Control for the Good Work App (see Adding GEMS to the Good Work Application Server List). Be sure to set the PRIORITY setting to Secondary or Tertiary. 4. Configure your DR GEMS-Presence instance in Good Control for the Good Enterprise Services Entitlement App (see Adding GEMS to the Good Enterprise Services Entitlement App). Be sure to set the PRIORITY setting to Secondary or Tertiary. Important: After the DR GEMS-Presence instance is installed and configure, you will need to stop the Good Technology Presence service. This places the DR GEMS-Presence instance in cold standby. In a DR situation in which you want to failover, you will need to: 1. Stop the Good Technology Presence service on all your Primary GEMS-Presence instances. 2. Start the Good Technology Presence service on your DR GEMS-Presence instance.

Using Friendly Names for Certificates in Presence The friendly name of a certificate can be helpful when multiple certificates with a similar subject exist in a certificate store. Friendly names are properties in the X.509 certificate store that associate aliases with certificates so they can be easily identified. You can restrict certificates used for GEMS-Presence to a Friendly Name by: a. Creating and enrolling a certificate, if you don't already have one b. Changing the certificate Friendly Name and Description, and c. Setting the new certificate friendly name string value in the GEMS Lync Presence Provider (LPP) Service configuration file. If you do not already have a certificate, you can create and verify a certificate for the Lync Presence Provider (LPP) by following the guidance under GEMS Prerequisites, above, for requesting a GEMS certificate from a local AD certificate authority. To change the certificate Friendly Name and Description: 1. Open a command prompt and run mmc. 2. Select File > Add/Remove Snap-in. 3. Click Certificates, click Add, click Computer Account, then click Next. 4. Click Local Computer, click Finish, and then clickOK. 5. Select Certificates (Local Computer) > Personal > Certificates.

Installation and Configuration Guide

147

Configuring GEMS Services

6. Locate the certificate you want to change and double-click it.

7. Open the Details tab and select Show: , then click Edit Properties... 8. Enter a Friendly Name. 9. Enter a Description. 10. Click Apply, then OK to save your changes. 11. Click OK again, to exit the Certificate popup. You're now ready to set the certificate's new Friendly Name in the configuration file for the GEMS Presence service.

Installation and Configuration Guide

148

Configuring GEMS Services

To update the LPP configuration file: 1. Open LyncPresenceProviderService.exe.config in your favorite text editor. You can find the file in \Technology\Good Enterprise Mobility Server\Good Presence\LyncPresenceProviderService.exe.config. 2. Add the following line (or change its value if it has already been added):

Note: The value for is case-sensitive. Enter it exactly as you see it from the certificate. 3. Save your changes. 4. Restart the Good Technology Presence service in the Windows Service Manager for this change to take effect.

Logging and Diagnostics The default GEMS host installation directory is: C:\Program Files\Good Technology\Good Enterprise Mobility Server All log directories are relative to this path.

GEMS Host Machine Log \Good Server Distribution\assembly-\data\log\.log Note: At 23:59 the timestamp resets to 0:00. It is also reset by a service restart or when the file size reaches 100 MB.

GEMS Presence Service \Good Presence\Logs\LPP-log.txt

Global Catalog for GEMS Connect and/or GEMS Presence The global catalog (GC) is a distributed data repository that contains a searchable, partial representation of every object in every domain in a multi-domain Active Directory Domain Services (AD DS) forest. GC’s are typically used in a single AD DS forest that has more than one domain. A GC provides a way for products and services to access data that is available in other domains in the same forest. (Refer to Microsoft® TechNet article titled “What Is the Global Catalog?” https://technet.microsoft.com/en-us/library/cc728188(v=ws.10).aspx) You can configure the GEMS Connect service to use the GC so that the Connect service can find users who exist in other domains within your AD DS forest. This enables the Connect client to search for people in those other domains and start conversations with them, or add them to the contact list.

Installation and Configuration Guide

149

Configuring GEMS Services

You can also configure the GEMS Presence service to use the GC so that the Presence service can subscribe the receive presence information for Lync users who exist in other domains within your AD DS forest. This is helpful if you are using a Presence client, such as Good Work, by users who email with others who reside in other domains in your AD DS forest. In order to provide this service, in addition to configuring the GEMS Connect and/or Presence service(s) to use the GC, you must also replicate a couple of additional Lync related attributes to the GC. Whether this is for one or both services, this only needs to be done once. To enable replication of the needed attributes, on one of the domain controllers (DC), perform the following steps: 1. Start > Run. 2. Type in: schmmgmt.msc . 3. In the left navigator window, click on or select Active Directory Schema. 4. In the middle window, double-click or open Attributes. 5. Find the attribute named mail (click on or select the first attribute, then just type in mail to jump to that entry). 6. Double-click or open the mail property. 7. Enable or confirm that “Replicate this attribute to the Global Catalog” is enabled, then click on the OK button. 8. Repeat steps 5-7 for the attribute msRTCSIP-PrimaryUserAddress. 9. Repeat steps 5-7 for the attribute msRTCSIP-UserEnabled.

Updating the Connect and Presence Services Using Lync Director The Lync Director role provides functionality for users accessing Lync, internally and externally1. To support this capability, Lync Server is deployed as one or more pools, based on Standard Edition or Enterprise Edition Lync Server. Users can be homed on only a single pool. Clients can be configured to find their Lync pool automatically. However, the DNS records that support this functionality can point to only a single pool. In a multi-pool environment, this "primary" pool will have to redirect users to their correct home pool. This is an overhead on the primary pool. The Lync Director is used to offload this redirection functionality. The Director does not home any users itself but instead redirects the user to their correct pool home. The requirement for the Lync Director is therefore for multi-pool environments with high user numbers. Once the user has been redirected to their correct pool, the Director plays no further role in communications between the client and the pool server.

1From http://social.technet.microsoft.com/wiki/contents/articles/3933.lync-director.aspx. ©2014 Microsoft Corporation. Used with permission.

Installation and Configuration Guide

150

Configuring GEMS Services

To update the Connect and Presence services to use a Director: 1. From the GEMS host, stop the following services: l

Good Technology Connect

l

Good Technology Presence

2. Locate the Good Connect configuration file. Its default location is: C:\Program Files\Good Technology\Good Enterprise Mobility Server\Good Connect\GoodConnectServer.exe.config 3. Open the file in notepad, locate the LYNC_SERVER key, then update its value with the FQDN of the Director pool you want to use. 4. Locate the Good Presence configuration file. Its default location is: C:\Program Files\Good Technology\Good Enterprise Mobility Server\Good Presence\LyncPresenceProviderService.exe.config As with Connect, open the file in notepad and locate the LYNC_SERVER key. Update this value with the FQDN of the Director pool you want to use. 5. Start the two services that you stopped in Step 1.

Configuring the Docs Service You will use the GEMS dashboard to configure and maintain document/file repositories (file shares, SharePoint, Box, CMIS-supported content management systems, etc.) and user access policies for mobile app users of the service. Please make sure that all requirements identified under Docs Service Prerequisites have been satisfied before continuing.

Configuring Docs in the GEMS Dashboard Just like configuring the other primary services, setting up the Docs service in the Dashboard starts on the Home page.

After clicking Docs under Good Services Configuration on the Dashboard home page, completing its service configuration comprisesproperly setting up the following modules:

Installation and Configuration Guide

151

Configuring GEMS Services

l

Web Proxy

l

Database

l

Repositories

l

Settings

l

Audit

l

Storages

Note: Your Good Dynamics servers must be operating before the Docs service can be configured for Good Dynamics.

Web Proxy If you use a web proxy to connect your enterprise servers to the Internet for SharePoint and Office Web App Server (OWAS), you will need to enable Use Web Proxy and configure its address, port, and authentication type for the Docs service. To configure a web proxy for the Docs service: 1. On the GOOD DOCS SERVICE CONFIGURATION page, click Web Proxy.

2. Check Use Web Proxy. Uncheck it to disable use of a web proxy. 3. For Proxy Address, enter the FQDN of the web proxy. 4. Enter a Proxy Port. 5. Select a Proxy Server Authentication Type (or None) from the drop-list. If you choose Basic or NTLM authentication, enter recognized credentials (Username, Password) and, optionally, the Domain.

Installation and Configuration Guide

152

Configuring GEMS Services

6. Click Test to confirm connection to the proxy server. 7. Click Save to commit your changes.

Database In configuring your SQL database for GEMS-Docs, you have a choice of using either Windows Authentication or SQL Authentication for granting access to the database by GEMS. Make sure you have already set the “Good Technology Common” service to run as the service account in Windows Service Manager (SrvMan). After restarting the Good Technology Common service, perform the steps below for either Windows Authentication or SQL Authentication.

Installation and Configuration Guide

153

Configuring GEMS Services

To use Windows Authentication to access the database: 1. On the GOOD DOCS SERVICE CONFIGURATION page, click Database.

2. Enter the Server host name and instance name; i.e., \. 3. Enter the Database name. 4. Select Windows Authentication for the Authentication Type. 5. Click the Test button to verify connectivity with the database. 6. Click Save to commit your changes. 7. Finally (and critical to the configuration process), restart the Good Technology Common service service in Windows Services Manager to allow these settings to take effect.

Installation and Configuration Guide

154

Configuring GEMS Services

To use SQL Authentication to access the database: 1. Select SQL Server Login as the Authentication Type. 2. Enter the SQL Server Username and Password. 3. Click the Test button to verify connectivity with the database. 4. Click Save to commit your changes. 5. Use the Windows Services Manager to locate the Good Technology Common service, then select Restart to allow these settings to take effect.

Repositories The Docs service furnishes your end users with access to stored enterprise data from their mobile devices. A Docs repository (also called a "share") lives on an enterprise server containing files shared by authorized users. Before you configure your repositories, you should first complete initial configuration of your Security Settings, and then configure Good Control to entitle your users so that they can access the repositories you will add and define later from their mobile devices. Finally, with respect to Docs, see Managing Repositories for detailed guidance on setting up and maintaining your enterprise shares in GEMS and the associated user access .

Storages The Docs service supports a number of storage services, including FileShare, SharePoint, Box, and CMIS-based providers such as Alfresco, Documentum, HP RM, IBM Filenet, etc. The Docs service supports the ability to add or delete access to any of these storage providers and their repositories from GEMS. Note: Only Active Directory users are supported for CMIS. That is, the content management system must be hooked up to Active Directory for user authentication for GEMS Docs to support it.

Settings Docs security settings control acceptable SharePoint Online domains, the URL of the approved Office Web App Server (OWAS), the appropriate LDAP domains to use, and whether you want to use Kerberos Constrained Delegation for user authentication. To configure your Docs security settings: 1. In the GOOD DOCS SERVICE CONFIGURATION page, click Settings. 2. Check Enable Kerberos Constrained Delegation to allow Docs to use KCD; uncheck it to disable KCD. Delegation is the act of allowing a service to impersonate a user account in order to access resources throughout the network. Constrained delegation limits this trust to a select group of services explicitly specified by a domain administrator. See Configuring Kerberos Constrained Delegation (KCD) for GEMS-Docs below for the steps to set up File Share servers and SharePoint apps for constrained delegation to GEMS.

Installation and Configuration Guide

155

Configuring GEMS Services

3. Separated by a comma, enter each of the SharePoint Online Domains you plan to make available. See Configuring Support for Hosted SharePoint for additional details. 4. Enter the URL for your approved Office Web App Server. See Configuring Office Web Apps (OWA) for Docs Service Support for guidance on setting up your OWA environment to work with GEMS-Docs. 5. Provide you Active Directory User Domains (separated by commas), then enter the corresponding LDAP Port. LDAP (Lighweight Directory Access Protocol) is used to look up users and their membership in user groups. 6. Check Use SSL for LDAP for secure communication with your AD servers.

7. Click Save to keep these settings. As indicated, restart the Good Technology Common service in order for your changes to take effect.

Audit Your Audit settings enable or disable GEMS-Docs audit logs. If audit logs are enabled, then different actions are logged to the database, including user downloads, deletions, browsing history, and files created. To configure your Docs Audit properties: 1. In the GOOD DOCS SERVICE CONFIGURATION page, click Audit.

Installation and Configuration Guide

156

Configuring GEMS Services

2. Click the AUDIT SETTINGS tab if not already open, then check/uncheck Enable Audit Logs.

3. If Audit Logs are enabled, activate the available Audit Operations you want by marking/unmarking the corresponding checkboxes. Logs include histories for: a. Browse – folders opened b. File Download – files downloaded to the device c. File Upload – files uploaded from the device d. Folder Creations – new folders added e. File Delete – files removed f. Check out – Files checked out (SharePoint) g. Check in – files checked in (SharePoint) h. Purge – audit logs purged from the database 4. Click Save to record your changes. As indicated onscreen, it might take up to two minutes for your changes to take effect. 5. Click the AUDIT PURGE tab to open it, then select a purge-before date and click Purge to remove audit records logged to the database earlier than the purge date selected.

With the Docs service configured for communication and storage, you're ready to configure Good Control to entitle your users, via application groups, to use the Docs service. Following user entitlement, see Managing Repositories to set up your file shares, SharePoint sites, and Box storage.

Installation and Configuration Guide

157

Configuring GEMS Services

Configuring GEMS-Docs for AD-RMS Active Directory Rights Management Services (AD RMS) from Microsoft allows documents to be protected against access by unauthorized people by storing permissions to the documents in the document file itself. Access restrictions can thus be enforced wherever the document resides or is copied or forwarded to. For documents to be protected with AD RMS, the application the document is associated with must be RMS aware. Refer to https://technet.microsoft.com/en-us/library/hh831364(v=ws.11).aspx for practical applications. This page also lists limitations to the technology including not being able to restrict content from being copied using third party screen capture programs. In GEMS Docs/Good Work, support for RMS protected documents is provided through Office Web Apps server with viewing and editing enabled through the Good Access browser. Note that while Good Access browser is a Good Dynamics application with all the secure features it provides, it has only partial support support for RMS features. For example, users might be able to do the following in Good Access which might not be possible with RMS aware client: l

Share the Office Web App URL that is used to render the document viewing/editing with other GD applications. The URL expires in thirty minutes but during this time, other GD applications might be able to access it without any authentication. For example, if shared with Good Work, the URL can be emailed to others. If shared with a GD application allows printing, then page that is rendered might be printed. Mitigation would be to enable user agent in Good Access policy and then use it to create filtering rules in Office Web Apps server so that only Good Access is able to access the URL. The IIS URL Rewrite extension can be used to create the rules.

l

Users can save what is on screen as a web clip and this screenshot file can be shared with other GD applications. Mitigation is to disable web clips in Good Access policy.

l

When editing a document, copy and paste of content would be possible but by default polices only within the Good Dynamics secure container environment. Ensure that the protection provided is adequate given these limitations and satisfies your RMS protection requirements before enabling this support.

RMS restrictions The following RMS restrictions are respected by GEMS Docs: l

View right is required to view documents.

l

Edit right is required to edit documents.

l

Print or Export rights are required to convert documents to PDF.

l

If a user is the owner of a document and the "Grant owner full control" right is set, then viewing, editing, and converting to PDF is allowed.

l

If the current date is beyond the content expiry date, then no access to the document is allowed except when the user is owner and the "Grant owner full control" right is set.

l

Revocation of rights is respected.

Installation and Configuration Guide

158

Configuring GEMS Services

l

Use licenses are acquired on every use of the document.

l

Both template-based and custom protection on documents are honored.

GEMS Docs deployment for AD-RMS support On GEMS Server, perform the following steps: 1. Install RMS Client 2.1 (https://www.microsoft.com/en-us/download/details.aspx?id=38396). 2. If using self-signed certificates in ADRMS server, add SSL certificate for https://ADRMS-SERVER URL to trusted CA list. 3. In Internet Explorer, add https://ADRMS-SERVER to Local Intranet site list. 4. Install GEMS Docs with GEMS common services service running as a domain user. 5. If a super users group is not already configured in AD-RMS server, configure one. Then add GEMS process user (GEMS common services service user) to this AD-RMS super users group. 6. On AD-RMS server, find the file %systemdrive%\Inetpub\wwwroot\_ wmcs\Certification\ServerCertification.asmx and add Read and Read & Execute permissions for the following: l

the "AD RMS Service Group”. Note that AD RMS Service Group is a local group and not a domain group.

l

the computer account for each of the GEMS servers.

l

The GEMS common services service user.

Configuring Good Control for the Docs Service Configuring Good Control for the Docs Service consists of three primary tasks: l

Entitling Users

l

Adding the GEMS server and port to GC

l

Publishing the Docs app

l

Configuring User Affinity

Follow the steps for each to complete set up of Good Control (GC) connectivity and communication with the Docs service.

Entitling Users To configure Docs Service entitlement: 1. Click Manage Apps under APPS , then, with the ENTERPRISE tab open, enter a full or partial search string for "Feature - Docs Service Entitlement". 2. Click on Feature - Docs Service Entitlement in the search results.

Installation and Configuration Guide

159

Configuring GEMS Services

3. Open the GOOD DYNAMICS tab. 4. In the GD Enterprise ID section, click EDIT. 5. Select a policy from the Policy Set Override drop-down if you want to override the default policy.

6. Click Save.

Adding the GEMS Server to GC To configure Docs Service entitlement: 1. Click Manage Apps under APPS , then, with the ENTERPRISE tab open, enter a full or partial search string for "Feature - Docs Service Entitlement". 2. Click on Feature - Docs Service Entitlement in the search results.

Installation and Configuration Guide

160

Configuring GEMS Services

3. Open the GOOD DYNAMICS tab. 4. In the Server section, click EDIT. 3. Add the GEMS server and its port 8443.

5. Click Save.

Publishing the Docs App To publish the Docs app for all users: 1. In Good Control under APPS, click App Groups and edit the Everyone group by clicking

Installation and Configuration Guide

.

161

Configuring GEMS Services

2. Click

Add More, then enable the checkbox for Feature - Docs Service Entitlement - ALL.

3. Click OK.

Configuring User Affinity for Docs Caution: As pointed out for the Presence service, when a distributed computer system is truly load balanced, each request is routed to a different server. This load balancing approach is diminished when server affinity techniques are applied. Be aware that once you set affinity, it takes precedence. To enable server affinity for Docs in Good Work: 1. In the Good Control console navigator, click Policy Sets, then locate the policy you want to apply and click it. 2. Click the APPS tab, then expand APP SPECIFIC POLICIES. 3. Scroll down to GOOD WORK and click it, then open the App Settings tab.

Installation and Configuration Guide

162

Configuring GEMS Services

4. In the Server Hosts field, enter in the FQDN of your GEMS host and a colon (:) followed by port 8443. Add more preferred servers in the same manner, each separated by a comma and no space. 5. Click Update. 6. Now, repeat Steps 1 through 5 for every policy that will use the Docs Service.

Troubleshooting the Docs Service Major errors and the recommended fixes are listed here on an advisory basis. For additional troubleshooting resources and support, please visit Good's Public KB. Remember to check back often for updates to this list.

Configuring GEMS-Docs for HA Like other GEMS services, high (HA) availability for GEMS-Docs is based on clustering. The GEMS-Docs service supports HA by adding additional GEMS servers running the GEMS-Docs service in a cluster. When adding a new GEMS-Docs instance for HA, you will need to: 1. Configure your new GEMS-Docs instance to use the existing database. 2. Configure your new GEMS-Docs instance to point to the same Good Proxy server. 3. Whitelist your new GEMS-Docs server host and port in Good Control (see Defining Allowed Domains and Servers). 4. Configure your new GEMS-Docs instance in Good Control for the Good Work App (see Configuring Good Control for the Docs Service).

Installation and Configuration Guide

163

Configuring GEMS Services

If you have GEMS-Docs user affinity configured, be sure to add the new GEMS-Docs instances to your affinity list as well.

Configuring GEMS-Docs for DR As with the other GEMS services, Disaster Recovery (DR) for GEMS-Docs is based on an active/cold standby clustering model. Before adding a GEMS-Docs instance for DR, you will need to: 1. Evaluate the DR strategy for your network resources—File Share, SharePoint, OWAS, etc., then make sure your network resources are accessible from your DR site in the event a DR situation arises. 2. Configure database replication for the GEMS-Docs database from your primary site to your DR site. SQL log shipping is recommended. Consult your database administrator for assistance. 3. Ensure that the appropriate network ports are open to allow GEMS-Docs servers in your DR site to communicate with the database, network resources, and Good Proxy servers in your DR and Primary sites. When adding a new DR GEMS-DOCS instance, you will need to: 1. Configure your DR GEMS-Docs instance to use the GEMS-Docs database in your primary site. 2. Configure your DR GEMS-Docs instance to use the primary Good Proxy server in the cluster. 3. Whitelist your DR GEMS-Docs server host and port in Good Control (see Whitelisting Your GEMS Host(s) in Good Control). 4. Configure your DR GEMS-Docs instance in Good Control for the Good Work App (see Adding GEMS to the Good Work Application Server List). Be sure to set the PRIORITY setting to Secondary or Tertiary. Important: After the DR GEMS-DOCS instance is installed and configure, you will need to stop the Good Technology Common service. This places your DR GEMS-Docs instance in cold standby. In a DR situation in which you want to failover, you will need to: 1. Stop the Good Technology Common service on all your Primary GEMS-Docs instances 2. Failover your GEMS-Docs database on your database server (i.e., make the GEMS-Docs database in your DR site active). 3. Failover your database FQDN DNS to your DR database server. If this is not possible, see Step 5. 4. Start the Good Technology Common service on your DR GEMS-DOCS instance. 5. If you were not able to do Step 3 (failover database DNS), then you will need to login to the GEMS Dashboard and update the GEMS-DOCS database information to point to your DR database server. Restart the Good Technology Common service for the new database settings to take effect. 6. If you also failed over your Good Proxy servers in this process, you will also need to update the Good Proxy information in the GEMS dashboard for the GEMS-Docs service.

Installation and Configuration Guide

164

Configuring GEMS Services

Managing Repositories There are the following repository storage providers: l

File Share – a secure directory on an enterprise file server containing shared files and sub-directories which can be remotely accessed.

l

SharePoint – a secure web server containing shared files which are accessed via the Internet.

l

Box – a secure cloud storage account furnished by box.com containing shared files which can be accessed via the Internet .

l

CMIS-based - Content Management Interoperability Services (CMIS) is an open standard that allows different content management systems to inter-operate over the Internet. CMIS supports such storage providers as Alfresco, Documentum, HP RM, IBM Filenet, etc.

A repository is further categorized in GEMS-Docs by who added/defined it as follows: l

Admin-defined – Storage provider sites added and maintained by GEMS administrators to which individual users and user groups are granted access.

l

User-defined – Sites added by individual end users from their mobile devices to which you, as the GEMS admin, may rescind and/or reinstate mobile-based access in accordance with your enterprise IT acceptable-use policies.

To get started, click Repositories on the GOOD DOCS SERVICE CONFIGURATION page. The REPOSITORIES CONFIGURATION page has three tabs: l

ADMIN DEFINED – in which you create and manage repositories, add/remove users and groups of users, then assign them file access and use permissions.

l

USER DEFINED – in which you add/remove users and groups of users, enable/disable their ability to create user-defined shares, and grant/rescind permission to perform a range of file-related actions on their userdefined shares.

l

USERS – allows you to search for a specific user in an Active Directory domain to view the repositories permitted by path or override, and who defined the share—the admin or the user.

Next, we briefly cover what you can do under each tab to create and maintain a robust yet secure file sharing environment for authorized members of your mobile device user community.

Installation and Configuration Guide

165

Configuring GEMS Services

Admin-Defined Shares Shares are document repositories for a particular storage provider. You can further organize your administratordefined shares into lists. A named (defined) share, however, can only belong to one list. This is enforced to help you avoid unwanted/unintended duplication. Stepwise guidance for defining repositories and lists is found under the following topics: l

Defining a Repository

l

Defining a New Repository List

l

Defining User Access Permissions

Defining a Repository To define a repository: 1. On the GEMS Dashboard Home page, click Docs then click Repositories. 2. On the REPOSITORIES CONFIGURATION page, click the ADMIN DEFINED tab. Existing (already defined) shares are listed by NAME and PATH and further organized by List name, where applicable. Click a List name expand/compress its member repositories. To view and/or edit an existing repository definition, just click the NAME or PATH of the repository in the list and skip to Step 4.

3. Click New Repository to create a new repository definition. 4. Provide the following information in the corresponding field to define the share: a. Display Name – the name of the repository to that will be displayed to users granted mobile access to the repository. The name must be unique; duplicate names are disallowed. Although spaces are allowed, the following special characters cannot be used due to third-party limitations: n

SharePoint 2007, 2010, 2013: ~ " # % & * : < > ? / \ { | }

n

File Share: \ / : * ? " < > |

n

Box: \ /

b. Storage – File Share,SharePoint, Box, or a CMIS-supported storage provider that you've added, selected from the drop-down list.

Installation and Configuration Guide

166

Configuring GEMS Services

If Storage is SharePoint, and the share is running under SharePoint 2013 or a later version, check Add sites followed by users on this site to make this feature available to users of this share. It will only work, however, if SharePoint's MySite plugin is enabled. c. Path – the path to the share. If Storage is File Share, Path can include AD attributes; e.g., \\fileshare1\ or . If Storage Type is SharePoint or Box, enter a fully qualified URL with/without AD attributes. If the path cannot be verified, an error caution is displayed when you attempt to save the definition. For storage providers using CMIS support that you have added to GEMS, both AtomPub and Web Services URLs are supported. A repository ID may be optionally specified and a path inside the repository may also be optionally specified. If no repository ID is specified, then all repositories that a user has access to are listed to the user. If no path is specified, then the listing starts at the repository root. Following is the format of the paths for GEMS Docs repositories for accessing CMIS repositories: ?RepositoryId=&RelativePath= ?RepositoryId=&RelativePath=&BindingType=WebService or is specific to a CMIS vendor and this information may be obtained from the vendor. is the CMIS repository ID to be used and is optional. is the path inside the CMIS repository and is optional. d. List – select an existing list from the drop-down to which you want this repository to belong. If no list is defined, you can create one later, as desired, or leave this field blank. If a List is selected, check Enable inheriting of access control of repository list to apply the Access Permissions of the List to this repository. Otherwise, you must define specific access permissions for this share (repository).

Installation and Configuration Guide

167

Configuring GEMS Services

5. Click Save to store this information (recommended), then see Defining User Access Permissions to complete the definition.

Defining a Repository List Use Lists to assign users to multiple repositories and/or to organize your repositories by common characteristics. This allows you to batch-configure user access permissions. Included repositories can inherit the configured user access permissions of the list or maintain permissions independent of the list. On the REPOSITORIES CONFIGURATION page (breadcrumb = Home > Docs > Repositories) under the ADMIN DEFINED tab: l

Click New List to create a list.

l

Click a list name to edit an existing list.

To define a repository list: 1. Enter/change the repository's Display Name. This is the list name that will be displayed to authorized users on their mobile devices. 2. Select/deselect the Repositories to include from the list of defined repositories. Remember that a repository must already be defined before it can be added to a Repository List. 3. See Adding Users and User Groups for steps to add new users to the list definition. 4. See Granting User Access Permissions for guidance on granting or rescinding user access permissions.

Installation and Configuration Guide

168

Configuring GEMS Services

5. Click Save to store the list definition.

Adding Users and User Groups Active Directory Users and Groups must be added to a repository definition or a list definition before access permissions can be configured.

To add a users and user groups to a repository or list definition: 1. If the repository definition is not already open, then on the REPOSITORIES CONFIGURATION page under the ADMIN DEFINED tab, click a repository or a list to open its definition. 2. Click Add Users / Groups. 3. In the Search In field, enter a new domain or keep the default domain. 4. Select either Users or Groups, then click in the search field, type a full or partial search string, and click Search. 5. Select from the results by checking one or more entries. 6. Optionally, you can enable Use Different Credentials to configure a different Username and Password for accessing this repository by these users.

Installation and Configuration Guide

169

Configuring GEMS Services

7. Click Add to include the selected users or groups in the repository definition. These users or groups will automatically receive default access permissions, which you can edit in the repository configuration. See Granting User Access Permissions.

Granting User Access Permissions Access permissions are defined for a single repository or inherited from an existing list of repositories. Permissions can be selectively granted to existing Active Directory domain users and user groups. At least one user or user group must be added to the repository definition in order to begin configuring access permissions. The user access permissions you can enable/disable are enumerated in the following table: User Access Permissions and Attributes

Access Permission

Permission Attributes

Default Setting

List (Browse)

View and browse repository content (subfolders and

Enabled

files) in a displayed list, and to sort the list(s) by Name, Date, Size, or Kind Delete Files

Remove files from the repository

Enabled

Read (Download)

Download repository files to user's device and open

Enabled

them to read Write (Upload)

Upload files (new/modified) from user's device to the

Enabled

repository for storage Cache (Offline Files)

Temporarily store a cache of repository files on the

Enabled

device for offline access Open In

Installation and Configuration Guide

Open a file in a format-compatible app on the device

Enabled

170

Configuring GEMS Services

Access Permission

Permission Attributes

Default Setting

Create Folder

Add new folders to the repository

Enabled

Copy/Paste

Copy repository file content and paste it into a different Enabled file or app

Check In/Check Out

While a file is checked out, user can edit the file, close it,

Enabled

reopen it, and work with the file offline. Other users

(SharePoint only)

cannot change the file or see changes until it is checked back in To change user access permissions: 1. Check or uncheck a permission under Access Permissions on the REPOSITORIES CONFIGURATION page (breadcrumb = Home > Docs > Repositories > Edit) , to grant or rescind it. 2. Click

in the far right column to remove a user or group from the repository definition.

3. Click Save.

User-Defined Shares You can allow users to define their own "named" data sources on admin-defined repositories for which they have already been granted permission.

Installation and Configuration Guide

171

Configuring GEMS Services

Configuring permissions for allowing your users to define their owned repositories involves: l

Setting access rights

l

Setting allowed data sources

l

Granting access permissions

Your users will then be able to define their own shares (data sources), presuming they already have the appropriate access permissions configured on the host server. If not, user-defined share creation will fail. To set access rights: 1. On the REPOSITORIES CONFIGURATION page (breadcrumb = Home > Docs > Repositories) click the USER DEFINED tab. 2. Check Enable "User Defined Shares" to allow your mobile users to define their own data sources. 3. (Optional) Check Automatically add sites followed by users for authorized SharePoint 2013 repositories with the required MySite plugin enabled. To set allowed data sources: 1. Check Allow Files Shares to enable user-defined File Share repositories. 2. Check Allow SharePoint Sites to enable user-defined SharePoint repositories. 3. Check Allow Box Repositories to enable user-defined Box repositories. Important: At least one of the above must be enabled or the entire user-defined option is disabled.

Installation and Configuration Guide

172

Configuring GEMS Services

To grant access permissions: Permissions can be selectively granted to existing Active Directory domain users and user groups. Bear in mind that the most restrictive permissions (admin-defined or user-defined) will be applied. The user access permissions you can enable/disable for user-defined repositories are enumerated in the following table: User Access Permissions and Attributes

Access Permission

Permission Attributes

Default Setting

List (Browse)

View and browse repository content (subfolders and

Enabled

files) in a displayed list, and to sort the list(s) by Name, Date, Size, or Kind Delete Files

Remove files from the repository

Enabled

Read (Download)

Download repository files to user's device and open

Enabled

them to read Write (Upload)

Upload files (new/modified) from user's device to the

Enabled

repository for storage Cache (Offline Files)

Temporarily store a cache of repository files on the

Enabled

device for offline access Open In

Open a file in a format-compatible app on the device

Enabled

Create Folder

Add new folders to the repository

Enabled

Copy/Paste

Copy repository file content and paste it into a different Enabled file or app

Check In/Check Out

While a file is checked out, user can edit the file, close it,

Enabled

reopen it, and work with the file offline. Other users

(SharePoint only)

cannot change the file or see changes until it is checked back in Add New Repositories

Permits new repositories to be added from the user's

Disabled

mobile device. To change user access permissions: 1. Check or uncheck a permission under Access Permissions on the REPOSITORIES CONFIGURATION page (breadcrumb = Home > Docs > Repositories > Edit) , to grant or rescind it. 2. Click

in the far right column to remove a user or group from the user-defined repository definition.

Installation and Configuration Guide

173

Configuring GEMS Services

3. Click Save.

User Repository Rights You may need to search for a particular user to review which repositories are configured for his/her access, as well as the specific permissions granted. This is especially true when a user is merely one member of an AD group configured for repositories—and therefore not listed individually in your admin-defined or user-defined repository configurations—and you need/want to consider making specific changes to this user's access permissions. To search for a specific user: 1. Click the USERS tab on REPOSITORIES CONFIGURATION page (breadcrumb = Home > Docs > Repositories). 2. Enter a full or partial search string for the users AD account.

Installation and Configuration Guide

174

Configuring GEMS Services

3. If you don't see the user you want, extend or narrow the search string or click Switch Domains to search a different AD domain. 4. When found, click the NAME you want to see the list of repositories currently allowed to this user.

Here, the DEFINED BY column identifies what type of repository it is—Admin-defined or User-defined. 5. Click the name of the repository (or anywhere on the row) to display this user's access permission.

Installation and Configuration Guide

175

Configuring GEMS Services

6. Optionally, enter an Override Path for this User to narrow or broaden access within this repository, then click Save. To make changes to this user's access permissions, see Granting User Access Permissions under Admin-Defined Shares or how to change access permissions under User-Defined Shares.

Using the Docs Self-Service Web Console Very similar to the method for adding user-defined repositories on/from the device (see "Adding a New Data Source" in the respective Blackberry Work Client User Guide for iOS or Android ), authorized users can conveniently login to a GEMS-Docs Self-Service Web Console from a browser on their office workstation or laptop to add user-defined File Share, Box, and SharePoint repositories. The self-service console is included in your GEMS installation and automatically configured with the Docs service in the GEMS Dashboard. The URL is http://:/docsconsole. Contact your GEMS/Blackberry Work administrator for the specific URL in your environment. To login and use the Docs Self-Service Console: 1. In your workstation browser, enter the URL above with the appropriate substitutions. 2. Login with your AD credentials—Username, Password and Domain. 3. Click Add Repository to define a new data source.

Installation and Configuration Guide

176

Configuring GEMS Services

4. Enter a Display Name - this is what will be displayed in repository lists in the console and on your device(s). 5. Enter a Storage Type, either File Share, SharePoint, or Box (iOS). 6. Enter the Path in accordance with the format indicated by the example. 7. Click Save. Your new user-defined repository is now listed and will be available on your device the next time login to Blackberry Work. To remove a repository, just click the X next to it.

Managing Storage Services GEMS is installed with support for a number of storage service providers: FileShare, Sharepoint, and Box. You can also add storage services that utilize the Content Management Interoperability Services (CMIS) protocol, an open standard that allows different content management systems to inter-operate over the Internet. CMIS supports such storage services as Alfresco, Documentum, HP RM, IBM Filenet, etc. You can also delete any storage service from GEMS. To add a CMIS-based storage service: 1. Navigate to the dashboard Good Doc Services Configuration page.

2. Click on Storages. A list of current storage providers is displayed. In this example, the admin has added an Alfresco provider.

Installation and Configuration Guide

177

Configuring GEMS Services

3. Click on New Storage to add a provider. Note: To delete a provider, click on the x to the right of the provider's line in the list. A Storage Configuration page is displayed for the new storage provider.

4. Enter a name for the new storage. 5. Select the type of provider from the Storage Provider drop-down menu. 6. Choose an authentication provider from the Authentication drop-down. 7. Click the Enable Storage checkbox to make the storage available on user devices. Note: It may take an hour or a restart of the apps for storage changes to take effect on user devices. It may take five minutes for the changes to take effect on the server. Enabling and disabling storage providers on this page impacts what storage resources are visible at any given time for users, but has no such impact on the server. 8. Now add any repositories in the storage provider as described in Managing Repositories

Installation and Configuration Guide

178

Configuring GEMS Services

Windows Folder Redirection (Native) This feature gives administrators the ability to redirect the path of a folder to a new location, which can be on the local computer or a directory on a network file share. Users can work with documents on a server as if the documents were based on a local drive. The documents in the folder are available to the user from any computer on the network. Folder Redirection is located under Windows Settings in the console tree when you edit a domain-based Group Policy using the Group Policy Management Console (GPMC). The path is [Group Policy Object Name]\User Configuration\Policies\Windows Settings\Folder Redirection. Offline File technology (turned on by default) gives users access to the folder even when they are not connected to the network, and is especially useful on laptops and mobile devices. Offline folders do not, however, work out of the box with Samba network drives. See Offline Folders (Native) for details. Otherwise, Windows Folder Redirection can be enabled for any of the predefined folders in the Group Policy Management Editor.

In Windows Server 2008, a total of 13 different folders can be redirected. Pictured above, these include: l

AppData(Roaming)

l

Music

l

Saved Games

l

Desktop

l

Favorites

l

Searches

l

Start Menu

l

Contacts

l

Videos

l

Documents

l

Downloads

l

Pictures

l

Links

Installation and Configuration Guide

179

Configuring GEMS Services

As an administrator, you will need to create the root folder for the destination location. This folder can be created on a local or remote machine (NAS), but it is important that all members of the group who will have Windows Folder Redirection enabled are given full access to the root folder. To enable Folder Redirection and configure access: 1. Create a root folder (e.g., RedirectShare) for the redirect destination. 2. In the Group Policy Management Editor, select a specific folder (e.g., Documents) and add one or more rules to determine which users/groups can redirect the selected folder to the root folder. 3. Set an environment variable %USERNAME% to the path [Root]\\Documents\. The tree structure of the root —for example, RedirectShare—will look something like:

Now the user’s folder has exclusive user permissions. No other user can see the files. The user can update these files, add new files, and delete files. Then, when the user connects to the corporate network again, the files are automatically synchronized with the redirected location. If modifications are attempted on the same file in both locations at the same time, an alert is issued (pictured next), and the user is responsible for resolving the conflict; i.e., keep source, keep destination, keep both files).

Thus, if a user uploads a file through a mobile app directly to the share, it will be visible on the local PC in the Documents folder. Moreover, when the Docs Service is configured with “User Private Shares” pointing to the redirected root folder—e.g., C:\RedirectShare\— users can automatically use their own folders inside the mobile app from the “Home Directory” on their phone or tablet.

Installation and Configuration Guide

180

Configuring GEMS Services

Note: For users with their home folder defined in AD, Folder Redirection works when the redirection path is the same as the user’s home folder in AD.

Local Folder Synchronization – Offline Folders (Native) Users who work remotely on content creation and save files locally for offline access, can now access these files on-the-go from their mobile devices without having to open their local machine. The Docs Service provides authorized users access to their Home Directory hosted on NAS shares and exposed through Active Directory. However, this synchronization feature—synching folders on the user’s remote laptop or desktop with their home directory—is only available on local machines running Microsoft Windows. When you select a network file or folder to make it available offline, Windows automatically creates a copy of that file or folder on your computer. Thereafter, any time you reconnect to the network folder, Windows synchronizes these files with those in the network folder. You can also synchronize them manually any time you want. As pointed out above, this feature does not work out of the box with a Samba network drive, and workarounds are not currently supported by Microsoft. Otherwise, the feature can be enabled from Windows Explorer and used for any shared folder as pictured.

Now that the shared folder is available offline, it can be used offline. Users can even make a shortcut to the shared folder on their desktop for convenience. Moreover, when working offline and changes are made to offline files in a network folder, Windows automatically syncs the changes the very next time you connect to that network folder. You can also manually sync changes by clicking the Sync Center tool

.

Additionally, there are more advanced sync scheduling controls available in the Windows Sync Center.

Installation and Configuration Guide

181

Configuring GEMS Services

If the user is working offline while someone else changes a file in a shared network folder, Windows syncs those changes with the offline file on the local computer the next time it connects to that network folder. If a sync conflict occurs—meaning changes were made to both the network and offline versions of the file between syncups—Windows will prompt the user to decide which change takes precedence. Files that were cached automatically are removed on a least-recently used basis once the maximum cache size is reached. Files cached manually are never removed from the local cache. When the total cache size limit is reached and all files that were cached automatically have already been removed, files cannot be made available offline until you specify a new limit or delete files from the local cache by using the Offline Files control panel applet (pictured below).

The default size limit for the Offline Files cache is 25-percent of the total disk space of the drive where the cache is located. The cache size can be configured through the Group Policy by setting the limit on disk space used by Offline Files—go to Computer Configuration > Policies > Administrative Templates > Network > Offline Files—on each client separately.

Installation and Configuration Guide

182

Configuring GEMS Services

Synchronization takes place a few minutes after the user logs in and connects/opens a shared network folder containing offline files and is schedule- or event-based. However, this must still be enabled manually by each user. Even so, through the Group Policy editor, the domain administrator can set various synchronization triggers; e.g., On Logon, On Logoff, Sync Interval, etc.

Pictured above, these settings are available in User Configuration\Administrative Templates\ Network\Offline Files and in Computer Configuration\Administrative Templates\Network\Offline Files in the Group Policy Object Editor snap-in. For more information about policy settings, see the Explain tab on the Properties page of each policy. See also Configuring Group Policy for Offline Files on Technet. These options—Folder Redirection and Offline Folders—offer these advantages compared to a proprietary laptop/desktop agent furnished by Good: l

IT does not have to manage and deploy another desktop agent

l

Microsoft Folder Redirection is integrated with GPO and manages conflicts

l

Existing compliance tools and processes govern the data.

Again, once the files are synchronized to the “Home Directory,” IT administrators can make use of the GEMS-Docs Service feature in which AD attributes can be specified in the path to expose the user’s “Home Directory” to the Good Work app running on provisioned mobile devices. It is also important to remember that for users who have their home folder defined in AD, Folder Redirection works when the folder redirection path is the same as the user’s home folder in AD.

Configuring Support for SharePoint Online/OneDrive for Business SharePoint Online locations can be added as repositories in Docs just like an on-premise SharePoint site to support both admin-defined and user-defined data sources. This is also true for OneDrive for Business (ODfB).

Installation and Configuration Guide

183

Configuring GEMS Services

SharePoint Online furnishes two different ways for on-premises Active Directory (AD) users to authenticate and perform normal SharePoint operations. These include: l

DirSync with Password Hash – wherein users and their passwords on AD are synchronized with Office 365 (O365). Users are presented with a login page where they can enter their credentials to access SharePoint Online.

l

Active Directory Federation Service (ADFS) – wherein ADFS serves as a Secure Token Service. Behind the scenes (in background), users are redirected to ADFS for authentication and are issued security tokens that are then used by SharePoint Online to sign in. SharePoint Online users will not need to enter credentials when accessing from the corporate network, which typically enables SSO scenarios.

Both authentication mechanisms are supported by the Docs Service and all preparations take place on the server side exclusively. No device changes are required. The only prerequisite is that SharePoint Online is already deployed based on either of the authentication mechanisms—DirSync with Password Hash or ADFS. Consult Microsoft O365 resources regarding SharePoint Online deployment for details and procedures. To configure SharePoint Online and/or ODfB: 1. From the GEMS Dashboard, click Docs, then click Settings (breadcrumb = Home > Docs > Settings). 2. Enter the FQDN for your primary SharePoint Online Domain. Then, separated by a comma, enter your FQDN for OneDrive for Business. In the example below, goodshare.sharepoint.com is the primary or "main site" URL, and goodshare-my.sharepoint.com is the ODfB site.

3. Click Save, then restart Good Technology Common service to allow the settings to take effect. 4. Next, click Docs, click Repositories, then click the New Repository button.

Installation and Configuration Guide

184

Configuring GEMS Services

5. Enter a Display Name of your choice, set the Storage Type to SharePoint, enter the Path for your primary SharePoint Online site from Step 2, then click Save.

6. Next, add another repository (optional) for OneDrive for Business by clicking New Repository. 7. Enter a Display Name of your choice, set the Storage Type to SharePoint, enter the Path for your ODfB site from Step 2, then click Save. Note: Here, you can use the username wild card (“”) in the URL, as in the example below. When the user tries to browse this location from the Good Work app, it will replace the wildcard with the current user’s username in the URL.

Installation and Configuration Guide

185

Configuring GEMS Services

Tip: You can login to the SharePoint Online website and click the OneDrive option, then copy the URL from your browser and paste it into Path.

8. Finally, confirm that both repositories are now shown in the repository list.

SharePoint Online Authentication Setup For Kerberos Constrained Delegation (KCD), which allows for Single Sign-On credential-less access to network resources from devices, only ADFS authentication to SharePoint Online is supported. Note: Configure delegation using the GEMS Windows Service Account (e.g., GoodAdmin). Also, when adding Kerberos delegation constraints for Docs service users, add the ADFS server HTTP service. Do not attempt to add SharePoint Online servers for delegation here. For non-KCD configurations—in which users must enter their credentials on the device—both DirSync with Password Hash and ADFS authentication mechanisms to SharePoint Online are supported. No extra authentication-related steps are needed to use this configuration.

ADFS Version and Location Good recommends ADFS 2.0. ADFS may be installed on either Windows 2008 R2 or Windows 2012. The ADFS server is automatically identified by the Docs Service based on the SharePoint Online location and  therefore does not need to be specified.

ADFS HTTPS Certificate If your ADFS server uses a self-signed certificate for HTTPS communication, the certificate must be added as a trusted CA on the GEMS server machine. To add the certificate, navigate to IIS Manager on the ADFS machine, then go to Server Certificates and export the certificate to a file. Next, on the GEMS machine, import this certificate into the trusted CA list.

Installation and Configuration Guide

186

Configuring GEMS Services

Once you have deployed SharePoint Online, you’re ready to configure the Docs Service for your SharePoint Online users.

Troubleshooting SharePoint Issues Major errors and the recommended fixes are listed here on an advisory basis. For additional troubleshooting resources and support, please visit Good's Public KB. Remember to check back often for updates to this list.

Issue:

Good Work Docs fails to find a SharePoint view by name

Suspected Cause:

HTTP URL length issue

Resolution:

In IIS, under site or server, open Configuration Editor and in the drop-down at the top, expand system.web and select httpRuntime. Should see maxUrlLength property here – default is 260 – increase this to 2048.

Configuring Office Web Apps Server (OWAS) for Docs Service Support Office Web Apps Server is a new Office server product from Microsoft that delivers browser-based versions of Word, PowerPoint, Excel, and OneNote. A single Office Web Apps Server farm can support Docs service users who access Office files through SharePoint and File Shares. The new stand-alone deployment model means that you can manage updates to your Office Web Apps Server farm independently of other Office Server products that are deployed in your organization.

GEMS-Docs Service and Good Work Support for OWAS GEMS-Docs support for OWAS gives your users the ability to view and edit Office documents and convert them to PDF format in Good Work and other GD-powered apps that use the Docs service. This is all done within the secure GD container. The Good Work Docs component is used to browse and select the files. Good Access is used to view and edit the documents. The following file types are supported: Microsoft Word

File Format

View Edit

Open XML (.docx)

Yes

Yes, on iPad only

Binary (.doc)

Yes

No

Macro (.docm)

Yes

No, and macros do not work

Templates (.dotm, .dotx)

Yes

No

Other file formats (.dot, .mht, .mhtml,

No

No

htm, .html, .odt, .rtf, .txt, .xml, .wps, .wpd)

Installation and Configuration Guide

187

Configuring GEMS Services

Microsoft Excel

File Format

View Edit

Open XML (.xlsx)

Yes

Yes, on iPad only

Binary (.xlsb)

Yes

Yes

Binary (.xls)

No

No

Macro (.xlsm)

Yes

Yes. However, you are prompted to create a copy of the file that has the macros removed when you save the changes that you have made

Other file formats (.xltx, .xltm, .xlam,

No

No

.xlm, .xla, .xlt, .xml, .xll, .xlw,ods, .prn, .txt, .csv, .mdb, .mde, .accdb, .accde, .dbc, .igy, .dqy, .rqy, .oqy, .cub, .uxdc, .dbf, .slk, .dif, .xlk, .bak, .xlb)

Microsoft PowerPoint

File Format

View Edit

Open XML (.pptx, .ppsx)

Yes

Yes, on iPad only

Binary (.ppt, .pps)

Yes

Yes, PowerPoint Online or PowerPoint Web App converts the .ppt or .pps file to a .pptx or .ppsx file to allow you to edit the file but you must save the file in as a .pptx or .ppsx file to save your changes.

Macro (.pptm, .potm, .ppam, .potx,

Yes

No

No

No

.ppsm) Other file formats (.pot, .htm, .html, .mht, .mhtml, .txt, .rtf, .wpd, .wps, .ppa, .odp, .thmx)

PDF and OpenDocument

File Format

View Edit

PDF (.pdf)

Yes

No

OpenDocument Text (.odt)

Yes

No

OpenDocument Spreadsheet (.ods)

Yes

Yes

OpenDocument Presentation (.odp)

Yes

Yes

For more information on the file types supported with OWAS, see MS Article 2028380. Documents in a supported format can reside on any of the following storage types:

Installation and Configuration Guide

188

Configuring GEMS Services

l

File Shares

l

SharePoint 2007/2010

l

SharePoint 2013

l

SharePoint Online

Client devices supported1: l

l

iOS devices o

iPad – viewing and editing

o

iPhone – view only

Android devices o

Phones – view only

o

Tablets – view only

OWAS Deployment Deploying Office Web Apps Server involves installing some prerequisite software and running a few Windows PowerShell commands. Overall the process is fairly straightforward and summarized here with convenient links to pertinent Microsoft documentation and other associated aids. Important: To download Office Web Apps Server you must have a license under a Volume Licensing Agreement, for Office Professional Plus 2013, Office Standard 2013, or Office for Mac 2011. To deploy Office Web Apps Server: 1. Install Microsoft Office Web App Server (OWAS) if one is not present on the network. Visit the following links for installation guidance: a. System requirements and planning steps b. Installation steps c. PowerShell commands 2. Configure GEMS Docs for OWA access: a. On the GEMS Dashboard, navigate to Docs, then Settings. b. Enter the Office Web Apps Server URL as http://OWASERVER where OWASERVER is the FQDN of the OWAS host machine and click Save. c. From the Windows folder on the OWAS machine , copy Microsoft.CobaltCore.dll to C:\Program Files\Good Technology\Good Enterprise Mobility Server\Good Server Distribution\gems-quickstart- 2.0.16\lib on the GEMS machine. d. Restart the Good Technology Common service.

1Device-specific functional limitations indicated for viewing/editing are the result of current OWA support for the devices rather than an inherent GEMS/Good

Work or Good Access software limitation.

Installation and Configuration Guide

189

Configuring GEMS Services

3. Export the SSL certificate of the GEMS server to a file: On the GEMS machine execute the following command (gems.jks is in the etc\keystores folder): keytool -export -alias serverkey -file gems.crt -keystore gems.jks

4. On the OWAS host, add the certificate from the previous step to the Trusted Root CA of the computer account as follows: a. Launch mmc.exe b. Go to File > Add/Remove Snap-in > Add Certificates c. Select Computer Account > Local Computer d. Expand Certificates, choose Trusted Root Certificate Authorities, right-click Import, and select the certificate from Step 3. 5. Obtain the OWAS server SSL certificate. 6. Add the OWAS SSL certificate to GEMS in accordance with the guidance under Importing CA Certificates for GEMS. Repeat Steps 3 through 6 for each GEMS machine deployed.

Troubleshooting OWAS logs are found at C:\ProgramData\Microsoft\OfficeWebApps\Data\Logs\ULS.

Configuring Kerberos Constrained Delegation (KCD) for GEMS-Docs Configuring GEMS-Docs to use KCD for accessing resources such as SharePoint and File Shares obviates any need for end-users to provide their network credentials to access to network resources via the GEMS-Docs service. However, before configuring the GEMS-Docs service to use KCD, it is important to understand that configuring KCD for GEMS-Docs is independent of configuring Good Dynamics KCD. This means, for example, that if your mobile app (i.e., Good Work) requires use of the GEMS-Docs service exclusively, you only need to configure KCD for GEMS-Docs. In other words, there is no need to configure Good Dynamics KCD. Configuring Support for SharePoint Online/OneDrive for Business To better illustrate this, the following diagram charts a sample KCD call flow for Good Work.

Installation and Configuration Guide

190

Configuring GEMS Services

All KCD (Kerberos constrained delegation) transactions are between the GEMS-Docs service account and the key distribution center (KDC) and respective resources. No KCD information is cached in the mobile app. The GEMS DOCS service utilizes Microsoft’s S4U specifications for KCD. For more information on S4U, see: https://msdn.microsoft.com/en-us/library/cc246071.aspx. Important: Configuring KCD for the Docs service requires v1.10.x or later of both Good Control and Good Proxy, and only Windows authentication in SharePoint is supported. Forms-based and claims-based authentication are not supported. Moreover, IP addresses are not allowed in the SharePoint URLs and File Share paths you configure in GEMS. Enabling Kerberos constrained authentication for the apps and files available through GEMS-Docs involves: 1. Finding an application’s Pool Identity and Port number 2. Applying a user in the Active Directory for the apps and files 3. Adding Kerberos constraints in AD for each user and app 4. Adding Kerberos constraints in AD for each file share server 5. Enabling Kerberos constraints on GEMS. Tip: If, at this time, you wish to configure KCD for File Share repositories only, you can safely skip the SharePoint configuration guidance that follows and proceed directly to Adding KCD for File Shares.

Installation and Configuration Guide

191

Configuring GEMS Services

Finding the SharePoint Application Pool Identity and Port To find the application pool identity and port number for the web applications to be shared: 1. Create a list of web applications that are going to be shared through GEMS-Docs. 2. Open Windows Internet Information Services (IIS) Manager. Note: Be sure to jot down any additional unique port numbers assigned if a web application was extended to create alternate access mappings. 3. Find the Application Pool identity in the Application Pools list view or in Central Administration > Security > Configure service accounts.

Caution: In most instances, for KCD to work properly, the application pool identity user must be the same for all application pools whose applications will be accessed by GEMS-Docs. This means you cannot have different application pools running under different users. 4. Find the Port for each of the web applications listed in the Web Application tab. Also look in the Alternate Access Mappings view as necessary.

Installation and Configuration Guide

192

Configuring GEMS Services

5. Navigate to Central Administration > Application Management, choose the web application and click Authentication Providers in the ribbon bar. Make sure that the authentication type for each web application is set to Windows and that Negotiate (Kerberos) is enabled under IIS Authentication Settings.

Tip: In certain scenarios, switching to Negotiate might also require enabling Kernel-mode authentication in IIS for the corresponding IIS site. For more information, see "Service Principal Name (SPN) checklist for Kerberos authentication with IIS 7.0/7.5" in MSDN.

Applying the GEMS Service Account to SharePoint in Active Directory Ideally, you should use the GEMS service account (GoodAdmin) as the Service Principal Name (SPN) for KCD. Hence, in the guidance that follows, the user is \GoodAdmin. To apply the GoodAdmin user in Active Directory and associate it with the web apps and files to be shared: 1. Make sure the password for GoodAdmin is set to never expire. Also, do not require a password change for logging on. 2. Create a Service Principle Name (SPN) for each web application that needs to be shared as follows: setspn setspn setspn setspn

–S –S –S –S

HTTP/SPHOST:PORT domain\AppPoolUser HTTP/SPHOST.FQDN:PORT domain\AppPoolUser HTTP/SPHOST domain\AppPoolUser HTTP/SPHOST.FQDN domain\AppPoolUser

If the port is a default port (80 or 443), omit the first two lines above. Note that some of the lines need just a host name while others need a fully qualified host name. If the application pool identity is for a built-in user such as Network Service, then specify the host name as shown below instead of \AppPoolUser; e.g.: setspn setspn setspn setspn

–S –S –S –S

HTTP/SPHOST:PORT domain\SPHOST HTTP/SPHOST.FQDN:PORT domain\SPHOST HTTP/SPHOST domain\SPHOST HTTP/SPHOST.FQDN domain\SPHOST

Note: If you are using SSL, the SPN must refer to HTTP instead of HTTPS.

Installation and Configuration Guide

193

Configuring GEMS Services

Adding KCD in Active Directory for SharePoint To create constrained delegations for GoodAdmin in each of the SPNs indicated below: 1. Open the Active Directory Users and Computers manager and look under Users to find GoodAdmin. 2. Right click GoodAdmin and select Properties.

3. Click the Delegation tab. 4. Select both Trust this user for delegation to specified services only option and the Use any authentication protocol option and click Add as shown below:  5. Select Users or Computers in the Add Services dialog box to open the Select users or Computers dialog box.

Installation and Configuration Guide

194

Configuring GEMS Services

6. Enter the SharePoint Application Pool Identity user name and click OK.

7. Select all the services that correspond to the SharePoint web applications running under the username chosen above, except for the HTTP service, and click OK.

7. The services to which GoodAdmin can provide delegated credentials are now listed in the DelegationUser Properties dialog box as shown below.

Installation and Configuration Guide

195

Configuring GEMS Services

8. Click Add and repeat Steps 2 through 7 above, but instead of choosing the application pool identity user, choose the computer account for the SharePoint server instead. When you choose the services, select HOST and http, then click OK to add each computer account to list of services.

The list of added services are then listed Delegation tab.

Installation and Configuration Guide

196

Configuring GEMS Services

Now, repeat Steps 3–5 for each application pool identity user and each Web Application identified, then click OK to save these GoodAdmin delegation changes. Note: A limit of 1300 services can be delegated to one account.

Adding KCD for File Shares The main difference between sharing files in File Share repositories, as opposed to sharing apps (SharePoint), is that here the delegation is to the GEMS computer account and not to the GEMS-Docs process user, GoodAdmin. To set up KCD for File Shares: 1. Go to Active Directory > Users and Computers > Computers 2. Right-click the GEMS computer entry and select Properties, then open the Delegation tab. 3. Click Add, select Users or Computers, type in the name of the server whose file share needs access and click OK. 4. In the list of services, select cifs and click OK.

Installation and Configuration Guide

197

Configuring GEMS Services

The Delegation tab should then look similar to the shot below (albeit with your computer's name):

5. Repeat Step 2 for each server that has file shares needing access. 6. For the changes above to be received right away, any servers whose network shares are to be accessed. Note: As Kerberos tokens are cached, rebooting is the only sure way to make sure all delegation changes are received on the machines.

Enabling KCD on the GEMS Host Finally, to enable Kerberos Constraints on the GEMS host machine: 1. Go to Settings under Docs in the GEMS Dashboard. 2. Under KERBEROS CONSTRAINED DELEGATION, enable Kerberos Constrained Delegation. 3. Restart the Good Technology Common Service.

Installation and Configuration Guide

198

Configuring GEMS Services

4. On the GEMS host running the Docs service, grant the Act as operating system privilege to the GEMS Windows Server Account (i.e., GoodAdmin). This can be done from Local Security Policy > User Rights Assignment on the GEMS host machine.

5. Click OK.

Configuring Good Launcher The Good Launcher, a UI component accessed in Good apps with the Launcher button

, is a library module

with numerous functions, currently comprising display of: l

User's name, photo, presence, and status

l

List of GD-powered apps and modules installed on the device

l

Quick create options to easily compose an email, create a note, schedule a calendar event, or add a contact, regardless of which app is currently open

In addition, the Launcher creates a convenient placeholder location for app settings. To provide this rich UX, the Launcher library requires GEMS server-side services to: 1. Synchronize policy-based sections (modules) between applications. so that, for instance, when Docs is enabled in Good Work, the Docs icon is enabled in the Launcher, even when it is opened outside of Good Work in apps like Good Access or Good Connect. 2. Fetch GAL information about the user to display the correct name and picture.

Installation and Configuration Guide

199

Configuring GEMS Services

3. Fetch presence information for the user and display appropriate status (available, busy, away, do not disturb) and the user's presence message. The required server-side services for the Launcher currently comprise: l

Presence (service id = com.good.gdservice.enterprise.presence)

l

Directory Lookup (service id = com.good.gdservice.enterprise.directory)

l

Follow-Me Store (service id = com.good.gdservice.enterprise.followme)

The client entitlement app to use these services is Good Enterprise Services (AppID = com.good.gdserviceentitlement.enterprise). GD clients like Good Work check the server list for available GEMS instances hosting these services. This means the list must be populated with at least one GEMS machine to enable Good Enterprise Services. In addition, the Good Enterprise Services entitlement app will need to be added to at least one App Group in Good Control like "Everyone." Hence, to configure Good Enterprise Services in Good Control, you must: l

Verify Good Enterprise Services in Good Control

l

Add GEMS to the GES Entitlement App

l

Add the GES Entitlement App to an App Group

See Appendix I for additional information related to advanced setup of multiple GEMS hosts with user affinity.

Verify Good Enterprise Services in Good Control Presuming Good Control is installed, and now that you've installed GEMS on, for example, GEMS-Host1 and GEMS-Host2, the Presence, Directory Lookup and Follow-Me services are now published in Good Control. Even so, it is wise to confirm that these services are available and ready. To confirm services availability: 1. Login to Good Control. 2. In the Good Control Dashboard under APPS, click Manage Services and verify that all three Launcherrequired services are present as shown below.

Installation and Configuration Guide

200

Configuring GEMS Services

If you cannot locate all three services, review Installing GEMS to make sure all tests and check-offs were completed successfully.

Adding GEMS to the Good Enterprise Services Entitlement App All GD applications must be associated with an application server in Good Control to enable communications between the client app and its application server. To add your GEMS host(s) to the GES entitlement app: 1. In the GC Dashboard under APPS, click Manage Apps, then scroll down or search for "Good Enterprise Services."

Installation and Configuration Guide

201

Configuring GEMS Services

2. Open Good Enterprise Services in the search results by clicking it, then click the GOOD DYNAMICS tab.

Installation and Configuration Guide

202

Configuring GEMS Services

3. In the Server section, click EDIT , then enter the FQDN of the GEMS machine under HOST NAME and "8443" under PORT. 4. Set PRIORITY and GP CLUSTER information as necessary. 5. Click

under ACTIONS to add the server.

6. Repeat Steps 3 to 5 for each GEMS host you are deploying. 7. Click Save. Your results will be depicted as follows, albeit listing the server hosts you configure.

Installation and Configuration Guide

203

Configuring GEMS Services

Adding the GES Entitlement App to an App Group The Good Services Entitlement (GES) app now needs to be added to an App Group in Good Control, such as the Everyone group, to entitle the services to users who belong to the group. To add the GES entitlement app to an App Group: 1. In the Good Control Dashboard under APPS, click App Groups. 2. Open a group or click

3. Click

under ACTIONS to edit.

.

4. Scroll down or search for "Good Enterprise Services - ALL" and enable it.

5. Click OK. Repeat to add the services entitlement app to another group.

Configuring the Certificate Lookup Service The Certificate Lookup service requires LDAP configuration in the GEMS Web Console.

Installation and Configuration Guide

204

Configuring GEMS Services

To configure the GEMS Certificate Lookup service: 1. Login to the GEMS Web Console as an administrator as a member of the local administrators group or use your AD credentials if included under GEMS Systems Settings. 2. Select OSGi > Configuration. 3. Scroll down to Directory Lookup Configuration.Configuring Good Control

4. Enter the LDAP Server Name and LDAP Server Port. 5. Enter the LDAP Login Account and Password. 6. Click Save.

Maintaining GEMS Cluster Identification in Good Control Always ensure that Connect servers listed in the Good Control application configuration for Good Connect identifies installed GEMS machines in that cluster. If you add a server to the cluster, please correlate the timing of both the server’s installation with updating the Good Control application configuration for Good Work, to include the additional server after it has been installed and is up and running. If you temporarily remove a server from the cluster for maintenance, it is not necessary to change the Good Control application configuration for GEMS. The Good Work client will detect that the server is offline and will automatically connect to another GEMS machine in the cluster. If you permanently remove a server from the cluster, first shut down the GEMS machine, then remove it from the Good Control application configuration.

Installation and Configuration Guide

205

Device Provisioning and Activation

Device Provisioning and Activation Users invited to install and activate Good Connect on their device(s), require an access key. The access key must be entered when the user opens Good Connect for the first time on a given device. The access key is a 15-character alphanumeric code sent to the user’s (registered) company email address and has the following properties: l

It can be used only once and is consumed immediately upon the activation of an application.

l

It is not application-exclusive. In other words, a user who has been sent four access keys can use them to activate any four applications to which s/he is entitled.

l

It does not support reactivation. Hence, if the client software is uninstalled, then reinstalled on the same device, a new access key is required. This is also true if a new or factory-reset device is in use, or if a device emulator is in use and its state is not persisted. However, a user who has been issued multiple access keys could use them to activate the same application multiple times.

l

It can be configured to expire after a specified period of time. This is done in Provisioning Policies under the SECURITY POLICIES tab by enabling the Access Keys expire option, and then selecting the number of days after which access keys expire if not consumed.

To grant access to all your enterprise users complete the following steps: 1. Assign the default policy set or create a new policy set in accordance with your enterprise’s user access protocols. The default policy set is automatically applied to all new users. For each user, the policy currently applied is located at the top of the user’s account page. To apply a different policy set, hover your cursor over it and select from the available policy sets in the listbox. It should be noted that the user must be granted access to the app in order to activate it. This is done by assigning the user to an App Group that includes the app (Good Work) for which the user is being permitted access. 2. Go to USERS > Users and Groups in the navigation panel, locate and select the user you want to provision by clicking the corresponding checkbox, then select Edit from the User Actions listbox.

Installation and Configuration Guide

206

Uninstalling GEMS

3. Click on the Keys tab, then click New Access Key. A new access key will be sent to the user’s registered enterprise email address—one email message per key. Hashes of the access keys are also copied to the GD NOC for validation. Assuming the user has received the email message containing the access key and downloaded and installed the GD client application from the pertinent online marketplace—App Store or Google Play—on the device, they can now activate the application until its GC-specified expiration date. At application start-up, the Good Dynamics user activation interface opens, whereupon the user must enter the access key and his/her enterprise email address in the input fields provided on the client so that the GD Client Library can promptly transmit the access key to the NOC. Additional provisioning and activation options are also available in Good Control. For more on these features see: l

Easy Activation

Uninstalling GEMS If you stop a GEMS instance, it will not be used any more by your HA implementation. and all users that were being serviced by the discontinued instance are reallocated to other servers automatically as soon as the discontinued instance goes down. This equally applies to Connect server instances. If you need to completely remove a GEMS or Connect instance from your environment, take the following steps.

Removing a Single GEMS Instance To completely remove a GEMS instance from your environment: 1. Uninstall the desired GEMS instance by running the GEMS installer, located on the host machine's \GoodEnterpriseMobilityServerSetup..exe. 2. Select Uninstall and follow the wizard's onscreen instructions.

Installation and Configuration Guide

207

Uninstalling GEMS

Alternatively, you can uninstall GEMS from the Control Panel, then follow the onscreen wizard after confirming that you want to uninstall.

3. Login to Good Control, then click Manage Apps and scroll down to or search for Good Work and click it. 4. Open the Good Dynamics tab. 5. In the Server section, click EDIT. 6. Locate the FQDN of the GEMS host you want to remove and click

.

7. Click Save.

Installation and Configuration Guide

208

Uninstalling GEMS

Removing a Connect Instance Similar steps to those above are followed to remove a Connect instance configured in Good Control. To completely remove a Connect server instance from your environment: 1. Uninstall the GEMS instance on the host machine. 2. Login to Good Control, click Manage Apps and scroll down to or search for Good Connect and click it. 3. Open the Good Dynamics tab. 4. In the Server section, click EDIT. 5. Locate the FQDN of the GEMS-Connect host you want to remove and click

.

6. Click Save.

Installation and Configuration Guide

209

Appendix A – Pre-Installation Checklists

Appendix A – Pre-Installation Checklists The following GEMS pre-installation checklists are for the respective services cited: l

Push Notifications

l

Connect and Presence

l

Docs

Upon completing these recommended checklists, please see the supplemental publication SSL/TLS Certificate Check for GEMS and Good Work for valuable information covering import/export of required security certificates to and from the relevant keystores on GEMS and GW client devices for authenticating with Good Dynamics, AD, Exchange, SharePoint, and OWAS.

Installation and Configuration Guide

210

Appendix A – Pre-Installation Checklists

Push Notifications It is highly recommended that this checklist be completed prior to implementation of your Good Enterprise Mobility Server (GEMS) with Push Notifications and Presence Services.

#

Task

Check Registration

1.1

Register with the GDN portal.

1.2

Download the latest GEMS software from the Good Admin Portal.

1.3

Request the Good Work app from the Good Marketplace. Network

2.1

Ensure the following ports are open for GEMS: l

l

Inbound TCP Ports o

61617 to and from GEMS machines in the same cluster (bidirectional)

o

61616 to and from GEMS machines in the same cluster (bidirectional)

o

8443 from the Good Proxy server (required for Presence and Push notifications); add port 8181 if SSL is not going to be used

Outbound TCP Ports o

443 to Good NOC/APNS

o

443 to GCM

o

443 to Exchange

o

17080 to the Good Proxy server (17433 for SSL)

o

61617 to and from GEMS machines in the same cluster (bidirectional)

o

61616 to and from GEMS machines in the same cluster (bidirectional) Active Directory and Exchange

3.1

Verify the supported version of Exchange you have already deployed: l

Exchange 2013+ 1

l

Exchange 2010 SP 1+

l

Microsoft O365

1A plus sign (+) indicates that all later service packs and updates to the version cited are also supported.

Installation and Configuration Guide

211

Appendix A – Pre-Installation Checklists

#

Task l

3.2

Check

Hosted Exchange (2010 SP 1+; e.g., Certified Rackspace)

Create an AD account for Good. The preferred UID is "GoodAdmin" set with the following attributes: l

Password must not contain ';', '@', '^', or '/'

l

Password Expired option must be set to Never for this account

l

GoodAdmin should be a member of the local administrator group on the GEMS host machine

3.3

Create an Exchange mailbox for the GoodAdmin account.

3.4

Grant Application Impersonation Permissions to the Good Admin account in Exchange (very important!). For convenience, the Exchange shell command to apply Application Impersonation is as follows: Command Format: New-ManagementRoleAssignment -Name:impersonationAssignmentName -Role:ApplicationImpersonation -User:serviceAccount

Example: New-ManagementRoleAssignment -Name:GoodAppImpersonation -Role:ApplicationImpersonation -User:GoodAdmin

For additional details, see "Configuring Exchange Impersonation" and "Grant Application Permission to the Service Account" in the GEMS Installation and Configuration Guide under "Setting Up a Windows Account for GEMS." 3.6

Make sure that your Exchange Autodiscover is set up correctly (very important!). See KB19909 for guidance on how to use GEMS Tech Tools to test autodiscover.

3.7

Make sure that Exchange EAS is enabled on port 443, and that connections are permitted for the Good Proxy server. .NET FRAMEWORK

4.1

Verify that you have the correct version(s) of .NET Framework installed for the version of Microsoft Lync you have deployed or plan to deploy: l

Lync 2010 – .NET 3.5 SP1 and .NET 4.5

l

Lync 2013 – .NET 4.5

Important: As of GEMS 1.5, .NET is required whether you are configuring Connect and Presence in addition to PNS and other services or not. GEMS 5.1

5.2

Verify that you have the correct OS support. The following Windows platforms are supported by GEMS: l

Windows Server 2008 R2

l

Windows Server 2008 R2 SP1

l

Windows Server 2012 R2

Verify that you have the minimum required hardware in place to host GEMS.

Installation and Configuration Guide

212

Appendix A – Pre-Installation Checklists

#

Task

Check

Production: l

Pentium 4 Quadcore / 2.4 GHz CPU or higher

l

16 GB RAM / 50 GB HDD

l

100 / 1000 Ethernet Card

5.3

Verify that you have deployed the correct Good Dynamics support. GEMS requires Good Dynamics 1.7.38.x or newer. Version 1.9.45.x is strongly recommended. Important: Good Dynamics must already be installed and operational before installing GEMS.

5.4

Make sure that the GoodAdmin service account is a local administrator on the server.

5.5

Make sure that the GC service account has Logon As a Service rights.

5.6

Ensure that the server's date and time are set correctly.

5.7

Ensure that the server has been joined to the domain.

5.8

Make sure that Windows Firewall is OFF.

5.9

Make sure all antivirus/backup and backup software is stopped during the installation.

5.10 Install JRE 7 Update 67 or higher Java 7 update (click here to download). Note: Java 8 is now supported as of GEMS v1.5. 5.11 Set the JAVA_HOME environment variable to the Java install folder; ensure that "C:\Program Files\Java\jre8"(if using Java 8) or "C:\Program Files\Java\jre7" (if using Java 7) is appended to the value string in accordance with Configuring the Java Runtime Environment "Configuring the Java Runtime Environment" in the GEMS Installation and Configuration Guide. 5.12 Ensure connectivity to SQL Server (typically, TCP port 1433). You can use the SQL Server Browser to verify. see this technical article from Microsoft on how to enable it. 5.13 Ensure connectivity to Exchange (EWS). See KB19909 for guidance on using GEMS Tech Tools to test connectivity. Database 6.1

Verify Database Server support. The following database servers are supported: l

All editions of MS SQL Server 2008 and 2008 R2

l

All editions of MS SQL Server 2012 and 2012 SP1

l

MS SQL Express 2008 R2 with Management Tools

To download MS SQL Express, click here. To configure remote TCP/IP connections for SQL Server Express, see Database Requirements "Database Requirements" under PNS Prequisites "PNS Prerequisites" in the GEMS Installation and Administration Guide. 6.2

Create a database for the PNS service and name it "GEMSDB."

6.3

Make sure that the SQL account or the GEMS Windows Service Account has db_owner privileges to the GEMSDB database created in 6.2 above.

Installation and Configuration Guide

213

Appendix A – Pre-Installation Checklists

Connect and Presence It is highly recommended that this checklist be completed prior to implementation of your Good Enterprise Mobility Server (GEMS) with Connect and Presence Services. (Presence is available only for Lync implementations.)

#

Task

Check Registration

1.1

Register with the GDN Portal (click here)

1.2

Download the latest GEMS software

1.3

Request the Good Connect App from the Good Marketplace. ( very important!)

1.4

Request the Good Presence App ONLY if you are using Lync and third-party GD apps that require presence. The Good Presence app can be requested from Mobile App Sales ([email protected]) Network - Lync

2.1a Ensure the following ports are open for GEMS: l

l

Inbound TCP ports o

8080/8082 from the Good Proxy Server

o

8443 from the Good Proxy Server (for Presence)

o

49555 from the Lync Server (for Connect)

o

49777 from the Lync Server (for Presence)

Outbound TCP ports o

443 to the Good Technology NOC 206.124.114.0/24 206.124.121.0/24 206.124.122.0/24

o

5061 to the Lync server

o

17080 to the Good Proxy server

o

17433 to the Good Proxy server

o

1433 to the MS SQL server (default)

o

1434 UDP to the Lync database (for initial setup only)

Installation and Configuration Guide

214

Appendix A – Pre-Installation Checklists

#

Task o

Check 49777 – 57500 TCP: Random port in this range to the Lync DB (for initial setup only)

2.2a If GEMS requires a Proxy server for external access, please note it here: Proxy Server Make/Model: __________________________ Authentication Method: _____________________________ Network - Jabber 2.1b Ensure the following ports are open for GEMS: l

Inbound TCP ports o

l

8080/8082 from the Good Proxy Server

Outbound TCP ports o

443 to the Good Technology NOC 206.124.114.0/24 206.124.121.0/24 206.124.122.0/24

o

8443 to the Cisco User Data Service

o

5222 to the Cisco Client Jabber XMPP Service

o

17080 to the Good Proxy server

o

17433 to the Good Proxy server

o

1433 to the MS SQL server (default)

2.2b If GEMS requires a Proxy server for external access, please note it here:

2.2

Proxy Server Make/Model: __________________________ Authentication Method: _____________________________ Active Directory -Lync 3.1a Create an AD service account for the GEMS software (can be the same account used for Good Dynmaics) 3.2a Ensure that the GEMS service account has RTCUniversalReadOnlyAdmins permission during the GEMS install. This permission is granted via AD. 3.3a Create a Trusted Application Pool, trusted application, and trusted application endpoint for GEMS via the Lync Shell Console (very important!) Note: The user creating the Trusted Application Pool must have RTCUniversalServerAdmins and Domain Admins permissions. For complete guidance, see "Preparing the Initial GEMS Machine" under "Preparing the Lync Topology for GEMS" in the GEMS Installation and Configuration Guide. Active Directory - Jabber 3.1b Create an AD service account for the GEMS software (can be the same account used for Good Dynmaics) GEMS - Lync

Installation and Configuration Guide

215

Appendix A – Pre-Installation Checklists

#

Task

Check

4.1a Verify Good Dynamics support. Good Dynamics must already be installed and operational before installing GEMS. Use Version 1.9.45 or later; the latest release is preferred. 4.2a Verify Lync Support. Lync 2010 and Lync 2013 are supported. 4.3a Ensure that the GC Service account is a local administrator on the server 4.4a Ensure that the GC Service account has Logon As a Service rights 4.5a Ensure that the server's date/time is correctly set 4.6a Ensure that the server has been joined to the domain 4.7a Ensure that MS Windows PowerShell (x86) is installed: l

l

For both Lync 2010 and Lync 2013, install PowerShell 3.0 RTM (click here to download) Open “Windows PowerShell (x86)” and run the following command to enable execution of remote signed scripts: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

4.8a Ensure that the Microsoft Unified Communications Managed API is installed: l

For Lync 2010, install UCMA 3.0 (contact Microsoft for download)

l

For Lync 2013, install UCMA 4.0 (click here to download) o

Enable Windows Media Foundation on Windows Server 2012

o

Enable Desktop Experience on Windows Server 2008 R2 SP1

After installing UcmaRuntimeSetup.exe, you must also run the OCSCore.msi file. This is a hidden file and must be run on the GEMS host machine. By default, this file is located at: C:\Program Data\Microsoft\Lync Server\Deployment\cache\5.0.8308.0\Setup\OCSCore.msi Note: The version number in the path will vary. 4.9a Request and install a SSL certificate on GEMS (very important!). See "SSL Certificate Requirements for Lync and Presence" in the GEMS Installation and Configuration Guide. 4.10a Ensure that all antivirus/backup and backup software is stopped during the installation. 4.11a Install JRE 7 Update 67 or JAVA8 4.12a Set the JAVA_HOME environment variable to the Java install folder; ensure that "C:\Program Files\Java\jre8"(if using Java 8) or "C:\Program Files\Java\jre7" (if using Java 7) is appended to the value string in accordance with Configuring the Java Runtime Environment "Configuring the Java Runtime Environment" in the GEMS Installation and Configuration Guide. GEMS - Jabber 4.1b Verify Good Dynamics support. Good Dynamics must already be installed and operational before installing GEMS. Use Version 1.9.45 or later; the latest release is preferred. 4.2b Ensure that the GC Service account is a local administrator on the server 4.3b Ensure that the GC Service account has Logon As a Service rights 4.4b Ensure that the server's date/time is correctly set 4.5b Ensure that the server has been joined to the domain 4.6b Ensure that all antivirus/backup and backup software is stopped during the installation.

Installation and Configuration Guide

216

Appendix A – Pre-Installation Checklists

#

Task

Check

4.7b Install JRE 7 Update 67 or JAVA 8. 4.8b Set the JAVA_HOME environment variable to the Java install folder; ensure that "C:\Program Files\Java\jre8"(if using Java 8) or "C:\Program Files\Java\jre7" (if using Java 7) is appended to the value string in accordance with Configuring the Java Runtime Environment "Configuring the Java Runtime Environment" in the GEMS Installation and Configuration Guide. Database 5.1

Verify Database server support. The following database servers are supported: l

All editions of MS SQL Server 2008 and 2008 R2

l

All editions of MS SQL Server 2012 and 2012 SP1

l

MS SQL Express 2008 R2 with Management Tools

To download MS SQL Express, click here. 5.2

Create a DB for the GEMS Connect Service and name it "GEMS-Connect" (very important!). This must be done prior to installing GEMS. For more information, see Database Requirements "Database Requirements" under Connect Prerequisites "Connect Prerequisites" in the GEMS Installation and Configuration Guide.

5.3

Ensure that the GEMS service account has db_owner permission for the GEMS Connect database.

Installation and Configuration Guide

217

Appendix A – Pre-Installation Checklists

Docs It is highly recommended that this checklist be completed prior to implementation of your Good Enterprise Mobility Server (GEMS) with the Docs Service.

#

Task

Check Registration

1.1

Register with the GDN portal.

1.2

Download the latest GEMS software from the Good Admin Portal.

1.3

Request the Good Work app from the Good Marketplace (very important!)

1.4

Request the "Feature-Docs Service" virtual (entitlement) app from the Marketplace (equally important)

2.1

Ensure the following ports are open for GEMS:

Network

l

Inbound TCP Ports o

l

l

Outbound TCP Ports o

80 or 443 to SharePoint

o

80 or 443 to Office Web App Server

o

17080 or 17433 to the Good Proxy Server

o

1433 to SQL (default)

o

445, 139 to CIFS share

o

389 or 636 to LDAP

Outbound UDP Ports o

2.2

8443 from the Good Proxy server

137–138 to CIFS share

If GEMS requires a Proxy server for external access, please note it here: l

Proxy Server Make/Model: ____________________________________________________

l

Authentication Method: ______________________________________________________ Active Directory

Installation and Configuration Guide

218

Appendix A – Pre-Installation Checklists

# 3.1

Task

Check

Create an AD service account for the GEMS software (this can be the same account that was used for Good Dynamics) .NET FRAMEWORK

4.1

Verify that you have the correct version(s) of .NET Framework installed for the version of Microsoft Lync you have deployed or plan to deploy: l

Lync 2010 – .NET 3.5 SP1 and .NET 4.5

l

Lync 2013 – .NET 4.5

Important: As of GEMS 1.5, .NET is required whether you are configuring Connect and Presence in addition to Docs and other services or not. GEMS 5.1

5.2

Verify that you have the correct OS support. The following Windows platforms are supported by GEMS: l

Windows Server 2008 R2

l

Windows Server 2008 R2 SP1

l

Windows Server 2012 R2

Verify that you have the minimum required hardware in place to host GEMS. POC: l

Dual Core / 2.4 GHz CPU or higher

l

4 GB RAM / 50 GB HDD

l

100 / 1000 Ethernet Card

Production: l

Pentium 4 Quadcore / 2.4 GHz CPU or higher

l

16 GB RAM / 50 GB HDD

l

100 / 1000 Ethernet Card

5.3

Verify that you have deployed the correct Good Dynamics support. GEMS requires Good Dynamics 1.7.38.x or newer. Version 1.9.45.x is strongly recommended. Important: Good Dynamics must already be installed and operational before installing GEMS.

5.4

Ensure that the server's time and date set correctly.

5.5

Ensure that the server has been joined to the domain.

5.6

If network shares are used, make sure all GEMS-Docs users have Allow Logon Locally permission on the GEMS host.

5.7

Verify SharePoint and Box support. SharePoint 2007, 2010, 2013, SharePoint Online, and Box are supported.

5.8

If you are using KCD, make sure that the GEMS service account (Good Admin) is a local administrator on the server.

5.9

Make sure that the GEMS service account has Logon As a Service rights.

5.10 Make sure that Windows Firewall is OFF.

Installation and Configuration Guide

219

Appendix A – Pre-Installation Checklists

#

Task

Check

5.11 Make sure all antivirus/backup and backup software is stopped during the installation. 5.12 Install JRE 7 Update 67 or higher update (click here to download) Note: Java 8 is now supported and is recommended. 5.13 Set the JAVA_HOME environment variable to the Java install folder; ensure that "C:\Program Files\Java\jre8"(if using Java 8) or "C:\Program Files\Java\jre7" (if using Java 7) is appended to the value string in accordance with 6Configuring the Java Runtime Environment "Configuring the Java Runtime Environment" in the GEMS Installation and Configuration Guide. Database 6.1

Verify Database Server support. The following database servers are supported: l

All editions of MS SQL Server 2008 and 2008 R2

l

All editions of MS SQL Server 2012 and 2012 SP1

l

MS SQL Express 2008 R2 with Management Tools

To download MS SQL Express, click here. 6.2

Create a database for the Docs service and name it "GEMS-Docs."

6.3

Make sure the GEMS Service Account has db_owner permissions for the GEMS-Docs database.

Installation and Configuration Guide

220

Appendix B – Importing/Configuring Certificates in the GEMS Java Keystore Java Keytool is a key and certificate management tool that is used to manipulate Java Keystores, and is included with Java. A Java Keystore is a container for authorization certificates or public key certificates, and is used by Java-based applications for encryption, authentication, and serving over HTTPS. Its entries are protected by a keystore password. A keystore entry is identified by an alias, and it consists of keys and certificates that form a trust chain.

Importing a Certificate As briefly covered under Replacing the Auto-Generated Self-Signed SSL Certificate above, a Java keystore file, called gems.jks, containing a SSL self-signed certificate is generated by the GEMS installer. Note: The browser will report that your SSL certificate is untrusted because it is a self-signed certificate. Default Location The default location is: \Good Enterprise Mobility\Server\Good Server Distribution\gems-quickstart\etc\keystores\gems.jks

Default Password The default password is changeit. Keystore File Reference The keystore file is referenced in jetty.xml. Its default location is: \Good Enterprise Mobility\Server\Good Server Distribution\gems-quickstart\etc\jetty.xml

The relevant snippet from jetty.xml referencing the location of the keystore file and its associated password would look like the following: /etc/keystores/gems.jks /etc/keystores/gems.jks OBF:1vn21ugu1saj1v9i1v941sar1ugw1vo0 OBF:1uh01xmu1k8k1juc1k5m1wg21kmk1w OBF:1vn21ugu1saj1v9i1v941sar1ugw1vo0 8443 30000

Installation and Configuration Guide

221

The passwords are obfuscated. The keyStorePassword and the trustStorePassword are typically the identical and represent the Java keystore password. The keyManagerPassword is the challenge password for the certificate. Certificate Format Any certificate used should be PKCS #12 and the private key must contain a challenge password. In addition, please also make sure that the certificate has the appropriate key chain; i.e., root and intermediate certificate. Importing the Certificate The Java keytool is used to import the certificate into the java keystore. The default location of this tool on the GEMS host is %JAVA_HOME%\bin. For example, C:\Program Files\Java\jre1.8.0_91\bin. To import a certificate: 1. Make a backup copy of the gems.jks file. 2. Open a command prompt and import the certificate using the following command: keytool -importkeystore -destkeystore -srckeystore srcstoretype pkcs12 -alias -storepass changeit

For example: keytool -importkeystore -destkeystore gems.jks -srckeystore mycert.p12 -srcstoretype pkcs12 -alias myserver.com -storepass changeit

3. Delete the old self-signed certificate from the keystore using the following command: keytool -delete -alias serverkey -keystore gems.jks -storepass changeit

4. Copy the new gems.jks file back to its original location. 5. Generate the obfuscated challenge password for your private key. In order for the GEM server to access your certificate private key, you must include the challenge password in the jetty.xml file. The password must be obfuscated. This can be done with the GEMS SSL Tech Tool. See KB16041 for details. Caution: When you run the GEMS SSL Tech Tool to obfuscate the password, it will generate a new gems.jks file. You can then delete the gems.jks file generated under Step 2 above because you are really only interested in the obfuscated password. GEMS SSL Tech Tool output will look similar this:

Installation and Configuration Guide

222

6. Update keyManagerPassword in the jetty.xml file with the obfuscated password. 7. Restart Good Technology Common service from the Windows Service Manager. 8. Test the new certificate by accessing the GEMS Dashboard in a browser. Its certificate information should now reflect the newly imported certificated.

Other Useful Keystore Commands The following keystore commands are available at the command line:

To check which certificates are currently in the keystore, use: keytool -list -v -keystore gems.jks

To export a certificate from the keystore, use: keytool -export -alias serverkey -file gems.crt -keystore gems.jks

To check a standalone certificate, use: keytool -printcert -v -file gems.crt

To delete a cert from the keystore, use: keytool -delete -alias serverkey -keystore gems.jks

To import a signed primary certificate to an existing GEMS Java keystore, use: keytool -import -trustcacerts -alias serverkey -file gems.crt -keystore gems.jks

Importing Certs from the Jabber Server Into the GEMS Server Java Keystore To import a cert into the Java keystore from the Jabber server: 1. Log on to the Jabber CUCM server. 2. Go to “Cisco Unified OS Administration.”

3. Go to “Security” > “Certificate Management.”

Installation and Configuration Guide

223

4. Download the certificate named “tomcat” as a .der file.

5. Log on to the Jabber CIMP server. 6. Go to “Cisco Unified IM and Presence OS Administration.”

7. Go to “Security”-“Certificate Management.” 8. Download the certificate named “cup-xmpp” as a .pem file.

9. Import these two certs into the Java keystore.

Configuring HTTPS for GEMS to Good Proxy By default, the java keystore on the GEMS host does not contain the CA certificate for the Good Proxy server. This means the GEMS server will not be able to verify the Good Proxy server’s SSL certificate; and, thus, any HTTPS connection made from GEMS to the Good Proxy server will fail.

Installation and Configuration Guide

224

Workaround A workaround for this issue is to disable SSL checking on the GEMS server. This can be done from the GEMS Console at https://localhost:8443/system/console/. The default login is admin/admin. Then, from OSGi > Configuration > Good Technology Async HTTP Client Configuration, select Disable SSL certificate checking. Caution: This workaround is only recommended for lab or proof of concept systems. For production systems, please follow the guidance found under Resolution. Resolution The Good Proxy CA certificate is in a Java keystore on the Good Control server. The default location of this file is C:\Program Files (x86)\Good Technology\Good Control\jre\lib\security\cacerts. Among the many certificates in this keystore is one with the alias "gdca." You will need to export this certificate and import it into the GEMS Java kestore. Note: The default password for the keystore is changeit. To import the required certficate into the keystore on the GEMS host: 1. Make sure you have the Java directory correctly specified in your environment PATH. For instructions, see Configuring the Java Runtime Environment (JRE). This will allow you to run the keytool from any directory. l

If necessary, confirm the version of JAVA that GEMS is using by complete the following steps: 1. In a command prompt, type set | findstr "JAVA_HOME". 2. Press Enter.

l

Verify the JAVA_HOME system variable is set to the correct JAVA bin directory.

2. Copy the Good Control Java keystore from C:\Program Files (x86)\Good Technology\Good Control\jre\lib\security\cacerts to the GEMS host and place it in a convenient location. For example, C:\gemscert. 3. Rename the file. The name is arbitrary. For this example, let’s call it cacerts.gdca. 4. Open a command prompt and navigate to C:\gemscert. 5. Export the Good Control CA certificate with the following command: keytool -exportcert -alias gdca -file gdca.cer -keystore cacerts.gdca -storepass changeit

6. When prompted to trust this certificate, type Yes. 7. On the GEMS host, make a backup of the Java keystore file. The default location of the Java keystore is C:\Program Files\Java\jre1.8.0_91\lib\security\cacerts.

Installation and Configuration Guide

225

8. Copy the Java keystore file to C:\gemscert. 9. Import the Good Control CA certificate into the GEMS Java keystore with the following command: keytool -importcert -trustcacerts -alias gdca -file gdca.cer -keystore cacerts -storepass changeit

10. Now copy the updated keystore file to its original Java keystore location. See step 7. 11. Restart the Good Technology Common service from the Windows Service Manager.

Installation and Configuration Guide

226

Appendix C – Understanding the GEMS-Connect Configuration File

Appendix C – Understanding the GEMS-Connect Configuration File Configuration settings can be manually updated directly in the GEMS configuration file located in \Good Technology\Good Server\Good Connect Server\GoodConnectServer.exe.config. However, the preferred method for updating this file is to use the GEMS admin console. After updating any of the configuration parameters, you must restart the GEMS machine for the changes to take effect. Parameter Name

Required Description

Default Setting

ACK_TIME_WAIT

No

Time (in milliseconds) that the Connect server waits for acknowledgment from client for a message received before sending message failed to deliver

90 000

ACTIVE_DIRECTORY_ CACHE_REFRESH_ SECS

Yes

The number of seconds the Good Connect Server waits before synchronizing with the Active Directory (any value smaller than 7200 is ignored in favor of 7200 seconds)

86,400 (24 hours)

ACTIVE_DIRECTORY_ SEARCH_RESULT_ MAX

Yes

The upper limit on the number of hits from a search of the Global Address List (GAL)

150

AD_USERS_SOURCE

No

Parameter indicates if Good Connect server should read AD or GC for SIP-enabled users; value can be “GC” or “LDAP” (default is LDAP, if empty)

AD_USERS_SOURCE_ DOMAIN

Yes, if Domain for the for AD or GC to query.  This value should be in users LDAP format; i.e., DC=GOOD,DC=COM source is GC

APN_ALERT

Yes

Apple push notification message string that notifies a user that there are unread messages

“You have unread messages.”

APN_BADGE

Yes

Determines whether or not to use the badge graphic for Apple push notifications

True

APN_SLEEP_TIME

Yes

The number of milliseconds the Good Connect Server waits in between queued Apple push notifications

100

APN_SOUND

Yes

Play sound when an Apple device receives a push notification

BASE_ADDRESS

Yes

URL for the Good Connect Server which takes the form http://goodconnect.mycompany.com:8080/

BUILD_VERSION

Yes

The version number of the Good Connect Server build

DB_AUTHTYPE

Yes

USE_INTEGRATEDAUTH when the specifying windows integrated authentication, otherwise SQL Server authentication will be used

DB_INIT_CATALOG

No

SQL Server database name; only valid if DB_TYPE=SQLSERVER Caution:This value is set by the installer, so do not change

GoodConnect

DB_PURGE_HOURS

No

Any IMs from invitations are will be obfuscated. In

0

Auto-populated

addition to obfuscation, the integer value representing the maximum age, in hours, of missed messages and

Installation and Configuration Guide

227

Appendix C – Understanding the GEMS-Connect Configuration File

Parameter Name

Required Description

Default Setting

invitations before they are automatically deleted (purged) is set with DB_PURGE_HOURS. Ex: If Connect is started 7/8/2015 @ 12:31pm, then on 7/9/2015 @ 12:31pm a process removes all invitations and all missed messages older than 72 hours. Connect will continue to run every 24 hours thereafter. DB_RECONNECT_ TRY_NUM

Yes

# of times Connect server to retry reconnecting to database after 3 a failure to connect to database

DB_RECONNECT_ WAITTIME_SEC

Yes

# of seconds to wait before reconnecting attempt to database

DB_SESSION_ TIMEOUT_SECS

Yes

Time limit for search Lync/OCS database as defined by LYNC_DB_ 300 CONNECTIONSTRING

DB_TYPE

Yes

SQLSERVER or ORACLE depending on what database is used

DISABLE_ MESSAGEUPDATE

No

Disable message not delivered errors which may potentially be due client/network latencies

ENABLE_SOURCE_ NETWORK

No

Labels address book contacts as "external" if they do not belong False to your organization. These are federated contacts. A federated contact is a member of a company whose Office Communications Server is federated (connected) with your company’s Office Communications Server

EWS_HISTORY_ INTERVAL_MINUTES

No

Defines the number of interval in minutes Good Connect server will wait before writing to Conversation history.  0 means that conversation history is written only after conversation has been terminated

EWS_HOST

No

FQDN of the Exchange server to which the Good Connect Server will write conversation history

EWS_VERSION

No

Version of Exchange server:

300

False

5

2

0 = Exchange 2007 SP1 1 = Exchange 2010 2 = Exchange 2010 SP1 3 = Exchange 2010 SP2 or SP3 4 = Exchange 2013 5 = Exchange 2016 GASLAMP_ USERNAME

Yes

Window Service account

GD_APN_HTTP_URL

Yes

Web Service URL for Good Dynamics Apple Push Notification Service (APNS)

GD_APN_PROXY_ AUTH_DOMAIN

No

Web Proxy Domain

Deprecated

GD_APN_PROXY_ AUTH_PASSWORD

No

Web Proxy Password

Deprecated

GD_APN_PROXY_ AUTH_USERNAME

No

Web Proxy Username

Deprecated

Installation and Configuration Guide

228

Appendix C – Understanding the GEMS-Connect Configuration File

Parameter Name

Required Description

GD_APN_PROXY_ HTTP_HOST

No

Web Proxy Host

GD_APN_PROXY_ HTTP_PORT

No

Web Proxy Port

GD_APN_PROXY_ TYPE

No

Web Proxy Authentication Mechanisms. Acceptable values are:

GD_APNS_ BLACKLIST_RETRY_ NO

Yes

Specifies # of retries after the server receives APNS response where the token has been blacklisted

GD_URL

Yes

Complete URL of the Good Proxy server, with protocol,

Default Setting

""

"" (empty string for no proxy) "Basic No Auth" "Basic" "Digest" 3

fully qualified domain name, and port. Example: https://gp.myCompany.com:17433 LONG_INVITATION_ TIME_DELAY

No

Time (in milliseconds) that a Connect client will wait for invitation 60 000 received to confirm/ignore a request to a conversation

LYNC_DB_ CONNECTIONSTRING

No

SQL Server connection string for the Lync/OCS database

OCS_SERVER

Yes

FQDN (Full Qualified Domain Name) of  the Microsoft Lync FrontEnd server or Front-End server pool

RESTRICT_CERT_BY_ FRIENDLY_NAME

No

Allows naming of certificate so that Connect server can load correct certificate; the certificate friendly name must match the name specified here

SEND_TIME_WAIT

No

Time (in milliseconds) the Connect server waits after sending message before reporting message failed to deliver

120 000

SESSION_TIMEOUT_ SECS

Yes

The number of seconds a client is allowed to remain idle

86,400 (24 hours)

UCMA_ APPLICATION_NAME

Yes

Name of application as defined through the installation provisioning process

Generated during application provisioning

UCMA_ APPLICATION_PORT

Yes

The fixed port used by the Good Connect Server to receive messages from the enterprise IM server

49555

UCMA_GRUU

Yes

GRUU = Globally Routable User-Agent URI that uniquely defines Generated during application the Session Initiation Protocol (SIP) URI for the application provisioning

Note: The minimum SESSION_TIMEOUT_SECS is 600, even if you put in 60 seconds or 1 second. This was done to mitigate stress related race conditions

Installation and Configuration Guide

229

Appendix D – Fine-Tuning Your Java Memory Settings

Appendix D – Fine-Tuning Your Java Memory Settings Java settings for GEMS are found in the configuration file Good Server Distribution\gems-karaf\etc\GoodServerDistribution-wrapper.conf. You may wish to review or modify the default Java settings used by GEMS. However, as a general rule, you won't need to make changes to these settings. In particular, the default memory settings for GEMS can be viewed at: Initial memory allocation: # Initial Java Heap Size (in MB) wrapper.java.initmemory=4096

# Maximum Java Heap Size (in MB) wrapper.java.maxmemory=4096

Java memory settings: wrapper.java.additional.14=-XX:PermSize=512m wrapper.java.additional.15=-XX:MaxPermSize=1024m

Installation and Configuration Guide

230

Appendix E – IIS SSL Offloading

Appendix E – IIS SSL Offloading SSL offloading takes all the processing of SSL encryption and decryption off the main Web server and moves it to the GEMS host. To set up IIS on the GEMS host: 1. Download and install the IIS Application Request Routing extension and install it.

2. When installation completes, select Start > IIS Manager. 3. Under Connections, select Server > Server Certificates, then double-click Import to import a trusted thirdparty certificate (the .PFX file received from your CA).

Installation and Configuration Guide

231

Appendix E – IIS SSL Offloading

4. After the certificate is added, click Server under Connections, double-click Application Request Routing, andclick Server Proxy Settings... under Actions. 5. Check Enable proxy, then click Apply.

6. Next, click Server under Connection, double-click URL Rewrite, then click Add Rule(s)... under Actions. 7. Select Blank Rule and click OK. 8. On the Edit Inbound Rule screen, enter a Name for the rule—e.g., "gems"—in the field provided. 9. With Requested URL: Matches the Pattern Using: Regular Expressions displayed, enter "pushnotify/pushchannels" in the Pattern field.

10. Scroll down and expand the Conditions section, then click Add...

Installation and Configuration Guide

232

Appendix E – IIS SSL Offloading

11. For Condition input enter {REQUEST_METHOD}. 12. For Pattern enter POST, then click OK. 13. Scroll down and expand the Action section. 14. For Rewrite URL enter http://localhost:8181/{R:0}.

Installation and Configuration Guide

233

Appendix E – IIS SSL Offloading

15. In the Actions panel on the far left, click Apply. Finally, verify that you can now access GEMS under its secure HTTPS port by opening the GEMS Dashboard in your browser using https://localhost:8443/dashboard. 16. After the certificate is added, click Server under Connections, double-click Application Request Routing, andclick Server Proxy Settings... under Actions. 17. Check Enable proxy, then click Apply.

18. Next, click Server under Connection, double-click URL Rewrite, then click Add Rule(s)... under Actions. 19. Select Blank Rule and click OK. 20. On the Edit Inbound Rule screen, enter a Name for the rule—e.g., "gems"—in the field provided. 21. With Requested URL: Matches the Pattern Using: Regular Expressions displayed, enter "pushnotify/pushchannels" in the Pattern field.

Installation and Configuration Guide

234

Appendix E – IIS SSL Offloading

22. Scroll down and expand the Conditions section, then click Add...

23. For Condition input enter {REQUEST_METHOD}. 24. For Pattern enter POST, then click OK. 25. Scroll down and expand the Action section. 26. For Rewrite URL enter http://localhost:8181/{R:0}.

Installation and Configuration Guide

235

Appendix E – IIS SSL Offloading

27. In the Actions panel on the far left, click Apply. Finally, verify that you can now access GEMS under its secure HTTPS port by opening the GEMS Dashboard in your browser using https://localhost:8443/dashboard.

Installation and Configuration Guide

236

Appendix F – GEMS Windows Event Log Messages

Appendix F – GEMS Windows Event Log Messages Message

Component

Level

Context

Error communicating with

server-core/gd-core

error

Could not connect to Good Proxy Server

Good Proxy Server - HTTP code

while verifying auth token (during Push

{}, Message {}

Registration from G3 Mail context)

Failed to retrieve the list of

server-core/gd-core

error

Used for HA and load balancing of requests

Good Proxy servers - code {} -

to Good Proxy server. The list of known GP

Reason {}

servers are maintained in memory and requests are load-balanced through this list.

Failed to retrieve the list of

server-core/gd-core

error

Good Proxy servers

Used for HA and load balancing of requests to Good Proxy server. The list of known GP servers are maintained in memory and requests are load-balanced through this list.

Incorrect Good Proxy Server

server-core/gd-spring

error

configuration

Communicate with Good Proxy server to verify Authorization token using HTTP(s) protocol. If URL is syntactically wrong or configuration error then error is logged in event log.

Autodiscover failed for {} users serverwith exception {}

warn

notifications/autodiscover

Failed to retrieve user’s settings through autodiscover. Needs administrator attention to fix the issue. The user will not receive notifications until issue is resolved. This is a batch request and the log only prints the number of users that failed auto discover.

Invalid syntax for property {},

server-

must be a valid URL

notifications/autodiscover

error

Server is configured with an invalid URL used for bypassing the steps to find the autodiscover end point. GEMS server would ignore this URL and follow the regular steps to perform autodiscover.

User {} being quarantined after server{} attempts to perform

notifications/autodiscover

autodiscover

warn

GEMS server could not autodiscover user’s settings for configured number of attempts. The user mentioned will be marked as ‘QUARANTINED’ and will not receive notifications. The status can be reset through karaf command (user:reset).

Installation and Configuration Guide

237

Appendix F – GEMS Windows Event Log Messages

Message

Component

No response from server while serverperforming autodiscover for

Level

Context

warn

Autodiscover failed for the user

notifications/autodiscover

mentioned.

user {} Autodiscover failed for user {}, servererror code: {}, Detail: {}

warn

notifications/autodiscover

Failed to retrieve user settings server-

Autodiscover failed for the user mentioned.

warn

while performing autodiscover notifications/autodiscover

Autodiscover failed for the user mentioned.

for user {} No valid EWS URL setting

server-

configured for the user {}

notifications/autodiscover

Error communicating with

server-

Database server - {error msg}

notifications/autodiscover

Database Error - {error msg}

server-

warn

mentioned. error

server. Last known error {}

GEMS failed to connect to SQL database. Needs immediate attention.

error

notifications/autodiscover Lost connection with exchange server-

Autodiscover failed for the user

GEMS failed to connect to SQL database. Needs immediate attention.

error

notifications/ewslistener

EWSListener: Lost connection with exchange server. This might be due to Exchange server\Autodiscover service down.

Error subscribing user {} with

server-

exchange server {}

notifications/ewslistener

error

Subscribe to the user email address with exchange server to track modifications of user mailbox.

User {} marked for re-

server-

autodiscover

notifications/ewslistener

info

Does a DB call to mark the user for reautodiscovery. This task is done every n interval of time.

Error communicating with

server-

error

Bootstrap database connection.

error

HA System: Check whether the node itself

Database server - {error details} notifications/pushnotifydbmanager {} is no longer the master

server-

(producer) since database

notifications/pushnotify-

is Producer or not. Prints the error in event

server time {}

ha-dbwatcher

log when the server has lost ownership of the HA system (not master any more).

{} is the master (producer) since serverdatabase server time {}

info

HA System: Check whether the node itself

notifications/pushnotify-

is Producer or not. If it was not master

ha-dbwatcher

before; the fail-over is happening.

Detected Server {} is inactive.

server-

Users will be load balanced to

notifications/pushnotify-

inactive\heartbeat fails, the users of the

other active servers

ha-dbwatcher

bad server are reassigned to other active

Installation and Configuration Guide

error

HA System: If server is detected as

238

Appendix F – GEMS Windows Event Log Messages

Message

Component

Level

Context servers.

Error communicating with

server-

error

Database server - {error details} notifications/pushnotify-

Database error due to server down\login error, etc.

prefs { Good Dynamic Proxy Server

server-console/config

error

connection error details }

Connect GD Module – Test from dashboard with GP down, connection failure error.

Connection to Good Dynamic

server-console/config

info

Proxy Server is successful

GP is up and running, successful test.

Connection Successful, Server: - server-console/config

info

{}: Database : {} Exception during connection

Connect GD – Test from dashboard when Mail – DB – Test database configurations from dashboard. Connection successful.

server-console/config

error

test - {}

Mail – DB – Test database configurations from dashboard. Connection issues due to bad password or user or host info.

Invalid configuration properties server-console/config

error

- {}

Mail – DB – Test database configurations from dashboard. Validation of database configuration values.

{ Good Dynamic Proxy Server

server-console/config

error

connection error details } Connection to Good Dynamic

Presence GD – Test from dashboard with GP down, connection failure error.

server-console/config

info

Proxy Server is successful

Presence GD – Test from dashboard when GP is up and running, successful test.

Lync Presence Provider Ping

server-presence/presence- error

Connection to Presence server. If response

failed with error status {} and

bundle

received, log the reason for failure.

server-presence/presence- error

Connection to Presence server. Most likely

reason - {} Lync Presence Provider Ping

failed with exception {}: {} - set bundle

connection refused because down

status {} Lync Presence Provider Ping

server-presence/presence- error

failed, cause unknown

bundle

Presence Service failed to reset server-presence/presence- error LPP, interrupted with error: {}

Connection to Presence server. Reset all contacts presence status.

bundle

Presence Service failed to reset server-presence/presence- error

Reset all contacts presence status. Timeout

LPP, timed out with error: {}

bundle

error.

Failed to reset LPP, {} with

server-presence/presence- error

Reset all contacts presence status.

error: {}

bundle

Presence Service started.

server-presence/presence- info

Presence service started.

bundle

Installation and Configuration Guide

239

Appendix F – GEMS Windows Event Log Messages

Message

Component

Level

Presence Service stopped.

server-presence/presence- info

Context Presence service stopped.

bundle Bad Lync Presence Provider

server-presence/presence- error

Presence service provider subscription URI.

Subscription URI: {}

bundle

Bad Lync Presence Provider

server-presence/presence- error

Ping URI: {} Ping

bundle

Redis Cache & Queue services

server-presence/presence- error

When cache provider is set to Redis and

are not available at the

bundle

Redis service is unavilable.

Presence service provider subscription URI.

moment. GNP Relay Service not available server-presence/presence- warn bundle

Installation and Configuration Guide

GNP service which sends GNP notification is not available or down.

240

Appendix G – File Types Supported by GEMS-Docs

Appendix G – File Types Supported by GEMS-Docs The following file types/extensions are currently supported by the Docs service and as mail attachments: l

.goodsharefile,

l

.doc, Docx

l

wordprocessingml.document,

l

powerpoint.ppt, PPTx

l

excel.xls, XLSX

l

spreadsheetml.sheet,

l

adobe.pdf,

l

apple.rtfd,

l

apple.webarchive,

l

.image,

l

.jpeg,

l

.tiff,

l

.apple.pict,

l

.compuserve.gif,

l

.png,

l

.quicktime-image,

l

.bmp,

l

.camera-raw-image,

l

.svg-image,

l

.text,

l

.plain-text,

l

.utf8-plain-text,

l

.utf16-plain-text,

l

.rtf,

l

.html,

l

.xml,

l

.xhtml,

l

.htm,

l

.data,

l

.content

Installation and Configuration Guide

241

Appendix G – File Types Supported by GEMS-Docs

l

.zip

l

Media Files (iOS only) o

.3gp

o

.mp3

o

.mp4

o

.m4a

o

.m4v

o

.wav

o

.caf

o

.aac

o

.adts

o

.aif

o

.aiff

o

.aifc

o

.au

o

.snd

o

.sd2

o

.mov

Installation and Configuration Guide

242

Appendix H – Obtaining a Google Cloud Messaging API Key

Appendix H – Obtaining a Google Cloud Messaging API Key Create Google Cloud Messaging API keys These are the details for obtaining keys for the Google Cloud Messaging (GCM) API, which BlackBerry Enterprise Mobility Server uses to send new mail notifications to Android devices. For more information about creating the Google Cloud Messaging API Keys, visit goodpkb.force.com/PublicKnowledgeBase to read article 21187.

Prerequisites You must have a Google account. Avoid using your personal account.

Steps After getting the API key from Google, you will enter its name and the value of the key into the GEMS Dashboard. 1. In a browser, open https://console.firebase.google.com/ and log in with a valid account. 2. Click CREATE NEW PROJECT. 3. In the Create a project dialog box, type a project name and select the Country/region you are located in. 4. Click Create Project. 5. In the upper left-hand side of the screen, click Settings icon. 6. Click Project settings. 7. Click CLOUD MESSAGING. 8. Copy the value of the Server key. The Server key is used as the GCM API Key value in the BlackBerry Enterprise Mobility ServerDashboard 9. Copy the value of the Sender ID. The Sender ID is used as the GCM Sender ID value in the BlackBerry Enterprise Mobility ServerDashboard.

Installing Google Cloud Messaging API Keys To enter Google Cloud Messaging API Key details, in the GEMS Console: 1. In the console, in the Good Services Configuration section, click Android Push Notification. 2. In the GCM Sender ID field, enter the Sender ID value of the Project you created in Google, as detailed in Create Google Cloud Messaging API keys . 3. In the GCMI API Key field, enter the Server key value of the Project you created in Google. 4. Click Save .

Installation and Configuration Guide

243

Appendix I – Advanced Launcher Setup

Appendix I – Advanced Launcher Setup Good Launcher relies on the services identified in Configuring the Good Launcher with Good Enterprise Services. In a basic setup, a Launcher search for a provider of the services produces a single result for all services (com.good.gdservice-entitlement.enterprise). In setups that require user affinity, however, or where there's a large list of GEMS machines deployed, each with different purposes, strict adherence to the basic setup approach is insufficient.

Deploying Multiple GEMS Environments containing multiple GEMS hosts with different servers tied to different purposes will need new, organization-level App IDs created for the appropriate services; after which, these services will then bind to the new App IDs, which will require updated server information so they point to the correct GEMS server(s). Finally, these App IDs need to be configured as allowed apps for select users via App Groups. To illustrate by example, consider a fictional company that wants to deploy 25 GEMS hosts, six of which will be used for Presence, with three others used for both Directory and Follow-Me services. Hence, the following steps would need to be performed via Good Control: 1. Create a couple of organization-level App IDs: com.xyzcorp.gdservice-entitlement.presence and com.xyzcorp.gdservice-entitlement.directory-followme. 2. Make com.xyzcorp.gdservice-entitlement.presence a provider of the enterprise Presence service and com.xyzcorp.gdservice-entitlement.directory-followme a provider of the enterprise Directory and FollowMe services. Notwithstanding the different App IDs, each would use the existing published Good Enterprise Services; they would not create their own. 3. Under the application details of com.xyzcorp.gdservice-entitlement.presence, set up the 6 GEMS hosts. Only the server list needs to be configured; the application configuration is left blank. For the application details of com.xyzcorp.gdservice-entitlement.directory-followme, populate the three severs to be used for Directory and Follow-Me. Again, leave the application configuration section blank. 4. Add com.xyzcorp.gdservice-entitlement.presence and com.xyzcorp.gdservice-entitlement.directoryfollowme to the appropriate application group(s). 5. Make sure that com.good.gdservice-entitlement.enterprise is NOT listed as an allowed application in the "Everyone" App Group. As a result of this configuration, when Launcher opens up, it will search for providers of the three services. For Presence, it will find com.xyzcorp.enterprise-services.presence, then read the provider's configured servers list, using it to set up communication with the Presence server. The same behavior applies to the other two services. Launcher is agnostic with respect to the providers of each service; i.e., whether they are the same machine or different.

Installation and Configuration Guide

244

Appendix I – Advanced Launcher Setup

Configuring User Affinity For most other apps, user affinity is done via the security policy configuration of that app. Good Work, for example, has a section for entering affinity servers. Users are divided into different security policies as a means of determining which server affinity to use. With Launcher, the same end-goal is accomplished by dividing users into different application groups. For purpose of simplicity, assume a company plans to deploy all three of the above services on a GEMS host but these servers will be geolocated across the world and will have different and/or unique sets of users connecting to them. For example, lets say there's a company with three different offices located in San Francisco, London, and Tokyo. Ideally, you would configure Good Control in the following manner: 1. Create three (3) organization-level App IDs: com.xyzcorp.gdservice-entitlement.enterprise.svl, com.xyzcorp.gdservice-entitlement.enterprise.ldn, and com.xyzcorp.gdserviceentitlement.enterprise.tyo. 2. In Good Control, go to Manage Apps > Add App > GD App ID and Version Only. 3. Populate the server information for the new application IDs in Step 1 with the appropriate server clusters for each affinity. For example, com.xyzcorp.gdservice-entitlement.enterprise.svl would have its servers be strictly those located in Sunnyvale. Do the following: a. Go to Manage Apps >newly created App ID > Good Dynamics > Server-Edit b. Configure all the servers for this particular location c. Repeat Steps a–b for each app that were created in Step 1. 4. Assign each of the app IDs as providers of the three enterprise services listed under basic setup, as follows: a. Go to Manage Apps >newly created App ID> Good Dynamics > Version-Edit b. Click Edit for your version, then click the Bind Service button. Add all three services (Presence, Directory, FollowMe) c. Repeat Step a–b for each app created in Step 1. 5. Create a different App Group for each affinity. 6. Make sure that com.good.gdservice-entitlement.enterprise is NOT listed as an allowed application in the "Everyone" App Group. 7. Assign each new App ID as an allowed application to the respective application group. Since users can be part of multiple application groups, it would be ideal that these new affinity groups be strictly limited to allowed apps for that affinity. 8. Add users to the appropriate App Groups.

Additional Considerations Since it is possible to mix and match multiple GEMS and user affinities, when desired, in deployments where there is a different Good Control server for different affinities, advanced setup may be unnecessary. This is because server configurations aren't shared across GCs. The major thing to watch out for when performing custom setup

Installation and Configuration Guide

245

Appendix I – Advanced Launcher Setup

is to ensure that a user will find only one provider of a particular service. If Launcher detects multiple providers of a service, it will choose one at random (and likely remain with that choice if nothing changes). In setups where organization-level App IDs are created for complex server mapping, such a scenario could happen in the following ways: a. com.good.gdservice-entitlement.enterprise is populated with server information and not removed from the "Everyone" application group. b. Multiple organization-level App IDs are created that become providers of the same service and a user is granted access to them. c. A user is added to more than one affinity App Group. From the client perspective, the best way to debug this is by enabling detailed logging and looking through the logs to determine if more than one provider has been found.

Troubleshooting Launcher Performance During Launcher setup in Good Control, your primary concern is making sure the configured services are visible to Good Launcher. If you use the Good Enterprise Services App ID com.good.gd-serviceentitlement.enterprise and it is incorrectly configured, the following log lines could appear. No FollowMe service available Unable to find Presence service provider Unable to find Directory service provider

One of two things could be causing this: a. App IDs that are providers of server-side services will not show up for an app if there no servers are specified for this particular App ID. b. Although users can be allowed access to an ID on an individual basis, assigning a user to an application group is typically more efficient; the pariticular user in question may not belong to an App Group with access to this App ID. To verify that servers are specified for this App ID: In Good Control, click Manage Applications, select com.good.gdservice-entitlement.enterprise, then open the Good Dynamics tab and add the pertinent FQDNs to the GEMS server cluster. See Adding GEMS to the Good Enterprise Services Entitlement App for detailed instructions. To verify that the user is entitled to this App ID: Find the App Groups to which this user belongs and check to see that the GES entitlement ID is set as an allowed application to at least one of the groups. If the setup is correct and none of the log messages above show up, make sure detailed logging is enabled and check for the following log line: Discovered service providers for service: (using first in list)

Installation and Configuration Guide

246

Appendix I – Advanced Launcher Setup

Here, should always be 1. If this number is greater than 1, it is because more than one app became a provider of one of the three enterprise services. If this provider happens to be an actual app that is installed on the device, it will show up as a provider, despite not listing any servers. Unfortunately, Launcher's logging doesn't list this case so it may be a challenge to track down the rogue provider. Future versions of Launcher will address this issue. Otherwise, immediately following this log line, look for the following: Discovered servers for service provider:

Here, verify that the is the correct or intended provider. For setups using the GES entitlement ID, the name should be Good Enterprise Mobility Server Entitlement. If remedial action is taken to specify servers for this App ID or to add this user to an entitled App Group, Launcher should now be attempting to connect to the appropriate GEMS host. Again, with detailed logging enabled, you should see the following: Directory info request: \n (directory info) Presence subscribe request: \n\n (presence)

A log line for Followme indicating the start of a request will be added in a future release of Launcher. If a connection error occurs, it could be for either of two reasons: a. The https connection could not be established b. The server returned with an error response. If the former (a), the following log lines will appear: Error in getting directory info (): (directory info) Error in subscribing to presence (): (presence) Connection error when trying to retrieve from FollowMe store: (followme)

These log entries don't require detailed logging to be enabled. In such cases, first verify that the user is connected to the web, that the required GEMS hosts are each online, and that the server URL(s) specified for the provider(s) of the Launcher services are correct. For cases where the server returns an error code, this is likely no longer an issue with Launcher but something for the GEMS engineering support team to take a look at.

Installation and Configuration Guide

247

Appendix J – Changing the GEMS Dashboard and Web Console Login

Appendix J – Changing the GEMS Dashboard and Web Console Login As of GEMS 1.4, both the Dashboard and Web Console support Active Directory-based login. However, for versions of GEMS numbered 1.3.x and earlier, it is a recommended practice to change the administrator's password for the GEMS Dashboard UID/PWD, in accordance with your IT policy. To change the administration password in v1.3.x and earlier: 1. In your favorite text editor, open \Good Enterprise Mobility Server\Good Server Distribution\gems-quickstart-\etc\users.properties. 2. Change the current password from admin (the SHA-1 Hash highlighted in yellow) to something else, after which, this will be the password for the GEMS Web Console. admin={CRYPT}a0089182becd921781d5ba1e58fa4d129b24060f{CRYPT}, _g_:admingroup ð admin=,_g_:admingroup You can enter a plain text value. It will automatically be replaced with a salted SHA-256 Hash the next time an admin user logs in. 3. Save your changes. To confirm the change: Restart the Good Technology Common service and login to the GEMS Web Console by going to http://.com:8443/system/console/configMgr using the new/changed password.

Installation and Configuration Guide

248

Appendix K – Migrating Your Good Share Database to GEMS-Docs

Appendix K – Migrating Your Good Share Database to GEMS-Docs A Good Share deployment can migrate/repurpose its database for the GEMS-Docs service to support existing user transition from the Good Share client to Good Work. First, however, GEMS and the Docs Configuration Console must be installed in accordance with the guidance offered in the GEMS Administration Guide.

Client App Support Considerations The following limitations must be considered in determining whether or not a migration is advisable: l

Good Share clients communicate with the Good Share server only; they are not supported by the GEMS-Docs service

l

Good Work Docs communicates with the GEMS-Docs service only; it is not supported by the Good Share server.

Given these inherent limitations, it is recommended that you continue to run your deployed Good Share servers in parallel with the GEMS-Docs service for a duration sufficient to conveniently transition your users from their Good Share client app to Good Work. Important: After upgrading your Good Share database to GEMS-Docs, discontinue using the old Good Share Console and use only the GEMS Dashboard Home > Docs pages for administration going forward. Otherwise, you will want to consider two basic migration scenarios: (1) Migrating with continued Good Share client support (2) Migrating to Good Work only (no Good Share client support) Each is covered in turn here.

Migrating with Continued Support for Good Share To migrate to GEMS-Docs while continuing to support Good Share clients: 1. Use the Performing a GEMS fresh installation or upgrade topic to install the GEMS-Docs Service. When you are prompted to select the database for Docs, select the Good Share database. Once the installation is complete and GEMS is running, both the GEMS-Docs service and Good Share server should be functional and sharing the same data. This means that policies, users, and data sources previously configured for Good Share should all be available in GEMS-Docs. Logged audit data continues to be available, and reports can be generated from the Good Share Web Console. Note: If you are using Windows Authentication for the Good Share database, Good Technology Common Services must run under a user who has access to the Good Share database. 2. When all Good Share users have switched to Good Work and Good Share clients are no longer being used, you can uninstall Good Share server and the Good Share Web Console.

Installation and Configuration Guide

249

Appendix K – Migrating Your Good Share Database to GEMS-Docs

Migrating to Good Work Only If there is no requirement to support both Good Work and Good Share at the same time (i.e., concurrently), then the machine(s) used for Good Share can be repurposed in accordance with the following steps: 1. Uninstall Good Share server and the Good Share Web Console but do not remove the database. 2. Install GEMS and configure the Docs service in accordance with the procedures enumerated in the GEMS Administration Guide. Again, if you are using Windows Authentication for the database, Good Technology Common Services must run under a user who has access to the Good Share database. 3. Launch the GEMS Dashboard, click Docs, then click Database, and here also select the database previously used by Good Share. Upon completion of Step 3, all previously configured policies, users, data sources and settings are now available to the GEMS-Docs service and configurable in the Docs Configuration Console.

Noteworthy Feature Differences (GEMS-Docs versus Good Share) The following feature changes will be noticed when comparing GEMS-Docs to Good Share server: l

Open-in application list is now managed in the Good Control application policy for Good Work. Any Open-in lists created in Good Share must now be added in Good Control.

l

Keep in-sync feature is not supported

l

Permissions in data sources not supported:

l

o

Allow Native email

o

Print

o

Open in

Security settings no longer supported: o

Allow playing of media files – iOS only (stored outside of the secure container during playback)

o

Enable device to remember user password

o

Display event information for calendar alerts

o

Force user to save Pending Uploads

Installation and Configuration Guide

250

Appendix L – Configuring AlwaysOn Support for SQL Server 2012

Appendix L – Configuring AlwaysOn Support for SQL Server 2012 The AlwaysOn Availability Groups feature is a high-availability and disaster-recovery solution providing an enterprise-level alternative to database mirroring. Introduced in SQL Server 2012, AlwaysOn Availability Groups maximize the availability of a set of user databases for an enterprise. An availability group supports a failover environment for a discrete set of user databases, known as availability databases, that fail over together. An availability group supports a set of read-write primary databases and 1 to 8 sets of corresponding secondary databases. Optionally, secondary databases can be made available for read-only access and/or some backup operations.

Setting Up SQL AlwaysOn AlwaysOn requires Windows Cluster, but not Quorum. For guidance from Microsoft on creating a Windows Server failover cluster, see Clustering and High-Availability. The guidance presented here is limited to AlwaysOn for SQL Server. To set up SQL Server for an AlwaysOn Availability Group: 1. Launch SQL Installation Center, and choose New SQL Server stand-alone installation or add features to an existing installation.

2. Click Next. Then, in the Feature Selection window, select the recommended features outlined below in red, and click Next again.

Installation and Configuration Guide

251

Appendix L – Configuring AlwaysOn Support for SQL Server 2012

3. In the Server Configuration window: a. Set the Account Name to the domain account. b. Select Manual as the Startup Type. c. Click Next.

Installation and Configuration Guide

252

Appendix L – Configuring AlwaysOn Support for SQL Server 2012

4. In the Database Engine Configuration window, click the Server Configuration tab: a. Select an Authentication Mode. b. Create a SQL Server sa password. c. Click Add Current User. d. Click Next.

5. Click the Data Directories tab and enter a directory or keep the default. Share storage is not required. 6. Click Next to complete installation. To set up SQL AlwaysOn: 1. On each machine in the cluster, launch SQL Server Configuration Manager, then right-click the desired SQL Server instance and select Properties.

2. Enable AlwaysOn Availability Groups, then click OK. 3. Now do a full back up of the database that will reside in the AlwaysOn group. The backup should be located in a shared folder that the other nodes of the cluster can reach and read.

Installation and Configuration Guide

253

Appendix L – Configuring AlwaysOn Support for SQL Server 2012

4. Launch Microsoft SQL Server Management Studio, right-click AlwaysOn High Availability in the Object Explorer and select New Availability Group Wizard...

5. Specify an Availability group name (for display, not connection) and click Next.

6. Select the databases for the AlwaysOn availablity group, then click Next.

Installation and Configuration Guide

254

Appendix L – Configuring AlwaysOn Support for SQL Server 2012

7. Open the Replicas tab and click Add Replica... to create a new replica (optional), then specify instances of SQL Server to host a secondary replica. Up to two replicas can be set for Automatic Failover; up to three for Synchronous Commit.

8. Click the Listener tab and if no Availability Group Listener exists, create one now, then click Next.

Installation and Configuration Guide

255

Appendix L – Configuring AlwaysOn Support for SQL Server 2012

9. Select Full as your data synchronization preference and specify a shared network location. Remember, it must be accessible by all replicas.

10. Click Next. Then, if validation is successful, clik Next again to complete availability group setup.

Testing Database Failover To test automatic failover: 1. Connect the database using the Listener. 2. In a query, execute: select @@servername

The host name of the current primary server should be listed. 3. Restart the primary server and verify that the replica configured for automatic failover can the take the AlwaysOn availability group to be the primary. 4. Execute select @@servername again to determine if a result is returned and whether or not the host name has changed. To test manual failover: 1. Connect to the database using the Listener. 2. In a query, execute: select @@servername

The host name of the current primary server should be listed.

Installation and Configuration Guide

256

Appendix L – Configuring AlwaysOn Support for SQL Server 2012

3. Now, connect to the database using the primary server name. 4. In the AlwaysOn group, right-click the target primary and select Failover, then select a target replica for failover.

5. Execute select @@servername on the AlwaysOn database to determine if a result is returned and whether or not the host name has changed.

Configuring Your GEMS Services Databases for AlwaysOn Availability To install GEMS services connected to a database in AlwaysOn, the instance name should be set to the Listener in the AlwaysOn group, not the cluster name and not the host name of the host server in the cluster. The databases created for GEMS services need to be added into the AlwaysOn group.

Installation and Configuration Guide

257

Appendix L – Configuring AlwaysOn Support for SQL Server 2012

Then, from the GEMS Dashboard, on the pertinent service configuration page (e.g., Home > Mail): l

Server = AlwaysOn Listener FQDN

l

Database = the name of the database added to the AlwaysOn Availability Group.

Installation and Configuration Guide

258

Glossary

Glossary A

Access Key Part of the activation key that is different for every GD application activation. Access keys consist of 15 letters and numbers. Access keys are generated by the enterprise GC server.

Activation Key All the credentials necessary for activation of a GD application for an end user. The necessary credentials are a provisioning ID and an access key.

AD Active Directory

ADSI Active Directory Services Interface

ADT Plugin Android Development Tools Plugin

Affinities The feature that enables enterprises to allocate their GP servers between their GC servers and their application servers. Allocation can be an absolute division, or based on a priority order, or both.

Application Policies The feature that enables GD application developers to add policies that are specific to their application to a GC server. Application policies are defined by developers, using an XML file format.

Application-Based Service A GD shared service that is provided by GD applications. An application-based service uses Good Dynamics AppKinetics for communication.

Authentication Delegation The feature for transferring authentication of the end user from one application to another. An application for which authentication is delegated does not display its unlock screen, and does not have its own security password. Authentication delegation can be used between two GD applications, and between GD applications and the GFE mobile client. Authentication delegation is controlled by the enterprise administrator through the management console of the respective software product, either GC or GFE Good Mobile Control.

Installation and Configuration Guide

259

Glossary

C

CIFS Common Internet File System - the standard way that computer users share files across corporate intranets and the Internet. An enhanced version of the Microsoft open, cross-platform Server Message Block (SMB) protocol, CIFS is a native file-sharing protocol in Windows.

CLI Command Line Interface

COTS Commercial Off the Shelf HTTP Proxy D

DC Direct Connect

DMZ Demilitarized Zone

DMZ proxy for Direct Connect HTTP proxy in the enterprise perimeter network that relays DC connections.

DN For a single domain Active Directory Domain Service, this is the text box for the Distinguished Name (DN) of the starting point for directory server searches. For example: DC=mmycompany,DC=com. The Connector starts from this DN to create master lists from which you can later filter out individual users and groups. For a multidomain Active Directory Domain Service (AD DS) forest, the appropriate action is to leave this text box blank. F

FQDN fully qualified domain name

Installation and Configuration Guide

260

Glossary

G

GC Good Control server. The GD server component which hosts the web-enabled Good Control management console, or GC console, for managing permissions and settings for Good Dynamics applications. GC resides on a machine belonging to your organization.

GD Good Dynamics. Good product that gives companies a set of development tools to create their own secure apps built on the technology used to create GFE.

GD Application ID The unique identifier used throughout GD to identify the application for the purposes of entitlement, publishing and service provider registration.

GD Authentication Token mechanism A token-based single sign-on feature that enables an end user to be authenticated by an application server without the need for entry of any further credentials.

GD Direct Connect The feature for relaying GD communication through a proxy in the enterprise perimeter network (also known as DMZ or demilitarised zone) instead of through the GD NOC. This feature also enables GP servers to be deployed in the enterprise perimeter network, instead of behind the firewall.

GD Enterprise Servers Two GD components installed behind the enterprise firewall: Good Control (GC) and Good Proxy (GP).

GD NOC Good Dynamics Network Operations Centre - provides a secure communications infrastructure between the GD Runtime on the mobile device and the GD enterprise servers behind the firewall.

GD Runtime The component that is embedded in a mobile application to enable its connection to the GD platform and container. Every GD application includes an instance of the Good Dynamics Runtime. Alternative form: Good Dynamics Runtime

Installation and Configuration Guide

261

Glossary

GD SDK Good Dynamics Software Development Kit. The products that enable developers to build GD applications from source code in the native programming languages of the mobile platform. Native source code includes, for example, Objective-C on iOS, and Java on Android. Other forms: Good Dynamics SDK Good Dynamics Software Development Kit

GD Shared Services Framework for collaboration that includes Application-Based Services and Server- Based Services. Both types of service use a consumer-provider model. The consumer is always a GD application. The provider of an application-based service will also be a GD application. The provider of a server-based service will be an application server. Alternative forms: GD Shared Services Good Dynamics Shared Services Framework GD Shared Services Framework Shared Services Framework

GD Wrapped Application An application in which the GD Runtime has been embedded by using the GD Wrapping process. Other form: Good Dynamics Wrapped Application

GD Wrapping The product for embedding the GD Runtime in a mobile application executable without requiring access to application source code. Other form: Good Dynamics Wrapping

GDN Good Developer Networking. A web portal to support app development. • Download the Good Dynamics SDK • Download the Good Dynamics Servers • Access technical support, the Good Community, and other resources • Get notifications for technical updates • Get access to Good Dynamics enabled applications • Connect with developers and Good ISV partners

GEMS Good Enterprise Mobility Server

GFE Good for Enterprise

GNP Good Notification Push. Protocol that allows notification messages to be pushed from an application server to GD app.

Installation and Configuration Guide

262

Glossary

Good Dynamics AppKinetics™ Mechanism for secure exchange of application data between two mobile applications on the same mobile device. AppKinetics data exchange uses a consumer-provider model. One application in the exchange provides a service that is consumed by the other.

GP Good Proxy. The GD server component which provides a secure bridge between the GC server and your enterprise application servers, if any exist, and delivers messages to and from GD applications. GP resides on a machine belonging to your organization.

GRP Good Relay Protocol. Protocol for end-to-end secure communications between the GD app and the GP server.

GUID Globally Unique Identifier - is a unique reference number used as an identifier and typically refers to various implementation of the universally unique identifier (UUID) standard. See UUID.

GW Good Wrapping. The GD server component which can be used to wrap non-GD iOS applications with GD technology, allowing you to secure your applications without the need for additional programming or access to source code. GW resides on a machine belonging to your organization. H

HTML/CSS/JS Hypertext Markup Language, Cascading Style Sheet, and JavaScript, which are the languages used to code applications in the Adobe PhoneGap MEAP. I

IDE Integrated Development Environment

IOPS Input/Output Operations Per Second (pronounced eye-ops) is a common performance measurement used to benchmark computer storage devices like hard disk drives (HDD), solid state drives (SSD), and storage area networks (SAN). As with any benchmark, IOPS numbers published by storage device manufacturers do not guarantee real-world application performance.

Installation and Configuration Guide

263

Glossary

ISV Indepdent Software Vendor - a third-party software developer or reseller who has executed a partnership agreement with Good. J

JKS Java keystore

JSON JavaScript Object Notation, the format used for AppKinetics service definitions files. JSON is a standard. K

KCD Kerberos Constrained Delegation. A single sign-on feature that enables an end user to be authenticated by an application server that uses Kerberos, without the need for entry of further credentials.

KDC Key Distribution Center. A logical component of the Kerberos infrastructure L

LDAP Lightweight Directory Access Protocol - a directory service protocol that runs on a layer above the TCP/IP stack

LUN In computer storage, a logical unit number, or LUN, is a number used to identify a logical unit, which is a device addressed by the SCSI protocol or Storage Area Network protocols which encapsulate SCSI, such as Fibre Channel or iSCSI.

LUSE Logical Unit Size Expansion

Installation and Configuration Guide

264

Glossary

M

MAM Mobile Application Management

MMC Microsoft Management Console

MyTerm

O

OWA Outlook Web Access P

Provisioning ID Part of the activation key that is the same for all GD applications activated by the same end user at the same enterprise. The provisioning ID is typically the end user’s enterprise email address. R

Relay Server Server in the NOC that provides communications between the GD app and GP servers.

Repository In GEMS-Docs, a repository is shared data source designated by a Display Name, a Storage Type (File Share or SharePoint), and a Path. Each repository is defined with user access permissions. Repositories can be further organized into Lists. When a repository is member of a list, it can inherent the user access permissions defined for the whole list.

RTT Round trip time

Installation and Configuration Guide

265

Glossary

S

SDK Software Development Kit. Typically a set of software development tools that allows for the creation of applications for a certain software package, software framework, hardware platform, computer system, video game console, operating system, or similar platform.

Server Clustering A feature within GD that enables enterprises to deploy groups of servers as single nodes in their GD infrastructure. The following servers can be deployed in clusters using this feature: GP, GC, application servers.

Server-Based Service A GD shared service that is provided by application servers. A server-based service could use any communication technology, including HTTP or TCP sockets.

Service Discovery Feature that enables a prospective consumer of a shared service to query for available providers of the service. The result of a service discovery query will be a list of GD applications, for an application-based service, or a list of servers, for a server- based service. Alternative forms: AppKinetics Service Discovery

Service provider registration Activity of adding a GD application or application server to the list of providers of a particular service. The list of service providers is hosted in the GD NOC.

Share In GEMS-Docs, a share is synonomous with a repository and can be one of two storage types: File Share or SharePoint. See Repository.

SPN Service Principal Name

SSL secure socket layer

Installation and Configuration Guide

266

Glossary

T

TLS transport layer security U

UI User Interface

UPN - User Principal Name In Active Directory, this is the name of the system user in email address format

UUID Universally Unique Identifier - an identifier standard used in software construction. A UUID is simply a 128-bit value. The meaning of each bit is defined by any of several variants. For humanreadable display, many systems use a canonical format using hexadecimal text with inserted hyphen characters. For example: de305d54-75b4-431b-adb2-eb6b9e546014 The intent of UUIDs is to enable distributed systems to uniquely identify information without significant central coordination.

UX User Experience

Installation and Configuration Guide

267