GEMS Installation and Configuration Guide

Transcription

GEMS Installation and
Configuration Guide
for Administrators
Product Version: 1.4
Doc Rev 3.8.4
Issued: 27-Mar-15 | Updated: 14-Apr-15
Good Enterprise Mobility ServerTM
Legal Notice
This document, as well as all accompanying documents for this product, is published by Good Technology Corporation
(“Good”). Good may have patents or pending patent applications, trademarks, copyrights, and other intellectual property
rights covering the subject matter in these documents. The furnishing of this, or any other document, does not in any way
imply any license to these or other intellectual properties, except as expressly provided in written license agreements with
Good. This document is for the use of licensed or authorized users only. No part of this document may be used, sold,
reproduced, stored in a database or retrieval system or transmitted in any form or by any means, electronic or physical, for
any purpose, other than the purchaser’s authorized use without the express written permission of Good. Any unauthorized
copying, distribution or disclosure of information is a violation of copyright laws.
While every effort has been made to ensure technical accuracy, information in this document is subject to change without
notice and does not represent a commitment on the part of Good. The software described in this document is furnished
under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the
terms of those written agreements.
The documentation provided is subject to change at Good’s sole discretion without notice. It is your responsibility to utilize
the most current documentation available. Good assumes no duty to update you, and therefore Good recommends that
you check frequently for new versions. This documentation is provided “as is” and Good assumes no liability for the
accuracy or completeness of the content. The content of this document may contain information regarding Good’s future
plans, including roadmaps and feature sets not yet available. It is stressed that this information is non-binding and Good
creates no contractual obligation to deliver the features and functionality described herein, and expressly disclaims all
theories of contract, detrimental reliance and/or promissory estoppel or similar theories.
Legal Information
© Copyright 2015. All rights reserved. All use is subject to license terms posted at www.good.com/legal. GOOD, GOOD
TECHNOLOGY, the GOOD logo, GOOD FOR ENTERPRISE, GOOD FOR GOVERNMENT, GOOD FOR YOU, GOOD APPCENTRAL,
GOOD DYNAMICS, SECURED BY GOOD, GOOD MOBILE MANAGER, GOOD CONNECT, GOOD SHARE, GOOD TRUST, GOOD
VAULT, and GOOD DYNAMICS APPKINETICS are trademarks of Good Technology Corporation and its related entities. All
third-party technology products are protected by issued and pending U.S. and foreign patents.
Good DynamicsTM™
2
Table of Contents
Good Integrated Mobile Services
1
Enhanced Notifications
1
Architecture
2
GEMS Prerequisites
4
Upgrade Notes
5
Supported Upgrades
5
Additional Considerations
5
Core Requirements
5
System and Network Requirements
5
Good Dynamics Requirements
8
Configuring the Java Runtime Environment
8
Setting Up a Windows Service Account for GEMS
9
Push Notification Service (PNS) Prerequisites
Supported Exchange Versions
9
9
EWS Proxy Support
10
Create an Exchange Mailbox for the Service Account
11
Grant Application Impersonation Permission to the Service Account
12
Set Authentication for the EWS Protocol
12
Set Up Exchange Autodiscover
12
Database Requirements
13
Connect Prerequisites
14
Microsoft Lync Server Requirements
14
Preparing the Lync Topology for GEMS
21
SSL Certificate Requirements for Lync
23
29
Presence Prerequisites
30
Docs Service Prerequisites
30
Server Software and Operating System Requirements
30
31
Good Enterprise Mobility Server™
iii
Enabling the IIS Role
32
Directory Lookup Service Prerequisites
34
Follow-Me Service Prerequisites
34
Installing GEMS
34
Upgrading
35
Downloading and Running the GEMS Installer
35
Configuring GEMS Core
39
Changing the GEMS Dashboard Admin Password
39
Replacing the Auto-Generated Self-Signed SSL Certificate
40
Enabling GEMS HTTP (Optional)
40
Configuring GEMS Services
Configuring the Push Notification (Mail) Service
41
42
Enabling Exchange ActiveSync (EAS)
42
Configuring PNS (Mail) in the GEMS Dashboard
42
Configuring Good Control
48
Configuring GEMS-PNS for HA
51
Device Verification and Testing
52
PNS Logging and Diagnostics
52
Configuring the Connect Service
57
Configuring Connect in the GEMS Dashboard
58
Configuring Good Control for Connect
66
Using Friendly Names for Certificates in Connect
75
Enabling SSL Support Via Good Proxy
77
Configuring Support for the Global Catalog
85
Configuring Windows Services
86
Connect Service Logging and Diagnostics
88
Configuring the Presence Service
90
Configuring Presence in the GEMS Dashboard
90
Configuring Good Control for Presence
91
Using Friendly Names for Certificates in Presence
93
Logging and Diagnostics
95
iv
Updating the Connect and Presence Services Using Lync Director
96
Maintaining GEMS Cluster Identification in Good Control
96
Configuring Good Enterprise Services in Good Control
97
Adding GEMS to the Good Enterprise Services Entitlement App
97
Adding the GES Entitlement App to an App Group
98
Configuring the Docs Service
Installing the Docs Configuration Console
99
99
Setting Up the Docs Service
105
Configuring Good Proxy
108
Configuring Good Control for the Docs Service
109
Adding Users to the Docs Configuration Console
113
Managing User Profile and Permissions
115
Defining User Access and File Sharing Policies
117
Fine-Tuning the Docs Service
127
Managing Roles
131
Managing Audit Logs
132
Configuring Support for Hosted SharePoint (SharePoint Online )
133
Local Folder Synchronization
134
Troubleshooting the Docs Service
139
Error 404: Connecting to Docs Service
140
Device Provisioning and Activation
141
Appendix A – GEMS with Push Notifications Service Pre-Installation Checklist
143
Appendix B – GEMS with Connect and Presence Pre-Installation Checklist
146
Appendix C – Importing Certificates into the GEMS Java Keystore
150
Appendix D – Understanding the GEMS-Connect Configuration File
153
Appendix E – Fine-Tuning Your Java Memory Settings
157
Appendix F – IIS SSL Offloading
158
Appendix G – GEMS Windows Event Log Messages
164
Appendix H – File Types Supported by GEMS-Docs
167
Appendix I – Obtaining a Google Cloud Messaging API Key
169
Creating a Google API Project
169
Adding the API Key to Good Control
172
v
Glossary
173
vi
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 their enterprise file server and SharePoint
documents natively, without the need for VPN software, firewall reconfiguration, or duplicate data stores.
A 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 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).
Enhanced Notifications
GEMS 1.3 introduced a greatly improved end-user experience for new email notifications in the iOS Notification
Center. Notifications now display reliably when Good Work is suspended in the background or even when it is
not running at all. This results in an end-user experience wherein they can reliably know which messages they
have received without having to enter the Good Work app.
1
In GEMS 1.4, an improved VIP Notification service is being introduced with the following enhancements:
o
Rules can be set for Sender, Subject, and Priority fields of an email
o
Automatic passing of rules from Good Work clients to GEMS
o
Rules can be synchronized across devices
o
Custom sound files can be associated with the rules.
Architecture
At a high level, the GEMS architecture looks like this:
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.
2
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, limited to the Connect and Presence architecture, looks like this—again at a high level:
The PNS architecture, leveraging Microsoft's Exchange Web Services (EWS) with Exchange ActiveSync (EAS) can be
viewed from a slightly different perspective, like this:
Note: While it is possible to consolidate Good Control/Good Proxy and GEMS on the same server, such a
configuration will require more memory and CPU on the single server. A single server approach is feasible in a
3
GEMS Prerequisites
proof-of-concept (POC) environment only. Moreover, if using a single server, you are likely to encounter a port
conflict between Good Dynamics and the Lync Presence Provider (LPP). To rectify this conflict on a single
machine, start Good Control and Good Proxy after Good Presence.
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, 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
l
Before attempting installation, be sure to carefully read and confirm that you meet all of the listed requirements.
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
Docs Requirements
l
Directory Lookup Requirements
l
Follow-Me 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.
4
GEMS Prerequisites
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.
Supported Upgrades
l
GEMS 1.3 (1.3.10.8) ð GEMS 1.4 (1.4.14.19)
l
GEMS 1.2 (1.2.16.32) ð GEMS 1.4 (1.4.14.19)
Additional Considerations
When upgrading instances in a cluster, use the GEMS installer to upgrade each GEMS instance in turn.
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.
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
l
l
Configuring the Java Runtime Environment (JRE)
l
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
1See GEMS Deployment Planning and Upgrade Guide for scalability and sizing guidelines for your specific enterprise traffic and use profile.
5
GEMS Prerequisites
l
50 GB disk space
l
100 / 1000 Ethernet Card
Software
l
Java Runtime Environment (JRE) 7 Update 67 (7up67) or higher Java 7 update for Microsoft Windows (64-bit),
available for download directly from Oracle.
Caution: Java 8 is not supported at this time.
Operating System
Because GEMS uses Microsoft's Unified Communications Managed API (UCMA) to integrate Microsoft Lync with
the GEMS Connect and Presence services, the latter also used by the Mail component of Good Work, the OS
version required to run GEMS is dependent upon the version of Microsoft Lync deployed. Per guidance from
Microsoft, use the following criteria to determine the version of MS Windows Server supported by GEMS:
l
l
For MS Lync 2010 Deployments use Windows Server in one of these 64-bit versions:
o
2008 R2
o
2008 R2 SP1
o
2008 R2 SP1
o
2012 R2
If Lync is not utilized in your environment, the above OS requirements are still required from an installation
standpoint. Due to a limitation in the installer, you will need to choose a version of Lync during the installation
process, even though Lync may not be used in your environment.
Supported Microsoft Exchange versions include:
l
Exchange 2010 (SP2 RU4 +)
l
Exchange 2013 (CU1, CU2, CU3, SP1 [CU4])
Supported Microsoft Lync versions include
l
Lync 2010
l
Lync 2013
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
6
GEMS Prerequisites
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
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 and Presence
l
49555 from the Lync Server for the Connect Service
l
49777 from the Lync Server for the Presence Service
Outbound TCP Ports (not blocked by any firewall)
l
443 to Good NOC/APNS
l
443 to Exchange
l
5061 to the Lync Server
l
17080 to the Good Proxy server
l
l
1433 to the MS SQL Server (default)
l
1434 UDP to the Lync database (for initial setup only)
l
49152 – 57500 TCP: Random port in this range to the Lync database (for initial setup only)
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-PSN and Presence
l
8099 for use by the .NET Component Manager
l
8060 for use by the Lync Presence Provider (LPP)
7
GEMS Prerequisites
TCP/IP Port Access to the Database
l
1433 to the Microsoft SQL Server default
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.7.38.19
l
Good Proxy (GP) Server 1.7.38.14
For best performance results, the most current software version available is strongly recommended and is
available from the Good Developer Network.
Important: Your Good Dynamics Server(s) must be operating prior to installation of GEMS.
Configuring the Java Runtime Environment
JRE 7 Update 67 for Windows x64 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 under PATH, create it and set it to the Java install folder; e.g.,
C:\Program Files\Java\jre7. Make sure the path is set to the 64-bit JRE.
3. Click OK and you're done.
8
GEMS Prerequisites
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.
Create an Active Directory Account for GEMS Services
Set the following attributes for the Good-GEMS AD Account:
l
The preferred UID is "GoodAdmin"
l
Account Password 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.
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
1.4 (in-cloud and on-premise)
Exchange 2007
No
Exchange 2010 SP 1+
Yes
Exchange 2013
Yes
Microsoft O365
Yes
Hosted Exchange* (Exchange 2010 SP 1+)
Yes
9
GEMS Prerequisites
GEMS Version
Exchange Version
Supported
Exchange 2007
No
Exchange 2010 SP 1+
Yes
Exchange 2013
Yes
Microsoft O365
Yes
Yes
Exchange 2007
No
Exchange 2010 SP 1+
Yes
Exchange 2013
Yes
Microsoft O365
Yes
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.
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:
10
GEMS Prerequisites
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:
Proxy Support
GEMS Versions
Remote Endpoint
Transparent
Anonymous
Basic
NTLM
1.1
NOC
Yes
Yes
Yes
No
1.2, 1.3, 1.4
NOC
Yes
Yes
Yes
Yes
1.1, 1.2, 1.3, 1.4
Remote O365
Yes
No
No
No
1.1, 1.2, 1.3, 1.4
On-prem Exchange
n/a
n/a
n/a
n/a
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.
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:
11
GEMS Prerequisites
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.
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
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.
12
GEMS Prerequisites
Please see also "Exchange Autodiscover" by Jaap Wesselius (2010) for more helpful information on Exchange
Autodiscover.
You will need to create a (blank) SQL database for GEMS-PNS. The recommended name for this database is
"GEMS-EWS."
Important: Make sure the Collate property is set to CI (case insensitive).
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-EWS, then check the return value. If the
value is:
l
l
‘SQL_Latin1_General_CP1_CI_AS’, the database is case insensitive
‘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
13
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 PNS.
The following versions of MS SQL Server are supported:
l
SQL Server 2008 and 2008 R2 (Standard/Enterprise)
l
SQL Server 2012 and 2012 SP1 (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.
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
l
Preparing the Lync Topology for GEMS-Connect
l
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
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.
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.
14
GEMS Prerequisites
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-x86.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-x86.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.
15
GEMS Prerequisites
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.
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:
16
GEMS Prerequisites
To install Microsoft .NET Framework 4.5:
1. Go to the Microsoft .NET Framework 4.5.
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 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. Go to Unified Communications Managed API 3.0 Runtime in the Microsoft Download .NET Framework 3.5
SP1 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.
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
17
GEMS Prerequisites
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.
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.
18
GEMS Prerequisites
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.
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.
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-x86.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-x86.msu executable.
7. Open Windows PowerShell (x86) and run the following command to enable execution of remote-signed
scripts:
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
19
GEMS Prerequisites
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:
To install Microsoft .NET Framework 4.5:
1. Go to the Microsoft .NET Framework 4.5.
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.
20
GEMS Prerequisites
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.
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
21
GEMS Prerequisites
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
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 <siteId number> -ComputerFqdn "FQDN of GEMS machine"
<registrar>
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:presence_<GEMS hostname>@mycompany.com"
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.
22
GEMS Prerequisites
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.
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 "<FQDN of GEMS machine>" -Pool "<name of GEMS pool previously
created>"
With the Lync topology now prepped for the new GEMS, you may proceed to Installing GEMS after reviewing the
next section on creating/acquiring a valid SSL certificate.
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 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.
1For more on TLS and MTLS for Lync Server 2010, see http://technet.microsoft.com/en-us/library/gg195752(v=ocs.14).aspx.
23
GEMS Prerequisites
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.
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.
24
GEMS Prerequisites
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.
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.
25
GEMS Prerequisites
1. 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.
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.
26
GEMS Prerequisites
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.
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.
27
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:
28
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 rthe Security tab, add the service account and grant it read access to the certificate.
You will need to create a (blank) SQL database for GEMS-Connect. The recommended name for this database is
"GEMS-CONNECT."
29
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.
l
l
l
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.
The Presence service has the same predeployment requirements as the Connect service. Please refer to the
complete list of Connect Prerequisites.
Docs Service Prerequisites
The Docs Service for GEMS comes with its own configuration console to set up the service's users and maintain
authenticated access to approved file shares and SharePoint sites. In addition, Docs requires its own SQL
database like the 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
l
IIS Role Requirement
Server Software and Operating System Requirements
The requirements cited here apply to the machine on which the Docs Configuration Console is installed, not for
GEMS or core server components comprising the Good Dynamics platform. It is recommended that you run
GEMS and Docs Configuration Console on separate machines, although for POC (non-production) purposes,
both GEMS and the Docs Configuration Console running on a single machine is supported.
l
Operating System:
o
Microsoft Windows Server 2012 R2
o
Microsoft Windows Server 2012
o
Microsoft Windows Server 2008 (64-bit) or Microsoft Windows Server 2008 R2
30
GEMS Prerequisites
l
l
Windows Role and Feature Requirements:
o
.NET Framework 4.0 or higher.
o
Windows Installer 4.5 Redistributable
Internet Information Services (IIS):
The IIS role must be installed on the Docs machine in order to install the web console. This role is added using
Server Manager > Add Roles > IIS.
Enable the following role features:
o
Static Content
o
Default Document
o
ASP.NET Extensibility
o
ASP
o
IIS Management Console
See Enabling the IIS Role for Windows 2012 guidance.
Important: Make sure you are a member of the Web Server Administrator IIS role on the Docs
Configuration Console host.
l
Network capabilities and resources:
o
The server must be a domain member and have access to Active Directory
o
Network shares must be accessible from the server
o
SharePoint sites must be accessible from the server
o
Docs Configuration Console users must be in the Allow Logon Locally local security policy or Group Policy.
A SQL database is also required for the Docs Service component of GEMS. GEMS-Docs currently supports
Microsoft SQL Server. The Docs Console installer creates this database, hard-coded to "SumooHServerDB" and
extends the schema.
Important: The user running the installer must have the DB sysadmin permission so the database can be
created. After installation, db_owner credentials suffice for access.
l
l
l
31
GEMS Prerequisites
If you do not have one of these SQL Service versions available, you can obtain one from the Microsoft Download
Center.
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.
Enabling the IIS Role
For supported versions of Windows Server 2008, IIS 7.x configuration is based on the existing .NET Framework
configuration store, which lets you store IIS configuration settings alongside ASP.NET configuration settings in
Web.config files. IIS 7.x also offers compatibility with other technologies such as Active Server Pages (ASP),
Common Gateway Interface (CGI), and Internet Server API (ISAPI). Most settings can be configured at the local
level (Web.config) and also at the global level (ApplicationHost.config), with redirect settings (Redirection.config)
to configuration files and schema located on another computer. Visit Microsoft's IIS Learning Center for a
complete introduction to IIS features and capabilities.
You can install IIS 7.5 by using the Add Roles and Features wizard in Server Manager or by using the command
line.
Specifically in Windows 2012:
1. Open Add Roles and Features , then select Server Roles and enable the checkbox for Application Server
in the Roles list.
2. Click Next.
3. Under Application Server, select Roles Services, then add .NET Framework 4.5, Web Server (IIS) Support,
and HTTP Activation by enabling each respective checkbox in the Roles Services list.
32
GEMS Prerequisites
4. Click Next.
5. Under Web Server Role (IIS), select Role Services, then expand Application Development and enable .NET
Extensibility 4.5, ASP, ASP.NET 4.5, along with ISAPI Extensions and Filters.
6. Click Next.
33
Installing GEMS
Important: The account under which the Docs Service application pool will run must belong to the Local
Administrators group.
7. Continue to click the Next button until the Install button is enabled, then click it to complete IIS role
configuration for the Docs Service.
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 (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 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:
34
Installing GEMS
l
Core Prerequisites
l
PNS Prerequisites
l
l
It is strongly recommended that installation be done with the GEMS service account.
Important: Before proceeding, verify that you have created the blank databases specified under PNS
Requirements and Connect Requirements.
Upon verifying that all prerequisites have been satisfied, download and unzip the GEMS installer package, then
continue with the steps below.
Upgrading
If you are upgrading from a previous version of GEMS, the installer will detect previously installed versions of
GEMS and offer an upgrade option. Please select Upgrade, then follow the on-screen instructions in accordance
with the instructions that follow here.
Tip: During an upgrade, when prompted to enter database information for the Mail/Core and Connect DBs,
remember to enter the database details that apply to your current (pre-1.4) GEMS deployment.
Important: Beta Upgrades are not supported. If you are a Good PTEP (beta testing program) participant, you
must do a fresh install of the GEMS beta version being evaluated.
Downloading and Running the GEMS Installer
To download and run GEMS Setup:
1. Download the installation zip package from the GEMS product page.
2. Unpack the contents of the zip and run GoodEnterpriseMobilityServerSetup.<version>.exe.
35
Installing GEMS
3. Choose either Lync Server 2010 or Lync Server 2013, then click Next.
Note: If you have a Lync environment, select the appropriate version. Otherwise, accept the default, even if
you don't use Lync.
The installer now runs a check of required components.
4. If all Prerequisites indicate Pass, click Next. If not, make a note of the failed components so that any issues
can be resolved during the configuration process, then click Next.
36
Installing GEMS
5. Accept the default installation path or click Browse to change it.
6. Accept the license agreement by clicking the checkbox, then click Next.
7. Specify the following database information GEMS in accordance with the prerequisites for Mail/Core and
Connect:
37
Installing GEMS
a. DB Server FQDN\SQL Server Instance
b. Mail/Core DB Name
c. Connect DB Name
8. Enable Windows Authentication by clicking its checkbox.
9. If you choose not to use Windows Authentication, enter the SQL Username and Password.
10. Click Install. It typically takes 3-5 minutes for the installer to finish.
11. When complete, click Configure to launch the GEMS Dashboard:
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.
12. The default Username and Password are both "admin." Enter admin in each respective field, then click
Login.
38
This displays the Good Services Configuration page, also called the GEMS Dashboard home page.
Note: Remember that in version 1.4 of GEMS, the Analytics service is strictly a preview for developers.
You're now ready to 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.
The Docs service enables SharePoint and NAS file access by Good Work clients.
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
Changing the GEMS Dashboard administration password
l
Installing the GEMS SSL Certificate
l
Enabling GEMS HTTP (optional)
Changing the GEMS Dashboard Admin Password
It is a recommended practice to change the administrator's password for GEMS periodically, in accordance with
your IT policy.
39
Important: Entering an incorrect username and password combination more than ten (10) consecutive times
results in a dashboard lockout. The lockout can be removed by using the following procedure for changing the
administration password.
To change the administration password for the GEMS Dashboard:
1. In your favorite text editor, open <GEMS Machine Path>\Good Enterprise Mobility Server\Good Server
Distribution\gems-karaf-<version>\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 Dashboard.
admin={CRYPT}a0089182becd921781d5ba1e58fa4d129b24060f{CRYPT},
_g_:admingroup ð admin=<new_password>,_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 Good Technology Common Services and login to the Dashboard by going to
http://localhost:8181/dashboard. You will be asked for the new password (username will still be admin).
The new admin password shall apply for the admin user of the GEMS Web Console.
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 <GEMS Machine Path>\Good Enterprise Mobility
Server\Good Server Distribution\gems-karaf-<version>\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 C.
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 disable SSL checking on the Good Work client. See "Adding the JSON Configuration
for EAS" in the Good Work Product Guide.
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.
40
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\gemskaraf-<version>\etc .
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-karaf-<version>\etc and open it in your text editor.
5. Find the following block of lines and delete the comment markers highlighted in yellow:
<!-<Call name="addConnector">
<Arg>
<New class="org.eclipse.jetty.server.nio.SelectChannelConnector">
<Set name="host">
<Property name="jetty.host" />
</Set>
<Set name="MaxIdleTime">300000</Set>
<Set name="Acceptors">2</Set>
<Set name="statsOn">false</Set>
<Set name="confidentialPort">8443</Set>
<Set name="lowResourcesConnections">20000</Set>
<Set name="lowResourcesMaxIdleTime">5000</Set>
</New>
</Arg>
</Call>
-->
6. Save the file.
7. Restart Good Technology Common 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
Directory Lookup
l
Follow-Me
41
Note: The Analytics service is currently an app developer's preview. In GEMS 1.4, 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
l
Configuring Mail in the GEMS Dashboard
l
l
Configuring GEMS-PNS for High Availability
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 or Exchange 2013.
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.
Upon clicking Mail, complete its service configuration in the following order:
Good Dynamics
Note: Your Good Dynamics Servers must be operating before the GEMS Push Notifications Service can be
configured for Good Dynamics.
1. On the Good Mail Service Configuration page, click Good Dynamics.
42
2. Enter the Good Proxy Hostname. If you have more than one Good Proxy server, pick any one you wish.
Autodiscover will correctly identify the others.
3. Enter the Good Proxy Port.
4. Select either HTTP or HTTPS, the latter being the more secure transport protocol.
5. Use the Test button to verify the connection.
6. Click Save to record the setting.
43
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., <your_sqlserver_hostname>\<instance_name>.
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 in Windows
Services Manager to allow these settings to take effect.
To use SQL Authentication to access the database:
1. Enter the database Server host name and instance; i.e., <your_sqlserver_hostname>\<instance_name>.
2. Enter the Database name.
44
3. Select SQL Authentication as the Authentication Type.
4. Click the Test button to verify connectivity with the database.
6. Use the Windows Services Manager to locate the service named Good Technology Common Services, 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. Then, as pictured
below...
2. Enter the Domain, Username ("GoodAdmin" is recommended), and Password of the Windows Service
Account. This account should have impersonation rights on Exchange.
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, you will need to turn off certificate verification
in accordance with the instructions found below under Problems Connecting to Exchange.
45
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.
To configure a Web Proxy for GEMS-PNS:
1. Returning to the Good Mail Service Configuration page, click Web Proxy. Then, as pictured...
2. Enable the Use Web Proxy checkbox.
3. For Proxy Address, enter the FQDN of the web proxy.
4. Enter a Proxy Port.
46
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. Click Test to confirm connection to the proxy server.
Android Push Notifications
Google Cloud Messaging (GCM) must be configured to support Android Push Notifications. This requires a GCM
sender ID and API key.
To configure Android Push Notifications:
1. On the dashboard's Good Mail Services Configuration page, click Android Push Notification.
2. Open a new browser tab and login to Good Control.
3. In the GC Dashboard under SETTINGS, click Licenses and Keys, then open the API Keys tab.
47
Note: If a GCM API Key does not currently exist in Good Control, follow the guidance in Appendix I for
obtaining a GCM API Key. If the key is already in Good Control vis-à-vis the screenshot above, continue with
the instructions here.
4. From the Good Cloud Messaging API section, copy the Sender ID and, switching to your browser's
GEMS Dashboard tab, paste the value into the GCM Sender ID field.
5. Returning to Good Control, copy the Key, switch to the GEMS Dashboard tab, and paste this value into the
GCM API Key field.
6. Click Save.
A few basic configuration settings are necessary so that Good Control can properly support Good Work
application users. These include:
l
Configuring EAS for the Good Work app
l
Adding Applications and Users
l
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.
48
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.
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 SETTINGS, click Client Connections.
2. Scroll down to ADDITIONAL SERVERS and click
.
3. 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).
49
4. White list additional GEMS hosts with GP Clusters by repeating from Step 2.
5. Click Submit to save 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.
50
Note:
Unless you import a publicly verifiable certificate into the GEMS Java keystore, please be aware of the
following:
4. If you have additional GEMS hosts, configure them for the application in the same way, after clicking
to
add a new row.
Configuring GEMS-PNS for HA
High Availability for GEMS-PNS is based upon multiple active instances with no instances in a passive/standby
mode.
When adding a new GEMS instance, you will need to:
1. Configure your new GEMS instance to use the existing database.
2. Configure your new GEMS 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 GEM servers
running PNS. The GEMS instances hosting PNS that you designate to participate in HA must share the same
database.
To setup a HA GEMS PNS host, simply provision an additional server and install GEMS-PNS. Use of 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.
51
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 would like to do
device verification and testing in a test environment, you can configure communications to use HTTP instead of
HTTPS.
This is a matter of making additional changes to the Good Control configuration (JSON) we set up when
configuring the Good Work app with Active Sync earlier.
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.
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.
52
To see the relevant logs in your browser:
1. Go to https://<fqdn_of_your_gems_host>.com:8443/system/console/configMgr
2. Login as an administrator (the default uid/pwd is "admin"/"admin").
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_karaf-<version>\data\log\
Problems Connecting to Exchange
Some environments may need to configure GEMS to communicate with an Exchange Server that does not have a
trusted SSL Certificate. Although this is not recommended for production deployments, if your Exchange server
53
is currently not using a publicly verifiable certificate, you can turn off SSL certificate verification using the
procedure enumerated below.
Caution: Do not modify the DisableSSLv2Hello property unless you know what you are doing. Contact Good
Technical Support for additional details.
To disable SSL certificate checking:
1. Login to the GEMS Web Console as an administrator (uid/pwd = "admin" / "admin"). The default URL for the
Web Console is https://localhost:8443/system/console.
2. Select OSGi > Configuration.
3. Scroll down to Good Technology Async HTTP Client Configuration and click it.
Caution: Editing this configuration will affect all your SSL clients, not just EWS Clients, as well as APNS and
GNP.
4. Check Disable SSL certificate checking.
54
5. Click Save.
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.
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.Configuring Good Control
6. Enter an Autodiscover override URL in the field provided. This typically takes the form
https://mycas.mydomain/autodiscover/autodiscover.svc.
55
7. Click Save.
8. Restart the “Good Technology Common Services” 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.
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
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}]
56
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",
"<email domain for end users>": {
"EASDomain":"<EAS Windows domain for end users>",
"EASServer":"<EAS server fully qualified DNS name>",
"AutodiscoverURL":"https://autodiscover.mydomain.com/autodiscover/autodiscover.xml",
"EASServerPort":"<EAS server port number>",
"EASUseSSL":"true"
}
}
If using Autodiscover, replace the EASServer parameter above with AutodiscoverURL so that
"EASServer":"<EAS server fully qualified DNS name>"
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.
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
l
l
Enabling SSL via Good Proxy
l
Configuring support for the Global Catalog
57
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 each of the following components to set up the Connect service:
l
Service Account
l
Database
l
Good Dynamics
l
Lync 2010 or Lync 2013
l
Microsoft Exchange (optional)
l
Web Proxy (optional)
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.
58
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.
59
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, then 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.
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.
60
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: An HTTPS connection requires a well-known 3rd Party CA-signed SSL certificate. See
Enabling SSL Support Via Good Proxy for details. See also your GD Server Installation Guide.
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.
61
2. From the Application ID drop-down list, select the pool_gems.<mycompany.com> 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.
The default location of the GEMS Connect Dashboard logs is:
(a) <install dir>\Good Enterprise Mobility Server\Good Component Manager\RunAsService\logs
(b) <install dir>\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.
62
2. From the Application ID drop-down list, select the pool_gems.<mycompany.com> 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.
The default location of the GEMS Connect Dashboard logs is:
(a) <install dir>\Good Enterprise Mobility Server\Good Component Manager\RunAsService\logs
(b) <install dir>\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 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.
63
To configure GEMS to access Exchange conversation histories:
1. From the Good Connect Service Configuration page, click on Microsoft Exchange.
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.
64
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.
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.
65
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
Step 3 above, and that all System and Network Requirements have been met. Correct as needed, then retry
by clicking Test again.
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.
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, you must launch the Good Control management console in
your browser.
Then, with the Good Control management console loaded in your browser, complete the following steps (as
pictured):
1. In the navigator under APPS, click Manage Apps, then search for or scroll down to select Good Connect.
2. Click it to open, then click the GOOD DYNAMICStab.
66
3. In the Server section, click EDIT.
4. 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.
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=<comma-separated list of available GEMS hosts using the format FQDN:port>
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.
First, locate ADDITIONAL SERVERS under Client Connections.
67
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
to add a blank row to the list.
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 Submit.
As indicated at the beginning of this topic, you can also whitelist or block domains.
68
To edit information for an allowed server:
1. Click the
Edit icon for the server.
2. Modify the server name or GP cluster configuration.
3. Click Submit to commit the change.
To remove a server from the list:
1. Click the
Delete icon for the server.
2. Click Submit .
To whitelist GEMS:
1. Click the Edit
icon.
2. Under Additional Servers, add an entry for the GEMS Connect service that will use port 8080. Reflecting
your specific machine information, the entry should look something like this:
goodconnect<n>.<mycomany.com>:8080
3. Make sure to save your changes.
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
69
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.
2. Click the APPLICATION POLICIES tab, then expand the GOOD CONNECT application listing.
3. Click 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 display this disclaimer at the top of each new client conversation window.
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.
70
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, then select the policy set corresponding to user affinity
assignments for Good Connect; e.g., “West Coast Connect Users.”
2. Open the APPLICATION POLICIES tab and expand the GOOD CONNECT application listing.
3. Click the Server Configuration tab.
4. Enter (type or paste) your Connect Server Hosts separated by commas in the following format:
<server_1_fqdn>:<port>,<server_2_fqdn>:<port>,<server_n_fqdn>:<port>
Example:
westcoast1.xyzcorp.com:8080,westcoast2.xyzcorp.com:8080,eastcoast1.xyzcorp.com:8080
71
5. In the navigator under USERS, click Manage Users.
6. Select the user(s) for whom you want to establish an affinity policy, then click Edit.
72
1. From the Policy Set dropdown, assign the user to the appropriate policy set.
2. Click 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 disable/enable the conversation history option:
1. In the Good Control navigator under POLICIES, click Policy Sets, then select the policy set governing
collaboration suite apps; i.e., Good Connect.
2. Click the APPLICATION POLICIES tab, then expand the GOOD CONNECT application listing.
3. Click the Conversation History tab, then check/uncheck Save more than 40 messages in a conversation
history on the device.
73
4. 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 APPLICATION POLICIES tab and expand the Good Connect or Good Work application listing.
3. Click the App Settings tab.
4. Disable (uncheck) either option or both, then click Update.
74
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.
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.
6. Locate the certificate you want to change and double-click it.
75
7. Open the Details tab and select Show: <All>, 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.
To update the Good Connect Server configuration file:
1. Open GoodConnectServer.exe.config in your favorite text editor.
You can find the file in <install path>\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):
<add key="RESTRICT_CERT_BY_FRIENDLY_NAME" value="<cert_friendly_name>"/>
Note: The value for <cert_friendly_name> is case-sensitive. Enter it exactly as you see it from the certificate.
76
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
l
Adding the certificate to the GEMS-Connect configuration file
l
Configuring Good Control to send requests over SSL
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:
77
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
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:
1. Click Start > Run, enter mmc, and click OK.
78
2. After the MMC launches, click File > Add/Remove Snap-in…
3. Select Certificates in the left panel and click Add to move it into the right panel, then click OK.
79
4. Select the Computer account option and click Next.
5. Confirm that Local computer is selected and click Finish.
6. Click OK to confirm Certificates in the Console Root.
80
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.
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.
81
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. Open a command prompt as an administrator and enter the following command string:
> netsh http add sslcert ipport+0.0.0.0:<port> certhash=<thumbprint> appid={AD67330E-7F41-4722-83E2F6DF9687BC71}
replacing <port> with the port number you want to use (e.g., 8082) and <thumbprint> with the contents of the
clipboard.
9. 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.
82
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 make the following change:
<addkey="USE_SSL" value="false" />
Note: Save your changes, then restart the Good Technology Connect service in the Windows Service Manager
for these changes to take effect.
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
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 and click the GOOD DYNAMICS tab.
4. In the Server section, click EDIT, then click the Add icon
.
5. Under HOST NAME, enter the fully qualified domain name (FQDN) of each GEMS-Connect Server.
6. Under PORT, enter the SSL port.
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.
83
To change user affinity-clustering:
1. Click on Policy Sets in the navigator, select the policy to modify and open the APP POLICIES tab.
2. Expand the GOOD CONNECT policy set, then open the Server Configuration tab.
3. Change the port numbers in Connect Server Hosts to the new SSL port for GEMS.
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
84
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”
<name of ssl cert>” > c:\temp\ssl.txt
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.
85
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
l
sn
l
sAMAccountName
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:
<addkey = "AD_USERS_SOURCE" value = "GC"/>
<addkey = "AD_USERS_SOURCE_DOMAIN" value="<root GC domain; LDAP format>"/>
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.
86
If you select the Log On tab, you should see the Service Account user you entered for the Connect service the
GEMS Dashboard.
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.
87
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 GEM server installation directory is:
GEMS Connect Service Log
\Good Connect\logs\Application-log_<data>.txt
88
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=<null>
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.
89
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
l
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, and can be reduced to the following
four steps:
1. Service Account: Enter the GEMS Service Account, but only after making sure this service account has
RTCUniversalReadOnlyAdmins rights. Click Save to record these settings.
2. Good Dynamics: Enter the Good Proxy Hostname. Use the Test button to test the connection. Click Save to
record these settings.
3. Settings: Default settings are typically sufficient.
90
4. 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.
Use the Test button to test connectivity. Click Save when done.
Additional resources for Good Presence Developers
If you are a Good Presence developer, the following will be useful links:
l
Good Presence Service API
l
Good Presence Sample app
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
l
Configuring Presence Affinity for the Good Work app
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.
91
Note:
Unless you import a publicly verifiable certificate into the GEMS Java keystore, please be aware of the
following:
4. If you have additional GEMS hosts, configure them for the application in the same way, after clicking
to
add a new row.
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.
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 click Policy Sets, then locate the policy you want to apply and click it.
2. Click the APP POLICIES tab.
3. Scroll down to Good Work and click it, then click the App Settings tab.
92
4. 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 in the same fashion, separated by a comma and no space.
5. Click Update.
6. Now, repeat Steps 1 through 5 for every policy that will use Good Work Presence.
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.
93
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.
6. Locate the certificate you want to change and double-click it.
94
7. Open the Details tab and select Show: <All>, 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.
To update the LPP configuration file:
1. Open LyncPresenceProviderService.exe.config in your favorite text editor.
You can find the file in <install path>\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):
<add key="RESTRICT_CERT_BY_FRIENDLY_NAME" value="<cert_friendly_name>"/>
Note: The value for <cert_friendly_name> is case-sensitive. Enter it exactly as you see it from the certificate.
4. Restart the Good Technology Presence service in the Windows Service Manager for this change to take effect.
Logging and Diagnostics
The default GEM server installation directory is:
GEM Server Log
\Good Server Distribution\assembly-<version>\data\log\<gems_server_name+timestamp>.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
95
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.
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.
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.
1From http://social.technet.microsoft.com/wiki/contents/articles/3933.lync-director.aspx. ©2014 Microsoft Corporation. Used with permission.
96
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.
Configuring Good Enterprise Services in Good Control
Good Dynamics applications require entitlement to Good Enterprise Services in order to use these services,
currently comprising:
l
Presence
l
Follow-Me
l
Directory Lookup
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
Add GEMS to the GES Entitlement App
l
Add the GES Entitlement App to an App Group
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."
97
2. Open Good Enterprise Services in the search results by clicking it, then open the GOOD DYNAMICS tab.
3. In the Server section, click , 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.
Adding the GES Entitlement App to an App Group
The services entitlement 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 GC Dashboard under APPS, click App Groups.
2. Open a group or click
under ACTIONS to edit.
98
3. Click
.
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 Docs Service
The Docs Configuration Console is required to configure and maintain data sources (file shares, SharePoint) 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.
Installing the Docs Configuration Console
A special web console is provided with GEMS to administer and control your Good Work users' secure access to
corporate documents from their mobile device. As authorized, they can browse, search, bookmark, download,
99
synchronize, and upload files, as well as check out, open-in to edit, open-in to annotate, and check in changes to a
document. In addition, the console configures secure offline synchronization of files between the device and the
corporate repositories so your users can stay productive while on the go.
To install and launch the Docs Configuration Console:
1. Run GEMSDocsConsoleSetup.exe, located in your unzipped GEMS installer package.
2. When the Welcome screen displays, click Next.
3. Accept the license agreement and click Next.
100
4. If you choose to install the Docs Configuration Console in a location other than the default directory
indicated, click Change, select the new destination, then click Next.
5. Make sure Docs Service Configuration Console is selected for setup, then click Next.
101
6. Select the Database Server from the drop-down list (local is the default) or click Browse to specify another
SQL Server.
7. Choose an authentication method.
If you select Windows authentication, the current user's credentials are used for database access. If
SQL server authentication is selected, enter an authorized Username and Password.
102
8. Click Next.
9. Set the following IIS configuration parameters for the console, then click Next:
a. Web Site – select the URL of the console or accept Default Web Site
b. HTTPS port – enter the port number to be used by the console (default is 443)
Note: If you are installing the console on a server that is already using port 443, change the port here to
an unused port greater than 1024.
a. SSL certificate – select an existing certificate or choose a new self-signed certificate (can be changed after
installation using the IIS Management Console)
b. Process Identity – account Username and Password under which the Docs Service application pool will
run.
Important: This account must belong to the Local Administrators group.
10. Click Next.
103
11. Click Install.
12. Click Finish to launch the console in your default browser.
Note: If the console does not launch automatically, do the following:
a. Go to Start > IIS Manager.
104
b. Select the server name, then click on Sites > Default site > bindings.
c. Remove HTTP port 80 (it is not bound), then restart IIS Manager.
The Docs console will now be accessible from the GEMS Dashboard. See Setting Up the Docs Service to
complete setup of the Docs Configuration Console.
Setting Up the Docs Service
Before you can launch the Docs Configuration Console, you must first establish database connectivity with GEMS
using the DB configured earlier under Installing the Docs Configuration Console.
In the GEMS Dashboard, click on Docs, then complete setup and configuration for the GEMS Docs Service,
including:
l
Connecting to the Database
l
Accessing the Docs Configuration Console
l
l
l
l
Defining User Access and Sharing Policies
l
Fine-tuning the Docs Service
Connecting to the Database
In the dashboard's Good Docs Service Configuration page, click Database to get started.
105
In order to connect to the database, you will need the authorized values and credentials from your database
administrator. You should also have installed the Docs Configuration Console earlier to execute the requisite
schema scripts, all of which are necessary prior to testing connectivity.
Server, Database and Authentication Type will be populated with the corresponding information you provided
to the Docs Console installer.
Caution: It is strongly recommended that you do not alter this installer-configured database information.
To verify the GEMS connection to the Docs database:
1. Click Test to verify the connection.
Accessing the Docs Configuration Console
Once database connectivity is assured, you're ready to configure your users for the Docs Service using the Docs
Configuration Console.
106
To access the Docs Configuration Console:
1. Click Configuration Console on the Good Docs Service Configuration page of the GEMS Dashboard.
Note: If you failed to install the Docs Configuration Console or it is installed incorrectly, the GEMS Dashboard
will throw an error to this effect.
2. Supply the service account credentials and domain you specified under Installing the Docs Configuration
Console.
3. Click Sign In.
107
The Dashboard/Welcome page lists SERVER STATISTICS comprising:
l
Users – number of active users currently using the Good Share Server.
l
Policies – number of policies created for Good Share users.
l
File Shares – number of total file shares in all policies.
l
SharePoint Sites – number of SharePoint sites in all policies.
Next, you need to add Good Proxy information for communications between users of the Docs service and your
enterprise backend.
To configure Good Proxy for the Docs Service:
1. In the Docs Console, click Settings, then click Security.
2. Enter the FQDN of your Good Proxy host.
108
3. If you want a secure connection, enable Use HTTPS for connection with Good Proxy Server.
4. Click Save.
Follow the steps here to configure Good Control (GC) connectivity and communication with the Docs Console
server.
Adding the Docs Service
Note: Adding Docs to Good Control as a service is only required if you will be offering the service to a thirdparty application. The Docs component of Good Work does not require it. The procedure for binding the
service to third-party apps will be issued shortly and included in this space.
Entitling Users
To configure Docs Service entitlement:
1. Click Manage Apps under APPS and enter a full or partial search string for "Feature - Docs Service
Entitlement".
2. Click on Feature - Docs Service Entitlement in the search results.
109
3. Open the GOOD DYNAMICS tab.
4. In the GD App 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.
7. In the Serversection click Edit, then:
a. In the Host Name field, enter the FQDN of the GEMS host in lower case. Good Control will not accept
upper case characters.
b. In the Port field, enter the server port (default = 8443), then click
under Actions.
c. Enter GP cluster assignments as appropriate.
110
8. Click Save.
Publishing the Docs App
To publish the Docs app for all users:
1. In the Good Control DASHBOARD, click App Groups under APPSand edit the Everyone group by clicking
2. Click
.
Add More, then enable the checkbox for Feature - Docs Service Entitlement - ALL.
111
3. Click OK.
Configuring Docs Server Affinity for Good Work
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 APP POLICIES tab.
3. Scroll down to Good Work and click it, then click the App Settings tab.
112
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.
To add an individual user:
1. Click Users, then click Options and select Add.
113
2. Enter the user’s Active Directory username and domain, then select aPolicy (see Defining User Access and File
Sharing Policies for guidance on creating user polices).
3. Click Save to commit.
To import multiple users:
1. Select Import from the Options list.
2. Select a Domain.
114
3. Select an AD Object Type and enter a search string to find particular users and groups, then click the search
icon.
4. Click Import Selected Users.
5. Click Close to return to Users page.
Note: Any user can be removed in the future without impacting the saved configuration. To save your user
selection configuration based on policy, select Save Configfrom the Options list.
See Auto-Add Users to Policy for guidance on setting up users automatically based on membership in a security
group.
Managing User Profile and Permissions
Based on your user role as an administrator, you can make changes to any user profile by selecting it.
115
The following actions can be performed on individual user profiles by clicking the respective button after
selecting the user:
1. Edit – to view/change the user's GENERAL SETTINGS and/or DATA SOURCES.
For admin-defined data sources, you can optionally enter an Override Path by selecting a data source from
the list and clicking Edit. Click Override Path for this user to specify an alternate path for the data source,
then click Update.
2. Delete – to remove a user.
3. Move to policy – to assign a different file sharing policy to this user.
4. Assign Roles – to change a user role. See Managing Roles for guidance on creating new roles.
116
Defining User Access and File Sharing Policies
Policies contain a list of shares and permissions that are applied to all the end users assigned to that policy.
Policies can be defined on a departmental level or a site-level, depending on the use-case that best serves the
organization according to the following criteria:
l
Policy Name and Description
l
No. of Users = number of users belong to that policy.
l
No. of File Shares = number of public share paths that belong to this policy.
l
No. of SharePoint sites = number of SharePoint sites that belong to the policy.
l
Rank = the order of restrictive precedence.
Each policy is then associated with the specified File Shares, SharePoint Sites, User Defined Shares, and
trusted apps (under the Open In tab).
Click on Policies to get started.
Creating a New Policy/Editing an Existing Policy
To create a new policy:
1. Click the Options list box and then select Add.
1. Open the General Setting tab.
117
2. Enter the new policy Name and Description.
3. Give the policy a Rank. Rank determines the order of precedence for enforcement of the policy.
4. Click Save.
Adding a Security Group
In Microsoft Active Directory, when you create a new group, you must select a group type. There are two group
types, security and distribution. Security groups allow you to manage user and computer access to shared
resources. You can also control who receives group policy settings.
Of course, when you first install the Docs Console, there will be no groups defined, so you will have to add them.
To add an AD Security Group to the policy:
1. Select a policy and click Edit, then open the SECURITY GROUPS tab.
2. Enable Link to Active Directory, then click Add Security Groups.
3. Select a Domain, then enter a search string for the security group you're looking for and click search icon.
4. From the results, select one or more Security Groups and click Add Selected Security Groups.
118
5. Search for more groups to add or click Close.
Tip: To remove a security group from a policy, select it, then click Remove.
Adding File Shares
A files share is a collection a files and documents stored on one of your enterprise file servers. When added to a
policy in the Docs Console, users assigned to that policy are granted access from their Good Work client to the
files located there. A SharePoint site is another type of Data Source.
The Docs service allows the sharing of both "public" and "private" file shares among a group or groups of users.
Private shares have a path containing a unique user-specific attribute. Public shares have a fixed path. Support
for Active Directory wild card attributes enable the configuration of multiple private shares.
Consequently, in specifying the path to a file share, you can enter the fully qualified path to the share or use AD
attributes (also called wild cards) associated with the user's AD profile.
For instance, if you use the wild card <homedirectory>, the path is automatically populated from the user’s home
directory attribute in their AD profile. Similarly, you can specify a base folder followed by the AD name wild card.
In which case, if thePath for Home Directory is set to \\fileserver1\files\<user_login_name>, this makes the
home directory for user jdoe= \\fileserver1\files\jdoe.
119
To add a file share to a policy:
1. Select the policy, click Edit, then open the FILE SHARES tab.
2. Click on Options and select either Add or Add Home Directory. The latter automatically populates the
Display Name with "Home Directory" and the Path with the user's <homedirectory> AD wild card, although
you can change either, as desired.
3. Enter/change the Display Name and Path.
4. Enable Keep synchronized with the mobile device for users assigned to this policy to force all contents
within this folder to be cached locally to the user’s device. This will mean that this folder is automatically
synchronized between the app and the backend every 24 hours, although users retain the ability to manually
sync from the app.
5. Set the Permissions to be as restrictive or as broad as needed. See the Table of Permissions for a description
of each.
120
TABLE OF PERMISSIONS
Permission
Description
List (Browse)
Allows user to list files and browse the list
Delete Files
Allows user to delete files from the File Share or SharePoint Site
Read (Download)
Permits users to download files to their mobile device. This file is stored in the secure container and is
deleted as soon as the user browses to a different location or exits the app (unless it is a ‘Keep In Sync’
share).
Write (Upload)
Permits users to upload and overwrite existing files
Cache (Favorites)
Allows users to cache files and subfolders to be saved locally on the mobile device for
offline availability
Allow Native Email
Allows the use of the native emai app on a mobile device, which means the document is no longer
containerized.
Open In
Permits the user to open files in other GD apps and ThirdParty applications
Create Folder
Allows users to create new folders in the File Share or SharePoint Site
Print
Allows the use of the native air-print option on the mobile device, when available. The document will no
longer be in the secure container. Use of a GD app like ‘Breezy for Good’ is strongly recommended to
securely print documents
Copy/Paste
Permits the copyand paste of selected contents from files to the local clipboard
Check In/Check Out
SharePoint only. Permits the user to check out files, modify them, and check them back in, thereby
updating the shared source.
6. Click Add (if editing, click Update) and the file sahre is displayed in the policy list.
7. Click Save to record these changes.
Adding SharePoint Sites
A SharePoint site is also an end user data source, but instead of specifying a fully qualified path to a file share,
you specify a URL to the SharePoint site. You can impose the same restrictions on the SharePoint site that you
applied to the Files Shares under this policy or grant different permissions.
121
Note: As indicated on the Docs Console display, the "Followed Sites" and "Shared with Me" options require the
MySite plugin and will only work with SharePoint 2013 and later versions of SharePoint.
Docs Console policies only support absolute URLs for SharePoint sites. An absolute URL specifies a full path and
begins with a protocol. For example, https://<domain_or_server>/<[sites/]Web_Site/Lists/List_Title/AllItems>.aspx.
To add a SharePoint site to the policy:
1. Select the policy, click Edit, then open the FILE SHARES tab.
2. Click on Options and select Add.
3. Enter a Display Name and SharePoint Site URL.
4. Enable Keep synchronized with the mobile device for users assigned to this policy to force all contents
within this SharePoint site/folder to be cached locally to the user’s device. This will mean that this folder is
automatically synchronized between the app and the backend every 24 hours, although users retain the
ability to manually sync from the app.
5. Optionally, you can enable Add sites followed by users on this site and Enable Shared with Me view in
accordiance withthe limitations displayed by the information icon and in the note above.
6. Next, set the Permissions to be as restrictive or as broad as needed. Refer to the Table of Permissions above
for a description of each.
122
7. Click Add (if editing, click Update) and the SharePoint site is displayed in the policy list.
8. Click Save to record these changes.
Configuring User-Defined Sharing Policies
You can allow your users to add their own file shares or SharePoint sites using the Good Work app. In addition,
you can let them “follow” sites on SharePoint that will show up automatically as data sources on their mobile
device. Moreover, you set permissions around these shares in the same way as administrator-defined shares.
To set user-defined shares permissions:
1. Click on the Policy Name, then click Edit.
2. Click
located on the immediate right of the SHAREPOINT SITES tab.
3. Open the USER DEFINED SHARES tab.
123
Restricting Access
You have three options for permitting user access to data sources:
1. Enable 'User Defined Shares' to allow users to add their own data sources.
2. Automatically add sites followed by users. This option takes advantage of the followed site feature in
SharePoint. Define a parent site in the SharePoint Sites tab, then enable this option if you choose to allow it
for users under this policy. All sub-sites within the primary site that users choose to ‘follow’ will automatically
appear as a Docs data source on their Good Work client.
3. Allow Web Services to Add 'User Defined Shares'. Good Share exposes several REST APIs which can be
integrated into existing consoles and work flows used by the enterprise. These APIs allow the Web Server to
enable Add User Defined Shares. Contact Good Technology Support for more information on integrating
these Docs service APIs with enterprise and ISV apps built with the GD SDK.
Restricting Data Sources
Two settings allow you to control which repositories end-users are allowed to add via the self-service console.
1. Allow File Shares – permits end-users to add file shares.
2. Allow SharePoint sites – permits end-users to enter SharePoint sites.
Setting Permissions
User-defined permissions are set in the same way as permissions for admin-defined shares. See the Table of
Permissions for descriptions of each.
Tip: You can add these user-defined sharing parameters to another policy by clicking Add to Policies and then
selecting the policies to which you want it added.
124
Enabling and Restricting Good Drive
Good Drive serves as a document repository that can be shared across devices and across apps just like other
data sources. You can enable/disable access to Good Drive selectively on a policy-by-policy basis. For guidance on
setting up your organization's Good Drive, see Configuring Good Drive.
To enable access to Good Drive:
2. Click
3. Open the GOOD DRIVE tab.
4. Mark the checkbox under ACCESS for Enable Good Drive.
5. Select one of the following options:
l
Good Dynamics apps only – lets users open files in GD apps only; that is, only apps currently in the GD
ecosystem. Visit the Good Marketplace to see the complete list of apps available from Good. This category
also applies to proprietary custom GD apps developed for or by your enterprise.
l
Any app – permits users to open files in any application available on the device, presuming the app supported
the file format in question.
l
Good Dynamics apps plus whitelisted apps – permits users to open files in GD apps as well as select
whitelisted non-GD applications.
6. Click How to retrieve an App IDto view instructions on retrieving an application's App ID to add it to the
white list. Be sure to click Update to save the App ID to the white list.
Tip: After updating the list for one policy, you can add any whitelisted app to another policy by selecting it from
the list, then clicking Add to Policies and selecting those policies to which you want it added.
125
7. Next, set the Permissions to be as restrictive or as broad as needed. Refer to the Table of Permissions above
for a description of each.
8. Click Saveto record your changes.
Restricting Files by App
To allow or block a user’s ability to open files based on the app used:
2. Click
3. Click the OPEN IN tab.
4. Select one of the following options:
l
Good Dynamics apps only – lets users open files in GD apps only; that is, only apps currently in the GD
ecosystem. Visit the Good Marketplace to see the complete list of apps available from Good. This category
also applies to proprietary custom GD apps developed for or by your enterprise.
l
Any app – permits users to open files in any application available on the device, presuming the app supported
the file format in question.
l
Good Dynamics apps plus whitelisted apps – permits users to open files in GD apps as well as select
whitelisted non-GD applications.
5. Click How to retrieve an App IDto view instructions on retrieving an application's App ID to add it to the
white list. Be sure to click Update to save the App ID to the white list.
Tip: After updating the list for one policy, you can add any whitelisted app to another policy by selecting it from
the list, then clicking Add to Policies and selecting those policies to which you want it added.
126
6. Click Save to record your changes.
Adding Users to a Policy Automatically
Optionally, you can also link a new policy to a Security Group in Active Directory to enable auto-addition of users
to Docs Configuration Console. Users in the Security Group are then added to the Docs Configuration Console
and assigned to the linked policy.
To auto-add users to policies based on their security group membership:
1. Select the desired Policy.
2. Open the Security Groups tab.
3. Enable the Link to Active Directory check box.
4. Select the appropriate security group. If none are listed, click the Add Security Groups button to see a list of
available security groups. Select the appropriate group and click Add.
5. Select the security group you wish to associate with the policy and click Save.
Fine-Tuning the Docs Service
You can change your current Docs Service settings at any time by clicking Settings in the console tool bar.
Security Settings
Security settings are organized into the following groups:
1. Kerberos Constrained Delegation– enable or disable Kerberos constrained delegation. See Configuring KCD
for additional guidance.
2. Specify the FQDN of the Good Proxy server.
127
3. Auto Add User and Home Directory
a. Enable/disable the automatic addition of users through the app. This setting is used in combination with
the linking policies to Active Directory. See Defining User Access and File Sharing Policies.
b. If the user’s home directory is not recorded in the Default attribute in AD, you can specify the appropriate
attribute.
3. SharePoint Online – sets the comma-separated list of approved SharePoint Online domains (e.g.,
mycompany.sharepoint.com, mycompany.sharepoint_2.com).
4. General
a. Allow or block preview of media files on iOS devices. This file is unencrypted on the iOS devices for the
duration of playback.
b. Enable/disable the app from remembering the user’s password.
c. Enable/Disable the display of event details for SharePoint Calendar alerts.
d. Force User to save Pending Uploads. Because there may be instances where a user works on an offline
version of a file and does not have the necessary network coverage to upload the file to the backend
repository, the user can save the file to the local Pending Files container within the app. For compliance
reasons, enterprises may not want data to reside in this offline location for an indeterminate amount of
time. The next time the user launches the application and has network connectivity, they will be greeted
with a prompt window asking them to upload the pending file. They will then be prompted to take an
action based to the following settings:
l
Unchecked – user receives the prompt to upload but has the option to cancel the prompt. They will get
this prompt again every 24 hours when the app is launched and the device has network connectivity.
This will continue as long as the file resides in the Pending Files container.
l
Checked – user receives the prompt but is not given the option to cancel the upload. The user is forced
to upload the file before continuing to use the application.
128
Configuring Good Drive
Setting up or changing your Good Drive storage provider is quick and easy in the Docs Console.
To configure Good Drive:
1. Click Settings in the console toolbar, then click Good Drive.
129
2. Select either File Share or SharePoint Site as the Storage Provider.
3. Enter the Storage Provider Root Path.
4. Enter the Username and Password required for Storage Provider authentication.
Note: As indicated on the console display, storage provider credentials are optional. If not specified, process
user context is used to access the path.
5. Click Save.
Audit Settings
Audit settings provide options for managing audit log operations and the number of audit log records in the
database. Every operation from every app can be recorded to an audit report. These records are stored in the
Docs database and can be used to meet compliance and e-discovery requirements.
130
Check Enable Audit Logs to enable the audit operations selected.
Managing Roles
Because the Docs Service supports role-based administration, enterprises wishing to have well-defined, tiered
administration can choose from the existing predefined roles or create their own roles with specific functions.
Out of the box, the three predefined roles include:
l
Compliance Officer – this role can change audit settings and run audit reports.
l
Default Admin – this role can perform all available operations within the Good Share Management Console.
l
Default User – this role only permits end-user permissions, able to view the drives that are available to them
via the policy assigned by the administrator. By default, all users are assigned this role.
As mentioned, admins can also create enterprise-defined roles by clicking the Options list box, selecting Add, and
then defining the specific operations permitted by that role.
An example of an IT Helpdesk role is pictured.
131
Of special significance here is the permission called Good Share Admin API Access. When this permission is
granted, it enables the role to add user-defined data sources with REST API calls.
Managing Audit Logs
You can choose to record every operation that is performed by users with the Docs Service and then access these
records from the Docs Configuration Console by selecting File > Audit Log Reports.
For generating audit reports, the following filters are available :
l
Date – sets the time frame for which you want to generate the reports.
l
Operation – sets the operations for which you want to generate a report.
l
Users – filters the report by specific users, displaying only users who have actually used the application.
l
Search – full or partial file name (key-word search) to filter which users have accessed a particular file.
132
Configuring Support for Hosted SharePoint (SharePoint Online )
SharePoint Online locations can be added to policies in the Good Share Console just like an on-premise
SharePoint site to support both admin-defined and user-defined data sources.
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.
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.
To help with configuring KCD, please follow the procedure specified in Good Share KCD Authentication
Instructions. Contact your Good representative for a copy of this document.
133
Note: 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.
Once you have deployed SharePoint Online, you’re ready to configure the Docs Service for your SharePoint
Online users.
Configuring the Docs Service for SharePoint Online
In accordance with the guidance offered in Security Settings, complete the following steps.
To configure Docs Service support for SharePoint Online:
1. Click Settings, then select Security.
2. Add one or more SharePoint Online Domains in the field provided, separated by commas.
Local Folder Synchronization
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.
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.
134
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 as pictured
next.
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
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.
135
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]\<username>\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.
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.
136
Offline Folders (Native)
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.
137
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.
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.
138
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's Private Share functionality to expose the user’s “Home Directory” to the Good Share 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.
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.
139
Error 404: Connecting to Docs Service
Situation
Unable to connect to GEMS-Docs Service. Receiving Error 404 after IIS HTTPS Bindings changed from Port 443 to
Port 5443.
Issue
Trying to install the Docs Service on the same server as Good Dynamics. When attempting to launch the Docs
Configuration Console via IE, a 404 error results.
Cause
The root issue is a result of IIS HTTPS Bindings changes made because the Docs Service is on the same host server
as your Good Control and Good Proxy servers, which means you'll need to bind IIS to a port other than 443 as
Good Control will be using that with Apache. Go to a command prompt and type netstat -ab and pipe the
output to a text file to identify what is using 443.
Solution
Good Dynamics listens on port 443 and 80. If you try to enable IIS on a GD server, Windows will let you add it;
however, the default Web Site in IIS will not start. This is because IIS's default website is configured to listen on
port 80, which creates a conflict with GD. But no worries. After you enable IIS, just open the IIS manager and
change the binding port to something other than 80. For example, 81. After you do this, IIS will let you start the
default website.
Start -> Administrative Tools -> Internet Information Services Manager
Expand the Server name, then click on Default Web Site. On the right, click on Binding.
By default, the Docs Service's web console UI wants to use port 443, but as we noted earlier, GD is already using
port 443. Once again, no worries. When you install GEMS, the installer will give you an option to change the
default port. Change it to something other than 443 (5443 is a safe choice) and the installer will take care of the
rest. You should be good to go after this.
If not, and you continue receiving Error 404 after changing IIS HTTPS Bindings, you probably need to reinstall the
Docs Service Web Console. Here's how:
Uninstall the Web Console
1. Run the installer package.
2. Select Modify.
3. In the drop-down list for Web Console, select This feature will not be available.
4. Click Next.
5. Select Update.
6. Uncheck Launch Good Share Server, then click Finish.
140
Reinstall the Web Console
1. Run the installer package.
2. Select Modify.
3. On the drop-down list for Web Console, select This feature and all sub-features will be installed on local
hard drive.
4. Click Next.
5. Make sure that Windows Authentication using the current user's credentials is selected and click Next.
6. For HTTPS port, enter 5443.
7. Enter your UID and PWD (no need for domain) and click Next.
8. Click Update.
9. Click Finish.
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.
141
2. Go to USERS > Manage Users in the navigation panel, locate and select the user you want to provision by
clicking the corresponding checkbox, then click Edit.
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
142
Appendix A – GEMS with Push Notifications Service
Pre-Installation Checklist
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.
c
1.2
Download the latest GEMS software from the Good Admin Portal.
c
1.3
Request the Good Work app from the Good Marketplace.
c
Network
2.1
Ensure the following ports are open for GEMS:
l
c
Inbound TCP Ports
o
8443 from the Good Proxy server (required for Presence and Push notifications);
add port 8181 if SSL is not going to be used
l
Outbound TCP Ports
o
443 to Good NOC/APNS
o
443 to Exchange
o
17080 to the Good Proxy server (17433 for SSL)
Active Directory and Exchange
3.1
3.2
Verify the supported version of Exchange you have already deployed:
l
Exchange 2010 (SP2 RU4 +)
l
Exchange 2013 (CU1, CU2, CU3, SP1 [CU4])
Create an AD account for Good. The preferred UID is "GoodAdmin" set with the following
attributes:
c
c
143
#
Task
Check
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:
c
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!).
c
Use EWSEditor to test, referencing KB3496 for information on how to use EWSEditor.
3.7
Make sure that Exchangew EAS is enabled on port 443, and thatr connections are permitted
for the Good Proxy server.
c
GEMS
4.1
4.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.
c
c
POC:
l
Dual Core / 2.4 GHz CPU or higher
l
4 GB RAM / 50 GB HDD
l
Production:
144
#
Task
Check
l
Pentium 4 Quadcore / 2.4 GHz CPU or higher
l
l
4.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.
c
4.4
Make sure that the GoodAdmin service account is a local administrator on the server.
c
4.5
Make sure that the GC service account has Logon As a Service rights.
c
4.6
Ensure that the server's date and time are set correctly.
c
4.7
Ensure that the server has been joined to the domain.
c
4.8
Make sure that Windows Firewall is OFF.
c
4.9
Make sure all antivirus/backup and backup software is stopped during the installation.
c
4.10
Install JRE 7 Update 67 or higher Java 7 update (click here to download).
c
Note: Java 8 is not supported at this time.
4.11
Set the JAVA_HOME environment variable to the Java install folder;
e.g., C:\Program Files\Java\jre7.
c
4.12
Ensure connectivity to SQL Server (typically, TCP port 1433.
c
4.13
Ensure connectivity to Exchange (EWS).
c
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
c
To download MS SQL Express, click here.
5.2
Create a database for the PNS service. The recommended DB name is “EWS”. Extend the DB
scheme with the schema file provided with the GEMS binary zip file.
c
5.3
Make sure that the SQL account or the GEMS Windows Service Account has db_owner
privileges to the GEMS-PNS database.
c
145
Appendix B – GEMS with Connect and Presence
Pre-Installation Checklist
It is highly recommended that this checklist be completed prior to implementation of your Good Enterprise
Mobility Server (GEMS) with Connect and Presence Services.
#
Task
Check
Registration
1.1
Register with the GDN Portal (click here)
c
1.2
Download the latest GEMS software
c
1.3
Request the Good Connect App (click here — very important!)
c
1.4
Request the Good Presence App ONLY if you are using third-party GD apps that require
presence. The Good Presence app can be requested from Mobile App Sales
([email protected])
c
Network
2.1
Ensure the following ports are open for GEMS:
l
l
c
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
146
#
2.2
Task
Check
o
o
o
1433 to the MS SQL server (default)
o
1434 UDP to the Lync database (for initial setup only)
o
49777 – 57500 TCP: Random port in this range to the Lync DB (for initial setup only)
If GEMS requires a Proxy server for external access, please note it here:
c
Proxy Server Make/Model: __________________________
Authentication Method: _____________________________
Active Directory and Lync
3.1
Create an AD service account for the GEMS software (can be the same account used for
Good Dynamics)
c
3.2
Ensure that the GEMS service account has RTCUniversalReadOnlyAdmins permission
during the GEMS install. This permission is granted via AD.
c
3.3
Create a Trusted Application Pool, trusted application, and trusted application endpoint for
GEMS via the Lync Shell Console (very important!)
c
Note: The user creating the Tusted Application Pool must have RTCUniversalServerAdmins
and Domain Admins permissions
GEMS
4.1
Verify OS support. The following are supported by GEMS:
l
l
4.2
4.3
c
o
2008 R2
o
2008 R2 SP1
o
2008 R2 SP1
o
2012 R2
Verify minimum hardware requirements:
l
Pentium 4 Quadcore / 2.4 GHz CPU or higher
l
l
Verify Good Dynamics support. GEMS requires Good Dynamics 1.7.38.x or newer. Good
Dynamics must already be installed and operational before installing GEMS.
c
c
147
#
Task
4.4
Verify Lync Support. Lync 2010 and Lync 2013 are supported.
c
4.5
Ensure that the GC Service account is a local administrator on the server
c
4.6
Ensure that the GC Service account has Logon As a Service rights
c
4.7
Ensure that the server's date/time is correctly set
c
4.8
Ensure that the server has been joined to the domain
c
4.9
Ensure that .NET 3.5 SP1 or later is enabled (Server manager > Add Features)
c
4.10
Ensure that either .NET Framework 4.5 or 4.5.1 is installed. Click here to download.
c
4.11
Ensure that MS Windows PowerShell is installed:
c
l
l
Check
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:
4.12
Ensure that the Microsoft Unified Communications Managed API is installed:
l
For Lync 2010, install UCMA 3.0 (click here to download)
l
For Lync 2013, install UCMA 4.0 (click here to download)
c
After installing UcmaRuntimeSetup.exe, you must also run the OCSCore.msi file. 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.13
Request and install a SSL certificate on GEMS (very important!). See "SSL Certificate
Requirement for Lync" in the GEMS Installation and Configuration Guide.
c
4.14
Ensure that all antivirus/backup and backup software is stopped during the installation.
c
4.15
Ensure that all GEMS software is installed with the GEMS service account
c
4.16
Install JRE 7 Update 67 or higher update of Java 7 (click here to download).
c
Note: Java 8 is not supported at this time.
4.17
Set JAVA_HOME environment variable to the Java install folder;
e.g., C:\Progam Files\Java\jre7
c
Database
5.1
Verify Database server support. The following database servers are supported:
c
148
#
Task
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
Check
To download MS SQL Express, click here.
5.2
Create a DB for the GEMS Connect Service and extend its scheme (very important!). This
must be done prior to installing GEMS. For more information, see "Database Requirements" in
the GEMS Installation and Configuration Guide.
c
5.3
Ensure that the GEMS service account has db_owner permission on the GEMS Connect
database.
c
149
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:
<GEMS Machine Path>\Good Enterprise Mobility\Server\Good Server Distribution\gems-karaf<version>\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:
<GEMS Machine Path>\Good Enterprise Mobility\Server\Good Server Distribution\gems-karaf-<version>\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:
<Call name="addConnector">
<Arg>
<New class="org.eclipse.jetty.server.ssl.SslSelectChannelConnector">
<Arg>
<New class="org.eclipse.jetty.http.ssl.SslContextFactory">
<Set name="keyStore"><SystemProperty default="." name="jetty.home"/>/etc/keystores/gems.jks</Set>
<Set name="trustStore"><SystemProperty default="." name="jetty.home"/>/etc/keystores/gems.jks</Set>
<Set name="keyStorePassword">OBF:1vn21ugu1saj1v9i1v941sar1ugw1vo0</Set>
<Set name="keyManagerPassword">OBF:1uh01xmu1k8k1juc1k5m1wg21kmk1w</Set>
<Set name="trustStorePassword">OBF:1vn21ugu1saj1v9i1v941sar1ugw1vo0</Set>
</New>
</Arg>
<Set name="port">8443</Set>
<Set name="maxIdleTime">30000</Set>
</New>
</Arg>
</Call>
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
150
The Java keytool is used to import the certificate into the java keystore. The default location of this tool on the
GEMS host is C:\Program Files\Java\jre7\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 <path to gems.jks file> -srckeystore <path to your certficiate> srcstoretype pkcs12 -alias <alias of your certficate> -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:
6. Update keyManagerPassword in the jetty.xml file with the obfuscated password.
7. Restart Good Technology Common Services 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:
151
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
152
Appendix D – Understanding the GEMS-Connect
Configuration File
Configuration settings can be manually updated directly in the GEMS configuration file located in <install
path>\Good Technology\Good Server\Good Connect Server\GoodConnectServer.exe.config. After updating
any of the configuration parameters, you must restart the GEMS machine for the changes to take effect.
Parameter Name
Required
(Y/N)
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
users
source is
GC
Domain for the for AD or GC to query. This value should be in
LDAP format; i.e., DC=GOOD,DC=COM
APN_ALERT
Yes
Apple push notification message string that notifies a user that
there are unread messages
“You have <number> 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
Auto-populated
153
Parameter Name
Required
(Y/N)
Description
Default Setting
GoodConnect
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
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
False
ENABLE_SOURCE_
NETWORK
No
Labels address book contacts as "external" if they do not belong
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
False
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
5
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
2
0 = Exchange 2007 SP1
1 = Exchange 2010
2 = Exchange 2010 SP1
3 = Exchange 2010 SP2 or SP3
4 = Exchange 2013
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
154
Parameter Name
Required
(Y/N)
Description
Default Setting
Deprecated
GD_APN_PROXY_
AUTH_USERNAME
No
Web Proxy Username
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_HOST
Yes
Good Dynamics Proxy host
GD_PORT
Yes
Good Dynamics Proxy port
17080
GD_USE_SSL
Yes
Determines whether or not the Good Connect Server uses the
Good Dynamics secure port (17433) or unsecured port (17080).
False
LONG_INVITATION_
TIME_DELAY
No
Time (in milliseconds) that a Connect client will wait for
invitation received to confirm/ignore a request to a conversation
60 000
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
Front-End 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_
Yes
The fixed port used by the Good Connect Server to receive
49555
""
"" (empty string for no proxy)
"Basic No Auth"
"Basic"
"Digest"
3
155
Parameter Name
Required
(Y/N)
APPLICATION_PORT
UCMA_GRUU
Description
Default Setting
messages from the enterprise IM server
Yes
GRUU = Globally Routable User-Agent URI that uniquely defines Generated during application
the Session Initiation Protocol (SIP) URI for the application
provisioning
156
Java settings for GEMS are found in the configuration file Good Server Distribution\gems-karaf<version>\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=2048
# Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=2048
Java memory settings:
wrapper.java.additional.14=-XX:PermSize=512m
wrapper.java.additional.15=-XX:MaxPermSize=1024m
By default, this means that the Java process used by GEMS will always need approximately 3 GB of memory free
for its use on the machine hosting it.
157
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).
158
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...
159
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}.
160
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.
161
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}.
162
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.
163
Message
Level
Context
Error communicating with Good
server-core/gd-core
Proxy Server - HTTP code {}, Message
{}
error
Could not connect to Good Proxy Server while
verifying auth token (during Push Registration from
G3 Mail context)
Failed to retrieve the list of Good
Proxy servers - code {} - Reason {}
server-core/gd-core
error
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 loadbalanced through this list.
Failed to retrieve the list of Good
Proxy servers
server-core/gd-core
error
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 loadbalanced through this list.
Incorrect Good Proxy Server
configuration
server-core/gd-spring
error
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 with
exception {}
servernotifications/autodiscover
warn
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 {}, must
be a valid URL
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 {}
attempts to perform 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).
No response from server while
performing autodiscover for user {}
warn
Autodiscover failed for the user mentioned.
Autodiscover failed for user {}, error
code: {}, Detail: {}
warn
Failed to retrieve user settings while serverperforming autodiscover for user {} notifications/autodiscover
warn
No valid EWS URL setting
warn
Component
server-
164
Message
Component
Level
Context
configured for the user {}
notifications/autodiscover
Error communicating with Database serverserver - {error msg}
notifications/autodiscover
error
GEMS failed to connect to SQL database. Needs
immediate attention.
Database Error - {error msg}
error
GEMS failed to connect to SQL database. Needs
immediate attention.
Lost connection with exchange
server. Last known error {}
servernotifications/ewslistener
error
EWSListener: Lost connection with exchange server.
This might be due to Exchange server\Autodiscover
service down.
Error subscribing user {} with
exchange server {}
error
Subscribe to the user email address with exchange
server to track modifications of user mailbox.
User {} marked for re-autodiscover
info
Does a DB call to mark the user for reautodiscovery. This task is done every n interval of
time.
Error communicating with Database serverserver - {error details}
notifications/pushnotifydbmanager
error
Bootstrap database connection.
{} is no longer the master (producer) serversince database server time {}
notifications/pushnotify-hadbwatcher
error
HA System: Check whether the node itself is
Producer or not. Prints the error in event log when
the server has lost ownership of the HA system (not
master any more).
{} is the master (producer) since
database server time {}
info
HA System: Check whether the node itself is
Producer or not. If it was not master before; the failover is happening.
Detected Server {} is inactive. Users serverwill be load balanced to other active notifications/pushnotify-haservers
dbwatcher
error
HA System: If server is detected as
inactive\heartbeat fails, the users of the bad server
are reassigned to other active servers.
Error communicating with Database serverserver - {error details}
notifications/pushnotifyprefs
error
Database error due to server down\login error, etc.
{ Good Dynamic Proxy Server
connection error details }
server-console/config
error
Connect GD Module – Test from dashboard with GP
down, connection failure error.
Connection to Good Dynamic Proxy
Server is successful
info
Connect GD – Test from dashboard when GP is up
and running, successful test.
Connection Successful, Server: - {}:
Database : {}
info
Mail – DB – Test database configurations from
dashboard. Connection successful.
Exception during connection test {}
error
dashboard. Connection issues due to bad
servernotifications/pushnotify-hadbwatcher
165
Message
Component
Level
Context
password or user or host info.
Invalid configuration properties - {}
error
dashboard. Validation of database configuration
values.
{ Good Dynamic Proxy Server
connection error details }
error
Presence GD – Test from dashboard with GP down,
connection failure error.
Connection to Good Dynamic Proxy
Server is successful
info
Presence GD – Test from dashboard when GP is up
and running, successful test.
Lync Presence Provider Ping failed
with error status {} and reason - {}
server-presence/presencebundle
error
Connection to Presence server. If response received,
log the reason for failure.
Lync Presence Provider Ping failed
with exception {}: {} - set status {}
error
Connection to Presence server. Most likely
connection refused because down
Lync Presence Provider Ping failed,
cause unknown
error
Connection to Presence server.
Presence Service failed to reset LPP,
interrupted with error: {}
error
Reset all contacts presence status.
Presence Service failed to reset LPP,
timed out with error: {}
error
Reset all contacts presence status. Timeout error.
Failed to reset LPP, {} with error: {}
error
Reset all contacts presence status.
Presence Service started.
info
Presence service started.
Presence Service stopped.
info
Presence service stopped.
Bad Lync Presence Provider
Subscription URI: {}
error
Presence service provider subscription URI.
Bad Lync Presence Provider Ping
URI: {} Ping
error
Presence service provider subscription URI.
Redis Cache & Queue services are
not available at the moment.
error
When cache provider is set to Redis and Redis
service is unavilable.
GNP Relay Service not available
warn
GNP service which sends GNP notification is not
available or down.
166
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
167
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
168
Required to support the Android Push Notifications service of GEMS, Google Cloud Messaging (GCM) is a free
service that sends data from EAS via GEMS to GD applications. GCM replaces the beta version of C2DM (Android
Cloud to Device Messaging).
You will need to have your enterprise's Google account handy. If possible, avoid using personal accounts.
Creating a Google API Project
Use of GCM requires an API key. If you are an existing C2DM user, you can use your C2DM token instead.
To create a Google API project:
1. Open the Google Developers Console, then click Create Project.
2. Enter a name for your project, accept the default Project ID, then click Create.
Note: The Project ID cannot be changed after the project is created, and must remain the same for the
lifetime of the project. The Project Number is automatically assigned by the Google Developers Console
when you create the project.
3. Click Projects in the console navigator, then click Overview. The Project Number appears at the top of the
Project Dashboard. Important: Jot down this Project Number or copy it to Notepad.
169
4. In the the Project Dashboard, under Boost your app with a Google API, click Enable an API.
5. Under Mobile APIs, click Cloud Messaging for Android.
6. Click Enable API.
7. In the navigator, under APIs and auth, click Credentials, then (on the right) under Public API Access, click
Create new Key.
170
8. Click Server key.
9. Click Create.
Important: Leave Accept requests from these server IP addresses blank. Do not specify any addresses
or address masks.
10. Jot down the API key under Key for server applications or copy it to Notepad.
171
11. Make sure you have the Project Number from Step 3 and API key from Step 10 accurately written down or
copied to Notepad. If you used the latter method, be sure to save the file.
Adding the API Key to Good Control
The API Key and GCM project number must now be added to Good Control.
To add the Google Cloud Messaging API Key to Good Control:
1. In Good Control, under SETTINGS, click Licenses and Keys, then open the API KEYS tab.
2. In the Sender ID field, enter the Project Number from Step 3 above (or paste it in from Notepad).
3. In the Key field, enter the API Key from Step 10 above (or paste it in from Notepad).
4. Click Save to record this information.
172
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.
173
Glossary
C
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.
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.
174
Glossary
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
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
175
Glossary
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
GFE
Good for Enterprise
GNP
Good Notification Push. Protocol that allows notification messages to be pushed from an application server to GD app.
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.
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.
176
Glossary
I
IDE
Integrated Development Environment
J
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
M
MAM
Mobile Application Management
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.
177
Glossary
R
Relay Server
Server in the NOC that provides communications between the GD app and GP servers.
RTT
Round trip time
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.
SPN
Service Principal Name
178
Glossary
U
UI
User Interface
UX
User Experience
179

GEMS Installation and Configuration Guide

Transcription

Similar documents

fashion

WHAT IS GEMS? - Miami International Film Festival

Recommended System Requirements | GEMS *

Trade shows - Jewelry Showcase Magazine

Student Brief - Kilowatt Smackdown

new gem exhibit sparkles in san diego 5.7.2010

Upcoming Shows

A Conference for 6th-8th Grade Girls Saturday, March 21, 2015 8

Board of Directors

Gems, Studs, Stones and Crystals