Administration Guide
Symphony Administration Guide Enterprise and Business Version – June 2017
Introducing Symphony ...... 8 Preparing your installation - what you need before starting ...... 8 Things you need to know ...... 8 FQDNs and names used in this guide ...... 8 Locating your admin credentials and pod configuration details ...... 8 Things you should have ...... 9 Equipment and platform compatibility ...... 9 Identifying and accessing your Symphony service ...... 9 Access to Symphony Cloud Services ...... 9 Emails from Symphony ...... 9 Getting Started – Logging in to the Admin Portal ...... 10 Understanding accounts ...... 10 Log in to the Admin Portal ...... 10 Take a quick tour ...... 12 Create another admin account ...... 14 Creating end user accounts ...... 14 Notification of Account creation ...... 16 Set up password with email ...... 17 First time user login—Pre-populating the user’s IM contacts and filters ...... 18 Reviewing your new accounts ...... 18 Account Audit Trail ...... 19 Filtering Interface for Audit Trail ...... 19 Conversations ...... 20 Changing your password ...... 21 Logging out of the Admin Portal ...... 21 Key Management Infrastructure (Assisted Installation) ...... 21 The Symphony Private Pod Architecture ...... 22 Selecting your Deployment Option ...... 24 Option 1: Software SM and Key Manager Operating in the cloud ...... 24 Option 2: Software SM and on-premises Key Manager ...... 25
Administration Guide – Enterprise / Business Version 2 June 5, 2017
Option 3: HSM and on-premises Key Manager ...... 26 Load Balancers ...... 27 Installing the Key Manager ...... 27 Install the host server for your Key Manager and Software SM ...... 27 Download the KeyManager RPM file ...... 29 Installing the Java Cryptography Extension (JCE) ...... 30 Running the RPM Installation ...... 30 Configuring Certificates ...... 31 Bootstrapping the Software SM and HSM Keys ...... 31 Software SM JSON file ...... 31 Safenet LUNA hardware HSM – Partition Requirements and Size ...... 32 Safenet LUNA hardware HSM – JSON File ...... 34 Bootstrapping your Keys ...... 36 Migrating keys from a SoftSM to an HSM ...... 36 Tomcat and KeyManager Configuration ...... 39 Starting and Stopping the Tomcat service ...... 40 Luna SA 7000 firmware versions ...... 41 The following versions of security modules are supported: ...... 41 Migrating keys from a SoftSM to an HSM ...... 43 Updating your Key Manager ...... 46 Managing your pod ...... 46 The Symphony Pod ...... 46 Roles ...... 47 Super Administrator and Administrator Roles ...... 47 Compliance Roles ...... 50 SCO can add sub permissions to COs ...... 50 Searching and filtering ...... 51 Create a user and generate a password manually ...... 52 Editing a user ...... 54 Changing the Username ...... 54 Deactivating an account ...... 55 Promoting an end user to admin ...... 55 Changing a user’s password ...... 56
Administration Guide – Enterprise / Business Version 3 June 5, 2017
Creating Service User Accounts ...... 56 Management of Certificates in the Admin Portal ...... 58 Feature Entitlements ...... 59 Configuration scenarios ...... 59 Disable features for the entire pod...... 60 Enabling feature settings for new users by default ...... 61 Manually setting features for all users (without using default values) ...... 61 Enabling External Communications ...... 61 Enabling “Can Send Files Internally” ...... 63 Pod level entitlements supported by Symphony ...... 64 Making changes to an individual user ...... 65 Entitling Users to push Signals ...... 66 Improved Confidentiality on mobile clients ...... 66 Blacklist unaffiliated public users ...... 67 Installing the desktop client ...... 67 Download the desktop client ...... 67 Note on dependencies ...... 67 Pre-Configuring your Pod URL ...... 67 Launching the desktop client ...... 68 Authenticating using Single Sign-On (SSO) ...... 68 Configuration information required ...... 69 Notes on Symphony’s implementation of SSO ...... 69 SSO and Domain Names ...... 69 Configuring SSO ...... 70 Implications of SSO ...... 72 Switching off SSO ...... 72 SSO accounts that also have passwords ...... 72 LDAP Synchronization (Sync) ...... 73 LDAP Sync Architecture ...... 74 Tools...... 75 Supported Directory Systems ...... 75 Preparing to Install ...... 76 Installing the Java Cryptography Extension (JCE) ...... 76
Administration Guide – Enterprise / Business Version 4 June 5, 2017
Creating the Service User Account ...... 78 Configuring the Directory Bridge ...... 79 Downloading the Directory Bridge ...... 81 Installation ...... 81 Account Deletion is NOT Possible ...... 95 Assigning Feature Entitlements ...... 95 Configuration Reference ...... 97 Elements of Configuration ...... 97 Sync Destinations ...... 97 Attribute Maps ...... 98 Mandatory fields in the user attributes mappings file ...... 99 End user management of avatars ...... 101 Sync Classes ...... 102 Sync Pipes ...... 103 Sync Sources ...... 103 Compliance ...... 103 Content Export ...... 103 Installing the Content Export Bridge ...... 105 Installing the Java Cryptography Extension (JCE) ...... 105 Managing and Upgrading the Content Export Bridge ...... 114 Enabling Content Export ...... 115 Enabling SFTP Content Export ...... 116 Recurring Export ...... 117 Manual Export (AD-HOC)...... 118 File names ...... 119 Content Export Verification ...... 120 Accessing the exported SFTP repository ...... 121 Exported Content ...... 122 Escaped Characters ...... 123 Content Export Self-Healing (CESH) ...... 124 Format of the catchup section in the validation.JSON file: ...... 125 Wall Post Information ...... 126 “From header” in EML export ...... 127
Administration Guide – Enterprise / Business Version 5 June 5, 2017
Recording Wall Post Likes ...... 127 Tracking of blastID in all formats ...... 127 Exporting shared articles ...... 128 Content Export Verification ...... 128 User Summary Information ...... 128 Active Compliance ...... 128 Expression Filters ...... 129 Audit Trail for Expression Filters ...... 130 Information Barriers ...... 130 Chat Room Remediation ...... 132 Disclaimers ...... 133 Audit Trail for Disclaimers ...... 133 List ALL ROOMS and Monitor ...... 134 Monitoring ...... 134 Session Log ...... 135 The Symphony Platform ...... 136 REST API ...... 136 Agent Installation ...... 137 Configuring the Agent Application ...... 139 Client Extension API (JavaScript) ...... 141 Managing Applications ...... 141 Application Subscription Management ...... 144 BULK MANAGE ACCOUNTS (CSV Import) ...... 146 Overview ...... 146 Get the CSV template ...... 146 Introducing the CSV format ...... 147 CSV for Symphony ...... 147 Password field ...... 148 More about SEND_EMAIL ...... 149 Importing CSV ...... 150 Displaying Bulk Job History ...... 151 Handling errors ...... 152 Create and modify users ...... 152
Administration Guide – Enterprise / Business Version 6 June 5, 2017
Managing admin accounts with the CSV file ...... 152 CSV best practices ...... 153 Deactivating accounts ...... 153 Usage Statistics and Audit Trail ...... 153 Usage statistics ...... 153 Appendix 1: Content Export Schema ...... 154
Administration Guide – Enterprise / Business Version 7 June 5, 2017
Introducing Symphony
Symphony is the cloud-based messaging and collaboration platform that connects markets, organizations and individuals, securely. Powered by an open and growing app ecosystem, and protected with customer-owned encryption keys, Symphony’s communications platform increases workflow productivity while maintaining global regulatory compliance. Already the platform of choice for the financial services industry, Symphony eliminates inefficient workflows to boost productivity in information driven businesses.
This guide describes how to plan, provision and administer a private pod - a dedicated version of Symphony.
Preparing your installation - what you need before starting
Things you need to know You are free to name your Symphony service as you want, but Symphony needs to configure your choice during the initial creation of your service. Once this is done, you should will receive confirmation of the creation of the pod, the pod name, the IP address range used in your cloud service and your admin credentials.
FQDNs and names used in this guide As we mentioned above, you are free to name your Symphony service the way you want. In this guide, we will use the following representation to indicate your pod’s name:
Locating your admin credentials and pod configuration details During the creation of your pod (your company’s dedicated Symphony cloud service) we provisioned the following items:
1. The FQDN (domain name) for your pod 2. The associated IP address range 3. The credentials for your Super Admin account 4. Credentials for the Super Compliance Officer account
Administration Guide – Enterprise / Business Version 8 June 5, 2017
You should have received all the relevant details in an email from Symphony Global Services. Note: Super Compliance Officers receive their credentials separately Please locate this email and follow the instructions it contains.
Things you should have
Equipment and platform compatibility You should have the latest version of the Google Chrome browser running on Windows, Mac or Chromebook computers or Internet Explorer (IE) 11.
Identifying and accessing your Symphony service The Symphony client needs to have access to various components located outside your Firewall.
Access to Symphony Cloud Services Please configure your firewall to allow the URLs and port numbers listed below. These values are provided as guidelines only. The actual names will be aligned with the service name you selected for your pod:
https://
To confirm that the firewall is open, testing each link will either result in a Symphony Login page or a 500 error confirming that the server was reached and responded. You should now be able to start managing your pod. Note: If you intend to activate Content Export then you will also need to allow the use of SFTP on port 22 by the system that will carry out the daily content download:
https://
Emails from Symphony We use Amazon Simple Email Service (Amazon SES) to send application transaction emails. Note: We will enable DKIM signature for all Symphony application emails. Please ensure that you take the necessary steps with your email infrastructure to enable DKIM signature verification. To avoid any spam filtering of Symphony application emails: • Whitelist the FROM address: no-reply-< OrgName >@symphony.com in your corporate email system. • Make sure that emails from the following IPs are not blocked by your spam filters:
Administration Guide – Enterprise / Business Version 9 June 5, 2017
199.255.192.0/22 199.127.232.0/22 54.240.0.0/18
For more information about AWS SES and DKIM features, visit:
• http://sesblog.amazon.com/blog/tag/SPF • http://sesblog.amazon.com/post/TxEH4YOF3YJG0L/Amazon-SES-IP-addresses • http://docs.aws.amazon.com/ses/latest/DeveloperGuide/easy-dkim.html
Access to the CAPTCHA sign-of-life mechanism We use the CAPTCHA mechanism to ensure a live person is using
Getting Started – Logging in to the Admin Portal
Understanding accounts There are two types of accounts: Service & End User Accounts. Service Accounts are used by service applications such as the Directory Bridge, Content Export Bridge and Bots developed using the Symphony SDK. End User accounts are for individuals. Symphony provides a hierarchy of roles for provisioning, managing and supporting your service – we provide full details on role management in the Roles section. With the Admin account you can create users and other admins, activate and de-activate accounts and set the security and password policy for the organization. Please protect your Admin account. As your system grows, so too do the risks associated with your credentials falling into the wrong hands. The Username field uniquely identifies each user in your pod and must be unique across all active or inactive user accounts. In addition, all users must have an email address, which must be unique across all active accounts in the pod. These rules apply to all accounts – including Admin accounts.
Log in to the Admin Portal As we mentioned in the previous section, this version works on Chrome and IE11 – please launch your browser and then enter the URL identifying the admin portal for your Pod. The precise URL would have been communicated to you along with your account details.
Administration Guide – Enterprise / Business Version 10 June 5, 2017
If you are the first (i.e. root) admin, you can set your password by clicking on Forgot Password and entering the email address in which you received the email from Symphony Global Services.
Once you have created your password, go back to the admin portal login page and enter your credentials. At first you will be presented with the standard Symphony user interface:
click on the settings “gear” symbol located at the top right corner of the interface. The Settings options will be displayed as shown below:
Administration Guide – Enterprise / Business Version 11 June 5, 2017
Click on the Go to AC portal option located at the bottom of the General options tab.
Take a quick tour You will now access the Admin portal. The left navigation bar shows the high-level features available in the admin portal:
Administration Guide – Enterprise / Business Version 12 June 5, 2017
Moving the mouse over the admin’s name (located on the top right corner) will display:
1. Logout – Note that for security reasons, your account will be logged out automatically after ten minutes of inactivity. 2. Symphony - this is your personal end-user Symphony account. 3. Help – a fully indexed version of this Admin Guide in electronic form (see screenshot below)
Administration Guide – Enterprise / Business Version 13 June 5, 2017
Create another admin account You should immediately create another Super Admin account as a backup in case you were to lose the credentials you are currently using. This is important because Symphony is designed with strict compliance in mind – Symphony Global Services do NOT have admin privileges on your pod.
Creating end user accounts There are two ways to create accounts for end-users:
• Manually using CREATE A USER option • Selecting BULK MANAGE ACCOUNTS to load a CSV file
Admin accounts cannot be created using the BULK MANAGE ACCOUNTS feature so we’ll use the admin portal interface to create an admin account. Click CREATE A USER on the left navigation menu. You will see the create new user form as shown below:
Administration Guide – Enterprise / Business Version 14 June 5, 2017
Things to notice:
1. Scroll down - There are actually two pages to this form so you should scroll up and down to make sure you have the complete picture 2. Username – This field is the username the user will log in with. If you intend to activate SSO, then your end-users’ company usernames should match their corporate SSO credentials (Kerberos for example). SSO can’t be used by admins but it’s worth being aware of this before you start creating standard end-users. The Username must be unique across all user active and inactive accounts in the pod. 3. Email: The email address is required and must be unique across all active accounts.
Administration Guide – Enterprise / Business Version 15 June 5, 2017
4. Regular User or Admin Account – Notice the table to the right where you can allocate multiple roles to special users. You can read more about ROLES in the section entitled Managing your Pod. 5. Password: Passwords must have at least 8 characters and three of the following: • At least 1 lowercase letter • At least 1 uppercase letter • At least 1 number • At least 1 special character
You should also be aware of your three options: a. Email the user a link so they can set their own passwords – this is actually the simplest option and is selected in the screenshot above. b. Have Symphony generate a password for you – you’ll then need to copy and communicate it to the user. c. If you want the user to have a specific password, select þ manually set – again you’ll need to communicate this to your user (Email, SMS etc..).
Notice the six required fields:
1. Username* 2. Display name* 3. Surname* 4. First name* 5. Email address* 6. Password*
Note: The Screen Sharing feature is in customer beta trials. Note: Don’t forget to make sure you have set user as active. Otherwise the account will be created in your Symphony pod but the user will not be able to log in. There may be occasions when you will want to do that in the future – but for now, we need an active admin account.
• Fill in all of the relevant organizational and location information (optional).
Then:
• Select the Admin checkbox and then select Super Administrator • Scroll down and choose how the password will be created • When you have entered all the information you need, press the Save button.
Notification of Account creation Depending on what you selected, you’ll see one of the following:
1. Email Link:
Administration Guide – Enterprise / Business Version 16 June 5, 2017
2. Password set manually:
• If you entered an invalid password:
Set up password with email
• If you were successful and were using the email link method then the user will receive following email:
• When the user clicks the link, they will be prompted to type in a new password:
The same rules we mentioned earlier will be applied to passwords created in this way.
Administration Guide – Enterprise / Business Version 17 June 5, 2017
If you enter a password that satisfies the requirements, the new admin user will be prompted to log in: Note: The username is the name you assigned when you created the account. Please make sure to communicate to the user what their username is.
First time user login—Pre-populating the user’s IM contacts and filters When the user logs into the client for the first time, they will be presented with a list of contacts pre-populated from the choices you or other admins made when assigning users to departments and divisions. The user can select the contacts to add from this list and they will be added to their IM list in the left navigation panel. Similarly, a second screen will display pre-populated topic filters that are generated from the asset classes and industries that you selected for each user. They can select the specific topics that are of interest and these will be added to their FILTERS list in the left navigation panel.
Reviewing your new accounts You can use the BROWSE ACCOUNTS option to display the account you just created (“Ann”). Your own Admin account (“John” in our example) should also be shown in this list.
Administration Guide – Enterprise / Business Version 18 June 5, 2017
Click once on a name to edit or display that user’s details.
Account Audit Trail Audit trails are used to display a change history for a specific user. You select a user from the BROWSE ACCOUNTS option in the left Nav and then select Audit Trail from the menu bar. The audit trail will display:
1. Date and timestamp of the event – in mm-dd-yy hh:mm format 2. Action 3. Attribute – if any 4. New value 5. Old value 6. Changed by
Filtering Interface for Audit Trail To make it easier to find relevant information and events when displaying the audit trail you can use the three Filter options above the audit trail columns as shown in the screenshot below:
Administration Guide – Enterprise / Business Version 19 June 5, 2017
Select a date range using the date picker. Once you’re satisfied with the date range, and have selected Apply, you can hide the picker again by clicking the up arrow located next to the date range at the top of the picker.
You can then add additional filters based on the Action performed on this user’s account and the Admin that performed the action. We show a date filter combined with an Action filter in the screenshot below:
Conversations Admins can also display a complete list of a users’ conversations – IMs and Rooms. Symphony displays the Conversation name, the type (IM or Room), the date the conversation was started, the last activity date (for the conversation rather than just this user) and the number of active members in the conversation. Conversations can also be filtered by type (Room, IM and Group IM) and by creation date and last active date (see below) :
Administration Guide – Enterprise / Business Version 20 June 5, 2017
Changing your password Users can change their password themselves by clicking on the Forgot Password? link on the login page. Note: Admins cannot use SSO to log in to the Admin Portal. They must always use a password.
Logging out of the Admin Portal Some organizations may prefer their admins to always log out of the Admin Portal once they’ve completed the tasks they needed to do. To log out: Click on the down arrow located at the top right-hand corner of the interface and then click Logout. Next, we will understand how to manage your pod.
Key Management Infrastructure (Assisted Installation)
The use of hardware security modules (HSMs) ensures the security and confidentiality of your data. These devices are installed on your premises or in a cloud service that you control. At no time is Symphony or its employees provided access to these devices. Their
Administration Guide – Enterprise / Business Version 21 June 5, 2017
role is to provide the master keys that generate the encryption keys used in each conversation and Chat Room. Specific HSMs have been selected and validated for use with your Symphony private pod. Other equipment may be selected in the future but at this time only three options are available: 1. Symphony Software SM – designed primarily for user acceptance testing. Software SMs can be used to generate keys in a similar way to full HSMs. These are delivered as part of the Key Manager download from the Symphony Admin Portal and can be used on premises or in a customer controlled virtual private clouds (VPCs) 2. SafeNet Luna SA 7000 HSMs running on the customer premises
Symphony Software SM Luna SA 7000 HSM
Hardware No Tampering will cause immediate protection deletion of keys
No Disconnection will cause immediate Network protection deletion of keys
Key Generation Software-based Hardware-based
Requires external LB or Enabled through HSM Client software HA Architecture DNS failover
Password-based PED-based Access Control FIPS 140-3
Platform Software SM code runs on Luna SA 7000 Hardware Description the Key Manager
Included with the Key Hardware purchase – indicative pricing Commercialization Manager download – no has been provided in the HSM section additional charge of this guide
All these options combine with the Symphony Key Manager downloaded from the Admin Portal. The remainder of this section introduces the equipment required to implement the Symphony encryption architecture and describes how to install, configure and validate your equipment.
The Symphony Private Pod Architecture
A Private (Dedicated) Pod (DP) runs Symphony on Google Cloud Platform (GCP) or Amazon Web Services (AWS) in a dedicated virtual private cloud (VPC) connected to the company’s intranet via VPN or direct connection. It uses cloud-based resources (storage, computation,
Administration Guide – Enterprise / Business Version 22 June 5, 2017
etc.) allocated exclusively to that customer. Single-Sign On (SSO) using SAML assertion is supported for authentication of users and LDAP sync is available for managing accounts and feature entitlement.
Communications between employees are encrypted in each client using keys generated by equipment owned and operated by the organization who’s customer is initiating the communication - HSMs and key managers - ensuring the security, privacy and compliance of all customer content.
Only encrypted data is stored in the customer’s private pod. Importantly, Symphony employees are unable to decrypt customer data as the keys are owned and operated by the customer and are never divulged to Symphony.
The private pod is administered by the customer using the admin portal which supports a hierarchy of administrative roles for managing user accounts, authentication, feature entitlement and content export.
Multiple formats are supported for integrating Symphony content export with corporate data retention systems. Additional compliance controls such as information barriers, disclaimers, keyword blocking and alerts will be made available through the compliance portal.
The diagram below provides a high level summary of the private pod architecture:
Private(Pod( Persistent(Data(
Transac-on(Engine(
Front2End(
DC(and(VPN( Enterprise(Premises( Na-ve(Desktop( Content(Export(
Browser( Key(Manager(
Mobile( HSM(
Administration Guide – Enterprise / Business Version 23 June 5, 2017
Figure – Private Pod
Three primary components are involved in encrypting and decrypting customer content: Hardware Security Module (HSM) or Software SM: Controlled by the customer and responds to new key generation requests received from the Key Manager. Key Manager: Can be controlled by the customer - Interfaces between the clients (on-premises) and the HSMs to request and then wrap encryption keys. Symphony Clients: Symphony clients are available for Windows, Chrome, IE11, iOS and Android. The clients obtain their keys by interacting either with the Wrapped Key Store located in the cloud or the Key Manager.
Before installing Key Managers and HSMs, we need to explore the advantages of each deployment option.
Selecting your Deployment Option Please review each of the deployment options shown below to determine which will be appropriate for you organization:
Option 1: Software SM and Key Manager Operating in the cloud As shown in the diagram below, the Key Manager and Software SM are hosted in the cloud. This has the advantage of being the easiest deployment option as Symphony will carry out the installation and configuration on behalf of the customer. However Option 1 should be considered a temporary less secure solution on the way to an on-premises HSM deployment.
Administration Guide – Enterprise / Business Version 24 June 5, 2017
Key(Store( Iden-ty(Store(
Transac-on(Engine( Persistent(Data(
Private(Pod( Request/Response( DC(and(VPN( Enterprise(Premises(
Key(Manager/SoGHSM( Mobile(Client( Directory(Bridge(
Key(Manager/SoGHSM( Symphony(Desktop(Client(
Customer( Content(Export(Bridge( Controlled(VPC(
Option 2: Software SM and on-premises Key Manager Option 2 is similar to Option 1, but this time the Software SM and Key Managers are installed on the customer premises. Notice that both applications are downloaded together from the Symphony Admin Portal and installed on the same server. Customers will typically deploy multiple Key Managers and Software SMs for resiliency.
Administration Guide – Enterprise / Business Version 25 June 5, 2017
Key(Store( Iden-ty(Store(
Transac-on(Engine( Persistent(Data(
Private(Pod( Request/Response( DC(and(VPN( Enterprise(Premises(
Mobile(Client( Directory(Bridge(
Symphony(Desktop(Client( Key(Manager/SoGHSM(
Content(Export(Bridge( Key(Manager/SoGHSM(
Option 3: HSM and on-premises Key Manager In Option 3, the customer deploys SafeNet Luna SA 7000 HSMs as well as matching Key Managers. Symphony recommends deploying at least two HSMs for high availability. It is also advisable for customers to deploy a backup device for storing keys, as well as a PIN Entry Device (PED) or Remote PED. These are all available from SafeNet and we provide ordering information later in the document. This architecture provides the highest level of reliability and security.
Administration Guide – Enterprise / Business Version 26 June 5, 2017
Key(Store( Iden-ty(Store(
Transac-on(Engine( Persistent(Data(
Private(Pod( Request/Response( DC(and(VPN( Enterprise(Premises(
Mobile(Client( Directory(Bridge(
Symphony(Desktop(Client( HSM( HSM(
Content(Export(Bridge( Key(Manager( Key(Manager(
Later in this document we describe how to order, install and configure the HSM as part of an Option 3 installation. First however we will focus on the Symphony Key Manager.
Load Balancers Load balancers can be used to front-end multiple Key Managers and HSMs (hard or soft) in order to protect against a failure of any single system. Later in these instructions we will describe how the address or hostname of the Key Manager must be configured into the Symphony desktop clients using the admin portal. Note: if a load balancer is used, then the address configured in the Symphony Admin Portal should be that of the load balancer rather than the Key Manager servers themselves.
Installing the Key Manager This step is required for all customer-managed deployments. The Key Manager will be able to interact with both Software SMs and HSMs, so that keys can be migrated. For this reason the Software SM can be deployed as a first step towards HSM support. The first task is to install a host computer for the Key Manager and Software SM.
Install the host server for your Key Manager and Software SM The Key manager server should have the following characteristics:
Administration Guide – Enterprise / Business Version 27 June 5, 2017
• 6 GB of memory should be made available to Key Manager and Software SM. It is more likely to be CPU-bound than memory-bound. (see note below) • CPU cores: 4 • Disk 250 GB • Operating System: Linux RHEL 6.5 or higher or CentOS 7.1 (used in our example below) • Privileges: root access is required to install the Symphony RPM • JVM: Java 7 Standard Edition, Enterprise Edition - a Java development kit (JDK) is recommended – you should create an environment variable pointing to your JDK. Example: JAVA_HOME="/usr/java/jdk1.7.0_55/" • Install Unlimited Strength JCE extensions for JDK or JRE • Install Java Cryptography Extension (JCE)
o Go to http://www.oracle.com/technetwork/java/javase/downloads/jce-7- download-432124.html • You will need to define your Key Manager domain name and communicate this to Symphony – please contact your account engineer or Symphony support.
keymanager domain name/potential keymanager domain name. Sample: mykeymanager.com Add the following configuration details to your Tomcat startup for proper cookie domain assignment. -Dsession.cookie.domain=.pubmy.mykeymanager.com \ -Daccess.control.allow.origin=symphony.com,mykeymanager.com \ -Dhost.name=pubmy.mykeymanager.com \
• java tomcat.keystore file with passwords for the keystore. It should contain an RSA private key under the "tomcat" alias. Sample: keystorePassword=changeit, truststorePassword=changeit. Add the following details to your Tomcat startup for proper key store configuration. -Djavax.net.ssl.keyStore=$DATA_BASE/certs/tomcat.keystore \ -Djavax.net.ssl.keyStorePassword=password \ By default java uses .$JAVA_HOME/jre/lib/security/cacert truststore. But we can use a custom one, as shown in the Tomcat startup file below: -Djavax.net.ssl.trustStore=$DATA_BASE/certs/tomcat.keystore \ -Djavax.net.ssl.trustStorePassword=password \
Administration Guide – Enterprise / Business Version 28 June 5, 2017
Software SM mode settings Symphony application layer cryptography requires the Key Manager to use the appropriate keys. These keys are used to encrypt and decrypt all user generated content for end-to-end encryption. When the Key Manager starts, it will register fingerprints of these keys to the pod. On successful registration, the Key Manager will begin operations. However, if the registration is not successful, it indicates these keys are inconsistent with previously registered keys. As a result, the Key Manager will not start to protect the integrity of existing cryptography.
"mode": "SoftHSM",
Mode signifies soft HSM or Luna HSM, keystorePassword is the password on the soft HSM keystore file, and keystore Name is a relative java resource path to the key store file.
General KM configuration. Get the following from ES/Security team (it will be on admin page later):
• symphony pod base URL. Sample: qa3.symphony.com
"applicationurl": "https://qa3.symphony.com/client/index.html", "baseurl": "https://qa3.symphony.com", "loginbaseurl": "https://qa3.symphony.com",
• KeyManager shared secret key (you can get it from admin page): Sample:
"secret": "RAr67in5QhTWAS7q98PfdeVE/xLGboCo3g/+iLQ5gvY="
• Keymanager entity key. Sample: "entityKey": "kxHpEh3ddcjNrxOXpuSbR5fvNUh8yl21/mmS5WSyzMs="
• Keymanager sesssion encryption key and settings:
"enablekeymanagersession" : "true", "sessionencryptionkey": "kxHpEh3ddcjNrxOXpuSbR5fvNUh8yl21/mmS5WSyzMs="
Network connectivity requirements The Key Manager must be accessible by all Symphony clients in your pod. All Key Managers must also have access to Symphony cloud.
Download the KeyManager RPM file We package keymanager rpm's in *.zip, which includes: - on-prem-keymanager-0.11.2.zip • wenger.tar.gz
Administration Guide – Enterprise / Business Version 29 June 5, 2017
• symphony-external-relay-centos65-0.11.2-22.x86_64.rpm • symphony-external-relay-centos70-0.11.2-22.x86_64.rpm • tomcat-8.0.24-13.x86_64.rpm
- 2 versions of keymanager's rpms (one for RHEL 6.0 - 6.9 and one for RHEL 7.0 +) - The latest version of Tomcat we support and an internal services tool called "Wenger" needed to bootstrap keys in the HSM.
Select DOWNLOAD option located in the left navigation pane of the Symphony Admin Portal and download the Key Manager file.
Once the Key Manager has been downloaded, we can begin the installation. Note: RPM’s are signed, and you download the certificate from https://resources.symphony.com/SYMPHONY-GPG-KEY.public and save it to a local path. Now run the following command to import Symphony’s public signing key into your RPM command line. $:>sudo rpm -import /path/SYMPHONY-GPG-KEY.public
Installing the Java Cryptography Extension (JCE) Go to http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html, accept the license agreement and download and install "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 7” (UnlimitedJCEPolicyJDK7.zip) If your installation fails, the Key Manager or Wenger script will report this error:
java.security.InvalidKeyException: Illegal key size
These errors may be due to different version of java being used than what you installed, permissions on the installed policy files prohibit use of the policy, or other configuration errors.
Running the RPM Installation Install the tomcat and keymanager RPMs that were downloaded.
$:> sudo rpm -i tomcat-7.0.61-9.x86_64.rpm
$:> sudo rpm -i keymanager-centos65-0.7.0-49.x86_64.rpm
Administration Guide – Enterprise / Business Version 30 June 5, 2017
Create a new directory for the Wenger installation and unzip the Wenger installation. The Wenger installation is named wenger.tar.gz. $:> mkdir wenger $:> tar –xvf wenger.tar.gz
Configuring Certificates Configure Tomcat to use https with a valid certificate.
Bootstrapping the Software SM and HSM Keys Depending on whether you’re configuring a Software SM or a full HSM, you will use different steps to bootstrap the encryption keys. Please ensure you are using the instructions that relate to your installation.
Software SM JSON file Please skip this step if Symphony is already managing your Software SM in the Symphony cloud service. Please contact Symphony global services to arrange the transfer of your Software SM and related configuration files. Navigate to the $Wenger/conf directory. Here you should create a new JSON file and name it keymanager_conf.json. You can do this using the following command – $:> vim keymanager_conf.json To bootstrap a Software SM you should have following set of values. Insert the following piece of code into the newly created JSON file. { "relay": { "mode": "SoftHSM", "keystorePassword": "soft_hsm_password", "keystoreName": "mysoft_HSM_keystore.jck", "account": "keymanager", "secret": "keymanager_shared_secret_key", "storagePassword": "session_storage_password", "secureDir": "/data/tomcat/secure/", "entityKey": "entity_key" }, "companyurls": { "applicationurl": "https://
Administration Guide – Enterprise / Business Version 31 June 5, 2017
}, "sessionmanagement": { "disableSkeyauthentication": "false", "sessionencryptionkey": "session_encryption_key" } } Special Notes: The Tomcat process that is running the Key Manager needs read and write access to Securedir. keystoreName path is relative to the Java resource path. Securedir is a canonical path i.e. not relative to the Java resource path. The following URLs should point to your Symphony cloud instance: applicationurl, baseurl, and loginbaseurl. The keymanagerurl should point to your Key Manager URL. The following keys are 32-byte base 64 encoded keys: secret, entityKey, and sessionencryptionkey. For customers looking to participate in cross-pod (cross-company) real-time $cashtag and #hashtag signals, please contact Symphony Global Services to get the “shared cross pod entity” key. Additionally, customers will need support from Symphony Global Services to apply the new key to their local Key Manager configurations.
Safenet LUNA hardware HSM – Partition Requirements and Size When configuring your HSM, you should plan a partition size to store the encryption (master) keys as well as the keys used for signing and authenticating data. Assuming you intend to implement monthly key rotation (in the future) you will need to create a partition size to accommodate the following: 7 years of monthly master encryption keys = 84 AES256 keys 7 years of monthly management encryption keys = 84 AES256 keys 2 RSA-2048 keys for signing operations 2 RSA-2048 keys for authentication operations 10 RSA keys for future use 10 certificates for future use Safenet LUNA hardware HSM – Partition Policies Normally you would now allow partition activation and allow auto activation: lunash:> partition changePolicy -par
Administration Guide – Enterprise / Business Version 32 June 5, 2017
The following partition policies can never be changed.
Description Value
Enable private key cloning Allowed
Enable private key wrapping Disallowed
Enable private key unwrapping Allowed
Enable private key masking Disallowed
Enable secret key cloning Allowed
Enable secret key wrapping Allowed
Enable secret key unwrapping Allowed
Enable secret key masking Disallowed
Enable multipurpose keys Allowed
Enable changing key attributes Allowed
Enable PED use without challenge Allowed
Allow failed challenge responses Allowed
Enable operation without RSA blinding Allowed
Enable signing with non-local keys Allowed
Enable raw RSA operations Allowed
Max failed user logins allowed 10
Enable high availability recovery Allowed
Enable activation Allowed
Enable auto-activation Allowed
Minimum pin length (inverted: 255 - min) 248
Maximum pin length 255
Enable Key Management Functions Allowed
Enable RSA signing without confirmation Allowed
Enable Remote Authentication Allowed
Enable private key unmasking Allowed
Enable secret key unmasking Allowed
Administration Guide – Enterprise / Business Version 33 June 5, 2017
The following policies may be changed by the HSM Administrator.
Description Value Code
Allow private key cloning On 0
Allow private key unwrapping On 2
Allow secret key cloning On 4
Allow secret key wrapping On 5
Allow secret key unwrapping On 6
Allow multipurpose keys On 10
Allow changing key attributes On 11
Ignore failed challenge responses Off 15
Operate without RSA blinding Off 16
Allow signing with non-local keys On 17
Allow raw RSA operations On 18
Max failed user logins allowed 10 20
Allow high availability recovery On 21
Allow activation On 22
Allow auto-activation On 23
Minimum pin length (inverted: 255 – min) 248 25
Maximum pin length 255 26
Allow Key Management Functions On 28
Perform RSA signing without confirmation On 29
Allow Remote Authentication On 30
Allow private key unmasking Off 31
Allow secret key unmasking Off 32
Safenet LUNA hardware HSM – JSON File Ensure that the Luna HSM has been configured before beginning the bootstrapping process for Luna HSM. Also ensure that the HSM client (installed on the Key Manager) has
Administration Guide – Enterprise / Business Version 34 June 5, 2017
been configured, using the “vtl verify” command. Please ensure that the HSM firmware and the client versions are supported with your version of the Key Manager, check the section titled “Luna SA 7000 firmware versions.” Finally ensure that the Wenger tool is installed on the Key Manager server. Navigate to the $Wenger/conf directory. Here you should create a new JSON file and name it keymanager_conf.json. You can do this using the following command – $:> vim keymanager_conf.json Insert the following piece of code into the newly created JSON file. { "relay": { "mode": "HSM", "partitionName": "partition_name_for_luna_hsm", "partition_name_for_luna_hsm": "partition_password_for_luna_hsm", "account": "keymanager", "secret": "keymanager_shared_secret_key", "storagePassword": "session_storage_password", "secureDir": "/data/tomcat/secure/", "entityKey": "entity_key" }, "companyurls": { "applicationurl": "https://
Administration Guide – Enterprise / Business Version 35 June 5, 2017
The keymanagerurl should point to your Key Manager URL. The following keys are 32-byte base 64 encoded keys: secret, entityKey, and sessionencryptionkey. For customers looking to participate in cross-pod (cross-company) real-time $cashtag and #hashtag signals, please contact Symphony Global Services to get the “shared cross pod entity” key. Additionally, customers will need support from Symphony Global Services to apply the new key to their local Key Manager configurations.
Bootstrapping your Keys Assuming you have configured the keymanager_conf.json file correctly for you installation, you can now edit the $WENGER/conf/ServiceConfigurationClient.properties file. To configure Wenger to work with a local file, input the following code snippet: #Backend configuration data storage, e.g. ZooKeeper, Memory, File #ConfigSource=ZooKeeper ConfigSource=File FileConfigSourceLocation=$WENGER/conf/keymanager_config.json
Migrating keys from a SoftSM to an HSM Often customers will have operated a preliminary Soft Security Module (SSM) prior to installing their Luna SA 7000 Hardware Security Module (HSM). If this is the case, the SSM would have been running on the same server as the Key Manager and this may have been either on-premises or in the cloud. In either case, keys generated during the SSM phase must be migrated to the HSM. First, make sure that you have your SSM *.jck file in the classpath of Wenger ($WENGER/conf for example), and your configuration contains the necessary path locations to access the SSM and a partition on your Luna appliance. Prerequisite: Please check that the HSM client was installed and configured correctly using the HSM vtl verify command on the HSM client. Note that the vtl command should be run on the same server that will host the Key Manager and the Wenger utility. A successful vtl verify will display the partition name for the Symphony Key Manager. In the example below, the partition for the Key Manager is: hapg-8f56e43a_472949.
centos@Dev8 - HSMControl2:~ $ vtl verify
The following Luna SA Slots/Partitions were found:
Slot Serial # Label
======1 472949007 hapg-8f56e43a_472949
Step 1: Configure Wenger.sh if this was not done previously
$> mkdir $WENGER
Administration Guide – Enterprise / Business Version 36 June 5, 2017
$> tar -xvzf wenger.tar.gz -C ./$WENGER
$> cd ./$WENGER Step2: Validate that the HSM client was setup correctly and that the HSM has the correct partitions
$> cmu list
Select token
[1] Token Label: hapg-8f56e43a_472949
[2] Token Label: ha-mk2015-1
Enter choice: 1
Please enter password for token in slot 1 : ****************************** At this point, the partition should be empty. Step 3: Add your SSM file
$> cp
Step 4: Validate the Wenger config keymanager_config.json
$> vi $WENGER/config/keymanager_config.json
{
"relay": {
"mode": "HSM",
"keystorePassword": "soft_hsm_password",
"keystoreName": "
"partitionName": "partition_name_for_luna_hsm",
"partition_name_for_luna_hsm": "partition_password_for_luna_hsm",
"account": "keymanager",
"secret": "keymanager_shared_secret_key",
"storagePassword": "session_storage_password",
"secureDir": "/data/tomcat/secure/",
"entityKey": "entity_key"
}
Administration Guide – Enterprise / Business Version 37 June 5, 2017
...
Step 5: Validate the ServiceConfigurationClient.properties file
$> vi $WENGER/config/ServiceConfigurationClient.properties
#Backend configuration data storage, e.g. ZooKeeper, Memory, File
ConfigSource=File
ServiceBasePath=Symphony/ServiceConfiguration
#File config
FileConfigSourceLocation=/$WENGER/conf/keymanager_config.json
Step 6: Migrate keys from the SSM to the HSM
$> $WENGER/sbin/wenger.sh soft-to-luna
Step 7: Validate the installation using the Certificate Management Unit commands (CMU) on your HSM
$> cmu list
Select token
[1] Token Label: hapg-8f56e43a_472949
[2] Token Label: ha-mk2015-1
Enter choice: 1
Please enter password for token in slot 1: ******************************
handle=20 label=mgmtRSA.key
handle=24 label=mk-0
handle=48 label=mgmtAES
handle=49 label=mgmtRSA.cert
Step 7.1 Application layer validation: Use the “Verify Key” functionality of the Wenger utility to validate the migration works at the application layer.
Administration Guide – Enterprise / Business Version 38 June 5, 2017
$> $WENGER/sbin/wenger.sh verify-key Note: Depending upon the number of users and rooms in your pod, this may take some time to verify the application layer cryptography.
Step 8: Switch the Key Manager to HSM mode KM config files are similar to Wenger config files and they can be found in the /data/tomcat/config folder. Change the keymanger mode from softHSM to HSM and add the partitionName and partition credentials there.
$> vi /data/tomcat/config/keymanager_config.json
{
"relay": {
"mode": "SoftHSM", = > "mode": "HSM",
"partitionName": "partition_name_for_luna_hsm_only",
"ha-mk2015-1": "partition_password_for_luna_hsm_only",
Step 9: Restart the Key Manager. Step 10: Verify you can now see historical room content The KM will use the HSM for all future keys rather than the SSM.
Tomcat and KeyManager Configuration Some organizations may prefer to use an internally approved version of Tomcat. This option will be supported in a future release and customers should work closely with Symphony Global Services to ensure that the internally approved version is compatible with the Key Manager. Warning: It is NOT currently possible to share Tomcat containers with other Symphony applications such as the Content Export Bridge. Tomcat configuration Next, configure the “environment.sh” file. Navigate to /data/tomcat/config/environment.sh and setup the ports, domain names and number of threads In the screenshot below, you should substitute your own
DATA_BASE="/data/tomcat/"
Administration Guide – Enterprise / Business Version 39 June 5, 2017
CATALINA_BASE="/opt/tomcat/" JAVA_HOME="/usr/java/jdk1.7.0_55/" CATALINA_OPTS="-server -Xms5048m -Xmx5048m -XX:MaxPermSize=256m \ -Djava.util.logging.config.file=$DATA_BASE/config/logging.properties \ -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager \ -Djava.endorsed.dirs=$CATALINA_BASE/endorsed \ -classpath $CATALINA_BASE/bin/bootstrap.jar:$CATALINA_BASE/bin/tomcat- juli.jar \ -Dcatalina.base=$CATALINA_BASE \ -Dcatalina.home=$CATALINA_BASE \ -Djava.io.tmpdir=$CATALINA_BASE/temp \ -Dsession.cookie.domain=.pubmy.mykeymanager.com \ -Daccess.control.allow.origin=symphony.com,mykeymanager.com \ -Djava.library.path=$CATALINA_BASE/native/ \ -Djavax.net.ssl.keyStore=$DATA_BASE/certs/tomcat.keystore \ -Djavax.net.ssl.keyStorePassword=password \ -Djavax.net.ssl.trustStore=$DATA_BASE/certs/tomcat.keystore \ -Djavax.net.ssl.trustStorePassword=password \ -Dserver.port=8443 \ -Dajp.port=8009 \ -Dserver.command.port=8005 \ -Ddisable.ib=true \ -Dhost.name=host.domain.com \ -Dmax.threads=3000" PATH=$JAVA_HOME/bin:$JAVA_HOME/jre:$PATH If using a proxy to access the KeyManager than the following line should be added to /data/tomcat/config/environment.sh – change
-Dproxy.uri=http:proxy.
Starting and Stopping the Tomcat service First ensure that the user running the Tomcat service has full read/write access to folders where tomcat and keymanager were installed. To start the Tomcat service, use the following command $:> sudo service tomcat start To stop the Tomcat service, use the following command $:> sudo service tomcat stop
Administration Guide – Enterprise / Business Version 40 June 5, 2017
If you have a High Availability cluster, repeat the set-up process on server cluster. In Soft SM configuration mode, use the same *.jck file across all components to ensure keymanager compatibility.
Verification of Logs Check the logs that are generated using the following commands – $:>tail -f /data/tomcat/logs/livecurrent.log $:>tail -f /data/tomcat/logs/catalina.YYYY-MM-DD.log $:>tail -f /data/tomcat/logs/error-livecurrent.log
Installation Verification Once you’ve completed your Key Manager and Software SM configuration, you can run $:> curl https://KeymanagerURL/relay/HealthCheck and you should expect a 200 OK response.
Functional Validation To validate a Key Manager and Software SM combination, log into your Symphony account. Post a message and check that the message is redisplayed in unencrypted clear text. If this is the case then the Key Manager is doing its job correctly. Repeat these steps and exchange messages between clients. If your messages are being displayed correctly then your Key Manager was installed successfully.
Luna SA 7000 firmware versions
The following versions of security modules are supported:
HSM HSM HSM Client Key Manager Qualified & Firmware version version Supported? version
Luna SA 7000 HSM 6.2.1 5.3.5-1 / All Key Manager Yes 5.4.5 versions
Luna SA 7000 HSM 6.10.9 5.3.5-1 / For Key Manager Yes 5.4.5 1.45.15 and higher
Luna SA 7000 HSM 6.24.2 6.2.2 For Key Manager Yes 1.45.15 and higher
Administration Guide – Enterprise / Business Version 41 June 5, 2017
Other versions of HSM firmware, HSM client, and Key Manager have not been tested and are not supported. If you are using High Availability partition for the Luna HSM, please note that the client must be “HAOnly” enabled, which you can set with the following vtl command. #vtl haAdmin HAOnly -enable Next set retry to -1 (infinite). This means the Key Manager will attempt to connect to the HSM every 60 seconds infinitely in the event of a connectivity failure. Setting the value for retry to -1 (infinity) allows the disconnected HSM to rejoin at any time. #vtl haAdmin autoRecovery -retry -1 -interval 60 To verify that the HA group has been successfully created, run the following command. #vtl haAdmin show You will see the following screenshot. Ensure that HA Auto recovery is enabled and that every member of the HA availability group is alive.
Installation Verification Use the “Verify Key” functionality of the Wenger utility to validate the migration works at the application layer. $> $WENGER/sbin/wenger.sh verify-key Note: Depending upon the number of users and rooms in your pod, this may take some time to verify the application layer cryptography.
Administration Guide – Enterprise / Business Version 42 June 5, 2017
Conclusion At this point your Key Manager and either Software SM or HSM with preferably a high availability group has been successfully installed. It is now time to go live with your infrastructure. This requires an address change by Symphony. Please work with Symphony Global Services to cutover to your infrastructure. You will need to provide the URL to your Key Manager to Symphony Global Services. Once this is completed, all your content will be encrypted using keys based on the infrastructure we installed above. This infrastructure is controlled by you and should be managed with the same diligence as other mission-critical services.
Migrating keys from a SoftSM to an HSM A script is available for customers seeking to migrate keys and corresponding historical content from a Pod supported by a Software Security Module (SSM) to one supported by a Luna SA 7000 Hardware Security Module (HSM). First, make sure that you have your SSM *.jck file in the classpath of Wenger ($WENGER/conf for example), and your configuration contains the necessary path locations to access the SSM and a partition on your Luna appliance. You also need read and wrire permission to the SSM.jck file. Step 1: Configure Wenger.sh if this was not done previously
$> mkdir $WENGER
$> tar -xvzf wenger.tar.gz -C ./$WENGER
$> cd ./$WENGER Step2: Validate that the HSM client was setup correctly and that the HSM has the correct partitions
$> cmu list
Select token
[1] Token Label: hapg-8f56e43a_472949
[2] Token Label: ha-mk2015-1
Enter choice: 1
Please enter password for token in slot 1 : ****************************** At this point, the partition should be empty. Step 3: Add your SSM file
$> cp
Step 4: Validate the Wenger config keymanager_config.json
Administration Guide – Enterprise / Business Version 43 June 5, 2017
$> vi $WENGER/config/keymanager_config.json
{
"relay": {
"mode": "HSM",
"keystorePassword": "soft_hsm_password",
"keystoreName": "
"partitionName": "partition_name_for_luna_hsm_only",
"partition_name_for_luna_hsm_only": "partition_password_for_luna_h sm_only",
"account": "keymanager",
"secret": "keymanager_shared_secret_key",
"storagePassword": "session_storage_password",
"secureDir": "/data/tomcat/secure/",
"entityKey": "entity_key"
}
...
Step 5: Validate the ServiceConfigurationClient.properties file
$> vi $WENGER/config/ServiceConfigurationClient.properties
#Backend configuration data storage, e.g. ZooKeeper, Memory, File
ConfigSource=File
ServiceBasePath=Symphony/ServiceConfiguration
#File config
FileConfigSourceLocation=/$WENGER/conf/keymanager_config.json
Step 6: Migrate keys from the SSM to the HSM
$> $WENGER/sbin/wenger.sh soft-to-luna
Administration Guide – Enterprise / Business Version 44 June 5, 2017
Step 7: Validate the installation using the Certificate Management Unit commands (CMU) on your HSM
$> cmu list
Select token
[1] Token Label: hapg-8f56e43a_472949
[2] Token Label: ha-mk2015-1
Enter choice: 1
Please enter password for token in slot 1 : ******************************
handle=20 label=mgmtRSA.key
handle=24 label=mk-0
handle=48 label=mgmtAES
handle=49 label=mgmtRSA.cert
Step 7.5: Verify the key-fingerprints after the key transfer
$> $WENGER/sbin/wenger.sh key-fingerprints
Step 8: Switch the Key Manager to HSM mode, to start using the keys in the HSM KM config files are similar to Wenger config files and they can be found in the /data/tomcat/config folder. Change the keymanger mode from softHSM to HSM and add the partitionName and partition credentials there.
$> vi /data/tomcat/config/keymanager_config.json
{
"relay": {
"mode": "SoftHSM", = > "mode": "HSM",
"partitionName": "partition_name_for_luna_hsm_only",
"partition_name_for_luna_hsm_only": "partition_password_for_luna_hsm_only ",
Step 9: Restart the Key Manager
Administration Guide – Enterprise / Business Version 45 June 5, 2017
Restart the Key Manager. Verify you can now see historical room content using your own account. The KM will use the HSM for all future keys rather than the SSM.
Step 10: Verify you can now see historical room content The KM will use the HSM for all future keys rather than the SSM. Use your own account to verify that historical data is being displayed correctly.
Updating your Key Manager First log into the Admin Portal and download the latest version of the Key Manager RPM distribution by visiting the DOWNLOADS option located in the left Nav. Copy this file to your Key Manager server: $> scp symphony-external-relay-centos*.rpm root@qa8-km:. stop tomcat and verify that it has bee successfully stopped:
$> service tomcat stop
$> service tomcat status update the key manager rpm: $> rpm -U symphony-external-relay-centos65-0.11.0-6.x86_64.rpm verify your update:
$> rpm -qa | grep sym
symphony-external-relay-centos70-0.11.0-6.x86_64 now restart tomcat: $> service tomcat start $> service tomcat status
Managing your pod
The Symphony Pod Symphony combines a frontend application with a highly reliable, secure backend platform. These backend platforms are called pods and come in two flavors (or deployment options):
• Public pod • Private pod
The Public pod is a multi-tenant system where businesses are hosted within the same environment. Each business hosted on the shared pod has its own domain managed and controlled by the business’s admin account. We anticipate that the shared pod will mainly host individual accounts, small and medium sized businesses and workgroups of larger organizations.
Administration Guide – Enterprise / Business Version 46 June 5, 2017
The Private pod: For company-wide deployments enterprise customers will prefer to use a dedicated pod designed specifically for the needs of global enterprises. The pod you are administering is a private pod, dedicated to your organization.
Roles Before we begin, it’s worth discussing the various roles available in Symphony:
Super Administrator and Administrator Roles
• The Super Administrator role provides the highest level of access. The super administrator sets the policies such as: o Assigning people to the following functions: § Administrative – super administrator or administrator § Support – L1 or L2 o Enabling feature entitlements at pod and user group levels o Managing the compliance features o Adding custom apps to the Symphony Market, and o Managing company level settings for SSO and Content Export. • The Administrator role is limited compared to the super administrator. The administrator can manage the end user accounts, but cannot make changes to service accounts or other roles such as compliance officers. Here are the example tasks that an administrator can accomplish: create end user accounts in bulk, manage passwords, search users in the Symphony directory, and assign disclaimers to accounts. • The End-User – will create rooms and chats in support of their daily activities. The end user does not have access to the Admin Portal.
All End-User, Admin and Support accounts are granted the INDIVIDUAL role. The Admin can assign additional responsibilities by adding roles to end-user accounts as shown in the screenshot below:
Administration Guide – Enterprise / Business Version 47 June 5, 2017
If the Admin box is selected, then either Super-Administrator or Administrator can be selected from the corresponding dropdown box. L1 and L2 Support Roles can also be added. Admin and Support Roles can be combined but only one of each role category can be selected - Super-Administrators cannot also be Administrators and L1’s cannot also be L2’s. It is important that administrators fully understand the implications of assigning the different admin and support roles available. The full matrix showing the tasks available to each role is shown below. Note: the table is in two parts in order to help with document formatting:
Administration Guide – Enterprise / Business Version 48 June 5, 2017
Table: Super Administrator, Administrator & Support Roles
Super L2 L1 Category Actions Administrator Administrator Support Support
Create, activate, deactivate, and modify end user and service accounts End users End users End users
Assign and remove the following roles: Super Admin., Super Administrator, Administrator, L2 Support, and L1 Support Admin. Admin., L2 & L1 Support
Manage users in bulk View bulk job history View usage statistics Accounts
Manage passwords: Email user a link to set password, generate a password, or set For end For end For all types of users, L1 & users, L1 & password manually accounts L2 support L2 support accounts accounts
Manage feature entitlements for end users and service Pods, end users End users End users End users accounts & service accounts
Assign disclaimers to end user and service accounts Enable, disable and manage Expression Filters Enable, disable and manage Information Barriers (IB) Enable, disable and manage disclaimers View disclaimers Compliance
View audit trail for Expression Filters and Disclaimer Insertion Disclaimer Disclaimer Insertion Insertion
Add custom apps Apps Manage custom and built-in apps: Enable/disable globally, visible or hidden in the Symphony Market, and automatic/manual end-user installation Enable and disable SSO Enable and disable pod level entitlements Specify the file types users can send Manage Content Export Company Manage blacklist: settings Block search and communication between public Symphony users and users in your company Import and manage PKI signing certificates for your company Download on premise components Manage certificates
The super administrator, administrator, or support roles that can perform the described actions.
Administration Guide – Enterprise / Business Version 49 June 5, 2017
Compliance Roles Compliance officer roles can only be assigned by compliance officers. For this reason the Super Compliance Officer Role is provided separately from the Super Admin Role when the customer pod is first created.
• The Super Compliance Officer role allows authorized users to define, manage and monitor tasks that help ensure compliance with regulations. For example, the Super Compliance Officers can search for rooms, monitor all chat rooms, view all posts of an account, and manage expression filters. They can run reports such as the session logs of all the Super Compliance Officers and the Compliance Officers. • The Compliance Officer role is limited compared to the Super Compliance Officer. The Compliance Officer can search for rooms and see attendees but does not have the ability to manage expression filters. The Compliance Officer can also monitor rooms and wall posts if given the right by the Super Compliance Officer.
In the table below, we list the specific entitlements for SCO and CO roles:
SCO can add sub permissions to COs Super Compliance Officers will be able to manage and grant additional entitlements to standard Compliance Officers (COs):
• Can monitor wall posts • Can monitor chats
Administration Guide – Enterprise / Business Version 50 June 5, 2017
Select BROWSE ACCOUNTS in the left Nav. Then filter the list by role and select compliance officers. Find the compliance officer who will be granted the additional entitlements and display their user details by clicking on their record in the list. Then use the Role section to grant the additional entitlements (see screenshot below):
Searching and filtering
In the previous section, we logged in to the Admin portal and created a user account. When you click the Manage menu item, Symphony will display a list of all the users created so far. At first, this list will be relatively short, probably containing your own account, “John” in our example below, as well as the new user you created in earlier sections. But once you start loading users, you find it more convenient to search and filter the users displayed. Symphony provides selection criteria for displaying exactly the users you’re looking for. You can sort and filter the contents of the search. Sort By
• First Name • Last Name • Location • Division • Department • Last login • Date Created • Date Updated • Role
Filter By
• Status: Active and inactive users
You can also search for users in the search window, see below:
Administration Guide – Enterprise / Business Version 51 June 5, 2017
If there are multiple users with the same name, the search results will display the following information for each user to help you differentiate between the users:
• Display Name (The default is First_Name Last_Name) • User Name • Email address • Avatar
Create a user and generate a password manually In the earlier example, we created our first user and selected ‘Email the user a link to set their password’ which led Symphony to generate a self-provisioning password email. This time, we will see how the set password manually option works.
Administration Guide – Enterprise / Business Version 52 June 5, 2017
Here we have selected to set the password manually. When you select CREATE A USER you will be prompted to enter your password and as you type, the system displays hints about the default password rules until the password entered complies with these rules as shown in the screen below:
Administration Guide – Enterprise / Business Version 53 June 5, 2017
Editing a user
• To edit a user, select BROWSE ACCOUNTS from the Admin menu and then highlight the user we want to manage:
Changing the Username You can change the Username in edit mode—you will see a warning before you change it. Remember that if you change the username, the user will not be able to login to Symphony using their old username and password. You must communicate the change to the user.
Administration Guide – Enterprise / Business Version 54 June 5, 2017
Deactivating an account
• To deactivate a user account, click the Deactivate button at the top right-hand side of the window to toggle the account —you will be asked for a confirmation:
• Once you confirm the account deactivation, the system will confirm as follows:
You can re-activate the account using the same process.
Promoting an end user to admin
• Click on the Browse Accounts, choose the user. • In the Role Type section, select the Admin row from the drop-down list.
Administration Guide – Enterprise / Business Version 55 June 5, 2017
Changing a user’s password
1. Select BROWSE ACCOUNT 2. Search for the user you want to manage 3. Select Reset Password 4. Select Email password reset link or Assign new password
See screenshot below:
When you click on Email password reset link, Symphony will display the following:
• If you choose Assign new password then you will be given the option to have Symphony suggest a password for you. Alternatively, you can simply type in your own password. • Remember to copy the password to the clipboard before completing the process. This is important because you need to let your user know what her new password will be. • Once you‘ve done this you can then submit the password change to the system.
Creating Service User Accounts Service User accounts are used by applications. They leverage the Symphony APIs to interact with your Symphony Pod – either to automate administration or for value-added applications. One important use case for service user accounts is LDAP Synchronization which requires a service user account in combination with the directory bridge server.
Administration Guide – Enterprise / Business Version 56 June 5, 2017
We use the same process to create a service user account as we used previously for creating an end-user account. When the
Note: The Screen Sharing feature is in customer beta trials. Note for LDAP Sync: When configuring the service account to support LDAP Sync you must configure it as an Admin role Once the fields have been entered as described above, press the CREATE button located at the bottom of the form. This will generate a security key. You should immediately copy the security.
Administration Guide – Enterprise / Business Version 57 June 5, 2017
The security key is system generated and acts as a shared secret between your service application and your pod. For security reasons, the Admin Portal uses a display timeout of between 15 and 30 seconds.
Changing your Security Key If you weren’t able to copy the key quickly enough, or need to change the key for any reason, use the Reset Security Key option located top right of the user information form:
You will be asked to confirm the reset:
At which point a new key will be displayed. Again you will have 15 to 30 seconds to copy this new key. Remember, this is the key that will be used by your service application so it needs to be configured in that application.
Management of Certificates in the Admin Portal Bots and other applications developed using the Symphony REST APIs use certificate- based authentication. These certificates can be configured by the Symphony Admin using the MANAGE CERTIFICATES option in the left Nav. The list of currently loaded certificates will be displayed:
Administration Guide – Enterprise / Business Version 58 June 5, 2017
Click the Import button to load a new PEM or CER file:
Feature Entitlements
When you first deploy your pod, three features are activated by default, meaning that whenever you create new users they are authorized to: 1. Delegate: Allow another user to POST on their behalf (deactivated by default) 2. Share Files internally 3. Communicate and share files externally 4. Allow users to create public rooms 5. Allow users to change their profile photos If you display a new user’s details, in a recently deployed pod by using BROWSE ACCOUNTS and then selecting a user, you will see that these features are all shown as activated for this user. While you can modify these selections on a per-user basis this might be time-consuming for larger implementations and FEATURE ENTITLEMENTS provides additional flexibility for controlling these three features at a system-wide level.
Configuration scenarios In this section we describe the various combinations for configuring feature entitlement using two dropdown boxes:
1. Disable for entire pod? • Disable for entire pod • Manage at user level 2. Assign to new users by default? • Yes • No
Administration Guide – Enterprise / Business Version 59 June 5, 2017
Disable features for the entire pod Disabling a feature for everyone on the pod is an important configuration decision but sometimes necessary. Note that the feature will also be disabled for any existing users. When you first provision your pod, you will see “Manage at user level” against the features (please see the screenshot above). If you have decided to disable one of these features then you turn it off by selecting “Disable for entire pod”. Follow these steps:
1. First decide whether you need to disable any of these features 2. Inform any existing users that you are about to disable the feature 3. Disable the feature for the entire pod (no users will be able to use the feature)
This screenshot shows a disabled “Can have delegates feature” (this is the default setting):
Note: Disabling file transfer does NOT inhibit the pasting of tables directly into IMs and users will still be able to receive and display files posted by others.
Administration Guide – Enterprise / Business Version 60 June 5, 2017
Important: Only disable features at the system-wide level if you intend to disable the feature for ALL users and preferably have informed existing users of the planned change. Note: The Screen Sharing feature is in customer beta trials.
Enabling feature settings for new users by default When you first provision your pod, please check if the features being assigned to new users by default are aligned with your corporate policies. For example, “Can have delegates” is allowed and is being assigned to new users by default. You will see “Manage at user level” against each feature and “Yes” as the value in the “Assign to new users by default?” column. You may prefer not to activate specific features for new users in which case you would simply select “No” in the “Assign to new users by default” column and then manage the user settings on a per user basis. The BULK MANAGE ACCOUNTS feature does NOT yet allow admins to set feature entitlement for groups of users. Follow these steps to configure default settings for your new users:
1. First decide which features will be enabled by default 2. Select “Manage at user level“ in the first column entitled: “Disable for entire pod?” on the row corresponding to each feature you want to set defaults for 3. Select “Yes” or “No” in the next column under the heading “Assign to new users by default?” depending on how you want the default settings to work – yes to allow, no to disable. 4. You can still toggle this feature for individual users through the BROWSE ACCOUNTS option or the search window in the top right (see section entitled “Making changes to an individual user” below)
Manually setting features for all users (without using default values) This approach requires that each user be modified manually. You might use this approach if your organization generally prefers a certain feature to be disabled for users but has a few special cases users who will be allowed to use the feature.
1. First decide which features you want to set exclusively by setting the feature for each user manually 2. Select “Manage at user level“ in the first column entitled: “Disable for entire pod?” on the row corresponding to each feature you want to set defaults for 3. Select “No” in the next column under the heading “Assign to new users by default?” 4. You can enable this setting for individual users with the BROWSE ACCOUNTS option and searching for a user (see section below)
Enabling External Communications Admins can control whether users will be able to communicate externally by default. There are important regulatory compliance issues to consider when activating this feature at the company level. Some regulated organizations will prefer to enable this feature at the user level which we describe in a section below.
Administration Guide – Enterprise / Business Version 61 June 5, 2017
Note: The Screen Sharing feature is in customer beta trials. If a user is granted either:
1. Can chat in external IM/MIMs 2. Can chat in private external rooms
Then they will be visible in searches by external users and will also be able to search for and communicate with external users.
Note: Both participants must have External communications activated by their respective admins for this feature to work.
Users must first request a connection with an external user before being able to communicate with them. Two additional entitlements are available for controlling external communications:
1. Can send files externally 2. Require user warning for external communications
Administration Guide – Enterprise / Business Version 62 June 5, 2017
You can also ensure that users will receive a warning whenever they initiate external communications using:
• Require user warning for external communications
Enabling “Can Send Files Internally” Admin’s can configure file attachments by logging into the Admin Portal, and selecting EDIT ENTITLEMENTS from the left Nav. Permitted file types can be added by Super Admins by entering a dot ‘.’ and selecting a file type from the resulting drop down list.
There is currently no way for Admins to add their own custom extensions to the list. The full list of supported file attachment extensions is shown below:
Administration Guide – Enterprise / Business Version 63 June 5, 2017
When File transfer is allowed by setting “Disable for entire pod?” to “Manage at user level”, you should also review the list of permitted file extensions. You can delete extensions from the list, but there is no way to add new extensions at this time. Here is the list of available extensions (these will be supported by default when you first activate your Pod): .avi, .bmp, .cdi, .csv, .doc, .docx, .gif, .jpg, .jpeg, .mov, .mpg, .mpeg, .msg, .m4v, .mp4, .pdf, .png, .ppt, .pptx, .rtf, .tif, .tiff, .txt, .wbmp, .xls, .xlsx, .xml, .xsd .x-tiff, .zip Follow these steps to whitelist file extensions:
1. Enable the “Can Send Files internally” or “Can send files externally” features following the instructions above 2. Add permitted extensions to the “Allowed file types …” entry field using the rules below: • Each extension begins with a dot • Multiple extensions should be separated by a comma • Extensions are case-insensitive Example: .jpg, .jpeg Will also allow .JPG and .JPEG extensions. Note: an empty “Allowed file types” field is equivalent to disabling the “Can send files” feature.
Pod level entitlements supported by Symphony The graphic below shows the pod-level entitlements supported by Symphony.
Administration Guide – Enterprise / Business Version 64 June 5, 2017
Pod-level entitlement Result when entitlement is enabled
Block receipt of files from Users cannot receive files sent by their contacts at other external users companies.
Require user warning for Users get a pop-up notification that their message will be sent external communications to contacts at other company.
Hide chat and user names User names and chat room names are removed from mobile in mobile notifications notifications.
Allow inline media to open Links to inline media such as images or videos are opened by default automatically.
Enable offline email If Symphony users are offline when they receive new notifications messages, they are notified via email.
Allow drag & drop Users can attach files to the message composition window simply by dragging and dropping.
Disable SSO on mobile Single Sign On is disabled on mobile clients. clients
Silence deactivation The chat rooms do not display the user has left the room when events an admin disables a user account.
Automatically connect to When new users are added to a bilateral (cross-company) external users chat room, they get connected to each other automatically. The new users do not need to send or accept connection requests.
Making changes to an individual user Use the ACCOUNTS option located on the left nav. Click on BROWSE ACCOUNTS then search for the user and select ENTITLEMENTS to enable the features you want to activate as shown below:
Administration Guide – Enterprise / Business Version 65 June 5, 2017
Note: There is currently no way to set entitlement features at the point of creating the account (either directly using the CREATE A USER option or indirectly using the BULK MANAGE ACCOUNTS option). Admin’s must first create the account and then use the ACCOUNTS option in the left nav to edit the user’s account settings. Note: The Screen Sharing feature is in customer beta trials.
Entitling Users to push Signals This entitlement can be applied to specific users who will be allowed to push company- wide signals. These signals will be automatically displayed in the left Nav. of all users on the pod.
Improved Confidentiality on mobile clients
Administration Guide – Enterprise / Business Version 66 June 5, 2017
An additional entitlement has been added to prevent information from being displayed on the iPhone and Android lock screen. This option is displayed as a new feature entitlement setting:
• Hide chat and usernames in mobile notification
Blacklist unaffiliated public users Users can be blocked from communicating with or receiving communications from unaffiliated users (public users) with the BLACKLIST option in the left Nav. The admin can set this feature by selecting MANAGE BLACKLIST from the left Nav.
Installing the desktop client
The Symphony desktop client has been developed so that customers can run Symphony directly from Windows or embed the client into their own applications instead of running it from a browser.
Download the desktop client Select DOWNLOADS from the left nav. of the Admin Portal. Click on Desktop client for Windows to download the 32-bit version.
Note on dependencies The desktop client for windows requires .NET version 3.5 or 4.0. On Windows 7 system, .NET 3.5 is pre-installed with the system and on Windows 8.x .NET 4.0 is pre-installed, so nothing should need to be installed. If for some reason neither .NET 3.5 nor .NET 4.0 is detected, the installer will stop and display a message requesting the installation of .NET 3.5 or 4.0.
Pre-Configuring your Pod URL Requires Symphony Desktop Client for Windows version: 1.44.0.7 or higher
Administration Guide – Enterprise / Business Version 67 June 5, 2017
Registry settings are available for simplifying the installation of the desktop client for Windows. At installation, the registry setting will be checked first and will override any other pod URL settings.
• When installing the Symphony desktop app version 1.44.0.7 (or higher) using the msi file provided by Symphony, a registry entry will be created at: Computer\HKEY_CLASSES_ROOT\symphony\PodUrl with an empty data string. • When the app starts, it will look at the registry PodUrl value and if it finds a valid URL then the app will open to the given address. In this case, the value in the pgx described in the following section will be ignored.
Notes: • The PodUrl should include a valid URL including protocol (e.g., https://symphony.mycompany.com/) • If the URL is invalid (e.g., missing protocol) then the value in the pgx file will be used. • If the URL is not reachable then an error will be shown saying: "Application load error. Additional details may be available in the log file: ..." • If the PodUrl is changed in the registry, the app will need to be restarted to pick up the new value.
Launching the desktop client Start Symphony by executing the “Symphony shortcut” icon located on your desktop or by selecting Symphony/”Symphony wrapper” from the Windows Start menu on Windows 7 and higher as shown below
Authenticating using Single Sign-On (SSO)
SSO can be configured so that a relationship of trust is established between corporate identity systems and Symphony. With SSO in place, users will no longer be required to re-authenticate with
Administration Guide – Enterprise / Business Version 68 June 5, 2017
Symphony after having logged into the corporate network. In this way, Symphony joins the family of corporate assets protected by the existing system. SSO makes life easier for both end-users and admins.
Configuration information required Before you configure SSO, you should obtain the following information:
• IdP entity ID • IdP SSO endpoint • IdP signing certificate (this will be a file)
Notes on Symphony’s implementation of SSO This section describes various elements of SSO and how they have been implemented at Symphony. In general we have preferred the most commonly used options wherever possible. Binding - the most widely used • POST binding for incoming assertions • Redirect binding for SAML Requests Assertions • Assertions should be signed • Responses should NOT be signed Signing cert • PEM format • Base64 encoded • Starts with ---BEGIN SAML subject • Should match the username field—this means that when you load your users into Symphony, you should take care to ensure the username field matches the NameID field in the SAML subject contained in the IdP’s SAML assertion.
SSO and Domain Names In order to use URLs in domains other than the Symphony.com domain, you need to provide your preferred domain name to [email protected]. Using this name, you will then update your IdP configuration with the desired ACS URL. The ACS url displayed in the Admin Portal SSO configuration window is provided as an example, but will not match what you configure on your IdP. For example if you see https://MYCOMPANY.symphony.com/login/sso/acs in the SSO configuration window, you can still configure your ACS URL in the IdP configuration as
Administration Guide – Enterprise / Business Version 69 June 5, 2017
https://symphony.MYCOMPANY.com/login/sso/acs as long as MYCOMPANY.com was whitelisted during initial installation.
Configuring SSO Select the Configure SSO option and you will then go through three steps:
In this example, we are configuring a pod called QA and the addresses for the Entity ID and ACS URL are displayed so that they can be noted down and communicated to the appropriate AD admin. Admin Portal SSO Fields • IDP entity ID - the name you give your directory application • IDP SSO endpoint - the URL for accessing that app e.g.: ADFS.example.com • IDP signing certificate - the public signing certificate and can be exported from your directory application Enter the fields corresponding to your corporate directory federation service and then Import the IdP signing certificate. Click Next. You will now move to the second phase in which we test whether we can access the URL you provided. If Symphony was able to access the URL then you will be notified with a pop- up. You will need to enable pop-ups in your browser to see the test.
Administration Guide – Enterprise / Business Version 70 June 5, 2017
After successfully logging in to your Symphony account using your corporate credentials, click Next. You can then select to Switch on SSO.
When you click on Turn on SSO, you will be asked to confirm that you want to switch on SSO:
If SSO was enabled, you will see the message:
Administration Guide – Enterprise / Business Version 71 June 5, 2017
Note: It can take up to two minutes for SSO to be activated after you have enabled it. Note that you will need to communicate to all current users that they need to use the corporate credentials from now on to log into Symphony and can no longer use their Symphony password.
Implications of SSO You will now find that whenever you attempt to change user passwords you will be informed that SSO is in place with the message: Your company has SSO authentication turned on. Note: Admins must have a password to log in to the Admin portal even when SSO has been enabled for the pod.
Switching off SSO In the future, if you decide to revert to manual passwords, you can select Configure SSO again and will see the following:
h"p://AD.XXXXXXXXX.com/adfs/services/trust7 h"ps://AD.XXXXXXXXX.com/adfs/ls7
Be aware that if you did select Disable SSO then your users would need to be notified to set their Symphony passwords.
We recommend that you send an email to your users before disabling SSO telling them how to reset/set a Symphony password.
SSO accounts that also have passwords In the future we will be providing a mobile client and at early stages the mobile client may require a manual password. For this reason, you have the flexibility to assign a password to
Administration Guide – Enterprise / Business Version 72 June 5, 2017
an account, even when you’ve activated SSO on your system. When those users log in using the desktop client, they will still use SSO. In addition to SSO, LDAP Sync is also an important feature that Admin’s can use to simplify the management of users on their private pod.
LDAP Synchronization (Sync)
LDAP is broadly supported by corporate directory systems. With LDAP sync, Admins can create and control their Symphony accounts directly from their corporate directory services.
Symphony has implemented a Directory bridge that provides a real-time interface between the corporate directory and your pod’s internal directory mechanism. We provide a summary of the installation and configuration steps below:
Create a Service Account for your Directory Bridge: 1. Log into the Admin Portal and create a user and select Service Account (see the section on managing Service Accounts) 2. Copy the system-generated security key (you will need this for configuring your Directory Bridge) 3. Also, display the download page located in the left nav of the admin portal and download the two “Directory Bridge Foundation” and “Directory Bridge Connector” files.
Download and install the Directory bridge: 4. Install a Linux RHEL server (virtual or physical) 5. Follow the installation instructions below i. Unzip the distribution ii. Run setup, following the instruction below iii. Configure the directory bridge to connect to your LDAP server and add your Symphony Security Key so that the Directory Bridge can authenticate with your Symphony Pod
‘Drive’ Accounts from the Corporate Directory following these steps: 1. Determine which LDAP server attribute will be used to identify (map) Symphony users on the corporate directory system and apply the attribute to those users 2. Map this group so the Directory Bridge ‘knows’ to forward requests to create, delete or update accounts each time any user details are changed, for members of this group, on the corporate directory system. 3. Define similar mappings for Feature Entitlement (including roles such as Admins) 4. Synchronize your directories – LDAP server to the Symphony Pod via the Directory Bridge
Administration Guide – Enterprise / Business Version 73 June 5, 2017
5. Check that your user additions and updates are being synchronized in Symphony using the Symphony Admin Portal
Before beginning your installation, you need to understand the Symphony LDAP architecture as well as Symphony Service Accounts which will be used for Authentication. Please review the section on managing Symphony service accounts earlier in the Admin Guide before proceeding.
LDAP Sync Architecture The Symphony Directory Bridge server has been implemented using UnboundID Data Sync and it will be helpful for you to familiarize yourself with the bundled components and concepts involved. The diagram below shows the Directory Bridge server configured to interface between the corporate LDAP service and the Symphony Pod.
meta MSG Files meta MSG Files meta MSG Files
Instance 1 Instance 2 Instance 3 Symphony Load Balancer Private (dedicated) Pod
New, accounts, Direct Admin& portal& Account,updates, Groups, Connect VPN displays,updated, account,information Entitlements,…
Corporate,Directory LDAP Bot App
periodic,login,to,Directory, account,(with,key) Load Balancer
KeyKeyUser&AccountsKeyKey ManagerManagerUpdated,settingsManagerManager
Sync Source: Corporate LDAP Service - this is where you create user accounts and assign privileges to your users. You control which information to transmit to the Symphony Pod (the Sync Destination). The Directory Bridge: The interface between the Sync Source and the Sync Destination. The Directory Bridge maintains Sync Classes and mapping of fields between the two. It
Administration Guide – Enterprise / Business Version 74 June 5, 2017
also operates the pipes used to maintain synchronization. The Directory Bridge has been developed using UnBoundID and various tools for managing the Directory Bridge are included with your installation. Sync Destination: In our case, this is the user metadata on your Symphony private pod. Sync Classes: These are used to determine the criteria for selecting subsets of your user data to include in synchronization. We provide an example in the diagram where the attribute “userparam” is being used to synchronize users for whom this attribute has been set to “SymphonyUser”. Sync Pipes: Synchronization is maintained using pipes that define specific objects, in our case: Users, and Groups. Groups are used to define feature entitlements and have also been leveraged to synchronize the Admin attribute. Service User Account: This is the account used by the Directory Bridge for authenticating with the Symphony Pod. It will include an Account name as well as a security key. This security key will be configured on your Directory Bridge.
Tools In this section we list the various tools used for installing, configuring and operating the Directory Bridge: Admin Portal: used to configure the Service User Account on your Symphony Pod Setup: Installs UnBoundID and prompts you to set your Directory Bridge password create-pipes.sh: Uses the config properties file containing your principal configuration information (including authentication with both Symphony Pod and LDAP service) to configure and initiate your pipes create-attribute-maps.sh: This script initiates your attribute mappings, it also uses the config properties file. LDAP-Search: Gathers the items that will need to be synchronized Resync: Runs synchronization dsconfig: Configuration and operational interface for the Directory Bridge. It can be run in both command line mode as well as menu mode. Directory Bridge Configuration files:
• directorybridge.properties: used to configure user activation and high level properties • groupMappings.json: used to configure feature entitlements, Information Barriers and Roles • userAttributeMappings.json: used to configure user properties like department
Supported Directory Systems Symphony has initially validated Active Directory 2008 R2. Symphony will continue to test and validate corporate directory systems based on customer demand. This section provides a snapshot of the directories supported by the underlying UnboundID technology:
Administration Guide – Enterprise / Business Version 75 June 5, 2017
• UnboundID Identity Data Store • UnboundID Identity Proxy (3.x) • Oracle Directory Server Enterprise Edition (DSEE 6.x, 7.x) • Oracle Directory Server (5.2 patch 3 or higher) • Microsoft Active Directory
Preparing to Install Before beginning your installation, you will need to obtain the Directory Bridge server image and install a server (or virtual server) to run the Directory Bridge. Directory Bridge Server Attributes • RAM: 4 GB gigabytes • Hard drive: logs will require 250 MB. • Processors: 4 • Operating System: Linux RHEL Fedora 2015.03 (This AWS supported OS has been validated by Symphony) • JVM: Java 7 Standard Edition, Enterprise Edition - a Java development kit (JDK) is recommended – see additional instructions for upgrading to TLS 1.2 below. • JVM 64-bit is recommended • Virtual Servers: both on-premises and cloud-hosted are supported
Installing the Java Cryptography Extension (JCE) The default Java7 distribution uses TLS 1.0. Symphony requires TLS 1.2 available with the Unlimited Strength Jurisdiction Policy Files.
Do that by downloading the package from here: http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html accept the license agreement and download "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 7” (UnlimitedJCEPolicyJDK7.zip)
Copy this package to the server where you will run KeyManager and unzip it.
Administration Guide – Enterprise / Business Version 76 June 5, 2017
UnlimitedJCEPolicyJDK7.zip contains 3 files 1. local_policy.jar 2. README.txt 3. US_export_policy.jar
And override the files in your local java installation. Copy local_policy.jar and US_export_policy.jar to one of the following:
JDK installation: $JAVA_HOME/jre/lib/security
JRE installation: $JAVA_HOME/lib/security
Information to gather
Before beginning the installation process, gather the following information:
1. LDAP source system info
a. The host and port of the LDAP system.
b. The DN and password of the LDAP user that LDAP Sync will use to connect to the LDAP source system. c. The base DN for all user and group entries that LDAP Sync will need to access d. The base DN for user entries e. The LDAP attribute that will be used to associate LDAP user entries with Symphony usernames. In the vast majority of cases, this will be "sAMAccountName", but that needs to be confirmed. f. The LDAP attribute that indicates which groups a user is a member of. Most LDAP systems use "member" as the attribute name, but this should be confirmed.
2. Symphony information a. The username and key for the Symphony service user that will be used to access the Symphony APIs b. The base path to the Symphony APIs. This will be something like "https://mycompany.symphony.com". 3. Sync configuration info a. See User Attributes section below for the complete list of user attributes available for syncing. For each of the attributes that you want to sync, determine the corresponding attribute name used by your LDAP system and have this mapping available before beginning installation. 4. When setting LDAP sync up for the first time, you will be asked to create a password that will be required for any future management/configuration of LDAP Sync. Decide on this password beforehand.
Administration Guide – Enterprise / Business Version 77 June 5, 2017
The Symphony Users Group The “Symphony Users Group” is effectively the list of all active Symphony users. A user account will be Activated when the account is added to this group and Deactivated if it is then removed. Adding the account name back into the group will Reactivate the account.
Mapping the group used in your corporate directory to the “Symphony Users Group” is accomplished by editing directorybridge.properties file – see step 13 below. The following table lists what happens when the “Symphony Users Group” is or is NOT enabled:
Change in Result WITHOUT “Symphony Users Result WITH “Symphony Users Group” enabled LDAP System Group” enabled
User added to N/A The LDAP Group Sync Pipe determines the differences All Users Group between the “All Users” and “Symphony Users” Groups to determine which users should be created or deactivated.
User created in The LDAP User Sync Pipe creates the The LDAP User Sync Pipe does not create the user in Directory user in Symphony (or updates with the Symphony because he/she is not initially a member of the All latest attributes if a user with the same Users Group. username already exists.) A misleading “SEVERE_WARNING” is logged that the user cannot be created because the user already exists in Symphony.
User removed N/A The LDAP Group Sync Pipe determines the differences from the All between the “All Users” and “Symphony Users” Groups to Users Group determine which users should be created or deactivated.
User removed The LDAP User Sync Pipe deactivates The LDAP User Sync Pipe does not deactivate the user in from Directory the user in Symphony. Symphony. Since the user is no longer in the LDAP system, he/she cannot be a member of the “All Users” Group. A misleading message is logged that the user was deleted successfully.
User updated The LDAP User Sync Pipe updates If the user is a member of the All Users Group, the LDAP User the user’s fields in Symphony. Sync Pipe correctly creates or updates the user in Symphony. Otherwise, the change is ignored.
Important Note: If you have existing users defined on your Symphony Pod prior to activating LDAP sync then you should ensure those users are added to the Symphony Users Group, otherwise their accounts will be deactivated when LDAP sync is deployed.
Creating the Service User Account The Directory Bridge interacts with your private pod using a Symphony Service user account. Before proceeding, please make sure you’re familiar with our instructions for creating and configuring service accounts using the Admin Portal. An earlier section describes this in more detail. Service accounts can be created using the CREATE USER option in the left nav.
Administration Guide – Enterprise / Business Version 78 June 5, 2017
Note: The Screen Sharing feature is in customer beta trials. Once the account has been configured a Security Key will be generated (see below):
You should copy this information immediately for inclusion in your Directory Bridge configuration. The Security code will only be displayed for a brief 15-30 seconds. If you miss it, you can regenerate another security code.
Configuring the Directory Bridge Once installed (see below), the directory bridge is configured by modifying three files:
• directorybridge.properties: used to configure user activation and high level properties • groupMappings.json: used to configure feature entitlements, Information Barriers and Roles • userAttributeMappings.json: used to configure user properties like department
Administration Guide – Enterprise / Business Version 79 June 5, 2017
Each time these files are modified, the Directory Bridge must be stopped and restarted using the commands below:
$> $syncroot/bin/stop-sync-server $> $syncroot/bin/start-sync-server
If errors are encountered with your configuration files (typically when you try to restart your bridge) then the Directory Bridge will fail to start and you should consult the error log file:
$syncroot/logs/errors
Limits and Issues with the current Implementation The stability of Directory Bridge declines when there are more than 1000 users created manually in Symphony who don't also exist and are not mapped to accounts in the corporate directory system. We recommend either deactivating the manually created Symphony users to bring the number of manually created users below 1000 or including those users in the LDAP sync’ed users.
When the admin simultaneously removes a user from a group and adds the same user to another group then the user does not get removed from the first group. In order to avoid this occurrence, admins should first apply one change (removing the user from the first group) and then applying the second change (adding the user to the second group).
When a group is mapped to two roles in the same category (ADMIN/SUPER_ADMIN or L1_SUPPORT/L2_SUPPORT), the user will retain the role that was assigned initially.
It is recommended that the admin perform a sync on startup. To do that run the following command before running bin/start-sync-server (please replace “fakecorp” with your own company name):
$> $syncroot/bin/resync --pipe-name 'Groups to Symphony Sync Pipe' --baseDN 'CN=Symphony Users,CN=Users,DC=fakecorp,DC=local'
Note: logs get written to $syncroot/logs/tools/resync.log. These logs get wiped out with every run of resync.
Administration Guide – Enterprise / Business Version 80 June 5, 2017
In order to avoid unintended consequences, Admins should manage accounts either via LDAP Synchronization as explained in this section, or via the Admin Portal. Symphony does not support doing both simultaneously.
The dsconfig command used to start the sync pipes can sometimes take up to 10 minutes. This can happen when “Symphony Users” is configured.
Downloading the Directory Bridge The Directory Bridge server image can be obtained by using the
Installation Create a Directory for the Server and load the RPM file into this directory Log in to your RHEL Linux server. Then create a directory and save the DirectoryBridge rpm file to this directory.
Installing the Directory Bridge distribution
1. Run the rpm file as follows. A new directory will be created /opt/directorybridge and for the remainder of this section, we will refer to the directory as $syncroot. $> sudo rpm --install
For an update of an existing installation: sudo rpm --upgrade
2. After running the RPM script, the following files and directories are available in $syncroot:
License.txt Licensing agreement for the Identity Data Store
README README file that describes the steps to set up and start the Identity Data Store
Administration Guide – Enterprise / Business Version 81 June 5, 2017
bak Stores the physical backup files used with the backup command-line tool
bat Stores Windows-based command-line tools for the Identity Data Store
bin Stores UNIX/Linux-based command-line tools for the Identity Data Store
classes Stores any external classes for server extensions
config Stores the configuration files for the backends (admin, config) as well as the directories for messages, schema, tools, and updates
db Stores the Oracle Berkeley Java Edition database files for the Identity Data Store
docs Provides the release notes, Configuration Reference file and a basic Getting Started Guide (HTML)
import-tmp Stores temporary imported items
ldif Stores any LDIF files that you may have created or imported
legal- Stores any legal notices for dependent software used with the notices Identity Data Store
lib Stores any scripts, jar, and library files needed for the server and its extensions
locks Stores any lock files in the backends
logs Stores log files for the Identity Data Store
Administration Guide – Enterprise / Business Version 82 June 5, 2017
resource Stores the MIB files for SNMP
revert- The revert-update tool for UNIX/Linux systems update
revert- The revert-update tool for Windows systems update.bat
setup The setup tool for UNIX/Linux systems
setup.bat The setup tool for Windows systems
uninstall The uninstall tool for UNIX/Linux systems
uninstall.bat The uninstall tool for Windows systems
update The update tool for UNIX/Linux systems
update.bat The update tool for Windows systems
3. From this point onwards we will run scripts from the $syncroot directory. Specify the file descriptor limit by executing this command from $syncroot:
$> echo -n "NUM_FILE_DESCRIPTORS=" > config/num-file-descriptors && ulimit -n >> config/num-file-descriptors this will prevent the following warning message from being displayed during your installation:
WARNING: Unable to set the file descriptor limit to 65535. This may interfere with the operation of this process. See the Administration Guide for information about configuring system file descriptor limits, and for configuring the number of file descriptors the server should attempt to use.
Then Specify the maximum number of processes available by executing the command below from $syncroot:
Administration Guide – Enterprise / Business Version 83 June 5, 2017
$> echo -n "NUM_USER_PROCESSES=" > config/num-user-processes && ulimit -u >> config/num-user-processes
4. From $syncroot, run $> ./setup This will launch a series of prompts. Some of them will be prepopulated with a default answer (shown within square brackets). To accept a default, simply press “enter” or “return” (depending on your keyboard). For a simple installation, we recommend that you accept the default value for each prompt as shown in the dialogue below (these settings can be changed later).
Do you accept the terms of this license? Enter 'yes' to accept, 'no' to reject, or press ENTER to display the next page of the license [yes] Would you like to add this server to an existing Identity Data Sync Server topology? (yes / no) [no] Enter the fully qualified host name or IP address of the local host [xx.xx.xx.xx] Create the initial root user DN for the Identity Data Sync Server [cn=Directory Manager] Create a password for the initial root user: [Enter your password] Re-enter the password for confirmation: [Enter your password] On which port should the Identity Data Sync Server accept connections from LDAP clients? [XXXX
Enter option: [3] for evaluation purposes or [1] for production
Do you want to start the server when the configuration is completed? (yes / no) [yes]
Setup Summary ======Host Name: 10.86.0.94 Root User DN: cn=Directory Manager LDAP Listener Port: 4389 Secure Access: disabled
Administration Guide – Enterprise / Business Version 84 June 5, 2017
The Identity Data Sync Server will be started after configuration What would you like to do? 1) Set up the server with the parameters above 2) Provide the setup parameters again 3) Cancel the setup Enter option [1]
Configuring Identity Data Sync Server ..... Done Starting Identity Data Sync Server ..... Done
This server is now ready for configuration. What would you like to do? 1) Start 'create-sync-pipe-config' to configure synchronization between two sets of servers 2) Start 'dsconfig' to edit the configuration 3) Quit At this point, choose quit: 3
5. Next, we will issue an LDAP search request to the source endpoint (LDAP system) to verify LDAP Sync's read access. Go to $syncroot/bin and execute:
$> ./ldapsearch --help
A few pages of documentation will be displayed, at the end of which are example uses of the ldapsearch utility. Execute the following command, substituting the values for your LDAP system and the password you created during execution of the setup script. Note the use of -ZX, which indicates the use of LDAPS (secure protocol) and blind trust of the LDAP system’s certificate.
$> $syncroot/bin/ldapsearch --hostname localhost --port 23317 -ZX -- bindDN "cn=Sync User,cn=Users,dc=fakecorp,dc=local" --bindPassword NotReallyThePassword --baseDN "dc=fakecorp,dc=local" --searchScope base '(objectclass=domainDNS)'
If the result of this command is:
Connect Error Result Code: 91 (Connect Error)
...then we do not have connectivity to the source LDAP system. Ensure connectivity and try again. If the result is:
Cannot read the bind response from the server: The connection to the Identity Data Sync Server was closed before the bind response could be read
Administration Guide – Enterprise / Business Version 85 June 5, 2017
(id=10748693 LDAPAuthenticationHandler.java:385 Build revision=18964) Result Code: 82 (Local Error)
...then ensure that your LDAP system is configured to accept connections over LDAPS. If all goes well, then the result will look something like this:
dn: cn=Users,dc=fakecorp,dc=local objectClass: top objectClass: container cn: Users description: Default container for upgraded user accounts distinguishedName: CN=Users,DC=fakecorp,DC=local instanceType: 4 whenCreated: 20150203201527.0Z whenChanged: 20150203201527.0Z uSNCreated: 5696 uSNChanged: 5696 showInAdvancedViewOnly: FALSE name: Users objectGUID:: VcT3+EE6zEa36KXS9SCNbw== systemFlags: -1946157056 objectCategory: CN=Container,CN=Schema,CN=Configuration,DC=fakecorp,DC=local isCriticalSystemObject: TRUE dSCorePropagationData: 16010101000000.0Z
6. Confirm that $syncroot/config/ldapsync.properties contains values appropriate for your system. In the following steps we will run commands that depend on these properties. An example file is provided as a reference: ldapsync-example.properties (see below):
# The login info for the UnboundID-Synch server LDAP_SYNC_BIND_DN="cn=Directory Manager" LDAP_SYNC_PASS="symphony" # The login info for the AD server when creating the pipe SOURCE_SERVER_NAME="symphony-ad-test" SOURCE_SERVER_HOST="localhost"
Administration Guide – Enterprise / Business Version 86 June 5, 2017
SOURCE_SERVER_HOST_PORT="23317" # NOTE: to see the full list of servers supported, use the dsconfig utility in the bin directory SOURCE_SERVER_TYPE=active-directory SOURCE_SERVER_BASE_DN="dc=fakecorp,dc=local" SOURCE_SERVER_USERS_DN="cn=Users,dc=fakecorp,dc=local" SOURCE_SERVER_HOST_BIND_DN="cn=Sync User,cn=Users,dc=fakecorp,dc=local" # to get a new hashed password, use the dsconfig utility in the bin directory to set the password -- the hashed password will be displayed SOURCE_SERVER_HOST_PASS="AACWeEOv7z2jqceYfwsqjC9rWjCBJebE9GE="
7. Create the primary elements of configuration by running the following script using your own version of the example we displayed in section 6 above:
$> syncroot/bin/create-pipes.sh ../config/ldapsync.properties Be sure to look at the output to ensure that all operations were successful. If any operation failed, then undo the script by running:
$> syncroot/bin/delete-pipes.sh ../config/ldapsync.properties If all goes well then the following output will be displayed.
Creating external servers The Active Directory External Server was created successfully Creating sync source plugin The Third Party LDAP Sync Source Plugin was created successfully Creating sync source The Active Directory Sync Source was created successfully Creating sync destination for users The Third Party Sync Destination was created successfully Creating sync destination for groups The Third Party Sync Destination was created successfully Creating sync pipe for users The Sync Pipe was created successfully Creating sync pipe for groups The Sync Pipe was created successfully Creating sync class for users The Sync Class was created successfully Creating sync class for groups
Administration Guide – Enterprise / Business Version 87 June 5, 2017
The Sync Class was created successfully Finished.
8. Until LDAP Sync is confirmed to be running smoothly, it is recommended that debug logging be enabled. Do this via the following command:
$>./dsconfig -n --bindDN "cn=Directory Manager" --bindPassword NotReallyThePassword set-log-publisher-prop --publisher-name "Server SDK Extension Debug Logger" --set enabled:true
9. We will now configure the primary Sync Class for users. This defines how a subset of users will be selected for inclusion in the Directory Sync.
• Define a specific LDAP attribute in your LDAP server that will “contain” your Symphony users. Example: userparam=symphonyusers • Still on your LDAP Server, add this attribute to the users who will have access to Symphony • Using the dsconfig command on the Directory Bridge configure include filters to use the attributes defined in the LDAP server above – these are the ones who will be synchronized with your Symphony accounts
$> ./dsconfig set-sync-class-prop --pipe-name "Users to Symphony Sync Pipe" --class-name "Users to Symphony Sync Class" --hostname "localhost" --bindDN "cn=Directory Manager" --bindPassword YourDirectoryBridgePassword --port 1389 -n --set include-base-dn:cn=Users,dc=fakecorp,dc=local - -add "include-filter:(userparam=symphonyusers)"
10. Now we are ready to start synchronizing data. Please note that by default LDAP Sync will start at the beginning of the source LDAP system's changelog. For many enterprise LDAP systems, the changelog is extremely long. In such cases, LDAP Sync may take a long time time to work its way through all of the changes. This is especially true if many of the entries in the changelog are not of interest to LDAP Sync. Therefore, it is recommended that we first use LDAP Sync's resync utility to take care of historical data, and then configure LDAP Sync to start at the end of the changelog (before enabling real-time synchronization).
To do this, start by setting the starting point of each sync pipe as follows (as always, run from $syncroot) and use the password you entered for LDAP_SYNC_PASS above.
$> ./realtime-sync set-startpoint --end-of-changelog --pipe- name "Users to Symphony Sync Pipe" --bindDN "cn=Directory Manager" -
Administration Guide – Enterprise / Business Version 88 June 5, 2017
-bindPassword NotReallyThePassword --port XXXX ß- default port number from setup
$> ./realtime-sync set-startpoint --end-of-changelog --pipe- name "Groups to Symphony Sync Pipe" --bindDN "cn=Directory Manager" --bindPassword NotReallyThePassword --port XXXXß- default port number from setup
Note that the above commands require that the sync pipes are stopped (i.e. disabled). This can be done with the same command; run ./realtime-sync --help for more information. These commands (./realtime-sync set-startpoint...) may take several minutes (especially if the source LDAP system is Microsoft Active Directory) but can be run in parallel. If all goes well, the following output will be displayed.
Set StartPoint task 2015040819121904 scheduled to start immediately
NOTE: This tool is running as a task. Killing or interrupting this tool will not have an impact on the task
11. Now that the pipes are all set to start at the end of the changelog, let's synchronize everything up to this point so that we can enable real-time synchronization. The following examples should be repeated for each of the sync pipes (i.e. users, and groups). To do this, execute an LDAP search to get all entries that that should be synchronized. Please use a filter that is appropriate for the source LDAP system being used. Here's an example:
$> ./ldapsearch --hostname localhost --port 23317 -ZX -- bindDN "cn=Sync User,cn=Users,dc=fakecorp,dc=local" -- bindPassword NotReallyThePassword -- baseDN "cn=Users,dc=fakecorp,dc=local" --simplePageSize 1000 -- searchScope sub '(userparam=SymphonyUsers)' dn > entriesToSync.ldif
Note the use of --simplePageSize 1000. If the source LDAP system has a lower limit on the number of entries returned by an LDAP search, then a lower page size should be used. If all goes well, a file named entriesToSync.ldif will be created with contents similar to this:
dn: CN=Ruth Reynolds,CN=Users,DC=fakecorp,DC=local
dn: CN=Super Man,CN=Users,DC=fakecorp,DC=local
Administration Guide – Enterprise / Business Version 89 June 5, 2017
dn: CN=Kelly Flores,CN=Users,DC=fakecorp,DC=local
dn: CN=Administrator,CN=Users,DC=fakecorp,DC=local
dn: CN=Jean Warren,CN=Users,DC=fakecorp,DC=local
dn: CN=Guest,CN=Users,DC=fakecorp,DC=local
dn: CN=Gary Rodriguez,CN=Users,DC=fakecorp,DC=local
12. Configure LDAP Sync properties by first copying the example file: $>cp directorybridge-example.properties directorybridge.properties edit this file and enter the name of your Symphony service (replacing fakecorp in the example file)
# SOURCE SERVER CONFIGURATION
source-server-base-dn="dc=fakecorp,dc=local"
ldap-user-search-basedn="cn=Users,dc=fakecorp,dc=local"
#
# SYMPHONY CONFIGURATION
# Please replace 'localhost.symphony.com:17443' with the URL and port number identifying your private pod
symphony-url="https://localhost.symphony.com:17443"
# This should be a service user.
symphony-user="LDAPSystem"
# This will be a shared secret.
symphony-auth="123Ro+A2CXsx3GDiKZm2YDawTmfZo4j4gOrheAOMfEE="
# SYNC CONFIGURATION – replace “fakecorp”
# To configure the Symphony Users Group, configure the following line:
symphony-users-ldap-group="cn=Symphony Users,cn=Users,dc=fakecorp,dc=local"
# The interval at which periodic sync should run:
sync-rate-seconds=60
# ATTRIBUTE MAPPING
Administration Guide – Enterprise / Business Version 90 June 5, 2017
# The username attribute is used to associate LDAP entries with Symphony users
ldap-username-attr=sAMAccountName
# This attribute is used to determine when an LDAP entry was last modified.
# For Active Directory, the usual attribute is "whenChanged".
# For the Oracle LDAP implementation, the usual attribute is "modifyTimestamp".
ldap-last-update-time-attr=whenChanged
# Most LDAP systems use "member" as the attribute to store group membership and "memberOf" to store the groups a user is a member of
ldap-group-member-attr=member
ldap-memberof-attr=memberOf
# Most LDAP systems use "member" as the attribute to store group membership
# and "memberOf" to store the groups a user is a member of
ldap-group-member-attr=member
ldap-memberof-attr=memberOf
# In Active Directory, the "userAccountControl" attribute is usually used to configure user account properties, with the hexadecimal property flag 0x2 used to mark a user as disabled.
# To use this (or another) attribute to disable users in Symphony, you must configure the attribute name in userAttributeMappings.json and configure the ldap-user-deactivation-value below.
# TIP: The entry in userAttributeMappings.json will look something like this:
# { "symphony": "isDisabled", "ldap": "userAccountControl" }
#ldap-user-deactivation-value=bitmask:0x2
13. Configure LDAP Sync group mappings by first copying the example file:
$>cp groupMappings-example.json groupMappings.json
Administration Guide – Enterprise / Business Version 91 June 5, 2017
The groupMappings.json file is used to map groups for roles as well as for managing membership of Information Barrier (IB) groups using the Information Barrier ID for a particular group within the Admin Portal.
Note: Disabling and Creating IB groups directly using LDAP sync is not currently supported.
Edit the file groupMappings.json and enter the name of your Symphony service (replacing fakecorp in the example file).
[ { "dn": "CN=ComplianceOfficers,CN=Users,DC=fakecorp,DC=local", "roles": ["COMPLIANCE_OFFICER"] }, { "dn": "CN=SuperComplianceOfficers,CN=Users,DC=fakecorp,DC=local", "roles": ["SUPER_COMPLIANCE_OFFICER"] }, { "dn": "CN=Admins,CN=Users,DC=fakecorp,DC=local", "roles": ["ADMINISTRATOR"] }, { "dn": "CN=Entitlements,CN=Users,DC=fakecorp,DC=local", "entitlements": ["sendFilesEnabled", “delegatesEnabled”] }, { "dn": "CN=IBGroupA,CN=Users,DC=fakecorp,DC=local", "infoBarrierGroups": ["56e700f6e4b088a70f00a1e5"] }, { "dn": "CN=IBGroupB,CN=Users,DC=fakecorp,DC=local", "infoBarrierGroups": ["56e700ffe4b0665dac11e117"] }, { "dn": "CN=Disclaimer,CN=Users,DC=fakecorp,DC=local", "disclaimerName": “Name of the disclaimer” } ]
14. Configure LDAP Sync user attribute mappings by first copying the example file: $>cp userAttributeMappings-example.json userAttributeMappings.json
[ { "symphony": "deptName",
Administration Guide – Enterprise / Business Version 92 June 5, 2017
"ldap": "department" }, { "symphony": "divName", "ldap": "division" }, { "symphony": "location", "ldap": "l" }, { "symphony": "givenName", "ldap": "givenName" } ]
The full list of “to-attribute” values is provided in the table below:
attribute(name required description assetClass no name*of*the*asset*class*to*which*the*user's*work*is*related deptName no name*of*the*department*to*which*the*user*belongs displayName yes divName no name*of*the*division*to*which*the*user*belongs givenName yes the*user's*first*name industry no industries*of*interest*for*the*user jobFunction no location no primary*location*of*the*user's*workplace mail yes email*address memberOf yes the*groups*that*the*user*is*a*member*of>*this*is*used*to*grant/remove*the*administrator*role sn yes the*user's*last*name title no professional*title isDisabled no used*to*power*activation/deactivation*of*Symphony*accounts username yes system*username>*should*correspond*to*SAML*user*ID*if*applicable photo no binary*data*for*avatar*photo photoUrl no url*via*which*the*binary*data*for*the*photo*may*be*retrieved
Each time the files mentioned in steps 13, 14 and 15 (above) are modified, the Directory Bridge must be stopped and restarted using the commands below:
$> $syncroot/bin/stop-sync-server $> $syncroot/bin/start-sync-server
15. Before proceeding, it is highly recommended that all pipes are properly configured. If there is any doubt, please review the “Configuring LDAP Directory Sync” section below. For synchronization of user entitlements in Symphony in particular, before executing the next step we should ensure that LDAP groups are mapped to Symphony entitlements as desired.
Administration Guide – Enterprise / Business Version 93 June 5, 2017
16. Use the file generated in the previous step as an argument to the resync utility, as follows.
$> ./resync --sourceInputFile entriesToSync.ldif --pipe- name "Users to Symphony Sync Pipe"
This will produce information concluding with a status summary similar to the one shown below:
Status after completing all passes
[09/Apr/2015:12:38:10 -0400]
------
Source entries retrieved 18
Entries in-sync 11
Entries dropped due to error 7
Duration (seconds) 25
Resync completed in 25 s.
11 entries were in-sync, 0 entries were modified, 0 entries were created, 0 entries are still out-of-sync, 0 entries are still missing, and 7 entries could not be processed due to an error
As documented in ./resync --help, ./resync log files can be found in $syncroot/logs/tools.
17. Assuming all has gone well up to this point, then we're ready to enable real-time synchronization. Let's do that by turning each of the sync pipes on. The following is an example command that accomplishes this. This command should be run from within $syncroot.
$> ./dsconfig set-sync-pipe-prop --pipe-name "Users to Symphony Sync Pipe" --set started:true
Administration Guide – Enterprise / Business Version 94 June 5, 2017
$> ./dsconfig set-sync-pipe-prop --pipe-name "Groups to Symphony Sync Pipe" --set started:true
18. From this point forward use the command line interface (i.e. $syncroot/dsconfig) to complete your configuration. You can also view the log files to ensure that LDAP Sync is running smoothly. The log files are located in $syncroot/logs.
The Directory Bridge is now running and you can verify that the configuration is working as intended by adding users to your SymphonyUsers group on your LDAP server and verifying that the user is listed in your Symphony Pod. Before doing this, please read the next section.
Account Deletion is NOT Possible Symphony’s LDAP Sync implementation has been designed to be “forward looking.” It cannot for example be used to delete accounts that have already been created. Such accounts should be deactivated rather than deleted and we provide an example below on how to configure ldap-user-deactivation.
A lot of flexibility is provided with the Directory Bridge and supporting utilities. However care has been taken to ensure that the configuration settings described in this chapter prevent the bulk loading of your entire LDAP directory. If this did occur, as we state in the previous paragraph none of those accounts (even dormant ones) could be deleted from Symphony. If this is unclear, please review the installation instructions above (particularly step 10).
Assigning the value used for deactivating or reactivating an account In order to map account deactivation between your corporate directory and Symphony, you need to configure a specific value in directorybridge.properties.
The deactivation value we are using in our example corresponds to the value used by Active Directory: 0x2. Please refer to your LDAP server documentation for the appropriate value used when deactivating accounts in your system.
ldap-user-deactivation-value=bitmask:0x2
Assigning Feature Entitlements When User Accounts are created using LDAP sync, they receive default Pod-wide entitlements set by the Symphony Admin using the Admin Portal (See Feature Entitlement section in this guide). In this section we explain how these default values can be overridden for specific groups of users.
Administration Guide – Enterprise / Business Version 95 June 5, 2017
These examples can be used as references for common LDAP Sync tasks. Please note that corresponding configuration is required on the LDAP Server.
Mapping a group to receive entitlements During the initial configuration steps described above, we explained that entitlements are configured by updating the file groupMappings.json These group mappings are used to configure:
• Roles: SUPER_ADMINISTRATOR, ADMINISTRATOR, SUPER_COMPLIANCE_OFFICER, COMPLIANCE_OFFICER, L1_SUPPORT, L2_SUPPORT - Symphony Roles Available for Mapping to LDAP Groups (Please refer to the Roles section of the Admin Guide for details of what each role can do) • Feature Entitlements: sendFilesEnabled, delegatesEnabled, isExternalIMEnabled, isExternalRoomEnabled, canShareFilesExternally, canUpdateAvatar, canCreatePublicRoom, isScreenSharingEnabled, canCreatePushedSignals • InfoBarrier group membership: Information Barrier ID number as listed in Admin portal. • Disclaimers: The disclaimer should be created in the Admin portal. LDAP sync then uses the disclaimer name to assign the appropriate disclaimers to the end users.
Note: The Screen Sharing feature is currently in customer beta trials. Note that we were previously referring to “External Communications” using an internal code name: “Cross Pod”. We have changed the entitlement name as shown in the list above but will continue to support the previous entitlement name:
New Entitlement Names: isExternalIMEnabled, isExternalRoomEnabled, Replaces: isCrossPodEnabled
We advise customers to move to the new entitlement name in order to avoid unwanted issues if support for the old entitlement name is dropped in the future.
At least one of these two new entitlements must be set for a user to appear in the global directory and be able to communicate externally.
In the example below we are still using the company “Fakecorp” which should be changed to your own company name. We show how to assign two roles: ADMINISTRATOR and COMPLIANCE OFFICER, how to grant the right to send files, how to configure Information barrier group membership and finally how to assign disclaimers. [ { "dn": "CN=ComplianceOfficers,CN=Users,DC=fakecorp,DC=local", "roles": ["COMPLIANCE_OFFICER"] }, {
Administration Guide – Enterprise / Business Version 96 June 5, 2017
"dn": "CN=Entitlements,CN=Users,DC=fakecorp,DC=local", "entitlements": ["sendFilesEnabled"] }, { "dn": "CN=Admins,CN=Users,DC=fakecorp,DC=local", "roles": ["ADMINISTRATOR"] }, { "dn": "CN=IBGroupA,CN=Users,DC=fakecorp,DC=local", "infoBarrierGroups": ["56e700f6e4b088a70f00a1e5"] }, { "dn": "CN=IBGroupB,CN=Users,DC=fakecorp,DC=local", "infoBarrierGroups": ["56e700ffe4b0665dac11e117"] }, { "dn": "CN=Disclaimer,CN=Users,DC=fakecorp,DC=local", "disclaimerName": “Name of the disclaimer” } ]
Configuration Reference This section is provided to help customers understand how the various components of Symphony’s LDAP Sync feature work together and provide details of the various mappings available.
Elements of Configuration
Configuration for LDAP Sync is managed primarily via the following elements: Sync Destinations, Attribute Maps, and Sync Classes. Other elements of configuration should rarely require modification after initial setup: Sync Sources, Sync Pipes.
Sync Destinations
A Sync Destination defines the destination of a Sync Pipe, where changes to be synchronized are applied. LDAP Sync currently features two Sync Destinations; users and user entitlements:
Each Sync Destination takes several arguments. The expectation is that most of these would be pre-populated during installation of LDAP Directory Sync.
A full list of the arguments supported by each Sync Destination follows.
Administration Guide – Enterprise / Business Version 97 June 5, 2017
Sync Destination Arguments
The following table contains Sync Destination arguments that are common to all sync pipes (i.e. users, user entitlements, and distribution lists). These values are configured in the directorybridge.properties file.
Attribute Maps
Attribute maps are used to convert entries in the source LDAP system to entries that can be fed as input to Symphony REST API calls.
Administration Guide – Enterprise / Business Version 98 June 5, 2017
User Attributes
The following image illustrates an attribute map for users.
The full list of "to-attribute" values that are accepted for Symphony users are as follows. attribute(name required description assetClass no name*of*the*asset*class*to*which*the*user's*work*is*related deptName no name*of*the*department*to*which*the*user*belongs displayName yes divName no name*of*the*division*to*which*the*user*belongs givenName yes the*user's*first*name industry no industries*of*interest*for*the*user jobFunction no location no primary*location*of*the*user's*workplace mail yes email*address memberOf yes the*groups*that*the*user*is*a*member*of>*this*is*used*to*grant/remove*the*administrator*role sn yes the*user's*last*name title no professional*title isDisabled no used*to*power*activation/deactivation*of*Symphony*accounts username yes system*username>*should*correspond*to*SAML*user*ID*if*applicable photo no binary*data*for*avatar*photo photoUrl no url*via*which*the*binary*data*for*the*photo*may*be*retrieved Group Attributes
The following screenshot shows an attribute map for groups. This attribute map is sufficient for mapping LDAP groups to both Symphony entitlements and distribution lists.
Mandatory fields in the user attributes mappings file The userAttributeMappings.json file is used to specify which user attributes are synced between a company’s LDAP system and Symphony. If the userAttributeMappings.json file does not contain an entry for an attribute, then that attribute will not be set by Directory Bridge on the Symphony user, regardless of whether the attribute exists on the LDAP entries.
Administration Guide – Enterprise / Business Version 99 June 5, 2017
For Symphony Release 1.46 and above, the customers must add the following three attributes to the userAttributeMappings.json file. { "symphony": "mail", "ldap": "mail" }, { "symphony": "givenName", "ldap": "givenName" }, { "symphony": "sn", "ldap": "sn" } Failure to include the above three attributes will cause two issues:
• No new users will be created • Changes made in LDAP to the mail, givenName and sn attributes for existing users will not be synced
Additionally, for Symphony Release 1.46 and above, it is required that customers include the following in the userAttributeMappings.json file if they want to sync the displayName, title and photo attributes. Prior to Release 1.46, these three attributes were synced by default. { "symphony": "displayName", "ldap": "displayName" }, { "symphony": "title", "ldap": "title" }, { "symphony": "photo", "ldap": "photo" }
Administration Guide – Enterprise / Business Version 100 June 5, 2017
End user management of avatars
Starting with Directory Bridge v1.45.8, admins can continue using the Directory Bridge for LDAP synchronization while allowing end users to manage their avatars. For example, the end users can upload new photos. The Directory Bridge continues maintaining all the other attributes for the user accounts.
Prior versions of the Directory Bridge automatically synchronized the user avatars when the Bridge detected a photo attribute in the sync source. The end users did not have the option of managing their avatars.
The following table shows how the photo attributes in the source and the userAttributeMappings.json file can be combined to create the outcome you want in the Symphony platform.
Attributes in Attributes in Result userAttributeMappings.json Corporate Directory file (source)
There is no entry for the photo Not Applicable. The Directory Bridge will not or photoURL attributes. activate or delete users’ avatars in Symphony. This is the new default setting for v1.45.8 and beyond.
The same attribute is The Directory Bridge will sync present and has a non- users’ avatars in Symphony to
null value. the corporate directory. There is an entry for the photo or photoURL attribute. The same attribute is The Directory Bridge will delete either not present or the users’ avatars in Symphony. has a null value.
Both photo and photoURL Not Applicable. The Directory Bridge will log an attributes are mapped. error and exit at startup.
Warning: Customers currently using the Directory Bridge and managing avatars from their corporate directory must modify the configuration of their Directory bridge when they upgrade to 1.43.8 or a newer version: they must configure an entry for photo or photoURL in the userAttributeMappings.json file.
Administration Guide – Enterprise / Business Version 101 June 5, 2017
Sync Classes
A Sync Class defines how a type of LDAP entry is synchronized. The following image illustrates a Sync Class for users.
Of particular interest here are "include-base-dn", "include-filter", and "attribute-map". The others are covered in detail in the admin guide. "include-base-dn" specifies the base DNs for the branches of the Sync Source that can be in this Sync Class. In the example above, "cn=Users,dc=fakecorp,dc=local" specifies a branch of the directory that will be included for user synchronization. "include-filter" contains a set of filters that define the source entries that should be included in this Sync Class. In the above example, only directory entries that have "person" as a value for the attribute "objectClass" shall be synchronized. For more information about "attribute-map" please refer to the corresponding section of this article.
The following image illustrates a Sync Class for groups.
Administration Guide – Enterprise / Business Version 102 June 5, 2017
Sync Pipes
A Sync Pipe defines how data is synchronized from a sync source to a sync destination. Sync can be turned on/off by toggling the "started" property of sync pipes (see below).
Sync Sources
A Sync Source defines the source of a Sync Pipe, where changes to be synchronized are detected.
External Servers
Sync Sources are defined with references to External Servers. The following image shows an External Server that corresponds to the above Sync Source.
Compliance
Content Export Organizations with strict compliance and information retention policies will already have archiving infrastructure in place. Symphony can be configured to interoperate with these archiving platforms. All messaging, events, and chat room data from your private pod can be exported in an XML format based on the frequency you configure (the default value is 24 hours).
Two approaches to content export have been developed. Originally customers were able to establish to use SFTP to access stored exports in their private pods. While this approach did resolve the short term content export requirements for financial service customers, it was not aligned with Symphony’s customer-controlled encryption key mechanism.
Administration Guide – Enterprise / Business Version 103 June 5, 2017
IP Address White-Listing: You must provide the IP address of the system(s) that downloads the content from the SFTP site – your own system for testing purposes for example and others as required. These IP addresses must be provided to Symphony global services so that they can be registered for access to the SFTP server. You should also configure your firewall to allow the computers used to access your pod’s SFTP server on port 22 (sftp).
More recently, Symphony has introduced a Content Export Bridge which works in conjunction with the on premises Key Manager to decrypted exported content locally. This approach protects the privacy and confidentiality of customer data.
Formats: Three formats are supported, each with a specific advantage, so it is important to understand the difference before making your choice:
Symphony format: This is the default for all pods and has the advantage of including “Read by” information, meaning it tracks who read each message post and when they read the post. The Symphony file is compressed in zip format. Important: Use this format unless you intend to integrate with Actiance Vantage or other equipment/archiving services.
Actiance format — Should only be used by customers using Actiance Vantage equipment. Two XML files are created —one for IM and chats and another for wall posts, these are both provided in a single zip file. No “Read by” information is included.
EML format – is widely used by various compliance and archiving solutions and may help the organization avoid the need to develop a Symphony-specific parser. Content export generates a single Zip file containing EML files for each active conversation. Note1: While it is possible for customers to direct their .EML files directly into compatible archiving systems it must be clear that Symphony is responsible for generating the .EML content export files, not for the ongoing processing of these files. Note2: The maximum size for EML files will be 100MB. Conversations that would normally generate larger file sizes when exported will be delivered in multiple smaller files.
Administration Guide – Enterprise / Business Version 104 June 5, 2017
Frequent Export: You can configure your export to run at a regular frequency, the default value is 24 hours. Starting at 23:59:59 UTC. When programming your download process, please allow enough time (for example, 2 hours) for the export process to complete before beginning your download script.
Manual Exports: You can also generate a manual (Ad Hoc) export based on a date range. We cover this in more detail in a later section.
The first task is to install a host computer for the Key Manager and Software SM.
Installing the Content Export Bridge Only one Content Export Bridge can be connected to your Pod. The Content Export Bridge should have the following characteristics: • 8 GB of memory (see note below) • 4 CPU Cores • 250 GB disk • Operating System: Linux RHEL Fedora 2015.03 (This AWS supported OS has been validated by Symphony) or CentOS 7.1 (used in our example below) • JVM: Java 7 Standard Edition, Enterprise Edition - a Java development kit (JDK) is recommended. See additional instructions for upgrading to TLS 1.2 below. • JVM 64-bit is recommended • CD Drive • Virtual Servers: both on-premises and cloud-hosted are supported
Installing the Java Cryptography Extension (JCE) The default Java7 distribution uses TLS 1.0. Symphony requires TLS 1.2 available with the Unlimited Strength Jurisdiction Policy Files.
Do that by downloading the package from here: http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html
Administration Guide – Enterprise / Business Version 105 June 5, 2017
accept the license agreement and download "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 7” (UnlimitedJCEPolicyJDK7.zip)
Copy this package to the server where you will run KeyManager and unzip it.
UnlimitedJCEPolicyJDK7.zip contains 3 files 1. local_policy.jar 2. README.txt 3. US_export_policy.jar
And override the files in your local java installation. Copy local_policy.jar and US_export_policy.jar to one of the following:
JDK installation: $JAVA_HOME/jre/lib/security
JRE installation: $JAVA_HOME/lib/security
CentOS Installation the Community Enterprise Operating System or CentOS is a Linux distribution that attempts to provide a free, enterprise class community-supported computing platform. We will install the Full ISO image of CentOS version of Linux (v7.1). Note that the full ISO image comes equipped with Java SDK version 1.7 and GNOME. To check the version of Java installed, use the following command.
$:> java –version
Administration Guide – Enterprise / Business Version 106 June 5, 2017
Name the Server and Attach it to your Network The server will now need to be connected your corporate network. Please refer to the instructions available with RedHat or CentOS.
Ensure this machine has access to your Symphony Pod: https://YourSymphonyPod.com/ on port 443.
Install a web browser To simplify the steps required to download and install your CE Bridge, you can optionally install a web browser.
To install the latest version of Chrome, visit https://www.google.com/chrome/browser/ and choose the appropriate installation package: 64-bit version for CentOS in our example.
Type the install command in the terminal and you will see the following screenshot
$:> sudo yum install packagename.rpm
Now enter the password and you will see chrome and the additional dependencies being installed. After the installation is complete, you will see a list of dependencies listed along with the success message.
Administration Guide – Enterprise / Business Version 107 June 5, 2017
Configure the Content Export Account and Download the Content Export Bridge and Tomcat Log in to the Admin Portal and select Export Content. Then select the EXPORT SERVICE ACCOUNT. Select Show Key and copy the resulting security key. This will be used later when configuring the Content Export Bridge.
Note: The Key can be displayed with the “Show Key” button and this should be configured on the Content Export Bridge.
Then click on the Export Clients tab and review (and store) the information shown in step 2.
Administration Guide – Enterprise / Business Version 108 June 5, 2017
…
Then select Download from the left Nav. and download both the Content Export Bridge. This zip file contains the Content Export Bridge RPM (This includes Tomcat). Once you have unzipped this file you can then follow the instructions below.
Option 1: CE Bridge standard installation
Installing Tomcat and establishing trust relationship with Symphony Some organizations may prefer to use an internally approved version of Tomcat. We provide instructions for installing the CE Bridge combined with your own version of Tomcat in the next section. Customers should contact Symphony Global Services to ensure that the internally approved version is compatible with the Content Export Bridge. Warning: it is not currently possible for the CE Bridge to use the same Tomcat library as the Key Manager (see earlier section). Install tomcat with the following command:
$> sudo rpm -ivh tomcat-8.0.24-18.x86_64.rpm
Administration Guide – Enterprise / Business Version 109 June 5, 2017
If you prefer to use a previously installed version of Tomcat please make the following changes:
catalina.home = /opt/tomcat
catalina_base = /data/tomcat
Configuring tomcat Please edit the Tomcat environment.sh file and customize it for your specific installation. This file is identical to the environment.sh file used by the Key Manager and certain lines highlighted below will need to be deleted. Please carefully review the example file below.
$> vi /data/tomcat/conf/environment.sh
#!/usr/bin/env bash DATA_BASE="/data/tomcat/" CATALINA_BASE="/opt/tomcat/" JAVA_HOME="/usr/java/jdk1.7.0_79" //Update with your java path CATALINA_OPTS="-server -Xms5048m -Xmx5048m -XX:MaxPermSize=256m \ -Djava.util.logging.config.file=$CATALINA_BASE/conf/logging.properties \ -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager \ -Dlog4j.configuration=file:$DATA_BASE/config/log4j.xml \ -Djava.endorsed.dirs=$CATALINA_BASE/endorsed \ -classpath $CATALINA_BASE/bin/bootstrap.jar:$CATALINA_BASE/bin/tomcat-juli.jar \ -Dcatalina.base=$CATALINA_BASE \ -Dcatalina.home=$CATALINA_BASE \ -Djava.io.tmpdir=$CATALINA_BASE/temp \ -Dsession.cookie.domain=.pubmy.mykeymanager.com \ -Daccess.control.allow.origin=podId.yourdomain.com,keymanager.yourdomain.com \ // pls change the first value to your domain url, and the second value to your on-prem keymanager -Djava.library.path=$CATALINA_BASE/native/ \ // The crypto lib compatible with your os version -Djavax.net.ssl.keyStore=$DATA_BASE/certs/keystore \ // we create an empty keystore for you, please make sure you replace this when you deploy to production -Djavax.net.ssl.keyStorePassword=password \ // and your keystore password -Djavax.net.ssl.trustStore=$DATA_BASE/certs/truststore \ //delete this line for CE Bridge -Djavax.net.ssl.trustStorePassword=changeit \ //delete this line for CEB -Dcom.symphony.keymanager.sdk.maxtotalconnections=2000 \ //delete this line for CEB -Dcom.symphony.keymanager.sdk.maxconnectionsperroute=1000 \ //delete this line for CEB -Dserver.bot.port=8444 \ //delete this line for CEB -Dserver.port=8443 \ -Dajp.port=8009 \ //delete this line for CEB -Dserver.command.port=8005 \ //delete this line for CEB -Dmax.threads=4000” \ -Dhost.name=change.it.to.full.server.host.name" //delete this line for CEB -Dceb.config.path=/opt/tomcat/symphony_cecs \ //optional, the folder containing the
Administration Guide – Enterprise / Business Version 110 June 5, 2017
configuration.prepertites and key folder -Dproxy.uri=http://proxy.com:8080"// this is the default, please add it if you use a proxy in your environment, and this proxy should support https requests PATH=$JAVA_HOME/bin:$JAVA_HOME/bin/jre:$PATH //ENDS
Next you will need to create a Tomcat keystore with the same name we assigned in the script above “keystore”:
$> keytool -keystore keystore -genkey -alias tomcat -keyalg RSA
When installing the password used to trust the Symphony cert you will be prompted for the cert password please contact Symphony Global Services to obtain this password. Now establish the trust relationship with Symphony:
$> sudo openssl s_client -connect podID.symphony.com:443 symphony.cert
$> sudo keytool -importcert -trustcacerts - keystore $CATALINA_BASE/certs/keystore -file symphony.cert -alias symphony
If you previously installed the key manager, please also trust the certificate from your key manager.
$> sudo openssl s_client -connect podID- keymanager.symphony.com:443 keymanager.cert
$> sudo keytool -importcert -trustcacerts - keystore $CATALINA_BASE/certs/keystore -file keymanager.cert -alias keymanager
import symphony public key
$> sudo rpm --import https://resources.symphony.com/SYMPHONY-GPG- KEY.public
Administration Guide – Enterprise / Business Version 111 June 5, 2017
Install the Content Export Bridge Locate the Content Export Bridge RPM file downloaded earlier and begin the installation:
$> sudo rpm -ivh --prefix=/opt/tomcat --replacefiles symphony- external-ceservice-centos70-0.14.0-45.x86_64.rpm
Note: the file name in the previous command will need to be the same as the RPM file downloaded from the Symphony Admin Portal. Please use the latest version.
Update the configuration.properties file located in $catalina.home/symphony_cecs, in our configuration it is located in: /opt/tomcat/symphony_cecs. The value for shared key is the Security key generated in the previous step.
# Information for pod access
version=1.0.0
podURL=https://YourSymphonyPod.com
sharedKey= ThisIsYourSecurityKey
archiveDirectory=/data/retention_result
Create the local directory to store exported content with ownership tomcat.tomcat with the following two commands:
$> sudo mkdir /data/retention_result
$> sudo chown tomcat.tomcat /data/retention_result
Option 2: CE Bridge Installation using a separate version of Tomcat
Using an existing Tomcat and establishing trust relationship with Symphony The first part of this section describes how to install a separate (approved) version of Tomcat. Customers who have already installed Tomcat can skip to section 7 below. We assume that Java has already been set up (eg: sudo yum install java).
1. Download sample tomcat http://mirror.cc.columbia.edu/pub/software/apache/tomcat/tomcat- 7/v7.0.63/bin/apache-tomcat-7.0.63.zip
2. Unzip the package
Administration Guide – Enterprise / Business Version 112 June 5, 2017
Assuming you already set up unzip (otherwise: $> sudo yum install unzip) $> sudo unzip -d [tomcat folder]
3. Add permission $> cd [tomcat folder]/bin $> sudo chmod 755 *.sh
4. Create setenv.sh under bin folder containing the following information:
#[correct it if needed! It should be the tomcat folder] CATALINA_BASE="/tmp/tomcat/" #[correct it if needed! It should be the jdk folder] JAVA_HOME="/usr/lib/jvm/jre/" CATALINA_OPTS="-server -Xms1024m -Xmx2048m -XX:MaxPermSize=256m \ -Djava.util.logging.config.file=$CATALINA_BASE/conf/logging.properties \ -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager \ -Djava.endorsed.dirs=$CATALINA_BASE/endorsed \ -classpath $CATALINA_BASE/bin/bootstrap.jar:$CATALINA_BASE/bin/tomcat- juli.jar \ -Dcatalina.base=$CATALINA_BASE \ -Dcatalina.home=$CATALINA_BASE \ -Djava.io.tmpdir=$CATALINA_BASE/temp \ -Djava.library.path=$CATALINA_BASE/native/ " PATH=$JAVA_HOME/bin:$JAVA_HOME/bin/jre:$PATH
5. Create the tomcat user and tomcat group
$> sudo useradd -U tomcat
6. Start Tomcat for your Content Export Bridge (CEB)
$> sudo ./startup.sh
7. Install Content Export Bridge rpm
If you already have a working Tomcat configuration, you can start here. First log into the Symphony Admin portal and select Download from the left Nav. and then select the Content Export Bridge rpm file.
Unzip the file and install the rpm (the rpm filename may have a different version number than the one shown below and prefix refers to the tomcat path)
$> sudo rpm -ivh --prefix=/opt/tomcat --replacefiles symphony- external-ceservice-centos70-0.14.0-45.x86_64.rpm
configuration properties
Administration Guide – Enterprise / Business Version 113 June 5, 2017
Information for pod access version=1.0.0 podURL=https://
Local directory to store exported content, please create this directory with ownership tomcat.tomcat Using the command below:
$> sudo chown tomcat.tomcat /data/retention_result
The security key used by the Content Export Bridge to authenticate with the Symphony service can be obtained from the Content Export option in the Admin Portal. We provide instructions on how to obtain this key in a previous section. archivedDirectory in the previous command refers to the location where you will be storing your export files.
Create the retention directory from the one you configured above
$> sudo mkdir /data/retention_result $> sudo chown tomcat.tomcat /data/retention_result
Once installation is complete, you will see a new symphony_cecs folder under tomcat catalina.home
Managing and Upgrading the Content Export Bridge You can start the Content Export Bridge using the following command:
$> sudo service tomcat start
At this point the CE Bridge should be running, you can check whether this is the case by running:
$> sudo service tomcat status
You can stop tomcat with the following command:
$> sudo service tomcat stop
To upgrade the Content Export Bridge:
Administration Guide – Enterprise / Business Version 114 June 5, 2017
Log into the Admin Portal and download the latest CEB distribution using the DOWNLOADS option in the left Nav.
First stop the CEB: $> sudo service tomcat stop
Then upgrade using the RPM file downloaded from the Admin Portal: $> sudo rpm -Uvh --prefix=/opt/tomcat --replacefiles single- cecservice-0.0.1-0.x86_64.rpm
and then start the Content Export Bridge again:
$> sudo service tomcat start
To uninstall the Content Export Bridge:
$> sudo rpm -e cecservice
Enabling Content Export The export process is activated by selecting CONTENT EXPORT in the Admin portal. You will be guided through the creation of a dedicated SFTP user account for accessing your SFTP server. To enable content export from the admin portal:
• In the left navigation panel, select CONTENT EXPORT. The Configure Content Export window appears.
Administration Guide – Enterprise / Business Version 115 June 5, 2017
• Click Enable Content Export.
Enabling SFTP Content Export Legacy installations may still be using the SFTP export process. Select SFTP and he content export feature will be enabled and the preset password for the SFTP account will be displayed.
Administration Guide – Enterprise / Business Version 116 June 5, 2017
• To change the password, in the Configure Content Export window, click Reset Password. • The Reset your content export password popup appears.
• Enter the new password or click Generate. • Remember to copy the generated password (press ctrl+c). • Click Submit to confirm the password change.
Recurring Export You can program content export to run at a regular frequency. The default value is 24 hours starting at 23:59:59 UTC. You can also select which format you want to use: Symphony (which contains Read-by information), Actiance, or EML format – see the screenshot below:
You can change the export setting to run more frequently than every 24 hours using the drop-down box. It is important to understand that these settings are relative in that you will get different results depending on when you decide to change the frequency and also, when an export was last run. Here are some examples:
1. It is 03:00 hrs. UTC and you change export frequency from 24 hours to 2 hours. In this case a first export will immediately run and will contain 2 hours worth of information (up to 02:00 hrs. UTC). Your next file will be created at 04:00 hrs UTC. 2. It is 07:15 hrs. UTC and you change export frequency from 24 hours to 2 hours. In this case three exports will be triggered, one for:
Administration Guide – Enterprise / Business Version 117 June 5, 2017
a. 02:00 hrs. UTC b. 04:00 hrs. UTC c. 06:00 hrs. UTC the next job to run would be at 08:00 hrs. UTC 3. Now lets make things a bit more complex. Imagine I work in New York and I actually want my exports to run with a frequency of 24 hours at midnight New York time, which corresponds to 05:00 hrs. UTC. To accomplish this, I make two changes: a. At 23:05 hrs. UTC (18:05 hrs. ET) I set the frequency to 6 hours – this will cause an export to run at 05:00 hrs. UTC (midnight in New York) and it will contain 6 hours of data. b. At 07:05 hrs. UTC (02:05 hrs. ET) I set the frequency to 24 hours. This second step will cause a 24-hour content export to run every night at midnight in New York. The previous 6-hour frequency is cancelled and replaced with this new schedule.
Important: In this third example, I waited the extra two hours in order to let the 6-hour job to complete because the Symphony scheduler requires the previous job to have successfully completed in order to book a new start time that uses the previous job’s end time (in our case midnight in New York).
In this third example we have illustrated:
1. How smaller frequencies can be used to move the start time to a later time 2. How partial exports can be interrupted mid-way to reset the start time to the last completed export time
Manual Export (AD-HOC) You can run a manual (AD-HOC) export based on a date range (see screenshot below) and as for frequent export, you select either: Symphony (which contains Read-by information), EML or Actiance format. Next, select the start-date and end-date for your export – dates will be shown in mm/dd/yyyy format. The times used will be 23:59:59 UTC to 23:59:59 UTC of the next day. It is important to recognize that the use of UTC may cause unanticipated difference in the way data is retrieved.
Rule 1: Dates are always based on 24hrs starting and finishing at 23:59:59 UTC Rule 2: No partial days are retrieved – information from the current day will be retrieved only after 23:59:59 UTC of the current day, this corresponds to 6:59:59pm ET.
This means that when testing the feature, admins in New York should enter test data leading up to 7pm ET and then run manual exports at 7pm ET onwards in order to see their test records in the manual export. When ready, press Start Manual Export. The export will be loaded into your SFTP content export site. Access the information using the machine with the IP address you registered with Symphony Global Services.
Administration Guide – Enterprise / Business Version 118 June 5, 2017
Note: There is currently no facility to cancel the export jobs that are running; however, the export jobs that are waiting in the queue can be canceled.
File names
AD HOC file names the zip file name will be,
In EML format, it will be
In Symphony format, it will be
File Names for frequent export
For Actiance format, it will be:
In EML format, it will be:
Administration Guide – Enterprise / Business Version 119 June 5, 2017
The reason that there is no hour in EML format individual file is that, the stream conversation can be very short, e.g. few minutes.
In Symphony format, it will be:
• The Manifest of all the .EML files in the .ZIP file o Total number of EML files o List of EML files with the number of records (messages) in each • A hash file for the zip file: .MD5 • Multiple .EML files: streamType_StreamID-
Example of zip and md5 file names: e_xyz-na-prod-chat-glb-1_SD-2015-10-25-00_ED-2015-10-26-00_GD-2015-10- 26_1445817600518.zip.md5 e_xyz-na-prod-chat-glb-1_SD-2015-10-25-00_ED-2015-10-26-00_GD-2015-10- 26_1445817600518.zip
Content Export Verification
Content Export includes an option entitled EXPORTED FILE LOG that will list each content export and flag any error that might have occurred with each export. The checks currently performed include:
• the zip file is not corrupted, • all content is included in the export, • content is decrypted.
The screen shot below shows the EXPORTED FILE LOG option:
Administration Guide – Enterprise / Business Version 120 June 5, 2017
Accessing the exported SFTP repository For legacy installations, the downloaded file is stored on an SFTP server using a similar name structure to other servers described in this document: e.g.
Actiance Vantage with SFTP This equipment does not currently support SFTP and therefore an intermediary script, running on another system, will need to be configured to download the Actiance zip file and place it in a location where the Actiance Vantage can access it. In this case, it is the intermediary server running the script that should be whitelisted to use port 22 on the firewall and its IP address should be provided to Symphony Global Services so that it can be whitelisted - see diagram below.
Allowed%IP% Addresses% 22% SFTP% ZIP% Server% Files% % Symphony% Access%Control%
Administration Guide – Enterprise / Business Version 121 June 5, 2017
Exported Content The timestamp used for content export is in the form HH:MM:SS:mm where mm represents milliseconds. The following information is exported:
New messages A message may be created in an IM conversation, chat room or a wall post. If a message was posted within the time range (24 hours), then it's considered a new message. The following data is provided in the Symphony export file:
• Attachments • SentTo: • for IM & chat - members of an IM/Room; • for Wall post - owner of the wall • ReadBy: • List of users who have read the message within the time range
When a message is being sent to an external user (a user located on a different Pod) then the message manifest will include the first name, last name, email address and company name of the external user.
Old messages A message may have been sent to an IM conversation, chat room or a wall post. Old messages are messages that were created before the current 24-hr time range. Symphony tracks who read the message during the time range and sends the “Read by” information that relates to those read events. Previously reported “Read by” information is not repeated, only the new “Read by” information. The following data is provided:
• Attachments (any kind of file) • ReadBy: list of users who have read the message within the time range
Events The following events are also included if they occurred within the time range (24 hours):
• Create room • Activate room • Deactivate room • User join room • User leave room • User in room is promoted to owner/demoted from owner
Administration Guide – Enterprise / Business Version 122 June 5, 2017
• Room setting update for the following settings:
o Room Name o Room Description o Type of room (private / public) o Copy Enabled o Read Writable o Member Invitations o Search
• Message is shared (wall post only) – includes any posted attachments • Message is deleted (wall post only) – original message is also included • Like a Message (wall post only) – original message and any attachments are also included • Share a Message (wall post only) – original message and any attachments are also included • Chimes • Email notification was sent either by the sender or by the system • Message suppression events
Content Export for Rich Text Editing Users have the option to highlight their posts and IMs using rich text editing. This highlighting can include bold, italics and bullets. Pasted content may also be handled as an attachment rather than native text. In either case, content export will include this markup in the content export. We show an example of the markup that would be included in the export.
Escaped Characters The Symphony client encodes rich text such as bold, Italics and bullets using a standard markdown syntax. For example, if the user inserts rich text as follows:
• testing bold, italics and bullets
Administration Guide – Enterprise / Business Version 123 June 5, 2017
then in the xml content export, this is translated to:
If on the other hand, the user types a message containing the ‘*’, ‘-‘ or ‘_’ characters, then these will be encoded with an escape backslash in the content export file. Original text entered by the user:
testing asterisk *, dash - and underscore _ converted as follows in the XML version:
Content Export Self-Healing (CESH) CESH helps provide timely delivery of content to compliance and surveillance teams. CESH also minimizes the amount of troubleshooting expected of customers for content export errors. CESH enables timely exports of messages by: • Limiting the re-export to messages that encountered errors during the initial content export runs. • Automating the re-export of relevant messages at the next regularly scheduled content export run. • Equipping the Symphony customer service team with diagnostic tools to ensure all messages are either exported or otherwise accounted for. CESH features are applicable to regularly scheduled jobs, not to ad-hoc jobs. The following table describes the CESH changes in Content Export Bridge (CEB) v1.44.2 or newer version.
Category Change Customer Action
CEB eliminates the content export verification Customers parsing this file must update their file result.JSON. script when they upgrade to CEB v1.44.2 or newer version. Content export verification Changes to the validation.JSON file: Customers parsing this file may need to update their script when they upgrade to CEB Includes a new section for the list of messages - v1.44.2 or newer version. that CEB is exporting via the CESH feature. See below for more details.
Administration Guide – Enterprise / Business Version 124 June 5, 2017
- Decryption exceptions are no longer listed. Symphony customer service team will automatically investigate the exceptions, and take appropriate action such as eliminating false positives, or contacting the customer if needed. Re-run CEB will automatically re-export internally No need to manually re-run the content export content flagged messages. job when the CEB returns errors related to export to fix message exports. errors
The Message_counts.csv file will continue None. Message counting messages for the current retention counts period, and not include messages exported by CESH.
The CEB will create a separate EML file for Please be aware whenever CEB re-exports a each stream/room per job. For example, if on record in this way, the content export will show day X the CEB exports content from stream 1 it as: “Record re-exported” and re-exports content from stream 1 of days CEB identifies the re-exported content with a X-5 and X-8, it will create three eml files for - EML new x-header “x-symphony-ReExported” stream 1: one each for content from days X, X- content which is set to the unique ID of the job used to 5, and X-8. exports re-export the message; for example “x- symphony-ReExported: 2ee1a48e-d364-46da- 85c2-82709977f50b” A new x-header in EML files will list any re- - To work with the Global Relay de-duping logic, exported content. the CEB extends the email subject string to show the date and time as follows: exported 1/1/2016 00:00:00 GMT CEB v1.44.2 uses v1.5.1 of the Symphony Customers tracking this version of the XML Symphony XML Schema which adds an optional attribute, may need to update their post processor when XML "isReExported=true", in "record" node if the they upgrade to CEB v1.44.2 or newer version. schema record is flagged for re-export.
Format of the catchup section in the validation.JSON file: "catchup": { "346900e3-26a3-431b-9512-96073b46fa08": { "jobId": "346900e3-26a3-431b-9512-96073b46fa08", "exported": { "hkyIKihCmckkwFjKd3JSO3///qYzXIcSdA==": [ "Pw/BiiVemSleVt58WGU3/n///qYzXEGpdA==" ], "ZJFUFpq1VQVmSvPk+T+kz3///qYzXI4wdA==": [ "coaIcw/xZZR2MkLshIGUIn///qYzXEK7dA==", ] } }, "a4c0d151-7cb0-4d45-b19a-4711cb6c9512": {
Administration Guide – Enterprise / Business Version 125 June 5, 2017
"jobId": "a4c0d151-7cb0-4d45-b19a-4711cb6c9512", "exported": { "hkyIKihCmckkwFjKd3JSO3///qYzXIcSdA==": [ "2yqof0mEReIPK5BsU3Bu53///qYzXILgdA==" ], "ZJFUFpq1VQVmSvPk+T+kz3///qYzXI4wdA==": [ "eSDHBOfc4APzVP8SVpUZnX///qYzXImidA==", "p/ZX4ujBfiFBExU3c4us0X///qYzXIhRdA==" ] } } }
In this example, the catchup section indicates content was re-exported for 2 previous scheduled jobs (e.g.: "jobId": "346900e3-26a3-431b-9512-96073b46fa08" and "jobId": "a4c0d151-7cb0-4d45-b19a- 4711cb6c9512"): For each job, the json element shows the list of streams and for each stream the list of messages re- exported for that stream (e.g.: message ID "2yqof0mEReIPK5BsU3Bu53///qYzXILgdA==" in stream ID"hkyIKihCmckkwFjKd3JSO3///qYzXIcSdA==")
External Communications
When a message is being sent to an external user (a user located on a different Pod) then the message manifest will include the first name, last name, email address and company name of the external user.
Timestamp The timestamp used for content export is in the form HH:MM:SS:mm where mm represents milliseconds.
Wall Post Information
Complete information is now included for wall post events as shown below:
• Message is shared (wall post only) – includes any posted attachments • Message is deleted (wall post only) – original message is also included • Like a Message (wall post only) – original message and any attachments are also included • Share a Message (wall post only) – original message and any attachments are also included
Administration Guide – Enterprise / Business Version 126 June 5, 2017
“From header” in EML export
Sets the “From header” to be the email address of the first person to either post content or create an event in a chatroom or IM in a given retention period. For example, the first action in a given retention period may be the creation of the IM or room or may be the addition of a member, etc. in such a case, the individual user who took that action. This might be the creator of the chatroom or a member who posted something to the room.
Note: the event could be from a service account that is not a member of the room (from S39 onward) since the room membership may be managed via the chat room provisioning APIs
Recording Wall Post Likes The email addresses of all users who “Liked” a post are shown in the “To List” in all formats.
Tracking of blastID in all formats
Include the blast ID with each exported blast message. This applies whether the blast was created by an internal account or created by an external account.
EML format: When exporting a blast message created by an internal account, include the blast ID as follows:
• 2016-03-19T20:43:09.080Z [email protected] says • test message M1 • Message ID: 3Kxt+IKF+KO4a1Ei4u/Gln///qvlXj1QdA== • BlastID: 7696581424657
Symphony XML: when exporting a record for a blast message created by an internal account, whether as a new message or an archived=True message, include an element listing the blastID. For example:
Actiance Format: adds the blastID to the content export as follows:
Administration Guide – Enterprise / Business Version 127 June 5, 2017
Note: this only applies to blasts created using the Sprint 38+ version of blasts.
Exporting shared articles CEB exports shared articles using HTML in all 3 formats. Older versions of the CEB export shared articles using JSON. The use of HTML allows the surveillance team to view the shared article in the same format as the format originally presented to the user.
Content Export Verification A file entitled results.json is included in each content export and will include the value “SUCCESS” if:
1. Download was successful 2. Decryption was successful 3. File matched what was sent
This file no longer exists once the CEB is upgraded to v1.44 or greater. Refer to the information in the Content Export Self-Healing section above for more details.
User Summary Information A file entitled Message_Counts.CSV is now included in each content export and shows summary usage data for each user on the Pod.
Obtaining Historical Data On the day that CONTENT EXPORT is activated all the content for the 24-hour period (23:59:59 UTC – 23:59:59 UTC) will be included in the first run of the procedure initiated at 9am UTC. This does not include any historical data generated prior to the day of activation.
It may be possible for Symphony Global Services to generate historical data on behalf of early stage customers if required. Contact Symphony Global Services if you need to generate historical data.
Active Compliance Compliance features are listed in the left Nav:
Administration Guide – Enterprise / Business Version 128 June 5, 2017
Expression Filters Companies will enforce expression filtering to reduce the risk of their employees generating inappropriate content and thus potentially impacting the reputation or compliance of the company. One example is profanity filtering.
First select Expression Filters from the left Nav. and you will be presented with the Dictionary Management interface.
This interface uses simple expressions as well as more complex regular expression rules. You can edit an expression by checking the relevant box to the left of the expression and then pressing the “edit” pen located to the right of the expression:
Administration Guide – Enterprise / Business Version 129 June 5, 2017
You can then enter a regular expression. Please note that expression filters are powerful and you run the risk of introducing unexpected filtering if you’re not careful. We strongly recommend that you test your regex to ensure your expression works as you intend.
Example: If the admin were to include the following keyword /dang/ then the result would be that words such as “dangerous” would be blocked and this may not be the desired behavior. Please structure regular expressions carefully to avoid undesirable results.
Words loaded without regex syntax will be interpreted as follows: /\sdang\s/ in other words we assume leading and trailing spaces. Admins seeking to be absolutely sure of the behavior of their expression filters should use regex syntax and test carefully.
Symphony supports JavaScript Regex syntax. Please refer to the following resource for more information: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
Filtering Using Unicode Unicode characters can be entered as regular expressions. For example, the expression to filter a Unicode character 877e would be: /[\u877e]+/
Audit Trail for Expression Filters The compliance officers can view an audit trail showing whenever expression filter rules were updated. In addition, the compliance officers can now view an audit trail showing whenever the expression filter (EF) policy was enforced.
Information Barriers Control internal information flow between groups of users in order to avoid inappropriate communication and collaboration that could result in compliance violations.
Use the Admin Portal to create internal boundaries between groups. Usage:
First create an IB Group by clicking GROUP MANAGEMENT, and then selecting Create an IB Group, as shown below:
Administration Guide – Enterprise / Business Version 130 June 5, 2017
Assign users to the group by searching for them in the Membership window.
Activate Block Policy between groups as follows.
Select POLICY MANAGEMENT, and click on Create IB Policy:
Administration Guide – Enterprise / Business Version 131 June 5, 2017
Block members of the IB group from communicating with another group:
Chat Room Remediation When the owner of a room is removed because of a new Information Barrier policy or because of a change to their external communications entitlement. The room will continue after the lone owner is removed by promoting the oldest member who is free of an IB or Entitlement constraint to owner.
Administration Guide – Enterprise / Business Version 132 June 5, 2017
Disclaimers Admins and later compliance officers can configure warning messages to be displayed following specific user actions – at this time, this is when users communicate with external users. Disclaimers can contain up to 1,500 characters.
To create a disclaimer, select DISCLAIMER INSERTION from the left Nav. Disclaimers can be set for individual users. This is accomplished by first creating a named disclaimer and then assigning the named disclaimer at the user level.
A disclaimer can be set to display based on a specific number of days: every two day etc. Setting this value to ‘0’ will cause the disclaimer to be displayed every time the user posts a message externally.
Audit Trail for Disclaimers Allows the super administrator to view all the changes made to any disclaimer in the pod.
Administration Guide – Enterprise / Business Version 133 June 5, 2017
The super administrator can also select a specific disclaimer and view the changes to that disclaimer, as shown below:
List ALL ROOMS and Monitor The Super Compliance Officers and the Compliance officers can use the All Rooms option in the left Nav. to display a list of rooms created by their users. The table includes a Scope tab showing either Internal or External, Member count, whether the room is enabled, the company that created the room and the room creator as well as basic information about activity and status (see the screenshot below for the complete list). More complete searching and sorting options will be delivered in a later release.
Monitoring The SCO and CO’s with appropriate entitlement will be able to display a room or wall post (per user) and monitor it in real time. First select ALL ROOMS from the left Nav (see above). Then display the room details by clicking on the room from the list and selecting the Monitor Room button located top right of the room details (shown in the screenshot below).
Administration Guide – Enterprise / Business Version 134 June 5, 2017
Here is an example of a room monitor in progress:
Session Log SCO and CO’s will be prompted to provide an explanation for their session and the description and relevant statistics related to the session will be logged and searchable in the audit trail.
Administration Guide – Enterprise / Business Version 135 June 5, 2017
Select SCO/CO SESSION LOG and a list of logins will be displayed as shown below:
Select the username and then Audit Trail from the user detail screen. Each login will be accompanied by an explanation based on what was entered when the compliance officer logged in.
The Symphony Platform This section is an extract from information provided on the Symphony developer site:
https://developers.symphony.com
REST API
The Symphony REST API lets you build tools and applications on top of Symphony's secure messaging platform:
Administration Guide – Enterprise / Business Version 136 June 5, 2017
• Use the Pod endpoints to build tools to manage Symphony for your organization. Pod API endpoints don't require encryption or decryption of content and include operations such as managing chat rooms or users.
• Use the Agent endpoints to build applications that send and receive messages and content. Agent API endpoints require an on-premises Agent installation to encrypt and decrypt content.
Agent Installation
The Agent server can be downloaded from the developers.symphony.com and requires:
• Centos 6.5 and 7.0 (update 80)
• Java 7
• Tomcat 8.0.26
• Atlas configuration (instructions provided)
Other Prerequisites
The Agent will be installed as part of an operational Symphony service where a certificate- based trust relationship has been established between your dedicated Symphony cloud service and your Key Manager.
In the diagram below, we show the various elements included in the certificate-based trust infrastructure. Two naming conventions for their dedicated Symphony services are available for customers:
1. MyCompany.Symphony.com 2. Symphony.mycompany.com and the approach for generating certificates is specific to the domain name option selected:
Administration Guide – Enterprise / Business Version 137 June 5, 2017
On the Agent server, install:
A. Root cert for the pod (scenario 1 or 2) added to the Trust Store B. The Key Manager's root cert (preferably from an external CA) in the Trust Store C. The Agent's Server cert added to the Agent's Key Store - obtained from internal PKI
Administration Guide – Enterprise / Business Version 138 June 5, 2017
The commands below can be used to install the certificates on the Agent server. The first command is used for adding A and B (from the diagram above) to the Trust Store and the second command is used for adding C to the Key Store:
$> keytool -importcert -trustcacerts -keystore /data/tomcat/certs/truststore -file
YourFile.CRT -alias pod -storepass changeit
$> keytool -genkeypair -keyalg RSA -alias 1 -keystore
./atlas/symphony/global/certs/server.keystore -storepass changeit -validity 730 -keysize
2048
Configuring the Agent Application Follow the three steps below to configure your Agent app on your pod: Step 1: Install a root signing cert for your app
Step 2: Create a service account for the app using the Admin Portal
Administration Guide – Enterprise / Business Version 139 June 5, 2017
Step 3: Configure certificates on the App host A. install root certs for the pod (scenario 1 or 2) in the Trust Store of the Bot. B. Install a Client Type cert in the Key Store of the BOT - obtained from internal PKI CA
Administration Guide – Enterprise / Business Version 140 June 5, 2017
The commands below can be used to install the certificates on the Agent app host machine. The first command is used for adding A (from the diagram above) to the Trust Store and the second command is used for adding B to the Key Store:
$> keytool -importcert -trustcacerts -keystore /data/tomcat/certs/truststore -file
YourFile.CRT -alias pod -storepass changeit
$> keytool -genkeypair -keyalg RSA -alias 1 -keystore
./atlas/symphony/global/certs/server.keystore -storepass changeit -validity 730 -keysize
2048
Client Extension API (JavaScript) The Client Extension API lets developers extend the functionality of the Symphony client by creating standalone applications. It also includes methods for adding items to the left navigation and adding buttons and interactions to the user interface.
Managing Applications Symphony provides APIs for Extending and Enriching the symphony experience with new functionality and 3rd–party content. Three partners (Dow Jones, S&P Capital IQ and Selerity) are currently providing free versions of their applications to Symphony users and these as well as any in-house applications developed using the Symphony API’s can be activated using the APP MANAGEMENT option located in the left Nav of the Admin Portal.
Installing a New Application To install a new in-house application, first select APP MANAGEMENT from the left Nav of the Admin Portal – see screenshot below.
You are presented with a list of currently installed applications. To add a new application to this list, click on the Add Custom App button. Symphony will present the following form (fields marked with stars are required):
Administration Guide – Enterprise / Business Version 141 June 5, 2017
Provide a name for your application and then provide the URL for the iFrame containing the app. This URL must be reachable from the network used by your target users.
Provide the name of the developer and then provide a domain restriction for your app. This is the domain name portion of the URL provided above and is a preliminary security feature used to prevent cross-site scripting – additional protections will be incorporated in the future.
You can also optionally provide a description as well as the location of an image to be used as an icon in the app store. This is the image users will see when they use the application inside Symphony.
Once you are satisfied with the information provided for your application, press Add and this application will be added to your list.
Application Entitlement The next step is to entitle your users to see, install and use the application. The steps described in this section are also applicable to 3rd-party applications such as the ones described at the beginning of this section. You can either manage App Entitlement for all users at once (system-wide settings) or at the individual user level.
Administration Guide – Enterprise / Business Version 142 June 5, 2017
To manage at a system-wide level either click on the APP SETTINGS screen (see screenshot below)
Global Status is used to set the application to Enabled or Disabled. This setting is the entry point for the release of the application to users in your organization. If the application is Disabled then users will not be able to see, install or use the application. Visibility (Visible or Hidden) determines whether users can see the application in their App Stores. Installation determines whether the application is Automatically installed for all users or whether it must be installed by users themselves: Manual. If Manual is set, it is still possible to fine tune this setting for specific users using individual Applications option within the User Detail screen shown below:
In this case, setting the Installation option to Installed will install the application for this user, otherwise if the application is set to Visible but the Installation field is set to Not Installed, then this user has to select Add from the App Store, see screenshot below:
Administration Guide – Enterprise / Business Version 143 June 5, 2017
Application Subscription Management Once an application partner has registered a premium app, it can be allocated and installed for users by the Pod Administrator. Users will either see the new app in the Symphony Market (Symphony’s application hub) from where they can install it, or the admin may prefer to have it installed automatically for their users. This can be configured using the APP SETTINGS option in the left Nav. of the admin portal.
Administration Guide – Enterprise / Business Version 144 June 5, 2017
In the screenshot below, we show a list of APPLICATIONS being assigned to a specific user. Standard applications are free, whereas Premium applications require a subscription.
When using the APP MANAGEMENT option, the admin can also display their current balance: • Licenses used • Licenses remaining (balance) • Total Licenses (used and remaining)
Audit trails are available to track when applications are assigned to users. The following events are tracked:
• App enabled/disabled • Licenses granted/removed for a product • App installation changed - automatic/manual • App visibility changed - visible/hidden
The audit trail displays, for each event:
Administration Guide – Enterprise / Business Version 145 June 5, 2017
• Date of event • Initiator (internal user, or publisher) • Product impacted • User impacted (for installs and subscriptions)
BULK MANAGE ACCOUNTS (CSV Import)
You can use the BULK MANAGE ACCOUNTS option to make changes to or add multiple users at once. In this section we provide the information you need for creating CSV files and managing the upload process.
Overview Here’s a quick summary of the steps you’ll use:
1. Select the BULK MANAGE ACCOUNTS option. 2. Obtain the CSV template. 3. Load the CSV file into a spreadsheet or other editor. 4. Enter user information in CSV format. 5. Save your updates (be careful to save as a CSV file). 6. Drag and drop your CSV file into the drag and drop zone on the Symphony Admin portal. 7. The CSV file will be validated. 8. Press Import. 9. A further verification will be carried out on the file contents. 10. View the report and fix any errors encountered.
Get the CSV template To help you set up the column headings of the CSV file correctly, we provide a CSV template file for you to download. The first time you do this, you may want to see the empty version. Later on, you will always pre-populate the file with your current user definitions. This is the best way to ensure you have the latest profile information for your users. Remember multiple admins may be making changes.
• Select BULK MANAGE ACCOUNTS on the Admin portal and you will see the screen below. First decide whether you want an empty template (de-select the Include all existing users… box) or select the box to get the complete list of users on your system. • Then click Download Sample CSV button.
Administration Guide – Enterprise / Business Version 146 June 5, 2017
Introducing the CSV format The CSV format is officially defined in RFC 4180. However you will find various interpretations of the “standard” which can lead to unpredictable behavior. In order to provide consistency we recommend the following:
1. Eliminate leading or trailing spaces as these will be interpreted as belonging to the field and that might not be what you want: Example: Leonardo,Fibonacci rather than Leonardo,
CSV for Symphony End-User and Admin Accounts: the CSV import process cannot be used to promote regular users to admins. Use the Admin Portal for the following tasks:
• Promoting regular users to admins / demoting admins to regular users • Deactivating accounts / reactivating accounts
Administration Guide – Enterprise / Business Version 147 June 5, 2017
Column Headings: The first row of the CSV file will contain the column headings. The column order does not matter but the headings must use the following values: companyUserId,surname,firstName,prettyName,emailAddress,title,location ,jobFunction,assetClass,industry,deptName,divName,password Case-Sensitive: Column headings are case-sensitive and must follow the format shown above. Size Limit: The maximum number of data rows (rows containing information about your users) is 3000. Required Fields: The required fields (emailAddress, surname, firstName, displayName, password) must be included. Username: If you activate SSO then this field will be used to identify and authenticate your users with your corporate directory so you should use the same unique identifiers that you use for your corporate directory. Optional Fields: Any combination of the optional fields can also be included and in this case a null value (empty field) will delete the contents of that field for that user. However the “password” field is a special case (see below).
Password field In this section we’ll focus specifically on the password field. So while it is acceptable to create and update other optional fields at the same time, our examples will be limited to password actions. Creating Users: When we create a user with the CSV import process, we have two options: Password: We can either type in a valid password manually (15 characters minimum, uses upper and lower case, includes a number and includes a special character). SEND_EMAIL: Enter “SEND_EMAIL” in which case Symphony will generate an email prompting that user to Set password. This second option avoids the burden of coming up with valid passwords on behalf of your users and communicating these passwords to them – and equally importantly, the need to secure or preferably delete the CSV file after use. Password Example 1 – Manually Setting the password companyUserId,surname,firstName,prettyName,emailAddress,password LBonacci,Bonacci,Leonardo,Leo Bonacci,[email protected],First7Fibonacci#s
Password Example 2 – Triggering the “Set Password” Email companyUserId,surname,firstName,prettyName,emailAddress,password LBonacci,Bonacci,Leonardo,Leo Bonacci,[email protected],SEND_EMAIL
Administration Guide – Enterprise / Business Version 148 June 5, 2017
Updating existing users’ passwords: If we want to make changes to user accounts it is strongly recommended that the admin first generate an up-to-date view of user definitions by downloading the CSV from the admin portal. The process for doing this is similar to the one we followed when we downloaded the CSV template earlier. This time, select Include all existing users in spreadsheet and then press Download sample CSV:
When you do this, you will notice that any users who have set their passwords will have “starred-out” password information (an asterisk) in their password field. Users who have not set their passwords will have blank null password fields. companyUserId,surname,firstName,prettyName,emailAddress,password LBonacci,Bonacci,Leonardo,Leo Bonacci,[email protected], LFib,Fibonacci,Leonardo,Leo Fibonacci,[email protected],* If SSO has been set, then you should expect to see mostly blank password fields. On the other hand if SSO is not enabled and you used the “SEND_EMAIL” method, then blank values will indicate users who have not yet set their passwords and therefore not yet started using Symphony. You may decide to trigger an additional email to those users to encourage them to activate their accounts: companyUserId,surname,firstName,prettyName,emailAddress,password LBonacci,Bonacci,Leonardo,Leo Bonacci,[email protected],SEND_EMAIL Using the password field, we have three options with the CSV files:
1. No change to the password: Leave the password field with one or more asterisks, or
In SSO mode: The third option can still be used if the pod has been configured for SSO. While it may seem redundant to allow a password to be set on an account that will not normally use one, there may be exceptions such as certain mobile scenarios where having a password is needed.
More about SEND_EMAIL It’s worth spending a little more time discussing the “SEND_EMAIL” instruction in order to avoid undesired outcomes.
Administration Guide – Enterprise / Business Version 149 June 5, 2017
Note: Symphony does not recommend reusing a CSV file and encourages you to delete CSV files after use in order to avoid security issues. If you decide to reuse a CSV file, you may have left SEND_EMAIL instructions in the password field. This would trigger an additional “Set Password” email to those users when they may have already set their passwords. Being asked to reset their passwords for no reason will be perceived as an annoyance. To help avoid this, certain rules have been implemented:
1. Active for 24 hours: The set password link is active for 24 hours and then expires. 2. No Repeat Usage during the 24 hours: If a CSV upload contains a request to “SEND_EMAIL” to a user who has an active set password email or a user who has set their password within the last 24 hours, then Symphony will flag that row as an error and move onto the next row in the file. 3. Use the Admin Portal: Use the admin portal to trigger the set password email if you need to override the two rules above.
Importing CSV
• Select Import in the Admin Portal and simply Drag and Drop your CSV file into the area shown on the Symphony interface.
• Symphony will verify the file and if an error is encountered you will see a message similar to the one shown below:
• If all went well on the other hand, the Import users button will be activated – click on the button.
Administration Guide – Enterprise / Business Version 150 June 5, 2017
Symphony will process the CSV file and once completed, will provide a link to a report as follows:
Displaying Bulk Job History If you click on the BULK JOB HISTORY option to display the summary report, you’ll see a list of CSV uploads similar to that shown below.
If you click on a row, you will then see details concerning this bulk import. Users will be grouped by:
• Created • Updated • Errors • Unchanged
Administration Guide – Enterprise / Business Version 151 June 5, 2017
Handling errors Follow these steps when resolving import errors to avoid any unforeseen impact on the users who were successfully processed. Note: Most such situations have been anticipated but they will still generate error messages when you try to process previously imported rows.
1. Edit the CSV file and remove the successfully created users. 2. Fix the remaining error records (the import report provides some guidance on where problems may exist). 3. Save and re-upload the CSV file.
Create and modify users Admins may want to combine account creation with account updates, see the example below: companyUserId,surname,firstName,prettyName,emailAddress,password LBonacci,Bonacci,Leonardo,Leo,[email protected],* LeoFib,Fibonacci,Leonardo,Leo Fibonacci,[email protected],SEND_EMAIL In the first data row, we are updating an existing user by changing his prettyName. In the second I am adding a new user and have set the password field to SEND_EMAIL, which will trigger a Set password email.
Managing admin accounts with the CSV file
Administration Guide – Enterprise / Business Version 152 June 5, 2017
While it is certainly possible to make changes to profile info of admin accounts using the CSV import process, you cannot promote a regular user to an administrator using CSV. This needs to be done via the UI in the Admin Portal.
CSV best practices Your CSV files contain information that identifies your users, their departments and potentially, even their passwords. So when you’re not actively working on a CSV file, it is important that you secure and preferably delete it.
Deactivating accounts There is no explicit way to deactive an account using the CSV important process. Changing a password to something unknown by the user will not have an immediate effect on that user – it really depends on the duration of the user’s current session (Symphony uses a 20- hour session time span). Once their timespan has elapsed, that user would be asked to re- authenticate which they would not be able to do until you communicate their password to them.
Usage Statistics and Audit Trail
Usage statistics Symphony Admins can take the pulse of their private pod at any time by selecting USAGE STATISTICS from the left nav. Symphony generates statistics for the last 24 hours and last 7 days, up to the time at which this option is selected: Total number of user accounts defined on the system – end-users and admins (any de-activated accounts will not be included in this number) % of users that have logged in at least once % of users that have logged in during the last 24 hours % of users that have sent a message at least once during the last 24 hours Top 10 users who sent the most messages over the last 7 days – Symphony lists the users’ email addresses
If usage statistics are being displayed for the purposes of trending then it is important to select this option at the same time each day.
Note: Usage Statistics generated during the first week after your Pod is activated will gradually populate this data. Full 7-day statistics will commence after the first week.
Administration Guide – Enterprise / Business Version 153 June 5, 2017
Appendix 1: Content Export Schema Please note CEB v1.44.x uses v1.5.1 of the Symphony xsd shown below. Important note for Actiance customers: The schema below is not applicable to the Actiance XML format. Actiance customers (customers with registered Actiance accounts) can obtain the Actiance xsd specification from the Actiance documentation portal at: https://webhelp.actiance.com/Vantage/ and then selecting 2015_R2 Symphony XML:
Administration Guide – Enterprise / Business Version 154 June 5, 2017
Administration Guide – Enterprise / Business Version 155 June 5, 2017
Administration Guide – Enterprise / Business Version 156 June 5, 2017
Administration Guide – Enterprise / Business Version 157 June 5, 2017
Administration Guide – Enterprise / Business Version 158 June 5, 2017
Administration Guide – Enterprise / Business Version 159 June 5, 2017
Administration Guide – Enterprise / Business Version 160 June 5, 2017