Symphony Administration Guide
Below you will find brief information for Symphony. Symphony is a cloud-based, secure communication and workflow platform designed to seamlessly exchange high value content and information, connect users to their community and improve workplace productivity through collaboration while maintaining organizational compliance.
Advertisement
Advertisement
Administration
Guide
Symphony Administration Guide
Enterprise and Business Version – April 2016
Discover Symphony! .................................................................................................................... 7
Preparing your installation -‐‑ what you need before starting ........................................ 7
Things you need to know ..................................................................................................................... 7
FQDNs and names used in this guide ............................................................................................................ 7
Locating your admin credentials and pod configuration details ...................................................... 7
Things you should have ........................................................................................................................ 8
Equipment and platform compatibility ........................................................................................................ 8
Identifying and accessing your Symphony service ..................................................................... 8
Access to Symphony Cloud Services .............................................................................................................. 8
Emails from Symphony ....................................................................................................................................... 8
Getting Started – Logging in to the Admin Portal .............................................................. 9
Understanding accounts ...................................................................................................................... 9
Log in to the Admin Portal .................................................................................................................. 9
Take a quick tour ................................................................................................................................. 11
Create another admin account ........................................................................................................ 13
Creating end user accounts ............................................................................................................... 13
Notification of Account creation ................................................................................................................... 15
Set up password with email .............................................................................................................. 16
First time user login—Pre-‐‑populating the user’s IM contacts and filters ......................... 16
Reviewing your new accounts ......................................................................................................... 17
Changing your password ................................................................................................................... 17
Logging out of the Admin Portal ...................................................................................................... 18
Key Management Infrastructure (Assisted Installation) ............................................. 18
The Symphony Private Pod Architecture ..................................................................................... 19
Selecting your Deployment Option ................................................................................................ 21
Option 1: Software SM and Key Manager Operating in the cloud .................................................. 21
Option2: Software SM and on-‐‑premises Key Manager ....................................................................... 22
Option3: HSM and on-‐‑prem KeyManager ................................................................................................ 23
Where to Install the Key Manager and HSM ................................................................................ 24
Load Balancers ..................................................................................................................................................... 25
Installing the Key Manager ............................................................................................................... 25
Install the host server for your Key Manager and Software SM ..................................................... 25
Create a Service Account for your Key Manager ................................................................................... 29
Download the KeyManager RPM file .......................................................................................................... 29
Installing the Java Cryptography Extension (JCE) ................................................................................ 30
Running the RPM Installation ........................................................................................................................ 31
Configuring Certificates .................................................................................................................................... 31
Bootstrapping the Software SM and HSM Keys ..................................................................................... 34
Software SM JSON file ....................................................................................................................................... 34
Safenet LUNA hardware HSM – JSON File ................................................................................................ 35
Bootstrapping your Keys ................................................................................................................................. 36
Administration Guide – Enterprise / Business Version 2 18-‐Apr-‐2016
Tomcat and KeyManager Configuration ................................................................................................... 37
Starting and Stopping the Tomcat service ............................................................................................... 39
Hardware Security Module -‐‑ HSM ................................................................................................... 40
Technical Specifications of SafeNet 7000 ........................................................................................... 41
KMs and HSMs installation on the customer network ................................................................ 42
Key Manager/HSM connectivity .............................................................................................................. 43
HSM Installation ................................................................................................................................... 43
Overview ............................................................................................................................................................... 43
Before you Begin ............................................................................................................................................... 44
Install Luna SA Appliance ................................................................................................................................ 44
Initial HSM Configuration .................................................................................................................. 47
Login ........................................................................................................................................................................ 47
Change Default Password ............................................................................................................................ 47
Set Time Zone, Date and Time .................................................................................................................. 47
Configure Network Parameters ............................................................................................................... 48
Change Network Configuration Settings ............................................................................................. 48
Generate a New Server Certificate ......................................................................................................... 50
Bind the Network Trust Link Service ................................................................................................... 51
Initialize the HSM and Adjust Policies ....................................................................................................... 52
SafeNet appliance software upgrade .......................................................................................................... 52
Introduction to Partitions ............................................................................................................................... 53
Partition Requirements and Size ................................................................................................................. 53
Create a Partition and Adjust Policies ........................................................................................................ 53
Activate Partition (Only If using PED based authentication) ........................................................... 55
Download Safenet software ....................................................................................................................... 55
Set Up a Network trust Link ........................................................................................................................... 60
High Availability Groups .................................................................................................................................. 63
Updating your Key Manager ............................................................................................................. 66
Managing your pod ................................................................................................................... 66
The Symphony Pod .............................................................................................................................. 66
Roles ......................................................................................................................................................... 66
Compliance Roles ................................................................................................................................................ 69
Roles for Information Barriers ...................................................................................................................... 70
Searching and filtering ....................................................................................................................... 71
Create a user and generate a password manually .................................................................... 71
Editing a user ........................................................................................................................................................ 73
Changing the Username ................................................................................................................................... 73
Deactivating an account ................................................................................................................................... 74
Promoting an end user to admin .................................................................................................................. 75
Changing a user’s password ........................................................................................................................... 75
Creating Service User Accounts ....................................................................................................... 75
Feature Entitlements ................................................................................................................ 77
Configuration scenarios ..................................................................................................................... 78
Disable features for the entire pod ................................................................................................ 78
Enabling feature settings for new users by default .................................................................. 79
Manually setting features for all users (without using default values) ............................. 79
Enabling External Communications (sharing files is not yet available) ............................ 80
Administration Guide – Enterprise / Business Version 3 18-‐Apr-‐2016
Enabling “Can Send Files Internally” ............................................................................................. 80
Making changes to an individual user ........................................................................................... 81
Managing Applications ............................................................................................................ 81
Installing a New Application ............................................................................................................. 81
Application Entitlement ..................................................................................................................... 83
Installing the desktop client .................................................................................................. 85
Download the desktop client ............................................................................................................ 85
Note on dependencies ....................................................................................................................................... 85
Installation Instructions -‐‑ Connecting the client to your Private Pod URL ................................ 85
Launching the desktop client ........................................................................................................... 87
Installing Symphony on multiple users’ computers ................................................................. 87
Authenticating using Single Sign-‐‑On (SSO) ....................................................................... 88
Configuration information required ............................................................................................. 88
Notes on Symphony’s implementation of SSO ............................................................................ 88
SSO and Domain Names ..................................................................................................................... 88
Configuring SSO ..................................................................................................................................... 89
Implications of SSO .............................................................................................................................. 90
Switching off SSO .................................................................................................................................. 90
SSO accounts that also have passwords ........................................................................................ 91
LDAP Synchronization (Sync) ................................................................................................ 91
LDAP Sync Architecture ..................................................................................................................... 92
Tools ......................................................................................................................................................................... 94
Supported Directory Systems .......................................................................................................... 94
Preparing to Install ............................................................................................................................................. 94
Creating the Service User Account .............................................................................................................. 96
Configuring the Directory Bridge ................................................................................................................. 97
Downloading the Directory Bridge ............................................................................................................. 98
Installation ............................................................................................................................................. 98
Account Deletion is NOT Possible .............................................................................................................. 109
Assigning Feature Entitlements.................................................................................................................. 110
Configuration Reference ................................................................................................................. 111
Elements of Configuration ............................................................................................................................ 111
Sync Destinations .............................................................................................................................................. 111
Attribute Maps ................................................................................................................................................... 113
Sync Classes ......................................................................................................................................................... 114
Sync Pipes ............................................................................................................................................................. 115
Sync Sources ........................................................................................................................................................ 116
Compliance ................................................................................................................................ 116
Content Export ................................................................................................................................... 116
Installing the Content Export Bridge ........................................................................................................ 118
Managing and Upgrading the Content Export Bridge ....................................................................... 125
Enabling Content Export ................................................................................................................................ 126
Enabling SFTP Content Export .................................................................................................................... 126
Recurring Export ............................................................................................................................................... 127
Manual Export .................................................................................................................................................... 129
Administration Guide – Enterprise / Business Version 4 18-‐Apr-‐2016
File names ............................................................................................................................................................ 129
Content Export Verification .......................................................................................................................... 131
Accessing the exported SFTP repository ................................................................................................ 131
Exported Content .............................................................................................................................................. 132
Escaped Characters .......................................................................................................................................... 134
Wall Post Information ..................................................................................................................... 135
Content Export Verification ........................................................................................................... 135
User Summary Information ........................................................................................................... 135
Content Export Schema ................................................................................................................... 135
Active Compliance ............................................................................................................................. 141
Expression Filters ............................................................................................................................................. 142
Information Barriers ....................................................................................................................................... 143
Disclaimers .......................................................................................................................................................... 144
List ALL ROOMS and Monitor ...................................................................................................................... 146
Symphony Platform -‐‑ Installing the Agent Server ........................................................ 146
Introduction ........................................................................................................................................ 146
Purpose and Scope of the Agent API ......................................................................................................... 147
User Stories supported by Version 1.0 .................................................................................................... 147
Deployment ......................................................................................................................................................... 148
Agent Purpose .................................................................................................................................................... 149
API Change Management ............................................................................................................................... 149
Authentication .................................................................................................................................................... 149
Agent Simulator Installation ......................................................................................................... 150
Platform Dependencies .................................................................................................................................. 150
Prerequisites ....................................................................................................................................................... 150
Installation and Configuration of the Agent Simulator ..................................................................... 150
Running The Curl Examples ......................................................................................................................... 152
Running the Bulk Presence Example ........................................................................................................ 155
Running the Get Messages Example ......................................................................................................... 155
Running the Test IM Example ..................................................................................................................... 156
Observing the Sent Messages ....................................................................................................................... 157
Observing curl Output and Testing Authorization ............................................................................. 158
Testing the Imposter Client Certificate ................................................................................................... 162
Running The Java Examples ......................................................................................................................... 164
The Java Example Implementation ........................................................................................................... 166
Generating API Documentation and Code Stubs ..................................................................... 169
MessageML .......................................................................................................................................... 170
Production Deployment .................................................................................................................. 171
Platform Dependencies ................................................................................................................... 171
Prerequisites ...................................................................................................................................... 171
Installation and Configuration of the Agent Server ............................................................... 171
Testing the Agent Server using the Simulator Example Programs .................................. 181
BULK MANAGE USERS (CSV Import) .................................................................................. 183
Overview .............................................................................................................................................. 183
Get the CSV template ........................................................................................................................ 184
Introducing the CSV format ........................................................................................................... 184
CSV for Symphony ............................................................................................................................. 185
Administration Guide – Enterprise / Business Version 5 18-‐Apr-‐2016
Password field .................................................................................................................................................... 185
More about SEND_EMAIL ................................................................................................................ 187
Importing CSV ..................................................................................................................................... 187
Displaying Bulk Job History ........................................................................................................... 188
Handling errors ................................................................................................................................. 189
Create and modify users ................................................................................................................. 189
Managing admin accounts with the CSV file ............................................................................. 189
CSV best practices ............................................................................................................................. 190
Deactivating accounts ...................................................................................................................... 190
Usage Statistics and Audit Trail .......................................................................................... 190
Usage statistics ................................................................................................................................... 190
Audit Trail ............................................................................................................................................ 191
Filtering Interface for Audit Trail .............................................................................................................. 191
Conversations ..................................................................................................................................... 193
Administration Guide – Enterprise / Business Version 6 18-‐Apr-‐2016
Discover Symphony!
Symphony is a cloud-based, secure communication and workflow platform designed to seamlessly exchange high value content and information, connect users to their community and improve workplace productivity through collaboration while maintaining organizational compliance.
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:
<OrgName>. Symphony.com
Some screenshots may also use: qa.Symphony.com
In either case, you should substitute the name you have selected for your Symphony service.
Finally some examples in the LDAP Sync section use “fakecorp” to represent your company name and this should be changed to the name used in your corporate directory service.
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
You should have received all of 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.
Administration Guide – Enterprise / Business Version 7 18-‐Apr-‐2016
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://
<OrgName>
.
symphony.com
port 443 http://
<OrgName>.
symphony.com
port 80 https://s3.amazonaws.com/user-‐pics-‐demo port 443 https://resources.symphony.com
port 443
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://<OrgName>-‐ tools.symphony.com
port 22
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:
199.255.192.0/22
199.127.232.0/22
54.240.0.0/18
Administration Guide – Enterprise / Business Version 8 18-‐Apr-‐2016
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 <set password>. Please allow access to: www.google.com/recaptcha
You can read more about configuring firewalls to support CAPTCHA at:
HTTPS://code.google.com/p/recaptcha/wiki/FirewallsAndRecaptcha
Getting Started – Logging in to the Admin Portal
Understanding accounts
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 9 18-‐Apr-‐2016
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 10 18-‐Apr-‐2016
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 11 18-‐Apr-‐2016
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 12 18-‐Apr-‐2016
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 USERS to load a CSV file
Admin accounts cannot be created using the BULK MANAGE USERS 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 13 18-‐Apr-‐2016
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.
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:
Administration Guide – Enterprise / Business Version 14 18-‐Apr-‐2016
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: 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:
2. Password set manually:
• If you entered an invalid password:
Administration Guide – Enterprise / Business Version 15 18-‐Apr-‐2016
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.
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
Administration Guide – Enterprise / Business Version 16 18-‐Apr-‐2016
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 MANAGE USERS option to display the account you just created (“Ann”).
Your own Admin account (“John” in our example) should also be shown in this list.
Click once on a name to edit or display that user’s details.
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.
To change your own password, follow the same procedure used for the end user:
1. Select MANAGE USERS
2. Click once on the user you want to manage
3. Select Account Security
4. Select Assign New Password or Send Link via Email
Administration Guide – Enterprise / Business Version 17 18-‐Apr-‐2016
See screenshot below:
When you select Send Link via Email, Symphony displays:
Although the password has now been changed, you are not automatically logged out.
Depending on when you logged in, your account will continue to function normally until the timeout occurs (10 minutes for admin accounts); After timeout, you will be prompted to reauthenticate to login.
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 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)
Administration Guide – Enterprise / Business Version 18 18-‐Apr-‐2016
2. SafeNet Luna SA 7000 HSMs running on the customer premises
3. CloudHSM an Amazon Web Service that uses the SafeNet Luna SA 7000
Symphony
Software SM
No
Hardware protection
AWS CloudHSM Luna SA 7000
HSM
Tampering will cause immediate
Tampering will cause immediate
Network protection
Key Generation
No
Software-based deletion of keys
Disconnection will cause immediate deletion of keys deletion of keys
Disconnection will cause immediate deletion of keys
Hardware-based Hardware-based
HA Architecture
Access Control
Requires external
LB or DNS failover
Enabled through
HSM Client software
Password-based Password-based
FIPS 140-2
Enabled through
HSM Client software
PED-based
FIPS 140-3
Platform
Description
Software SM code runs on the Key
Manager
Based on the Luna
SA 7000 but delivered as a cloud-based
Luna SA 7000
Hardware
Commercialization
Included with the
Key Manager download – no additional charge service
A subscription service from AWS
$5000 upfront fee
$1,373/month est.
Hardware purchase – indicative pricing has been provided in the HSM section of this guide
All three of 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 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, 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.
Administration Guide – Enterprise / Business Version 19 18-‐Apr-‐2016
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(
Mobile(
Key(Manager(
HSM(
Figure – Private Pod
Three primary components are involved in encrypting and decrypting customer content:
Administration Guide – Enterprise / Business Version 20 18-‐Apr-‐2016
Hardware Security Module (HSM) or Software SM: Controlled by the customer - generates daily master keys and responds to new key generation requests received from the key Manager.
Key Manager: Also controlled by the customer - Interfaces between the clients (on- prem) and the HSMs to request and then wrap encryption keys.
Symphony Clients: Symphony clients are available for Windows, Chrome, IE11 and iOS and obtain their keys by interacting with the key managers located on the
Enterprise Premises.
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 a customer- controlled Virtual Private Cloud (VPC). 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 a full HSM deployment.
Administration Guide – Enterprise / Business Version 21 18-‐Apr-‐2016
Key(Store(
Transac-on(Engine(
Iden-ty(Store(
Persistent(Data(
Key(Manager/SoGHSM(
Key(Manager/SoGHSM(
Customer(
Controlled(VPC(
Private(Pod(
Request/Response(
DC(and(VPN(
Enterprise(Premises(
Mobile(Client( Directory(Bridge(
Symphony(Desktop(Client(
Content(Export(Bridge(
Option2: 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 manager / Software SMs for resiliency.
Administration Guide – Enterprise / Business Version 22 18-‐Apr-‐2016
Key(Store(
Transac-on(Engine(
Iden-ty(Store(
Persistent(Data(
Private(Pod(
Request/Response(
DC(and(VPN(
Enterprise(Premises(
Mobile(Client(
Symphony(Desktop(Client(
Directory(Bridge(
Key(Manager/SoGHSM(
Content(Export(Bridge(
Key(Manager/SoGHSM(
Option3: HSM and on-prem KeyManager
In Option 3, the customer deploys SafeNet Luna SA 7000 HSMs – at least two, as well as matching Key Managers. 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, security but it is also the most complex to install – we recommend that customers include a SafeNet installation with their purchase.
Administration Guide – Enterprise / Business Version 23 18-‐Apr-‐2016
Key(Store(
Transac-on(Engine(
Iden-ty(Store(
Persistent(Data(
Private(Pod(
Request/Response(
DC(and(VPN(
Enterprise(Premises(
Mobile(Client( Directory(Bridge(
Symphony(Desktop(Client(
HSM(
Content(Export(Bridge(
Key(Manager(
HSM(
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.
Where to Install the Key Manager and HSM
This section provides guidance on where, on your corporate network, to install the
Key Managers and HSMs. Considerations:
1. Who will manage these devices in the future?
2. Whether a physical access is required in order to back up the keys
3. How firmware and software upgrades will be deployed?
4. Will backup power be available?
5. Is physical access to the devices tightly controlled?
Typically the answers to these questions will indicate that the ‘best’ location to install the HSMs and Key Managers is: a. in the same physical location (Each Key Manager and HSM should be close to each other) b. Similar location to other mission-‐critical systems like corporate email servers or directory services – to benefit from the high levels of security, access control and backup power systems
Failover scenarios should be carefully evaluated. If connectivity is lost at one key site, can other users still reach other HSM/Key Managers in order to maintain
Symphony operation?
Administration Guide – Enterprise / Business Version 24 18-‐Apr-‐2016
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 full HSMs, so that keys can be migrated. For this reason the Software SM can be deployed as a first step towards full 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:
•
•
•
•
•
•
•
•
•
•
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 JCE extensions for JDK or JRE
JVM 64-bit is recommended
Virtual Servers: both on-premises and cloud-hosted are supported
Install Java Cryptography Extension (JCE) o
Go to http://www.oracle.com/technetwork/java/javase/downloads/jce-7- download-432124.html
, o o o accept the license agreement and download "Java Cryptography
Extension (JCE) Unlimited
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
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
Administration Guide – Enterprise / Business Version 25 18-‐Apr-‐2016
•
If you plan to use the Safenet luna SA HSM, you need to install the HSM client on the key KeyManager. We describe how to do this in the HSM installation section.
centos@Dev8 -‐ HSMControl2:~ $ vtl verify
The following Luna SA Slots/Partitions were found:
Slot
====
1
Serial # Label
======== =====
472949007 hapg-‐8f56e43a_472949
•
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
-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.
-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.
-Djavax.net.ssl.trustStore=$DATA_BASE/certs/tomcat.keystore \
-Djavax.net.ssl.trustStorePassword=password \
•
Software SM file(hsm.jck) and password for it. Or Luna SA HSM with bootstrapped keys in it(use wenger tools to bootstrap hsm and follow the admin guide) . Sample
Luna HSM mode settings:
"mode" : "HSM" ,
"partitionName" : "ha-mk2015-1" ,
"ha-mk2015-1" : "Xmp9mcupFNw6QGcKdbn2WEudAq4CwD" ,
"ha-mk2015-2" : "Xmp9mcupFNw6QGcKdbn2WEudAq4CwD" ,
Software SM mode settings
"mode" : "Software SM" ,
"keystorePassword" : "Xmp9mcupFNw6QGcKdbn2WEudAq4CwD" ,
"keystoreName" : "hsm.jck" ,
General KM configuration. Get the following from ES/Security team(it will be on admin page later):
Administration Guide – Enterprise / Business Version 26 18-‐Apr-‐2016
• 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="
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
Configure the Host Name for your Key Manager and Attach it to your Network
The server will need to be visible on your corporate network and will therefore need a hostname, IP address and physical connection to the network. Please refer to the instructions available with RedHat or CentOS.
•
•
Assign your corporate domain certificate to your Key Managers: Make sure you have a certificate for your domain (e.g: *.customername.com). Import it into the java keystore file
“tomcat.keystore” on each of your keymanager servers.
Generate Private Key: Please generate a random private key and also import it into the java keystore file “tomcat.keystore” on each of your keymanager servers. The Keystore alias for the private key must also be set to “tomcat”.
Administration Guide – Enterprise / Business Version 27 18-‐Apr-‐2016
•
•
CNAME or Load Balancer: Make sure you have a cname for your keymanager or LB of keymanagers, attached to your host server/servers. Sample: symphony-‐ keymanager.customername.com.
Verify Connectivity: Once the Key Manager has been successfully installed, ping the hostname from the public network using the following command.
$:> ping symphony-keymanager.<customername>.com
Ensure you have access to the Symphony cloud base URL. This can be accomplished using a telnet session to the https port of the Admin page URL. If the server responds with “Connected” then you have validated your connectivity. We show an example below:
Install a web browser
To simplify the steps required to download and install your Key Manager, 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
$:> rpm -‐i packagename.rpm
Now enter the password and you Chrome along with its dependencies will be installed. After the
installation is complete, you will see a list of dependencies listed along with the success message.
Administration Guide – Enterprise / Business Version 28 18-‐Apr-‐2016
The following command can be used to update an rpm:
$:> rpm -U packagename.rpm and the following command can be used to verify that software was installed:
$:> rpm -qa | grep packagename(like relay/tomcat)
Create a Service Account for your Key Manager
Using the browser on your new Key Manager server:
• Log in to the Admin Portal and select Create a User from the left Nav. in the user detail, select Service Account (see the section on managing Service Accounts).
We named our account – keymanager.
• Copy and store the system-generated security key (you will need this for configuring your Key Manager)
Download the KeyManager RPM file
We package keymanager rpm's in *.zip, which includes:
- on-prem-keymanager-0.11.2.zip
• wenger.tar.gz
• 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 +)
Administration Guide – Enterprise / Business Version 29 18-‐Apr-‐2016
-‐ 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. The download is comprised of 4 individual components – Tomcat,
Key Manager, Software SM and the Wenger tool used to bootstrap encryption keys. Installation instructions for these files are provided later in the document.
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
$:>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 "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
Administration Guide – Enterprise / Business Version 30 18-‐Apr-‐2016
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
Note: if you have multiple JDKs or JREs installed, make sure that you copy JCE extension packages to the one which will be used to run the Key Manager. Otherwise you will see the following exception when the Key Manager is running: java.security.InvalidKeyException: Illegal key size
If you have already installed your Key Manager and are adding the JCE in a different order, then you need to restart Tomcat.
Running the RPM Installation
Install the tomcat and keymanager RPMs that were downloaded. You can use either the sudo or rpm commands as follows
$:> sudo rpm -‐i tomcat-‐7.0.61-‐9.x86_64.rpm
$:> sudo rpm -‐i keymanager-‐centos65-‐0.7.0-‐49.x86_64.rpm
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
For each Symphony on-prem Java-based application (Key Manager, Content Export Bridge,
Directory Bridge), we use a tomcat.keystore file as a javax.net.ssl.keyStore value. This file has to contain the full chain of trust so that we can rely on built-in CA bundles, which contain a list of major CA companies, to verify our wildcard certificate.
Administration Guide – Enterprise / Business Version 31 18-‐Apr-‐2016
To import the full chain of trust into the tomcat.keystore perform the following steps
1. Concatenate the RSA private and public keys in PEM format within a single file
(symphony-pair.PEM):
$:> cat symphony-private.pem symphony-public.pem > symphony-pair.pem
2. Concatenate the of CA chain in PEM format within a separate file
$:> cat symphony-chain.pem gdroot-g2.crt > symphony-ca-chain.pem
symphony-chain.pem - GoDaddy G2 intermediate certificate
gdroot-g2.crt - GoDaddy G2 root certificate
3. Export results of 1 and 2 into PKCS#12 format (providing alias!). The System will ask you to provide a password, you should use the one used by the tomcat.keystore4.
Import results of 3 into the tomcat.keystore
$:> openssl pkcs12 -export -in symphony-pair.pem -certfile symphony-ca-chain.pem - out symphony-full-chain.p12 –name tomcat
4.
Import results of 3 into the tomcat.keystore
$:> keytool -v -importkeystore -srckeystore symphony-full-chain.p12 -srcstoretype
PKCS12 -destkeystore tomcat.keystore -deststoretype JKS
To verify that the new keystore works as expected we created a simple servlet. We configured
Tomcat to serve HTTPS using a keystore file constructed in the way described above. We launched this Tomcat on a development server with a public CNAME in the
*.symphony.com domain.
We created the following validation curl script:
Administration Guide – Enterprise / Business Version 32 18-‐Apr-‐2016
[centos@centos-‐vm ~]$ curl -‐v https://dev8-‐ausw2-‐all.symphony.com:8443/hello/helloworld
* About to connect() to dev8-‐ausw2-‐all.symphony.com port 8443 (#0)
* Trying 52.11.157.17...
* Connected to dev8-‐ausw2-‐all.symphony.com (52.11.157.17) port 8443 (#0)
* Initializing NSS with certpath: sql:/etc/pki/nssdb
* CAfile: /etc/pki/tls/certs/ca-‐bundle.crt
CApath: none
* SSL connection using TLS_DHE_RSA_WITH_AES_128_CBC_SHA
* Server certificate:
* subject: CN=*.symphony.com,OU=Domain Control Validated
* start date: Sep 24 21:52:38 2015 GMT
* expire date: Oct 10 20:22:07 2017 GMT
* common name: *.symphony.com
* issuer: CN=Go Daddy Secure Certificate Authority -‐
G2,OU=http://certs.godaddy.com/repository/,O="GoDaddy.com,
Inc.",L=Scottsdale,ST=Arizona,C=US
> GET /hello/helloworld HTTP/1.1
> User-‐Agent: curl/7.29.0
> Host: dev8-‐ausw2-‐all.symphony.com:8443
> Accept: */*
>
< HTTP/1.1 200 OK
< Server: Apache-‐Coyote/1.1
< Content-‐Length: 13
< Date: Tue, 06 Oct 2015 03:20:37 GMT
<
Hello world!
* Connection #0 to host dev8-‐ausw2-‐all.symphony.com left intact
[centos@centos-‐vm ~]$
Using the code snippet above, we were able to establish an HTTPS connection and receive the response shown below:
Administration Guide – Enterprise / Business Version 33 18-‐Apr-‐2016
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 (this file was previously called relay_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" : "Software SM" ,
"keystorePassword" : "soft_hsm_password" ,
"keystoreName" : "<env>-hsm.jck" ,
"account" : "keymanager" ,
"secret" : "keymanager_shared_secret_key" ,
Administration Guide – Enterprise / Business Version 34 18-‐Apr-‐2016
"storagePassword" : "session_storage_password" ,
"secureDir" : "/data/tomcat/secure/" ,
"entityKey" : "entity_key"
},
"companyurls" : {
"applicationurl" : "https://<env>.symphony.com/client/index.html" ,
"baseurl" : "https://<env>.symphony.com" ,
"loginbaseurl" : "https://<env>.symphony.com" ,
"keymanagerurl" : "https://<env>.symphony.com/relay"
},
"ssoconfig" : {
"idp.entityid" : "http://sso-
<env>.symphony.com/adfs/services/trust" ,
"sp.entityid" : "https://<env>.symphony.com" ,
"idp.ssoendpoint" : "https://sso-<env>.symphony.com/adfs/ls" ,
"sp.acsurl" : "https://<env>.symphony.com/relay/sso/acs" ,
"idp.signingcertificate" : "sso-<env>.symphony.com.cer" ,
"ssoenabled" : "false"
},
"sessionmanagement" : {
"disableSkeyauthentication" : "false" ,
"sessionencryptionkey" : "session_encryption_key"
}
}
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 been configured, using the “vtl verify” command. The configuration procedure and the usage of the “vtl verify” commands are provided later in the document. 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_only" ,
"ha-mk2015-1" : "partition_password_for_luna_hsm_only" ,
"account" : "keymanager" ,
"secret" : "keymanager_shared_secret_key" ,
"storagePassword" : "session_storage_password" ,
"secureDir" : "/data/tomcat/secure/" ,
"entityKey" : "entity_key"
},
"companyurls" : {
"applicationurl" : "https://<env>.symphony.com/client/index.html" ,
"baseurl" : "https://<env>.symphony.com" ,
Administration Guide – Enterprise / Business Version 35 18-‐Apr-‐2016
"loginbaseurl" : "https://<env>.symphony.com" ,
"keymanagerurl" : "https://<env>.symphony.com/relay"
},
"ssoconfig" : {
"idp.entityid" : "http://sso-
<env>.symphony.com/adfs/services/trust" ,
"sp.entityid" : "https://<env>.symphony.com" ,
"idp.ssoendpoint" : "https://sso-<env>.symphony.com/adfs/ls" ,
"sp.acsurl" : "https://localhost.symphony.com:8443/relay/sso/acs" ,
"idp.signingcertificate" : "sso-<env>.symphony.com.cer" ,
"ssoenabled" : "false"
},
"sessionmanagement" : {
" disableSkeyauthentication" : "false" ,
"sessionencryptionkey" : "session_encryption_key"
}
}
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
Note: in the previous example you may see a file named relay_config.json – this name is being changed
The code snapshot looks as follows:
Now run the following command to bootstrap the encryption keys.
$:>/sbin/wenger.sh hsm-bootstrap -resultDir /home/Sidv100 where resultDir is an output directory for *.jck file in case of Software SM.
Once the command has been successfully executed, you will see the following screenshot.
Administration Guide – Enterprise / Business Version 36 18-‐Apr-‐2016
You should also be able to navigate to the resultDir folder and see that the *.jck file has been created.
Note: it is important to put the *.jck file that was created into the /data/tomcat/config directory.
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 1: It is NOT currently possible to share Tomcat containers with other Symphony applications such as the Content Export Bridge.
Warning 2: Be aware that the Tomcat configuration is also different depending on whether you are installing the Software SM or full HSM from Safenet.
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
<DomainName> where you see
“mykeymanager” in the example URLs.
#!/usr/bin/env bash
DATA_BASE= "/data/tomcat/"
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/tomcatjuli.jar \
-Dcatalina.base=$CATALINA_BASE \
Administration Guide – Enterprise / Business Version 37 18-‐Apr-‐2016
-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 <Domain> to the domain name of your proxy.
-
Dproxy.uri=http:proxy.<Domain>.com:8080
Next configure your Tomcat KeyManager. Please use one of the two sections below – either for Software SM or Luna SA HSM.
Tomcat KeyManager Configuration - Software SM mode
Navigate to /data/tomcat/config and edit the keymanager_config.json file (this file is
currently named relay_config.json). Move the hsm.jck file that was pregenerated using the wenger tool, into /data/tomcat/config and configure the “relay” property block in keymanager_config.json as follows
{
"relay" : {
"mode" : "Software SM" ,
"keystorePassword" : "soft_hsm_password" ,
"keystoreName" : "<env>-hsm.jck" ,
"account" : "keymanager" ,
"secret" : "keymanager_shared_secret_key" ,
"storagePassword" : "session_storage_password" ,
"secureDir" : "/data/tomcat/secure/" ,
"entityKey" : "entity_key"
},
"companyurls" : {
"applicationurl" : "https://<env>.symphony.com/client/index.html" ,
"baseurl" : "https://<env>.symphony.com" ,
"loginbaseurl" : "https://<env>.symphony.com" ,
"keymanagerurl" : "https://<env>.symphony.com/relay"
},
"ssoconfig" : {
"idp.entityid" : "http://sso-
<env>.symphony.com/adfs/services/trust" ,
"sp.entityid" : "https://<env>.symphony.com" ,
"idp.ssoendpoint" : "https://sso-<env>.symphony.com/adfs/ls" ,
"sp.acsurl" : "https://<env>.symphony.com/relay/sso/acs" ,
Administration Guide – Enterprise / Business Version 38 18-‐Apr-‐2016
"idp.signingcertificate" : "sso-<env>.symphony.com.cer" ,
"ssoenabled" : "false"
},
"sessionmanagement" : {
"enablekeymanagersession" : "false" ,
"sessionencryptionkey" : "session_encryption_key"
}
}
Tomcat KeyManager Configuration – Lusa SA HSM mode
Navigate to /data/tomcat/config and edit the keymanager_config.json file (this file was
previously called relay_config.json). Move the hsm.jck file that was pregenerated using the wenger tool, into /data/tomcat/config and configure relay property block in keymanager_config.json as follows
{
"relay" : {
"mode" : "HSM" ,
"partitionName" : "partition_name_for_luna_hsm_only" ,
"ha-mk2015-1" : "partition_password_for_luna_hsm_only" ,
"account" : "keymanager" ,
"secret" : "keymanager_shared_secret_key" ,
"storagePassword" : "session_storage_password" ,
"secureDir" : "/data/tomcat/secure/" ,
"entityKey" : "entity_key"
},
"companyurls" : {
"applicationurl" : "https://<env>.symphony.com/client/index.html" ,
"baseurl" : "https://<env>.symphony.com" ,
"loginbaseurl" : "https://<env>.symphony.com" ,
"keymanagerurl" : "https://<env>.symphony.com/relay"
},
"ssoconfig" : {
"idp.entityid" : "http://sso-
<env>.symphony.com/adfs/services/trust" ,
"sp.entityid" : "https://<env>.symphony.com" ,
"idp.ssoendpoint" : "https://sso-<env>.symphony.com/adfs/ls" ,
"sp.acsurl" : "https://localhost.symphony.com:8443/relay/sso/acs" ,
"idp.signingcertificate" : "sso-<env>.symphony.com.cer" ,
"ssoenabled" : "false"
},
"sessionmanagement" : {
"disableSkeyauthentication" : "false" ,
"sessionencryptionkey" : "session_encryption_key"
}
}
Starting and Stopping the Tomcat service
First ensure that the linux user running the Tomcat service has full read/write access to
/data/tomcat and /data/opt folders or the folders where tomcat and keymanager were
Administration Guide – Enterprise / Business Version 39 18-‐Apr-‐2016
installed. (Sample tomcat.keystore, hsm.jck should be under "tomcat" user).
First copy the tomcat certificates from your domain into /data/tomcat/cert folder and configure in the environment.sh file.
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
If you have a High Availability cluster, repeat the set up process on server cluster. 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 see the following message :
System is healthy: Keymanager URL cname
Next, check your tomcat service status
$:> sudo service tomcat status
Functional Validation
In order to validate a Key Manager and Software SM combination, the admin should install the Symphony desktop client downloaded from the Admin Portal. If you followed the steps described in this section carefully, then this client will have been updated with the correct hostname for your new key manager and can be installed and tested directly.
Important: If the name of the key manager has changed. Or if the Key manager has now been located behind a load balancer, then repeat the Key Manager configuration step using the Admin Portal and then download the Desktop Client for Windows.
Install this client using the instructions provided in the Desktop Client for Windows section of this guide and then log in using a valid user 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 and Software SM installation was Successful.
Hardware Security Module -‐ HSM
Administration Guide – Enterprise / Business Version 40 18-‐Apr-‐2016
Hardware Security Modules (HSMs) provide reliable protection for transactions, identities, and applications by securing cryptographic keys and provisioning encryption, decryption, authentication, and digital signing services. HSMs offer end-to-end protection for organizations, helping them achieve regulatory compliance, streamline business processes, reduce legal liabilities, and improve profitability. Symphony has chosen Luna SafeNet 7000 solution.
Technical Specifications of SafeNet 7000
The SafeNet Luna SA 7000 is a high performance HSM capable of best in class performance across a breadth of algorithms including ECC, RSA, and symmetric transactions. It also features a dual, hot-swappable power supply that ensures consistent performance and no down time.
Technical Specification
Operating System Support
Win2003(64 bit), Windows Server 2008 (64 bit), Solaris 9.10(32 and 64 bit), Linux E4,E5 2.6
Cryptographic Processing Asymmetric Key Encryption and Key Exchange
Suite B Algorithm Support
RSA (1024-4096 bit), PKCS #1 v1.5, OAEP PKCS#1 v2.0 •
Diffie-Hellman (1024 bit)
ECC Support • ECDSA • ECC Brainpool Curves (named and user-defined)
Digital Signing
Symmetric Key Algorithms
RSA (1024-4096-bit), DSA (1024-bit), PKCS #1 v1.5
DES, 3DES (double & triple key lengths), RC2, RC4, RC5,
CAST-3, CAST- 128, AES Message Digest Algorithms
Message Digest Algorithms SHA-1, SHA-224, SHA-256, SHA-384, SHA-512
Message Authentication
Codes
SHA-1, SHA-224,SHA-256,SHA-384, SHA-512
HMAC-SHA-1, HMAC-SHA-256, HMACSHA-384, HMAC-
SHA-512, SSL3-MD5- MAC, SSL3-SHA- 1-MAC
Random Number
Generation
Luna PCI supports random number generation based on
Appendix A 2.4 of ANSI X9.31
1280 Object Limit Physical
Physical Characteristics
Card type PCI Card, Universal
Operating Temperature 0°C to 40°C
Storage Temperature
Power Requirements
Dimensions
Connectivity
PCI Module
-20°C to +65°C
+5V@3A Max; [email protected] Max (FIPS Level 3 only)
4.1” by 7.88”
PCI-X r1.0b
Full Height 7.88” length • PCI Module PCI-X rl.ob compliant at
64-bit 66MMHZ
PCI 2.3 compatible at 33/66 MHZ, 32/64-bit.
PCI Express Bus
Administration Guide – Enterprise / Business Version 41 18-‐Apr-‐2016
We have provided vendor price list information for the SafeNet Luna SA 7000 along with the order numbers to help you estimate the cost of the HSM equipment you plan to deploy.
Qty
.
Part # Description
MSRP
Unit
Extended
Unit
Extended
Build
Safenet Luna
1
1
908-000095-004-
000
908-000071-004-
000
LUNA SA 7000
REMOTE PED
BNDL (2
HSMP,CL,SW
5.3.5,FW
6.2.1/6.10.2,REMOT
E PED,20 PED
KEYS,BACKUP
HSM)
Luna SA 7000 PED-
Auth,2
HSMP,CL,SW
V5.2.3,FW6.2.1/6.10.
2)
$36,500.0
0
$29,500.0
0
$24,436.75 $24,436.75
$19,750.25 $19,750.25
4
912-00004-901-
000
$25.00 $16.74 $66.96
1
1
020-160005-021-
000
020-160001-014-
000
POWER CORD,110
VAC,USA,ROHS
Professional Services quickstart,HSM,LUN
A EFT,3RD PARTY
PAYMENT HSM
Key migration,one site, incl travel
Three year of Plus maintenance service
17% of product list price
$11,500.0
0
$33,660.0
0
$10,660.50 $10,660.50
$33,660.00 $62,500.20
$88,641.42
Additional Equipment
Additional User licenses (optional) = $2,200 each.
Additional power supply and cords – these are not included in the base price and should be ordered separately.
KMs and HSMs installation on the customer network
We repeat our previous guidance concerning Key Managers. We recommend that the people responsible for installing and maintaining the software should have easy access to the equipment during the early phases, especially if the vendor will be providing assistance with the installation.
Administration Guide – Enterprise / Business Version 42 18-‐Apr-‐2016
The ideal permanent location will be to co-locate the Key Manager and HSMs and to place them in similar network locations as email servers/ERP systems or directory services. These locations will have high capacity connectivity and security.
Key Manager/HSM connectivity
Key Manager servers can only be connected to a single HSM, although it is possible to connect multiple Key Managers with a single HSM for improved reliability. Please review the diagram below:
Symphony.Pod
VPN
Load Balancer
Key
Manager
Key
Manager
Key.Generation
user%specific encrypted.keys
User%A
RSA%key
Room%key
Symphony.client
Customer.Premises
HSM Installation
If you have not already installed your Key Manager, you should return to the previous section and complete that installation. The key bootstrapping process is different for HSM.
Please ensure you have followed the relevant steps described for bootstrapping HSMs in the key manager section above.
Overview
Configuration of the Luna SA and application workstation is completed using the Luna SA front panel command console (CLI) RS232 connection and Putty (SSH) connection.
Administration Guide – Enterprise / Business Version 43 18-‐Apr-‐2016
Configuration of the Luna SA consists of the following steps:
1. Configure Luna SA for your network
2. Initialize the HSM and adjust polices
3. Create a partition and adjust policies
4. Set up a network trust link to a client
5. Assign a registered client to the partition
6. Use the partition from the client
Before you Begin
Before you begin, gather the following information and write it down:
• Appliance Admin password
• Network Parameters o Network Address (IP) o Hostname o Domain Name* o Default Gateway o DNS Name Server* o Search Domain* o Subnet Mask
* Only required if using DNS. Have your network administrator add an entry to your company’s DNS for the Luna SA.
• HSM Label
• Domain PW
• Security Officer PIN (optional)/PW
• Partition Name
• Partition User PIN (optional)
• Partition Password
Partition Password will be generated later, by the Luna PED. You will need to record it at that time for your Clients to use
Install Luna SA Appliance
• Rack Mount
• connect power chord
• Connect Ethernet cable to port eth1 (top port – equates to eth0)
The HSM Luna SA 7000 must be primed with IP address and basic information before it can use network-based management.
Serial Connection on Mac
• Connect to DB9 serial port with a terminal emulation (in this case Serial).
Administration Guide – Enterprise / Business Version 44 18-‐Apr-‐2016
• Serial: is a full feature serial terminal for MAC. It can be downloaded from https://www.decisivetactics.com/products/serial/
• Serial setup and connection: After opening the Serial application, the following screen will be displayed, where you have to choose the port connected to the HSM.
After selecting the right port, set the following connection parameters: o Speed (baud): 115200 o Data bits: 8 o Stop bits: 1 o Parity: None o VT-100 terminal emulation o Hardware flow control
(You may need to press [ENTER] several times to initiate the session)
Serial Connection on Windows
• Connect to DB9 serial port with a terminal emulation (in this case PuTTy).
• Download PuTTy, a free SSH and Telnet client, from http://www.putty.org/ .
• When you run PuTTy, you will see the following screenshot.
Administration Guide – Enterprise / Business Version 45 18-‐Apr-‐2016
• On the Navigation pane, on the lef, click on Connection and then on SSH and select “Serial”.
Enter the correct serial port (in our case COM3) and ensure that the Baud rate is 115200.
Your setup should resemble the screenshot below:
Click Open and the terminal session will launch and prompt you to enter the admin login and password as shown below:
Administration Guide – Enterprise / Business Version 46 18-‐Apr-‐2016
Initial HSM Configuration
Login
Log in as admin and enter the Safenet factory password:
Local_host login: admin
Password: PASSWORD
Change Default Password
For security, you are immediately prompted to change the factory-default password for the
‘admin’ account. Change the admin password.
To protect Luna SA from vulnerabilities due to weak passwords, new passwords must be at least eight characters in length, must not be based on a dictionary word, and must include characters from at least three of the following four groups: lowercase alphabetic (abcd...xyz) uppercase alphabetic (ABCD...XYZ) numeric (0123456789) special (non-alphanumeric, -_!@#$%&*...)
Set Time Zone, Date and Time
Verify the current date and time on the Luna SA: lunash:> status date
Change them using: lunash:> sysconf timezone -set <TimezoneCode> lunash:> sysconf time <HH:MM YYYYMMDD>
After the change has been made, you will see the following screen.
Administration Guide – Enterprise / Business Version 47 18-‐Apr-‐2016
Configure Network Parameters
Set the hostname of the Luna SA (the hostname must match the name that your network administrator entered into the hostname list). lunash:> net hostname <HostName>
After a hostname has been successfully entered, you will see the following screen.
If you are using DNS on your network, follow these next 3 steps. If not, proceed to Change
Network Configuration settings..
Set the name of the network domain in which the Luna SA HSM Server is to operate. lunash:> net domain <DomainName>
Set the address for the local name server. lunash:> net dns –add -nameserver <NameServerIP>
Set the DNS Search Domain. lunash:> net dns –add -searchdomain <DomainName>
The following screenshot shows the results after dns is correctly set.
Change Network Configuration Settings
The structure of the network configuration command is shown below:
Administration Guide – Enterprise / Business Version 48 18-‐Apr-‐2016
lunash:> net interface static -device <NetDevice> -ip <NetDeviceIP> -netmask
<NetMaskIP> -gateway <GatewayIP>
Example: lunash:> net i static -dev eth0 -ip 192.168.159.30 -n 255.255.255.0 -g 192.168.159.1
Note: The ethernet ports are logical eth0 labeled 1 and logical eth1 labeled 2 on the back panel.
After the above command is executed, the network service needs to be restarted for the new settings to take effect. Type “proceed” when asked to confirm the restart.
Use the net show command to display the current settings, to see how they need to be modified for your network. At the lunash prompt, type: lunash:> net show
Restart the syslog service. This puts the proper hostname in the logs.
Administration Guide – Enterprise / Business Version 49 18-‐Apr-‐2016
lunash:> service restart syslog
Apply network changes and restart network with: lunash:> service restart network
After successfully restarting the syslog and network, you should see the following screen.
The net show command (used earlier) displays the current settings, so you can verify that they are now correct for your environment before attempting to use them. lunash:> net show
Verify your network setup by pinging another server and having the other server ping this
Luna SA. lunash:> net ping <IP or Hostname>
Generate a New Server Certificate
Although your Luna SA HSM Server came with a server certificate, the original certificate does not contain the IP or hostname that you have just configured. Therefore, you must generate a new Luna SA Server Cert. lunash:> sysconf regenCert
If not using DNS, then: lunash:> sysconf regenCert <IP of Eth0>
Since this command overwrites the current server certificate and private keys, a confirmation needs to be provided. Type “proceed” when asked to confirm.
Administration Guide – Enterprise / Business Version 50 18-‐Apr-‐2016
Bind the Network Trust Link Service
From the factory, the network trust link service (ntls) is bound to the loopback device, by default. In order to use the appliance on your network, you must bind ntls to one of the two ethernet ports, ETH0 or ETH1, or to a hostname or IP address. Examples: lunash:> ntls bind eth0 lunash:> ntls bind all lunash:> ntls bind none –bind 192.168.159.50
You can use the ntls show command to see current status. lunash:>ntls show
The NTLS service should be restarted for the changes to take effect and type ”proceed” when asked to confirm.
Administration Guide – Enterprise / Business Version 51 18-‐Apr-‐2016
Initialize the HSM and Adjust Policies
Before you perform any action on the Luna SA that requires access to the HSM, ensure that the Luna PED is connected and displaying Awaiting command… (Press Enter on the touchpad). Have a set of PED keys available.
Type the hsm init command at the lunash prompt, supplying a text label for the new HSM. lunash:> hsm init -‐label <HSMLabel>
You are directed to the Luna PED, which prompts you for the required PED Keys and touchpad actions. Complete. View HSM status: lunash:> hsm show
View and Set any of the modifiable policies of the HSM, if required. lunash:> hsm showPolicies lunash:> hsm changePolicy -‐policy <PolicyNumber> -‐value <1 or 0>
SafeNet appliance software upgrade
Upgrade the Luna SA appliance software from default to version 5.3.5. Perform the following steps on a control instance that has IP connectivity to the HSM appliance.
1. Stop all applications and services that are using the HSM.
2. Download the Luna SA appliance software upgrade packages from the following links
Upgrade(Appliance(So0ware( from(5.1.X(to(5.1.5(
Upgrade(Appliance(So0ware( from(5.1.5(to(5.2.6( https://s3.amazonaws.com/cloudhsm-software/630-010165-018_REVA.tar
https://s3.amazonaws.com/cloudhsm-software/630-010165-022_RevA.tar
Upgrade(Appliance(So0ware( from(5.2.6(to(5.3.5( https://s3.amazonaws.com/cloudhsm-software/630-010165-023_RevA.tar
3. Copy the <package_name>.spkg file to the HSM appliance, where <private_key_file> is the private portion of the SSH key that you provided when your HSM was provisioned.
$ scp -‐i <private_key_file> <package_name>.spkg admin@<hsm_ip_address>:
4.Connect to the HSM appliance and log in to the HSM with the following commands:
$ ssh -‐i <private_key_file> admin@<hsm_ip_address> lunash:> hsm login
5. Verify and install the Luna SA appliance software update with the following commands.
The value to use for <auth_code> is in the <package_name>.auth file contained in the archive. lunash:> package verify <package_name>.spkg -‐authcode <auth_code> lunash:> package update <package_name>.spkg -‐authcode <auth_code>
6.Reboot the HSM appliance with the following command: lunash:> sysconf appliance reboot
7.Confirm that you are using Firmware version 6.2.1 and software version 5.3.5 using the following command: lunash:> hsm show
If the updates are successful, you should see the following screenshot.
Administration Guide – Enterprise / Business Version 52 18-‐Apr-‐2016
Introduction to Partitions
The SafeNet Luna SA 7000 uses partitions to store keys.
1. Every physical partition has to have a unique name and the same password
2. Every Key Manager server has to be connected to one(and only one) physical partition
3. Key Managers can share physical partitions
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
Create a Partition and Adjust Policies
Login to the Luna SA Server as HSM Admin: lunash:> hsm login
You are directed to the Luna PED, which prompts for the blue HSM Admin PED Key set.
You must supply a label or name for the new Partition when you issue the command. You will also have to provide a password for the partition.
lunash:> partition create -‐partition <PartitionName>
(If using PW based authentication) Prompted for partition PW – please enter and confirm
The screenshot shows a new partition, called partition4 being created. The password for the partition is entered twice and you will see a ‘partition create’ success message.
Administration Guide – Enterprise / Business Version 53 18-‐Apr-‐2016
(If using PED based authentication) You are directed to the Luna PED, which prompts you to create or reuse a black User PED Key set.
The Luna PED now generates and displays the Client Password (login secret) by which
Clients will later authenticate themselves to this partition.
Login secret value… btqx-‐EFGH-‐3456-‐7/K9
Please write it down.
Press ENTER.
For demo or eval purposes, it would be easier, at this time, to change the partition password to something more easy to type. THIS IS NOT RECOMMENDED FOR PRODUCTION
AS YOU NEED A STRONG PASSWORD FOR GOOD SECURITY PRACTICES IN A
PRODUCTION ENVIRONMENT! lunash:> partition changepw -‐par <PartitionName> -‐n <PartitionPassword> -‐o
<PartitionPassword>
View and Set any of the modifiable policies of the HSM Partition, if required.
lunash:> partition showPolicies -‐partition <PartitionName>
Normally you would now allow partition activation and allow auto activation: lunash:> partition changePolicy -‐par <PartitionName> -‐policy <PolicyNumber> -‐value <1 or
0> lunash:> par changePo -‐par <PartitionName> -‐po 22 -‐v 1 lunash:> par changePo -‐par <PartitionName> -‐po 23 -‐v 1
Administration Guide – Enterprise / Business Version 54 18-‐Apr-‐2016
Activate Partition (Only If using PED based authentication)
Now, activate the HSM Partition. The command is: lunash:> partition activate -‐partition <PartitionName>
To verify, look at the HSM Partition assigned to the client. lunash:> partition show –partition <PartitionName>
Download Safenet software
The Safenet Client SW can be downloaded from the following website: https:// serviceportal.safenet-‐inc.com. Enter the username and password for your account.
Navigate to Support -‐> Access Articles and Downloads.
Administration Guide – Enterprise / Business Version 55 18-‐Apr-‐2016
From the Download Wizard Menu manager select “Hardware Security Module (HSM) download”
Within the Hardware Security Module Downloads page, select Luna SA (Network Based HSM)
Administration Guide – Enterprise / Business Version 56 18-‐Apr-‐2016
Now navigate to Luna Client version 5.3 and click on the Luna HSM 5.3.0 Client (ID
DOW2949)
In the Client’s terminal window, execute the following command and you will see the files uncompressing as shown in the screenshot.
$:> tar –xvf filename.tar
Administration Guide – Enterprise / Business Version 57 18-‐Apr-‐2016
After the files are unzipped, go to the directory: /usr/linux/64 and enter the following command
#:> ./install.sh
This runs the install script and asks you to select whether you want the product to be installed. Select “Yes” or “y”
Now choose the client you want to install. Select the number to place the ‘*’ next to the install package. Then enter ‘n’ to continue to next…
Choose to install (or not) the javasp and SDK options. Select the number to place the ‘*’ next to the components you want to install. Then enter ‘i’ to continue to the install…
Administration Guide – Enterprise / Business Version 58 18-‐Apr-‐2016
After the installations are successful, you will see the following screen.
Now that we have completed this part of the installation, we need to change the owner of some of the directories:
$> sudo chown <user>:<userGroup> /etc/Chrystoki.conf
$> chmod u+rwx /etc/Chrystoki.conf
$> sudo chown -R <user>:<userGroup>
/usr/safenet/lunaclient/
where:
<user> = userName of a Linux user, which will be used to establish NTLS and to configure HA group
<userGroup> = the user group which <user> belongs to
Administration Guide – Enterprise / Business Version 59 18-‐Apr-‐2016
For example
$> sudo chown ivan:admins /etc/Chrystoki.conf
$> sudo chown -R ivan:admins /usr/safenet/lunaclient/
Set Up a Network trust Link
In order to connect a Client to an HSM Partition on the Luna appliance, you must first create a Network Trust Link (NTL) between them. An NTL consists of:
• the Network Trust Link Agent (NTLA), a software library that resides on the Client
• the Network Trust Link Server (NTLS), the server software that manages Network
Trust Links on the Luna appliance
• the NTL itself, an encrypted, secure communications channel between the Client’s
NTLA and the Luna appliance's NTLS.
Network Trust Links use digital certificates to verify the identities of connecting clients.
During the initial Luna system configuration, the Administrator generated a unique certificate that identifies the Luna appliance. Similarly, each Client must generate its own certificate that identifies it uniquely. Both the Client and the Luna appliance use these certificates to verify the other’s identity before an NTL is created between them.
To create an NTL, the Client and Luna appliance must first exchange certificates. Once the certificates have been exchanged, the Client registers the Luna SA’s certificate in a trust list, and the Luna appliance, in turn, registers the Client’s certificate in its list of clients.
When the certificates have been exchanged and registered at each end, the NTL is ready to use.
Copy the HSM Appliance Server Cert to a Client
Open a terminal window on the Client, and change directory to /usr/ safenet/lunaclient/bin.
Securely transfer the server.pem file from the Luna SA, using scp command
$> scp admin@<LunaIP>:server.pem . admin@<LunaIP>'s password:
Note the dot (.) at the end of the command, denoting “place the resulting file in the current directory”.
Verify that the Server Certificate has arrived on the Client.
Register the HSM Appliance Server Cert with the Client
Use vtl, the supplied client-side tool for managing HSM client/server setup.
Invoke the vtl addServer command so that the client can create a secure connection with the
HSM.
$:> ./vtl addServer -n <LunaIP or Hostname> -c server.pem
Administration Guide – Enterprise / Business Version 60 18-‐Apr-‐2016
Now you can confirm whether the server has been added by using the following command:
$:>./vtl listservers
Create a Client Cert
Begin by creating a certificate and private key for the client, using the vtl command-line interface. (vtl is located in the usr/safenet/lunaclient/bin directory)
$:> ./vtl createCert -n <ClientIP>
You should see the following message with information about the Private key and
Cretificate.
Private Key created and written to: /usr/safenet/lunaclient/cert/client/<ClientIP>Key.pem
Certificate created and written to: /usr/safenet/lunaclient/cert/client/<ClientIP>.pem
Copy the Client Cert to the HSM Appliance
Copy the client certificate that you created to the HSM appliance using the following command and then you will be required to enter the admin password for the Luna HSM.
$:> scp /usr/safenet/lunaclient/cert/client/<ClientIP or Hostname>.pem admin@<LunaIP>: admin@<LunaIP>'s password:
Register the Client Cert with the HSM Appliance
The client certificate must be registered with the HSM Appliance. You must be connected to the HSM Appliance and logged in as admin. The command is: lunash:> client register -client <ClientName> -hostname <Client hostname> or -ip
<ClientIP>
The <ClientName>, above can be any string that allows you to easily identify this client - many people use the hostname. The command is expecting to find a client certificate filename that matches the client’s hostname (or ip-address if you are not using DNS hostnames), as you provide it here. In other words, this is a check that you are registering the client whose .pem file you created in the previous steps and copied to the HSM appliance. You can register several clients to the appliance.
Administration Guide – Enterprise / Business Version 61 18-‐Apr-‐2016
Now you should confirm whether the client has been registered using the following command and you will see a list of registered clients. lunash:> client list
Assign Client to Partition
Now, assign the registered client to the HSM Partition. The command is: lunash:> client assignPartition -client <ClientName> -partition <PartitionName>
To verify, look at the HSM Partition assigned to the client. lunash:> client show -client <ClientName>
The result of the commands is provided.
Verify Client Setup
Before beginning to use a Client application with your newly configured Luna system, you can verify that the foregoing setup has been properly performed. On the client computer, use the following command to see a list of partitions.
$:> ./vtl verify
Administration Guide – Enterprise / Business Version 62 18-‐Apr-‐2016
If you get an error message, then some part of the configuration has not been properly completed. Retrace the procedure.
At this point, the client and HSM are configured and registered with each other. You can now begin to use the Luna HSM with your application.
High Availability Groups
For mission-‐critical applications that require uninterrupted up-‐time, the Luna SA's High
Availability (HA) feature allows multiple Luna SA appliances to be grouped together to form one virtual device. In an HA configuration, service is maintained even if one or several physical devices are unavailable.
Perform the necessary setup on the Luna SA appliances that you will be including in the HA group, including
• the network setup and naming,
• the policy settings needed for HA (cloning),
• the initialization of the Luna SA appliances into a common cloning domain (same red PED Key for Trusted Path Authentication),
• the creation of partitions with matching Passwords across all the Luna SA appliances, and
• the recording of Partition serial numbers
Register your Client(s) with each Partition that will be part of the HA group on your Client, use the vtl utility to configure the HA group and then add the Partitions (on the respective
Luna Sas) to that HA group.
The following are the set of commands to be used to create a HA group. You can get the serial for the individual partitions using the following command. lunash:> hsm show
Administration Guide – Enterprise / Business Version 63 18-‐Apr-‐2016
Please ensure that all partitions that participate in the HA group have the same
password.
# vtl haAdmin newGroup -serialNum 474770011 -label ha-health -password qwerty123456789
#vtl haAdmin addMember -group 1474770011 -serialNum 474770033 password qwerty123456789
#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 HS 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.
Administration Guide – Enterprise / Business Version 64 18-‐Apr-‐2016
Installation Verification
Once you’ve completed your Key Manager and Safenet Luna SA HSM installation you can run the KMVerification script. The script will display a message similar to the one shown below if your installation was completed successfully:
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.
Administration Guide – Enterprise / Business Version 65 18-‐Apr-‐2016
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.
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.
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:
Administration Guide – Enterprise / Business Version 66 18-‐Apr-‐2016
• Symphony Administrator and Support Roles – Responsible for creating and managing
Symphony user accounts as well as configuring LDAP sync and SSO authentication.
• Compliance Office Roles – Can also manage user accounts but is also responsible for active compliance features and monitoring user activity.
• The End-‐User – will create rooms and chats in support of their daily activities.
• Service Accounts – used by service applications such as the Directory Bridge, Content
Export Bridge and Bots developed using the Symphony SDK
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:
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:
Table: Roles part 1 of 2:
Administration Guide – Enterprise / Business Version 67 18-‐Apr-‐2016
SUPER
ADMINISTRATOR
ADMINISTRATOR L2 SUPPORT L1 SUPPORT
USER
PROVISIONING
INDIVIDUAL
Can create end-user accounts (i.e. users with Role = Individual)
Can deactivate end-user accounts
Can activate end-user accounts
Can create service accounts
Can activate service accounts
Can de-activate service accounts
Can manage users in bulk
View usage statistics
Can assign the Administrator role
Can remove the Administrator role
Can assign the Super Administrator role
Can remove the Super
Administrator role
Can assign the L1 role
Can remove the L1 role
Can assign the L2 role
Can remove the L2 role
Can assign the Compliance Officer role
Can remove the Compliance Officer role
Can assign the Super Compliance
Officer role
Can remove the Super Compliance
Officer role
Can modify end-user accounts
Can modify service accounts
Can login using username/password
Can login using SSO
Can login using shared secret
Can configure SSO for the pod
Can enable SSO for the pod
Can disable SSO for the pod
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE (remove only)
TRUE (remove only)
TRUE (remove only)
TRUE (remove only)
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
The User Provisioning role is available for the service account supporting the directory bridge software – see LDAP Sync section in this guide. With LDAP Sync, accounts can be created and modified directly from the corporate directory and the user-provisioning column in this table shows what functions are supported.
Table: Roles part 2 of 2:
Administration Guide – Enterprise / Business Version 68 18-‐Apr-‐2016
Can manage CE
Can modify pod entitlements
Can update feature entitlements for end-user accounts
Can update feature entitlements for service accounts
Can reset password
Can trigger password reset
Can search users in the company directory
Can search for chat rooms
Can access DOWNLOADS screen and hence download components
Enable Can Communicate
Externally at the pod level
Disable Can Communicate
Externally at the pod level
Enable Can Send Files
Externally at the pod level
Disable Can Send Files
Externally at the pod level
Enable Require Warnings for
External Communications at the pod level
Disable Require Warnings for
External Communications at the pod level
Enable Can Communicate
Externally at the account level
Disable Can Communicate
Externally at the account level
Enable Can Send Files
Externally at the account level
Disable Can Send Files
Externally at the account level
Enable Disclaimers Insertion at the pod level
Disable Disclaimers Insertion at the pod level
Edit disclaimer content
View the Disclaimer Insertion audit trail
Access the base admin APIs
(basically the initial gateway to any admin endpoints)
SUPER
ADMINISTRATOR
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
ADMINISTRATOR
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
L2 SUPPORT
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
L1 SUPPORT
USER
PROVISIONING
INDIVIDUAL
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
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.
Administration Guide – Enterprise / Business Version 69 18-‐Apr-‐2016
ALLOWED ACTION
Can create end-user accounts (i.e. users with Role = Individual)
Can deactivate end-user accounts
Can activate end-user accounts
Can manage users in bulk
Can assign the Compliance Officer role
Can remove the Compliance Officer role
Can assign the Super Compliance Officer role
Can remove the Super Compliance Officer role
Can modify end-user accounts
Can login using username/password
Can reset password
Can trigger password reset
Can search users in the company directory
Can search for chat rooms
Enable Disclaimers Insertion at the pod level
Disable Disclaimers Insertion at the pod level
Edit disclaimer content
View the Disclaimer Insertion audit trail
Access the base admin APIs (basically the initial gateway to any admin endpoints)
SUPER
COMPLIANCE
OFFICER
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
COMPLIANCE
OFFICER
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
Roles for Information Barriers
ALLOWED ACTION
Create IB Group
Disable IB Group
Rename IB Group
Add member to IB Group
Remove member from IB Group
View IB Group Detail page
View IB Group Audit Trail
View List of IB Groups
Import Group csv file
View List of group import reports
View group import report
Create IB Policy
Disable IB Policy
View IB Policy Detail Page
Super
Administrator
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
Super
Compliance
Officer
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
User
Provisioning
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
View IB Policy Audit Trail Page
View List of IB Policies
Enable logging of IB enforcement decisions to CE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
TRUE
Disable logging of IB enforcement decisions to CE TRUE TRUE TRUE
Please refer to the Compliance section for more information on Information barriers.
Super Admins:
- can reset a password (set a string) on any role
- can trigger password reset email on any role
Compliance Officer/Super Compliance Officer/Admin:
- can no longer reset or trigger password reset email on an account. This is to prevent an admin from taking over the account of a user who is theoretically more powerful (CO/SCO), say. Ability to set a password allows them to theoretically take over an account. Hence this is blocked. And some of the customers told us that
Administration Guide – Enterprise / Business Version 70 18-‐Apr-‐2016
CO/SCO/A will not be in the business of even triggering a password rest. Hence this is blocked too.
L1/L2:
- L1 and L2 should continue to be able to trigger password reset for all roles AND set a password for roles of equal or lesser privilege. i.e. for all roles, the L1 and L2 roles should see the "Email password reset link" button and for some roles see the
"Assign new password" link. For example, if you are an L1 support person then you can email a password reset link to anyone but can reset the password for other L1 support people and individual users only, not to L2, Admin, Super Admin,
Compliance or Super Compliance users.
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
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 71 18-‐Apr-‐2016
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 72 18-‐Apr-‐2016
Editing a user
• To edit a user, select MANAGE USERS 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 73 18-‐Apr-‐2016
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.
Administration Guide – Enterprise / Business Version 74 18-‐Apr-‐2016
Promoting an end user to admin
• Click on the Account Settings.
• Select the Administrator box.
Changing a user’s password
• Select Account Security to modify a user’s password.
• Select to send a password reset link to the user (as shown below) or assign a new password manually.
• 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
Administration Guide – Enterprise / Business Version 75 18-‐Apr-‐2016
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.
We use the same process to create a service user account as we used previously for creating an end-user account. When the <CREATE AN ACCOUNT> option is selected, Symphony presents the Admin with the create user form.
Selecting the Service Account option in the high-level menu above will display the form shown below:
You will also notice Feature entitlement options and fields for assigning the service account to a specific organization. These fields are not required and can be ignored at this time. Fill in the required Fields.
Note for LDAP Sync: When configuring the service account to support LDAP Sync you must configure it as an Admin role
Administration Guide – Enterprise / Business Version 76 18-‐Apr-‐2016
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.
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.
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 MANAGE USERS and then selecting ACCOUNT SETTINGS, 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
Administration Guide – Enterprise / Business Version 77 18-‐Apr-‐2016
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
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, each feature is allowed and you will see “Manage at user level” against each of the three features (please refer back to the screenshot above if
Administration Guide – Enterprise / Business Version 78 18-‐Apr-‐2016
this is not clear). 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.
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.
Enabling feature settings for new users by default
When you first provision your pod, each feature except “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 USERS feature does NOT yet allow admin’s 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 with the MANAGE USERS option (see section entitled “Making changes to an individual user” below)
The screen extract below shows the relevant settings for activating Twitter content for all new users.
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.
Administration Guide – Enterprise / Business Version 79 18-‐Apr-‐2016
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 MANAGE USERS option (see section below)
Enabling External Communications (sharing files is not yet available)
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. Many regulated organizations will prefer to enable this feature at the user level which we describe in a section below.
Once this feature has been activated for a given user, that user can create one-to-one IM conversations with external users after first searching for them.
Note: Both participants must have External communications activated by their respective admins for this feature to work.
Users who have been granted the Communicate Externally feature will be searchable in the global Symphony directory and will be able to search for and then connect with external users. Details on how to do this are provided in the user guide.
Users of the public version of Symphony must first request a connection with an enterprise or business user located on a private pod. Enterprise and Business users can send messages to public users and private pod users without first requesting a connection.
Enabling “Can Send Files Internally”
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 listed by default when you first activate your Pod):
.doc, .png, .jpg, .cls, .pdf, .pptx, .tiff, .x-tiff, .docx, .ppt, .tif, .gif, .jpeg, .xlsx
Follow these steps to whitelist file extensions:
1. Enable the “Can Send Files” feature 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
Administration Guide – Enterprise / Business Version 80 18-‐Apr-‐2016
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.
Making changes to an individual user
Use the MANAGE USERS option located on the left nav. Then click on a user’s name and select ACCOUNT SETTINGS to enable the features you want to activate as shown below:
Note: There is currently no way to set the three entitlement features at the point of creating the account (either directly using the CREATE A USER option or indirectly using the
BULK MANAGE USERS option). Admin’s must first create the account and then use the
MANAGE USERS option in the left nav to edit the user’s account settings.
Managing Applications
Symphony provides APIs for Extending and Enriching the symphony experience with new functionality and 3 rd
–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.
Developer Access to the APIs is available on the symphony developers site to organizations that have signed the Symphony MSA.
• Request access: https://symphony.com/developers
• Developer site: https://developers.symphony.com/
Once the developer has logged in, they will be presented with guides and references materials for each API. The remainder of this section focuses on the process of managing user access to applications using the APP MANAGEMENT feature as well as the reviewing the steps for installing new in-house applications.
Installing a New Application
Administration Guide – Enterprise / Business Version 81 18-‐Apr-‐2016
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 Register New button. Symphony will present the following form
(fields marked with stars are required):
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.
Administration Guide – Enterprise / Business Version 82 18-‐Apr-‐2016
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 Register 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 3 rd
-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.
To manage at a system-wide level either click on the App Entitlements link in the APP
MANAGEMENT screen (see screenshot above), or alternatively select APP
ENTITLEMENTS from the EDIT ENTITLEMENTS Tab located in the left Nav (shown below).
Once this is selected, the Admin will see the following interface:
Administration Guide – Enterprise / Business Version 83 18-‐Apr-‐2016
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
App Entitlements option within the User Detail screen shown below:
Administration Guide – Enterprise / Business Version 84 18-‐Apr-‐2016
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:
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 messaging requesting the installation of .net
3.5 or 4.0.
Installation Instructions - Connecting the client to your Private Pod URL
In previous versions of the Desktop client for Windows, two mechanisms were provided for connecting the client to the URL of a private pod. The process (which will be updated) is more complex in this new version of the client and is described below:
Administration Guide – Enterprise / Business Version 85 18-‐Apr-‐2016
1. Login into the Admin Portal of your private pod
2. Select the DOWNLOAD option in the left nav.
3. Select the Desktop client for Windows (this is an MSI file - first download it)
4. Then verify the digital signature of the downloaded MSI file in the Windows file properties menu. If the file is signed by Symphony, then it is a valid file.
5. If the installation is successful, a shortcut is added to the Windows desktop
6. Right click on the shortcut and display Properties
7. Locate the installation path
Administration Guide – Enterprise / Business Version 86 18-‐Apr-‐2016
8. Copy Symphony.pgx located under your <install path>/minuet/symphony/bin/apps to a temp location such as c:\temp
9. Navigate to your temp folder and rename Symphony.pgx to Symphony.zip (Windows may ask you to confirm the renaming of the file extension)
10. Unzip the Symphony.zip file and you will see a new Symphony folder
11. Navigate to the Symphony folder and open config.json using notepad or any text editor and modify the URL to <yourPodURL>.com, and save the file
12. Inside the Symphony folder, select all files and right click, select Send to -‐> Compressed
(zipped) folder, and name the file Symphony.zip
13. Rename Symphony.zip to Symphony.pgx (Again, Windows may ask for confirmation)
14. Copy Symphony.pgx back to <your installed path>/minuet/symphony/bin/apps
Once you have completed these steps you can run Symphony following the instructions below.
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 or 8 as shown below
Installing Symphony on multiple users’ computers
Follow your organization’s procedure to deploy the MSI installer on your end users’ computers. Remember that they also need to change the URL (see section above). This can be automated by copying the Symphony.pgx file to the directory containing the Symphony executable on each computer that will run the Symphony client. This step can be automated.
Administration Guide – Enterprise / Business Version 87 18-‐Apr-‐2016
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
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 https://symphony.MYCOMPANY.com/login/sso/acs as long as MYCOMPANY.com was whitelisted during initial installation.
Administration Guide – Enterprise / Business Version 88 18-‐Apr-‐2016
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.
After successfully logging in to your Symphony account using your corporate credentials, click Next.
You can then select to Switch on SSO.
Administration Guide – Enterprise / Business Version 89 18-‐Apr-‐2016
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:
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:
Administration Guide – Enterprise / Business Version 90 18-‐Apr-‐2016
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 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:
Administration Guide – Enterprise / Business Version 91 18-‐Apr-‐2016
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
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.
Administration Guide – Enterprise / Business Version 92 18-‐Apr-‐2016
Sync(Des;na;on(
Service)User)Account)
Security(Key(
Persistent(Data(
(
Request(
Process(
(
Response(
Process(
Symphony(Private(Pod(
Source)to)Des0na0on)
Users(
Distribu;on(Lists(
Groups((En;tlement)(
Sync(Pipes(
Directory)Bridge)
Corporate(
LDAP(
Directory(
Sync(Classes((
Include(filter:((userparam=SymphonyUser)(
Directory(Bridge(
Sync(Source(
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 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.
Administration Guide – Enterprise / Business Version 93 18-‐Apr-‐2016
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:
•
•
•
•
•
•
•
UnboundID Identity Data Store
UnboundID Identity Proxy (3.x)
Alcatel-Lucent 8661 Directory Server
Alcatel-Lucent 8661 Directory Proxy Server (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
•
•
512 megabytes of memory should be made available to LDAP Sync. It is more likely to be CPU-bound than memory-bound.
Operating System: Linux RHEL Fedora 2015.03 (This AWS supported OS has been validated by Symphony)
Administration Guide – Enterprise / Business Version 94 18-‐Apr-‐2016
•
JVM: Java 7 Standard Edition, Enterprise Edition - a Java development kit (JDK) is recommended
•
JVM 64-bit is recommended
•
Virtual Servers: both on-premises and cloud-hosted are supported
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 info 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.
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.
Administration Guide – Enterprise / Business Version 95 18-‐Apr-‐2016
The following table lists what happens when the Symphony “Symphony Users Group” is or is NOT enabled:
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 96 18-‐Apr-‐2016
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
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.
Administration Guide – Enterprise / Business Version 97 18-‐Apr-‐2016
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) then the weakest of the two roles gets assigned and an error is logged in the log file.
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.
In order to avoid unintended consequences, Admins should manage users 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 10mins. This can happen when “Symphony Users” is configured. Please be patient if this happens.
Downloading the Directory Bridge
The Directory Bridge server image can be obtained by using the <DOWNLOAD> option located in the left Nav. of the admin Portal. You should then select the DirectoryBridge-
<version>-<date>.RPM file.
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 <file>
This will create user symphonyldapsync, install the software at
/opt/DirectoryBridge, which we will hereafter refer to as $syncroot.
Administration Guide – Enterprise / Business Version 98 18-‐Apr-‐2016
Note: this application logs to a directory named “logs” in the installation directory (hereafter referred to as $syncroot). It is sometimes desirable to link the “logs” directory to a separate mount.
For an update of an existing installation: sudo rpm --upgrade <file>.
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 bak bat
Stores the physical backup files used with the backup command-line tool
Stores Windows-based command-line tools for the
Identity Data Store bin classes config db
Stores UNIX/Linux-based command-line tools for the
Identity Data Store
Stores any external classes for server extensions
Stores the configuration files for the backends (admin, config) as well as the directories for messages, schema, tools, and updates
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- notices lib locks
Stores any legal notices for dependent software used with the Identity Data Store
Stores any scripts, jar, and library files needed for the server and its extensions
Stores any lock files in the backends
Administration Guide – Enterprise / Business Version 99 18-‐Apr-‐2016
logs resource revert- update revert- update.bat
Stores log files for the Identity Data Store
Stores the MIB files for SNMP setup The setup tool for UNIX/Linux systems setup.bat
uninstall
The setup tool for Windows systems
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
The revert-update tool for UNIX/Linux systems
The revert-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:
$> 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
Administration Guide – Enterprise / Business Version 100 18-‐Apr-‐2016
“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<port number will change each time, accept default>]
Do you want to enable LDAPS? (yes / no) [no]
Do you want to enable StartTLS? (yes / no) [no]
By default the server listens on all available network interfaces for client connections.
Would you like to specify particular addresses on which this server will listen for client connections? (yes / no) [no]
An adequate amount of memory must be assigned to the server for optimal performance. Choose the option that best characterizes how this installation should be allocated memory:
For the Memory allocation choice:
1. Aggressive – Used for production deployments
2. Semi-Aggressive
3. Minimal – Used for QA and evaluation deployments
4. Manual
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
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
Administration Guide – Enterprise / Business Version 101 18-‐Apr-‐2016
5.
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
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
(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
Administration Guide – Enterprise / Business Version 102 18-‐Apr-‐2016
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"
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="
SYNC_SRC="Microsoft Active Directory Source"
USERS_SYNC_DEST="Users Destination"
USERS_SYNC_CLASS="Users to Symphony Sync Class"
USERS_SYNC_PIPE="Users to Symphony Sync Pipe"
USERS_ATTRIBUTE_MAP="Users to Symphony Attribute Map"
GROUPS_SYNC_DEST="Groups Destination"
GROUPS_SYNC_PIPE="Groups to Symphony Sync Pipe"
GROUPS_SYNC_CLASS="Groups to Symphony Sync Class"
GROUPS_ATTRIBUTE_MAP="Groups to Symphony Attribute Map"
DISTROLISTS_SYNC_DEST="Distribution Lists Destination"
DISTROLISTS_SYNC_CLASS="Distribution Lists to Symphony Sync Class"
DISTROLISTS_SYNC_PIPE="Distribution Lists to Symphony Sync Pipe"
DISTROLISTS_ATTRIBUTE_MAP="Distribution Lists to Symphony Attribute Map"
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
Administration Guide – Enterprise / Business Version 103 18-‐Apr-‐2016
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
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 --publishername "Server SDK Extension Debug Logger" --set enabled:true
10.
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)"
11. 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
Administration Guide – Enterprise / Business Version 104 18-‐Apr-‐2016
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 --pipename "Users to Symphony Sync Pipe" --bindDN "cn=Directory Manager" -
-bindPassword NotReallyThePassword --port XXXX
ß
-‐ default port number from setup
$> ./realtime-sync set-startpoint --end-of-changelog --pipename "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
12. 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:
Administration Guide – Enterprise / Business Version 105 18-‐Apr-‐2016
dn: CN=Ruth Reynolds,CN=Users,DC=fakecorp,DC=local
dn: CN=Super Man,CN=Users,DC=fakecorp,DC=local 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
13. 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 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"
# Enter the service account name symphony-‐user="LDAPSystem"
# and the shared secret associated with this account symphony-‐auth="123Ro+A2CXsx3GDiKZm2YDawTmfZo4j4gOrheAOMfEE="
# SYNC CONFIGURATION – replace “fakecorp”
# To configure the “All Symphony Users Group” please edit the following line: symphony-‐users-‐ldap-‐group="cn=Symphony
Users,cn=Users,dc=fakecorp,dc=local"
# ATTRIBUTE MAPPING
# The username attribute is used to associate LDAP entries with Symphony users ldap-‐username-‐attr=sAMAccountName
# 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
Administration Guide – Enterprise / Business Version 106 18-‐Apr-‐2016
ldap-‐memberof-‐attr=memberOf
14. Configure LDAP Sync group mappings by first copying the example file:
$>cp groupMappings-example.json groupMappings.json
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=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"]
}
]
15. Configure LDAP Sync user attribute mappings by first copying the example file:
$>cp userAttributeMappings-example.json userAttributeMappings.json
[
{
"symphony": "deptName",
"ldap": "department"
},
Administration Guide – Enterprise / Business Version 107 18-‐Apr-‐2016
attribute(name
assetClass deptName displayName divName givenName industry jobFunction location mail memberOf sn title isDisabled username photo photoUrl
{
"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: no yes yes yes no no yes no no
required description
no no name*of*the*asset*class*to*which*the*user's*work*is*related name*of*the*department*to*which*the*user*belongs yes no yes no no name*of*the*division*to*which*the*user*belongs the*user's*first*name industries*of*interest*for*the*user primary*location*of*the*user's*workplace email*address the*groups*that*the*user*is*a*member*of>*this*is*used*to*grant/remove*the*administrator*role the*user's*last*name professional*title used*to*power*activation/deactivation*of*Symphony*accounts system*username>*should*correspond*to*SAML*user*ID*if*applicable binary*data*for*avatar*photo 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
16. 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.
17. Use the file generated in the previous step as an argument to the resync utility, as follows.
$> ./resync --sourceInputFile entriesToSync.ldif --pipename "Users to Symphony Sync Pipe"
Administration Guide – Enterprise / Business Version 108 18-‐Apr-‐2016
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.
15. 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
$> ./dsconfig set-sync-pipe-prop --pipe-name "Groups to Symphony
Sync Pipe" --set started:true
16. 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 SymphonyGroup 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
Administration Guide – Enterprise / Business Version 109 18-‐Apr-‐2016
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.
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, 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, isCrossPodEnabled, canUpdateAvatar, canCreatePublicRoom
• InfoBarrier group membership: IB Name and ID number as listed in AC portal
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 and finally how to configure
Information barrier group membership.
[
{
Administration Guide – Enterprise / Business Version 110 18-‐Apr-‐2016
"dn": "CN=ComplianceOfficers,CN=Users,DC=fakecorp,DC=local",
"roles": ["COMPLIANCE_OFFICER"]
},
{
"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"]
}
]
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 a number of arguments. The expectation is that most of these would be pre-populated during installation of LDAP Directory Sync.
Administration Guide – Enterprise / Business Version 111 18-‐Apr-‐2016
A full list of the arguments supported by each Sync Destination follows.
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.
Administration Guide – Enterprise / Business Version 112 18-‐Apr-‐2016
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.
User Attributes
The following image illustrates an attribute map for users.
Administration Guide – Enterprise / Business Version 113 18-‐Apr-‐2016
The full list of "to-attribute" values that are accepted for Symphony users are as follows.
attribute(name
assetClass deptName displayName divName givenName industry jobFunction location mail memberOf sn title isDisabled username photo photoUrl
Group Attributes
no no yes no no no no yes yes yes
required description
no name*of*the*asset*class*to*which*the*user's*work*is*related no yes no yes no name*of*the*department*to*which*the*user*belongs name*of*the*division*to*which*the*user*belongs the*user's*first*name industries*of*interest*for*the*user primary*location*of*the*user's*workplace email*address the*groups*that*the*user*is*a*member*of>*this*is*used*to*grant/remove*the*administrator*role the*user's*last*name professional*title used*to*power*activation/deactivation*of*Symphony*accounts system*username>*should*correspond*to*SAML*user*ID*if*applicable binary*data*for*avatar*photo url*via*which*the*binary*data*for*the*photo*may*be*retrieved
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.
Sync Classes
A Sync Class defines how a type of LDAP entry is synchronized. The following image illustrates a Sync Class for users.
Administration Guide – Enterprise / Business Version 114 18-‐Apr-‐2016
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.
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).
Administration Guide – Enterprise / Business Version 115 18-‐Apr-‐2016
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.
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).
Administration Guide – Enterprise / Business Version 116 18-‐Apr-‐2016
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.
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.
Administration Guide – Enterprise / Business Version 117 18-‐Apr-‐2016
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
JVM 64-bit is recommended
CD Drive
Virtual Servers: both on-premises and cloud-hosted are supported
Note: if you plan to run the Content Export Bridge on the same server as the Key
Manager, then 16GB RAM will be required.
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
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.
Administration Guide – Enterprise / Business Version 118 18-‐Apr-‐2016
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.
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.
Administration Guide – Enterprise / Business Version 119 18-‐Apr-‐2016
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.
…
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.
Administration Guide – Enterprise / Business Version 120 18-‐Apr-‐2016
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
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
Administration Guide – Enterprise / Business Version 121 18-‐Apr-‐2016
-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 \
configuration.prepertites and key folder
//optional, the folder containing the
-
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
</dev/null > 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 podIDkeymanager.symphony.com:443 </dev/null > 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 122 18-‐Apr-‐2016
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 symphonyexternal-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
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:
Administration Guide – Enterprise / Business Version 123 18-‐Apr-‐2016
#[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/tomcatjuli.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 symphonyexternal-ceservice-centos70-0.14.0-45.x86_64.rpm
configuration properties
Information for pod access version=1.0.0 podURL=https://<OrgName>.symphony.com sharedKey= ThisIsYourSecurityKey archiveDirectory=/data/retention_result
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
Administration Guide – Enterprise / Business Version 124 18-‐Apr-‐2016
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:
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 singlececservice-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
Administration Guide – Enterprise / Business Version 125 18-‐Apr-‐2016
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.
• 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 126
18-‐Apr-‐2016
• 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) or Actiance format – see the screenshot below:
Administration Guide – Enterprise / Business Version 127 18-‐Apr-‐2016
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: 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
Administration Guide – Enterprise / Business Version 128 18-‐Apr-‐2016
Manual Export
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) or EML and 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.
Note: there is currently no facility to cancel an export once the process is initiated.
File names
AD HOC file names
the zip file name will be,
<a_/s_/e_><pod-name>_CD-<ContentDateUTC>_GD-
<GenDateUTC><GenTimestampInMillisecond>.zip the individual files are: in Actiance format, it will be
<pod-name>_CD-<ContentDateUTC>_GD-
<GenerationDateUTC><timestamp>_content_import.xml
<pod-name>_CD-<ContentDataUTC>_GD-
<GenerationDateUTC><timestamp>_conversation.xml
Administration Guide – Enterprise / Business Version 129 18-‐Apr-‐2016
In EML format, it will be
<SI/SP/SC>_ Part<N>_ CD-<ContentDateUTC>_GD-<GenerateDateUTC>_timestamp.xml
In Symphony format, it will be
<pod_name>_CD-<ContentDateUTC>_GD-<GenerateDateUTC><timestamp>.xml
File Names for frequent export
<a_/s_/e_><pod-name>_SD-<ContentStartDateHourUTC>_ED-
<ContentEndDateHourUTC>_GD-<GenDateUTC><GenTimestampInMillisecond>.zip
For Actiance format, it will be:
<pod-name>_SD-<ContentStartDateHourUTC>_ED-<ContentEndDateHourUTC>_GD-
<GenerationDateUTC><timestamp>_content_import.xml
<pod-name>__SD-<ContentStartDateHourUTC>_ED-<ContentEndDateHourUTC>_GD-
<GenerationDateUTC><timestamp>_conversation.xml
In EML format, it will be:
<SI/SP/SC>_Part<N>_SD-<ContentStartDateUTC>_ED-<ContentEndDateUTC>_ GD-
<GenerateDateUTC>_timestamp.xml
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:
<pod_name>_SD-<ContentStartDateHourUTC>_ED-<ContentEndDateHourUTC>_GD-
<GenerateDateUTC><timestamp>.xml
EML files contain the following:
• 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-
<streamID>_Part<n>Of<M>_ContentStartDateUTC-<Contentstartdate+time(UTC)>_ContentStopDateUTC-<Contentstopdate+time(UTC)>_GenTimestampUTC-
<file_generated_timestamp-in-millionsecond>.eml
• Symphony internal data integrity file: .JSON
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
Administration Guide – Enterprise / Business Version 130 18-‐Apr-‐2016
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:
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. <organization-name>tools.symphony.com. It can be accessed with the SFTP user name (podname-
ContentExporter) along with the password that was created during the activation process.
The password for the SFTP account is preset but can be changed in the admin portal. This user account is not a Symphony user account and cannot be used to log into the admin portal or Symphony client—it is only used for downloading the exported content. You cannot delete your content from the SFTP server.
Administration Guide – Enterprise / Business Version 131 18-‐Apr-‐2016
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%
Symphony%
Access%Control%
SFTP%
Server%
%
ZIP%
Files%
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
Administration Guide – Enterprise / Business Version 132 18-‐Apr-‐2016
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
Room setting update for the following settings:
Room Name
Room Description
Type of room (private / public)
Copy Enabled
Read Writable
Member Invitations
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
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.
Administration Guide – Enterprise / Business Version 133 18-‐Apr-‐2016
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 then in the xml content export, this is translated to:
<content>
<![CDATA[ -‐ testing **bold**, _italics_ and bullets ]]>
</content>
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>
<![CDATA[ test of star \*, dash \-‐ and underscore \_ ]]>
</content>
Administration Guide – Enterprise / Business Version 134 18-‐Apr-‐2016
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
Content Export Verification
A file entitled results.json is now 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
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.
Note: There is currently an issue with the way usage is reported across multiple export periods. If user A sends a message to user B on day 1, then the report will show that user
A sent this message on day 1
’s export. On day 2, user B reads the message and this event will be reported in the user summary. However user A will be shown as having sent the message again, even though user A did not send this message on Day 2. This issue will be addressed in a later release.
Content Export Schema
Administration Guide – Enterprise / Business Version 135 18-‐Apr-‐2016
The XML schema below provides the latest description of the information and format of the
Symphony content export.
Note: Free Attribute information for message suppression has been moved up one level and will no longer be nested within <eventinfo>.
<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://www.symphony.com" attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://www.symphony.com">
<xs:element name="log" type="logType"/>
<xs:complexType name="creationDateType">
<xs:sequence>
<xs:element type="xs:string" name="iso_8601" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="freeAttributeType">
<xs:sequence>
<xs:element type="xs:string" name="key"/>
<xs:element type="xs:string" name="value"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="freeAttributesType">
<xs:sequence>
<xs:element type="freeAttributeType" name="freeAttribute" maxOccurs="unbounded" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="userDetailsType">
<xs:sequence>
<xs:element type="xs:string" name="userId"/>
<xs:element type="xs:string" name="userName" minOccurs="0"/>
<xs:element type="xs:string" name="companyUserEmail" minOccurs="0"/>
<xs:element type="xs:boolean" name="isPerson"/>
<xs:element type="xs:string" name="firstName" minOccurs="0"/>
<xs:element type="xs:string" name="lastName" minOccurs="0"/>
<xs:element type="xs:string" name="prettyName" minOccurs="0"/>
<xs:element type="freeAttributesType" name="freeAttributes" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="userType">
<xs:sequence>
<xs:element type="xs:string" name="userId"/>
<xs:element type="xs:string" name="companyUserEmail" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="initiatorType">
<xs:sequence>
Administration Guide – Enterprise / Business Version 136 18-‐Apr-‐2016
<xs:element type="userType" name="user"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="postedByDelegateType">
<xs:sequence>
<xs:element type="userType" name="user"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="emailSenderType">
<xs:sequence>
<xs:element type="userType" name="user"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="recipientsType">
<xs:sequence>
<xs:element type="userType" name="user" maxOccurs="unbounded" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="attachmentType">
<xs:sequence>
<xs:element type="xs:string" name="filename"/>
<xs:element type="xs:string" name="filetype"/>
<xs:element type="xs:string" name="description" minOccurs="0"/>
<xs:element type="recipientsType" name="downloadedBy" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="attachmentsType">
<xs:sequence>
<xs:element type="attachmentType" name="attachment" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:simpleType name="contentType">
<xs:restriction base="xs:string">
<xs:enumeration value="text/plain"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="eventInfoType">
<xs:sequence>
<xs:element type="xs:string" name="content"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="messageInfoType">
<xs:sequence>
<xs:element type="xs:string" name="comment" minOccurs="0"/>
<xs:element type="xs:string" name="content" minOccurs="0"/>
<xs:element type="xs:string" name="richMediaContent" minOccurs="0"/>
<xs:element type="xs:string" name="CustomEntities" minOccurs="0"/>
<xs:element type="xs:string" name="Disclaimer" minOccurs="0"/>
Administration Guide – Enterprise / Business Version 137 18-‐Apr-‐2016
</xs:sequence>
<xs:attribute type="contentType" name="contentType"/>
<xs:attribute type="xs:string" name="encoding"/>
<xs:attribute type="xs:boolean" name="isChime"/>
<xs:attribute type="xs:boolean" name="shared"/>
<xs:attribute type="xs:string" name="originalTimestamp"/>
<xs:attribute type="xs:string" name="originalMessageID"/>
<xs:attribute type="xs:string" name="originalAuthorID"/>
<xs:attribute type="xs:string" name="originalAuthorEmail"/>
<xs:attribute type="xs:string" name="onBehalfOfID"/>
<xs:attribute type="xs:string" name="onBehalfOfEmail"/>
<xs:attribute type="xs:string" name="messageTimestamp"/>
</xs:complexType>
<xs:simpleType name="socialMessageType">
<xs:restriction base="xs:string">
<xs:enumeration value="BOARD"/>
<xs:enumeration value="CHAT ROOM"/>
<xs:enumeration value="WALL POST"/>
<xs:enumeration value="SHARED WALL POST"/>
<xs:enumeration value="INSTANT CHAT"/>
<xs:enumeration value="LIKED WALL POST"/>
<xs:enumeration value="UNKNOWN"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="eventActionType">
<xs:restriction base="xs:string">
<xs:enumeration value="CREATE ROOM"/>
<xs:enumeration value="ACTIVATE ROOM"/>
<xs:enumeration value="DEACTIVATE ROOM"/>
<xs:enumeration value="JOIN ROOM"/>
<xs:enumeration value="LEAVE ROOM"/>
<xs:enumeration value="PROMOTED TO ROOM OWNER"/>
<xs:enumeration value="DEMOTED FROM ROOM OWNER"/>
<xs:enumeration value="UPDATE ROOM SETTING"/>
<xs:enumeration value="KICK USER OUT OF ROOM"/>
<xs:enumeration value="INVITE USER TO ROOM"/>
<xs:enumeration value="DELETE WALL POST"/>
<xs:enumeration value="REQUEST JOIN ROOM"/>
<xs:enumeration value="REACTIVATE ROOM"/>
<xs:enumeration value="SUPPRESS MESSAGE"/>
<xs:enumeration value="SEND EMAIL NOTIFICATION"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="eventSubject">
<xs:restriction base="xs:string">
<xs:enumeration value="CHAT ROOM"/>
<xs:enumeration value="INSTANT CHAT"/>
<xs:enumeration value="WALL POST"/>
Administration Guide – Enterprise / Business Version 138 18-‐Apr-‐2016
<xs:enumeration value="EMAIL NOTIFICATION"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="recordEnumerationType">
<xs:restriction base="xs:string">
<xs:enumeration value="EVENT"/>
<xs:enumeration value="SOCIAL MESSAGE"/>
<xs:enumeration value="NOTIFICATION"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="scopeType">
<xs:restriction base="xs:string">
<xs:enumeration value="PRIVATE"/>
<xs:enumeration value="PUBLIC"/>
<xs:enumeration value="UNKNOWN"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="triggerType">
<xs:restriction base="xs:string">
<xs:enumeration value="SYSTEM"/>
<xs:enumeration value="USER"/>
<xs:enumeration value="UNKNOWN"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="emailNotificationRecordType">
<xs:complexContent>
<xs:extension base="eventRecordType">
<xs:sequence>
<xs:element type="emailSenderType" name="emailSender"/>
</xs:sequence>
<xs:attribute type="triggerType" name="trigger"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="eventRecordType">
<xs:complexContent>
<xs:extension base="recordType">
<xs:sequence>
<xs:element type="recipientsType" name="affectedUsers" minOccurs="0"/>
<xs:element type="recipientsType" name="recipients" minOccurs="0" />
<xs:element type="freeAttributesType" name="freeAttributes" minOccurs="0"/>
<xs:element type="eventInfoType" name="eventInfo"/>
</xs:sequence>
<xs:attribute type="eventSubject" name="eventSubject"/>
<xs:attribute type="eventActionType" name="eventAction"/>
<xs:attribute type="socialMessageType" name="relatedSocialMessageType"/>
</xs:extension>
</xs:complexContent>
Administration Guide – Enterprise / Business Version 139 18-‐Apr-‐2016
</xs:complexType>
<xs:complexType name="socialMessageRecordType">
<xs:complexContent>
<xs:extension base="recordType">
<xs:sequence>
<xs:element type="freeAttributesType" name="freeAttributes" minOccurs="0"/>
<xs:element type="postedByDelegateType" name="postedByDelegate" minOccurs="0"/>
<xs:element type="recipientsType" name="sentTo" minOccurs="0"/>
<xs:element type="recipientsType" name="readBy" minOccurs="0"/>
<xs:element type="attachmentsType" name="attachments" minOccurs="0"/>
<xs:element type="messageInfoType" name="messageInfo" />
</xs:sequence>
<xs:attribute type="socialMessageType" name="socialMessageType"/>
<xs:attribute type="xs:boolean" name="isArchived"/>
<xs:attribute type="xs:string" name="platform"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:complexType name="recordType" abstract="true">
<xs:sequence>
<xs:element type="xs:string" name="threadId" minOccurs="0"/>
<xs:element type="xs:string" name="roomName" minOccurs="0"/>
<xs:element type="xs:string" name="messageId"/>
<xs:element type="creationDateType" name="creationDate"/>
<xs:element type="initiatorType" name="initiator"/>
</xs:sequence>
<xs:attribute type="xs:integer" name="id"/>
<xs:attribute type="recordEnumerationType" name="recordType"/>
<xs:attribute type="scopeType" name="scope"/>
</xs:complexType>
<xs:complexType name="fileType">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute type="xs:string" name="name"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:complexType name="filelistType">
<xs:sequence>
<xs:element type="fileType" name="file" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="userlistType">
<xs:sequence>
<xs:element type="userDetailsType" name="userDetails" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
Administration Guide – Enterprise / Business Version 140 18-‐Apr-‐2016
<xs:complexType name="manifestType">
<xs:sequence>
<xs:element type="userlistType" name="userlist" minOccurs="0"/>
<xs:element type="xs:integer" name="userCount" minOccurs="0"/>
<xs:element type="filelistType" name="filelist" minOccurs="0"/>
<xs:element type="xs:integer" name="fileCount" minOccurs="0"/>
<xs:element type="xs:integer" name="firstRecord"/>
<xs:element type="xs:integer" name="recordCount"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="logType">
<xs:sequence>
<xs:element type="recordType" nillable="true" name="record" maxOccurs="unbounded" minOccurs="0"/>
<xs:element type="manifestType" name="manifest"/>
</xs:sequence>
<xs:attribute type="xs:long" name="id"/>
<xs:attribute type="xs:string" name="podName"/>
<xs:attribute type="xs:string" name="schemaVersion" use="required" fixed="1.3.0"/>
</xs:complexType>
</xs:schema>
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 141 18-‐Apr-‐2016
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 142
18-‐Apr-‐2016
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]+/
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 and add users to this groupAssign users to IB Groups
–
Activate Block Policy between groups
Administration Guide – Enterprise / Business Version 143 18-‐Apr-‐2016
Select an IB Group from the list::
Block members of the IB group from communicating with another group:
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. To configure disclaimers, select Disclaimers from the left Nav.
Administration Guide – Enterprise / Business Version 144 18-‐Apr-‐2016
Disclaimers can also be set for individual users. This is accomplished by first creating a named disclaimer and then assigning the named disclaimer at the user level. In the example below a disclaimer called “External Communications” is being created.
This 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.
Administration Guide – Enterprise / Business Version 145 18-‐Apr-‐2016
List ALL ROOMS and Monitor
Compliance officers can list all the rooms on their Symphony Pod, using the ALL ROOMS option located in the left Nav.,
enabling compliance officers to list all the rooms created on their Pods.
Rooms can be filtered/searched by:
•
Active/Deactivated rooms
•
Specific users or groups of users
•
Activity date
•
Room name
Scope can be either Internal or External.
Symphony Platform -‐ Installing the Agent Server
Introduction
This section is an extract from information provided on the Symphony developer site: developers.symphony.com. It describes the provisioning of the Agent server, a server providing abstraction of encryption and Pod access for developers of messaging bots, autoresponders and also provisioning programs.
Once the server has been installed, the Agent API provides a RESTful interface and the
Agent API has also been specified as a Swagger YAML interface definition providing support for a range of programming languages. A simulator to help programmers design and test applications prior to the installation of the Agent has also been provided on developers.symphony.com – for more information on the Simulator please refer to the guides provided on developers.symphony.com.
Administration Guide – Enterprise / Business Version 146 18-‐Apr-‐2016
Purpose and Scope of the Agent API
The purpose of the Agent API is to allow programmatic access to Symphony to send and receive messages (such programs are commonly referred to as Bots). The functionality of the API is defined by a set of User Stories, which describe a set of usage scenarios. Other scenarios may be possible, but the set of API methods provided are those needed to support the defined set of User Stories.
All methods will be rate limited at the server. The limits will depend on the type and size of pods, and will be outlined once empirical performance characterization of the interface has been established. Response headers will be included to give callers forward visibility of threshold limits.
User Stories supported by Version 1.0
IM Notification Bot
The IM notification bot can lookup the user ID of one or more users and then open an instant message stream to those users. If an existing IM stream exists which includes the bot user and the exact set of users requested then it will be returned, otherwise a new stream containing those users will be created.
The bot can then post messages into that stream.
Room Notification Bot
This Scenario describes a type of Bot which is a member of a chat room and which periodically posts messages into that room. The Bot knows which room it is supposed to post into and anyone who is an active member of that room will see all messages generated by the Bot.
Posted messages may contain formatting, hashtags, cashtags and user mentions.
The process of setting up the Bot, creating the chat room and granting access to the chat room to appropriate users are all manual setup steps.
Async Chat Bot
The async chat bot can read messages from and post messages to a stream of which it is a member. The bot will be required to know the ID of the stream in advance, and is described as asynchronous as it will be required to periodically request new messages which may have been posted into the stream.
Posted messages may contain formatting, hashtags, cashtags and user mentions.
User Presence Bot
The user presence bot can lookup the user ID of another user given an email address. It can then read and set the Symphony presence indication of that user.
The user presence bot can read the presence indications for all active users within the scope of the bot's administration context (i.e. all users in the Pod to which the bot belongs).
User Provisioning
A subset of the Agent API, provides support for programmatic account provisioning:
Administration Guide – Enterprise / Business Version 147 18-‐Apr-‐2016
• create a new user
• update an existing user
• retrieve a list of all user IDs
• retrieve user details
• get the user’s status
• update the user’s status as for the Agent API, the programmer guides and references for the provisioning API are available on developers.symphony.com
Deployment
The Agent API is implemented as a REST like API which is served by a process called the
Agent. This component, together with the Key Manager and the Bot process (API client) executes on the customer's premises. The Agent then connects across the Internet to the
Symphony servers. All communications between these components takes place over SSL protected HTTP, the authentication methods require a client authenticated TLS connection.
The interface between the Agent and the Symphony servers is private to Symphony and subject to change at any time. The interface between the Bot and the other components is a public API and subject to change management.
The contents of all user messages (chat posts etc.) sent as payload over that TLS protected channel are additionally encrypted by the Agent, using the end user's encryption keys. These keys are available only to the participants of the chat session and this therefore provides an
Administration Guide – Enterprise / Business Version 148 18-‐Apr-‐2016
additional layer of security against an intruder on the Internet and against access by
Symphony or its staff.
Agent Purpose
The purpose of the Agent process is
1. To encrypt the payload of messages sent and decrypt those received by caller of the API, thus relieving those processes of the need to implement encryption.
2. To provide a stable public API for bot developers to use while allowing private Symphony
APIs to change as necessary.
API Change Management
The API is defined in the YAML specification and detailed documentation can be generated from this using the online editor at http://editor.swagger.io
. Once finalized, the interface of all endpoints is immutable, if changes or additions to published endpoints become necessary then a new endpoint with a different version number segment in the URI path will be published.
Requests to any endpoint which include unknown or unexpected parameters will be treated as an error and return a 4XX HTTP response.
Endpoints which are to be removed from the API will be marked as deprecated in the interface specification and reference documentation and maintained for a period of at least six months.
The simulator implementation of the Agent process may support a configuration to disable deprecated endpoints, with this option enabled calls to the disabled methods will result in
HTTP response 420 Gone. This will be provided as a means of testing to discover usages of deprecated methods before they are finally removed from the API.
Notwithstanding any of the above, the security of the Symphony service is paramount and in the event that any security vulnerability is detected, any and all necessary steps to safeguard our customers' privacy will be taken without delay.
Authentication
When a bot process starts it will begin by connecting to an authentication endpoint on the
Symphony servers. The server endpoint will examine the client certificate provided in the
TLS session to identify the bot user and return a session token.
The bot then repeats this process, calling an identical API endpoint on the Key Manager, which returns another session token.
These two tokens, which should be treated as opaque data by the bot, must be presented in custom headers with each subsequent request made against the Agent.
This approach provides a cryptographically secure authentication mechanism for callers of the API without the need to burden the bot process with the need to perform any cryptographic operations. The secure authentication is implemented in the TLS layer and handled for the client by the SSL Socket library used to establish the network connection.
Administration Guide – Enterprise / Business Version 149 18-‐Apr-‐2016
Agent Simulator Installation
This section describes the steps necessary to download and install the Agent Simulator for development and testing scenarios. The Agent Simulator is a stand alone set of server processes which provide a dummy implementation of the Agent API and authentication endpoints without the need for any server back end. This is provided for development and testing purposes.
Platform Dependencies
The production Agent is certified for deployment on Centos, however the Agent Simulator is intended for development and testing purposes, and ideally it should be possible to deploy it on any system including a developer workstation.
The Agent (including the Simulator implementation) is implemented as a set of Java Web
Applications intended for deployment on Java 7 and Tomcat 8. As such this should be deployable on any Java capable platform and any standards compliant servlet container.
Example client programs supplied with the Agent Simulator are implemented as Java programs and Bash scripts using curl for access to the API endpoints. The curl based implementation approach was chosen to demonstrate that the API can be called from even the most rudimentary client platform and to show the mechanics of the API in the rawest form. This platform is not recommended for production client implementations.
The authentication of processes calling the API is performed by validating client TLS certificates and the version of curl used to run these scripts needs to support the presentation of client certificates.
The Agent Simulator is known to work correctly on Mac OS X. Versions of curl compiled against the NSS secure sockets library are known to be problematic. Developers wishing to deploy the examples on platforms whose default curl implementation is compiled against
NSS (which includes current versions of RedHat and Centos) are advised to install an
OpenSSL based version of curl.
Prerequisites
The Agent process is developed and tested with version 7 update 80 of the Java Runtime, and version 8.0.26 of the Tomcat servlet container, but should work on later versions and other standards compliant servlet containers.
The Agent process relies on these components having been installed and the environment variables
JAVA_HOME
and
CATALINA_HOME
having been correctly set. The various start scripts set the value of
CATALINA_BASE to an appropriate value.
Installation and Configuration of the Agent Simulator
Once all of the above prerequisites have been installed, download the Agent Simulator release from https://developers.symphony.com
The release download is called agent-simulator-${version}-bin.tar.gz where
${version}
is a version number, take the latest available version.
Administration Guide – Enterprise / Business Version 150 18-‐Apr-‐2016
This tarball should be extracted in the desired location as the user id of the process under which it is intended to execute. The distribution archive contains a single directory called agent-simulator
:
$ cd /tmp
$ tar xf ~/Downloads/agent-simulator-0.0.3-bin.tar
$ cd agent-simulator
$ ls bin docs examples lib
$ cd bin
$ ls install.sh taillog.sh
$ template webapps
The Agent Simulator consists of three tomcat instances representing the Key Manager,
Symphony servers and the Agent process itself. In the root directory of the distribution the directories agent
, keymanager
and pod
will be created by the install script to represent the tomcat instance directories for each of these server instances.
The webapps
directory contains the web applications (war files), the examples
directory contains the example client code and the bin
directory contains scripts to manage the api simulator processes.
The lib
directory contains all of the
.jar
files needed by the java client examples, these are not needed for the server processes which are built with self contained
.war
files. cd into the bin
directory and execute install.sh
. This will create startup and shutdown scripts configured for your system.
The install script will prompt you to enter a base port number to configure the servers so that if the default ports are in use on your system you can select a suitable alternative. The recommended default base port number is 9 which will cause the following ports to be used:
9003, 9013, 9083, 9443
9004, 9014, 9084, 9444
9005, 9015, 9085, 9445
Enter the desired value and enter y after the "OK to proceed" prompt.
This will
1. Copy required files into each of the server runtime conf
directories.
2. Create a set of self signed certificates and keystore files in the certs directory in the root of the distribution.
3. Create startup and shutdown scripts in the bin directory
Now execute the startup.sh
script to start the servers:
$ ./startup.sh
Using CATALINA_BASE: /tmp/agent-simulator/agent
Using CATALINA_HOME: /symphony/apache/apache-tomcat-8.0.26
Using CATALINA_TMPDIR: /tmp/agent-simulator/agent/temp
Using JRE_HOME:
/Library/Java/JavaVirtualMachines/jdk1.7.0_80.jdk/Contents/Home
Using CLASSPATH: /symphony/apache/apache-tomcat-
8.0.26/bin/bootstrap.jar:/symphony/apache/apache-tomcat-8.0.26/bin/tomcat-juli.jar
Tomcat started.
Using CATALINA_BASE: /tmp/agent-simulator/pod
Using CATALINA_HOME: /symphony/apache/apache-tomcat-8.0.26
Using CATALINA_TMPDIR: /tmp/agent-simulator/pod/temp
Using JRE_HOME:
/Library/Java/JavaVirtualMachines/jdk1.7.0_80.jdk/Contents/Home
Administration Guide – Enterprise / Business Version 151 18-‐Apr-‐2016
Using CLASSPATH: /symphony/apache/apache-tomcat-
8.0.26/bin/bootstrap.jar:/symphony/apache/apache-tomcat-8.0.26/bin/tomcat-juli.jar
Tomcat started.
Using CATALINA_BASE: /tmp/agent-simulator/keymanager
Using CATALINA_HOME: /symphony/apache/apache-tomcat-8.0.26
Using CATALINA_TMPDIR: /tmp/agent-simulator/keymanager/temp
Using JRE_HOME:
/Library/Java/JavaVirtualMachines/jdk1.7.0_80.jdk/Contents/Home
Using CLASSPATH: /symphony/apache/apache-tomcat-
8.0.26/bin/bootstrap.jar:/symphony/apache/apache-tomcat-8.0.26/bin/tomcat-juli.jar
Tomcat started.
$
The tailog.sh script can be used to tail the last 10 lines of each of the tomcat log files. Once the servers have started you will see a line like this at the end of the output for each server:
22-Jan-2016 21:30:11.482 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in 2262 ms
Running The Curl Examples
Now cd to the examples directory and run the testPresence.sh script:
$ cd ../examples/
$ ./testPresence.sh scriptDir is /tmp/agent-simulator/examples
Show curl commands and verbose curl output [n]?
The first prompt asks whether verbose curl output should be displayed, the default value is no, just press return to accept the default. certDir is /tmp/agent-simulator/certs
============================================================================
Select User to Authenticate as
============================================================================
1. bot.user1 (Valid user)
2. bot.user2 (User with no permissions)
3. bot.user3 (User from another company)
4. Imposter
1
Next you will be given the option to select which certificate should be used to authenticate with. Enter 1 and press return to select the valid user certificate.
============================================================================
Authenticate user client...
============================================================================
######################################################################## 100.0%
============================================================================
Session Token is sessionToken cb54d7fa87eae0f6ae29f40d54772288e709bc94d8a5834f3a68f00267885febbaa7568a053f373fcd
48c089e39bbe3023c0ccfce7f4a31c7d3a73dcf2cd4f94
============================================================================
######################################################################## 100.0%
============================================================================
Administration Guide – Enterprise / Business Version 152 18-‐Apr-‐2016
KeyManager Token is keyManagerToken
0100d244e67932d8cfad09878fac1fdc3c715c3e2050a23b49ab7a3ddf296d257125bcfeedd8099f54 ae1a5477b2fb24b36e8ad8d9a4761d509251318c3382029fb284e6d81411009320702de7d7b1d5a64e
1f1cf7ea65ecd481f54000d2c86551383e8bd54a2f7122b4cbcdbaa569206b858226735e526c21f7f9
741db8e1b7adceba0ade46c1e82eac917231c811dd84948bd77f81e1b5dcf249d977a82677ad00f275 cad83a3ab65577531ee6d05db763
============================================================================
============================================================================
Test Echo
============================================================================
######################################################################## 100.0%
Server response OK
Next the script will make an authentication call to the Symphony servers, which returns a sessionToken
. A similar call is then made to the Key Manager process which returns a keyManagerToken
. These calls both use the certificate presented as part of the client authenticated TLS session to authenticate the user calling the API. If you re-run the script and select the Imposter certificate, then you will see these calls fail.
Once authentication has been completed the script calls the Echo method on the Agent passing the message "Hello World" and verifying that the same message is echoed back.
The message "Server response OK" indicates that the expected result was obtained.
Enter user email [[email protected]] :
######################################################################## 100.0%
User ID is 6627861917700
Enter userId [6627861917700] :
Now you will be prompted to enter a user email address, press return to accept the default value. The script then calls the method to look up a user by email address to discover the user ID for that user. The recovered user ID is then provided as the default value for a userId prompt. This is the user whose presence information will be updated. Again, press return to accept the default value.
============================================================================
Get Presence
============================================================================
######################################################################## 100.0%
Current category is
ON_THE_PHONE
Select presence to set:
1. UNDEFINED
2. AVAILABLE
3. BUSY
4. DO_NOT_DISTURB
5. ON_THE_PHONE
6. BE_RIGHT_BACK
7. AWAY
8. OFFLINE
? Display Help Text
q Quit Program
The script then calls the method to fetch the user's presence category and displays it.
Administration Guide – Enterprise / Business Version 153 18-‐Apr-‐2016
Finally the program main menu is displayed which allows you to choose a different status, which will then be set for the given user.
2
============================================================================
Set Presence to AVAILABLE
============================================================================
######################################################################## 100.0%
{"category":"AVAILABLE"}
Enter 2 for AVAILABLE and press return. The script will call the set presence method, display the result and then call the get presence method and display the main menu again.
Now enter 8 to select the OFFLINE state:
============================================================================
Set Presence to OFFLINE
============================================================================
######################################################################## 100.0%
============================================================================
Call to curl failed, status 403 returned.
============================================================================
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> curl -H sessionToken: cb54d7fa87eae0f6ae29f40d54772288e709bc94d8a5834f3a68f00267885febbaa7568a053f373fcd
48c089e39bbe3023c0ccfce7f4a31c7d3a73dcf2cd4f94 -H keyManagerToken:
0100d244e67932d8cfad09878fac1fdc3c715c3e2050a23b49ab7a3ddf296d257125bcfeedd8099f54 ae1a5477b2fb24b36e8ad8d9a4761d509251318c3382029fb284e6d81411009320702de7d7b1d5a64e
1f1cf7ea65ecd481f54000d2c86551383e8bd54a2f7122b4cbcdbaa569206b858226735e526c21f7f9
741db8e1b7adceba0ade46c1e82eac917231c811dd84948bd77f81e1b5dcf249d977a82677ad00f275 cad83a3ab65577531ee6d05db763 -k --cert /tmp/bruce/agentsimulator/certs/client.p12:changeit --cert-type P12 -H Content-Type: application/json --data { "category": "OFFLINE"} https://127.0.0.1:9443/pod/v1/user/6627861917700/presence
/tmp/curlTmp12005 left undeleted
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
{"code":221,"message":"Category OFFLINE cannot be set, although it could be read."}
============================================================================
FAILED FAILED FAILED FAILED FAILED FAILED FAILED FAILED FAILED FAILED FAILED
============================================================================
This time the call fails because although the OFFLINE state may be returned by the system it cannot the set through the API. In the error response we can see that the HTTP response code 403 FORBIDDEN was returned along with a JSON response object which contains the detailed error code 221 and the message
"Category OFFLINE cannot be set, although it could be read.".
Only the following states can be set
• AVAILABLE
• BUSY
• ON_THE_PHONE
• AWAY
Administration Guide – Enterprise / Business Version 154 18-‐Apr-‐2016
Running the Bulk Presence Example
Now open another terminal window and cd to the examples directory.
Execute the testBulkPresence.sh
script:
$ ./testBulkPresence.sh scriptDir is /tmp/agent-simulator/examples
Show curl commands and verbose curl output [n]?
You will be prompted for verbose curl output and the certificate to use for authentication as before, press return to accept the default value of n for verbose curl output and enter 1 for the Valid User certificate.
######################################################################## 100.0%
Server response OK
Press return to fetch bulk presence or:
? Display Help Text
q Quit Program
You will then see a simple menu, press return
to call the fetch bulk presence method.
============================================================================
Get all presence data
============================================================================
######################################################################## 100.0%
UID = 6627861917700
Category = AVAILABLE
Press return to fetch bulk presence or:
? Display Help Text
q Quit Program
You will see the presence category previously set for the default user.
Go back to the first window and select a different presence category and then press return in the second window to see the effect of the change reflected.
If you re-run the testPresence.sh script and select a different user ID
(try [email protected] or [email protected] as email addresses or simply make up a different user ID) then you will see the values for all users displayed by the testBulkPresence.sh
script.
Running the Get Messages Example
The testGetMessages.sh example begins with the same sequence of prompts as the testPresence.sh
script. Run it and press return for no verbose curl output, select certificate 1 for the Valid user and accept the default email address and user ID, as before.
The script will then create a new 1 to 1 Instant Message session between the API user and the user whose email address was entered.
Administration Guide – Enterprise / Business Version 155 18-‐Apr-‐2016
============================================================================
Create IM
============================================================================
######################################################################## 100.0%
Thread ID is sBiRipWWz3Zdmx2lLi9Ls3___rJiqKoXdQ
Press return to fetch messages or:
? Display Help Text
q Quit Program
You will see the session ID of the new IM session and the program menu.
This script calls the get messages API method to fetch up to 5 unseen messages from the given IM session. Press return and you will see a message that there are no more messages.
============================================================================
Get all messages
============================================================================
No new messages
Press return to fetch messages or:
? Display Help Text
q Quit Program
Leave this program running while you follow the next section.
Running the Test IM Example
Open a separate terminal session to run the testIM.sh
example. This begins with the same sequence of prompts as before. Run it and press return for no verbose curl output, select certificate 1 for the Valid user and accept the default email address and user ID, as before.
The script will then call the method to create a new 1 to 1 Instant Message session between the API user and the user whose email address was entered. Since a session with those exact participants already exists, its ID is returned and the program is connected to the same conversation which the testGetMessages.sh example is listening to.
============================================================================
Create IM
============================================================================
Thread ID is sBiRipWWz3Zdmx2lLi9Ls3___rJiqKoXdQ
Select message type:
1. TEXT
2. MESSAGEML
? Display Help Text
q Quit Program
You will see the session ID of the IM session and the program menu.
Administration Guide – Enterprise / Business Version 156 18-‐Apr-‐2016
Messages can be entered as plain text or MessageML which allows for formatting. Enter 1 for a plain text message and then enter the message "Hello World":
1
============================================================================
Send TEXT message
============================================================================
Enter message:
Hello World
######################################################################## 100.0%
Message sent OK
ID = sBiRipWWz3Zdmx2lLi9Ls3___rJiqKoXdg
Timestamp = 1453528080000
Select message type:
1. TEXT
2. MESSAGEML
? Display Help Text
q Quit Program
The program will call the method to send a message and display the message ID and timestamp for the newly created message.
Observing the Sent Messages
Go back to the terminal session where the testGetMessages.sh
example is running and press return
to fetch new messages:
============================================================================
Get all messages
============================================================================
######################################################################## 100.0%
ID = sBiRipWWz3Zdmx2lLi9Ls3___rJiqKoXdg
Timestamp = 1453528080000
From = 206158450789
Message = Hello World
Press return to fetch messages or:
? Display Help Text
q Quit Program
You will see the same message details displayed. Press return again:
============================================================================
Get messages since 1453528080000 offset 1
============================================================================
No new messages
Press return to fetch messages or:
? Display Help Text
Administration Guide – Enterprise / Business Version 157 18-‐Apr-‐2016
q Quit Program
This time you will see that rather than "Get all messages" the program requests only messages received since the one it has already received, and that the response is that there are no new messages. The API method has actually returned an HTTP
204 No Content response.
IMPORTANT NOTE: The get messages method allows the caller to specify which messages are required by passing a timestamp and an offset. In the above example the timestamp 1449447180000 and offset 1 are passed. Think of this as the client saying "please send messages I have not yet seen, the last message I saw was the first (offset 1) message with the timestamp 1449447180000". Messages in the system are strictly ordered and have timestamps in Java time format (milliseconds since January 1st 1970), it is unlikely, but not impossible, that two messages occur in the same millisecond, which is why the offset is needed.
In order to facilitate testing of the correct behavior in callers of the API, the Agent
Simulator rounds all timestamps to the nearest minute when creating messages, notice the trailing zeros on the timestamp above, this is not a coincidence. In production, messages will have timestamps to millisecond resolution, but it is important that callers of the API deal with the unusual case of multiple messages with the same timestamp correctly.
Observing curl Output and Testing Authorization
Next run the testPresence.sh
example, but this time, enter y
at the prompt for verbose curl output and select certificate
2
, a valid user with no permissions:
$ ./testPresence.sh scriptDir is /tmp/agent-simulator/examples
Show curl commands and verbose curl output [n]? y certDir is /tmp/agent-simulator/certs
============================================================================
Select User to Authenticate as
============================================================================
1. bot.user1 (Valid user)
2. bot.user2 (User with no permissions)
3. bot.user3 (User from another company)
4. Imposter
2
============================================================================
Authenticate user noperms...
============================================================================
This time the program will run to completion without any further prompts, and will generate a lot of output, so lets examine this step by step. The figure above shows the initial prompts, and indicates that it is going to authenticate using the certificate "noperms". As before, the next step is to call the authenticate API method on the Symphony servers to obtain a sessionToken
, but because of the verbose curl output we see much more output:
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> curl -v -X POST -k --cert /tmp/agent-simulator/certs/noperms.p12:changeit --certtype P12 https://127.0.0.1:9444/sessionauth/v1/authenticate
* Trying 127.0.0.1...
Administration Guide – Enterprise / Business Version 158 18-‐Apr-‐2016
* Connected to 127.0.0.1 (127.0.0.1) port 9444 (#0)
* Client certificate: bot.user2
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
* Server certificate: *.symphony.com
> POST /sessionauth/v1/authenticate HTTP/1.1
> Host: 127.0.0.1:9444
> User-Agent: curl/7.43.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Content-Type: application/json
< Content-Length: 164
< Date: Mon, 07 Dec 2015 00:17:02 GMT
<
{ [164 bytes data]
######################################################################## 100.0%*
Connection #0 to host 127.0.0.1 left intact
The section following the line of right chevrons shows the request being sent, the first line is a copy of the curl command being used, which from left to right requests:
-v
Verbose output
-X POST an HTTP POST request
-k
--cert <filename>:<password> do not validate the server certificate
use the given client certificate
--cert-type P12 which is in PKCS#12 format
The URL of the request, 9 was used as the base port number in this example, and the SBE authentication server listens on port X444.
The lines starting with an asterisk show the network parameters curl is using, the server uses a self signed certificate with the common name
*.symphony.com
, but it has a subject alternate name of
127.0.0.1
, the client certificates have a common name containing the user's Symphony User Name ( bot.user2
in this case).
The lines starting with a right chevron show the HTTP request being sent.
The lines starting with a left chevron show the HTTP response headers from the server, which in this case has been successful. This is a valid user, so they can authenticate, they lack permissions to perform all API calls so we will see a failure later.
The final two lines in the figure above show the size of the response body and a progress bar output by curl.
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
{"name":"sessionToken","token":"9954d7fa87eae0f6ae29f40d54772288e709bc94d8a5834f3a
68f00267885febbaa7568a053f373fcd48c089e39bbe3023c0ccfce7f4a31c7d3a73dcf2cd4f99"}
----------------------------------------------------------------------------
============================================================================
Session Token is sessionToken
9954d7fa87eae0f6ae29f40d54772288e709bc94d8a5834f3a68f00267885febbaa7568a053f373fcd
48c089e39bbe3023c0ccfce7f4a31c7d3a73dcf2cd4f99
============================================================================
Administration Guide – Enterprise / Business Version 159 18-‐Apr-‐2016
The section following the line of left chevrons shows the response received, which is a
JSON document.
The authenticate method returns two properties, the name of the token being returned and the token value. In this case we are receiving the sessionToken
. The example script then displays the session token name and value as it did in the non-verbose examples.
We then see an almost identical request where the example script requests a keyManagerToken
from the dummy key manager, which is listening on port 9445.
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> curl -v -X POST -k --cert /tmp/agent-simulator/certs/noperms.p12:changeit --certtype P12 https://127.0.0.1:9445/keyauth/v1/authenticate
* Trying 127.0.0.1...
* Connected to 127.0.0.1 (127.0.0.1) port 9445 (#0)
* Client certificate: bot.user2
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
* Server certificate: *.symphony.com
> POST /keyauth/v1/authenticate HTTP/1.1
> Host: 127.0.0.1:9445
> User-Agent: curl/7.43.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Content-Type: application/json
< Content-Length: 395
< Date: Mon, 07 Dec 2015 00:17:02 GMT
<
{ [395 bytes data]
######################################################################## 100.0%*
Connection #0 to host 127.0.0.1 left intact
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
{"name":"keyManagerToken","token":"9900d244e67932d8cfad09878fac1fdc3c715c3e2050a23 b49ab7a3ddf296d257125bcfeedd8099f54ae1a5477b2fb24b36e8ad8d9a4761d509251318c3382029 fb284e6d81411009320702de7d7b1d5a64e1f1cf7ea65ecd481f54000d2c86551383e8bd54a2f7122b
4cbcdbaa569206b858226735e526c21f7f9741db8e1b7adceba0ade46c1e82eac917231c811dd84948 bd77f81e1b5dcf249d977a82677ad00f275cad83a3ab65577531ee6d05db799"}
----------------------------------------------------------------------------
Now the script will attempt to call the echo method on the Agent Simulator, which listens on port 9443 and this is where things go wrong for our user with no permissions:
============================================================================
Test Echo
============================================================================
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> curl -v -H sessionToken:
9954d7fa87eae0f6ae29f40d54772288e709bc94d8a5834f3a68f00267885febbaa7568a053f373fcd
48c089e39bbe3023c0ccfce7f4a31c7d3a73dcf2cd4f99 -H keyManagerToken:
9900d244e67932d8cfad09878fac1fdc3c715c3e2050a23b49ab7a3ddf296d257125bcfeedd8099f54 ae1a5477b2fb24b36e8ad8d9a4761d509251318c3382029fb284e6d81411009320702de7d7b1d5a64e
1f1cf7ea65ecd481f54000d2c86551383e8bd54a2f7122b4cbcdbaa569206b858226735e526c21f7f9
741db8e1b7adceba0ade46c1e82eac917231c811dd84948bd77f81e1b5dcf249d977a82677ad00f275 cad83a3ab65577531ee6d05db799 -k --cert /tmp/agentsimulator/certs/noperms.p12:changeit --cert-type P12 -H Content-Type: application/json --data { "message": "Hello World"} https://127.0.0.1:9443/bridge/v1/util/echo
* Trying 127.0.0.1...
Administration Guide – Enterprise / Business Version 160 18-‐Apr-‐2016
* Connected to 127.0.0.1 (127.0.0.1) port 9443 (#0)
* Client certificate: bot.user2
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
* Server certificate: *.symphony.com
> POST /bridge/v1/util/echo HTTP/1.1
> Host: 127.0.0.1:9443
> User-Agent: curl/7.43.0
> Accept: */*
> sessionToken:
9954d7fa87eae0f6ae29f40d54772288e709bc94d8a5834f3a68f00267885febbaa7568a053f373fcd
48c089e39bbe3023c0ccfce7f4a31c7d3a73dcf2cd4f99
> keyManagerToken:
9900d244e67932d8cfad09878fac1fdc3c715c3e2050a23b49ab7a3ddf296d257125bcfeedd8099f54 ae1a5477b2fb24b36e8ad8d9a4761d509251318c3382029fb284e6d81411009320702de7d7b1d5a64e
1f1cf7ea65ecd481f54000d2c86551383e8bd54a2f7122b4cbcdbaa569206b858226735e526c21f7f9
741db8e1b7adceba0ade46c1e82eac917231c811dd84948bd77f81e1b5dcf249d977a82677ad00f275 cad83a3ab65577531ee6d05db799
> Content-Type: application/json
> Content-Length: 27
>
} [27 bytes data]
######################################################################## 100.0%* upload completely sent off: 27 out of 27 bytes
In the request section of this call, notice that the sessionToken
and keyManagerToken
are passed as headers, on the curl command line they are shown as
-H
parameters and they can be seen in the section indicated by right chevrons in the request header being sent.
Also note the JSON payload in the request being passed on the curl command line as a
-data
parameter.
< HTTP/1.1 403 Forbidden
< Server: Apache-Coyote/1.1
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Methods: GET, POST, DELETE, PUT
< Access-Control-Allow-Headers: Content-Type
< Content-Type: application/json
< Content-Length: 78
< Date: Mon, 07 Dec 2015 00:17:03 GMT
<
{ [78 bytes data]
######################################################################## 100.0%*
Connection #0 to host 127.0.0.1 left intact
============================================================================
Call to curl failed, status 403 returned.
============================================================================
{"code":303,"message":"Caller is not entitled to perform requested operation"}
============================================================================
FAILED FAILED FAILED FAILED FAILED FAILED FAILED FAILED FAILED FAILED FAILED
============================================================================
In the response section (some output has been omitted from the figure above for clarity) we see that the API returns an HTTP
403 FORBIDDEN
response, and that the body of the response contains a JSON document with more detailed information including a numeric error code and a text message describing the specific reason for the call failure. All API
Administration Guide – Enterprise / Business Version 161 18-‐Apr-‐2016
methods return this type of response in the case of an error (although see the next section for the special case of an invalid certificate).
Testing the Imposter Client Certificate
Now run the testPresence.sh
example again, but this time, enter y
at the prompt for verbose curl output and select certificate
4
, an imposter:
$ ./testPresence.sh scriptDir is /tmp/agent-simulator/examples
Show curl commands and verbose curl output [n]? y certDir is /tmp/agent-simulator/certs
============================================================================
Select User to Authenticate as
============================================================================
1. bot.user1 (Valid user)
2. bot.user2 (User with no permissions)
3. bot.user3 (User from another company)
4. Imposter
4
============================================================================
Authenticate user imposter...
============================================================================
This time the program will run to completion without any further prompts. The figure above shows the initial prompts, and indicates that it is going to authenticate using the certificate
"imposter". As before, the next step is to call the authenticate API method on the Symphony servers to obtain a sessionToken
:
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> curl -v -X POST -k --cert /tmp/agent-simulator/certs/imposter.p12:changeit --certtype P12 https://127.0.0.1:9444/sessionauth/v1/authenticate
* Trying 127.0.0.1...
* Connected to 127.0.0.1 (127.0.0.1) port 9444 (#0)
* Client certificate: An Imposter
* Unknown SSL protocol error in connection to 127.0.0.1:-9829
* Closing connection 0 curl: (35) Unknown SSL protocol error in connection to 127.0.0.1:-9829
============================================================================
Call to curl failed, status 000 returned.
============================================================================
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> curl -v -X POST -k --cert /tmp/agent-simulator/certs/imposter.p12:changeit --certtype P12 https://127.0.0.1:9444/sessionauth/v1/authenticate
/tmp/curlTmp37991 left undeleted
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
============================================================================
FAILED FAILED FAILED FAILED FAILED FAILED FAILED FAILED FAILED FAILED FAILED
============================================================================
Authentication (session) failed
In this case we are connecting to the server with a client certificate issued by an untrusted certificate authority. There are several stages to the verification of client certificates, the first
Administration Guide – Enterprise / Business Version 162 18-‐Apr-‐2016
is that the servlet container (Tomcat in this case) performs standard certificate path validation against a truststore containing trusted signing and end user certificates.
In the case of the Agent Simulator all of the certificates are self-signed and the server truststore contains all three of the valid end user certificates directly. The certificates and truststore file are created by the install.sh
script used to set up the Agent Simulator. In a production deployment the end user certificates would be issued by the customer's own PKI and the server truststore would be configured with the appropriate root or intermediate signing certificates for the trusted PKI.
In this example the imposter certificate is not included in the server truststore so the initial certificate path validation performed by Tomcat fails. The request is rejected directly from the TLS session establishment phase and the Agent servlets never see the request. This means that there is no opportunity to provide any response with detailed information. In this case the request is rejected early as indicated by the output from curl in the line curl: (35) Unknown SSL protocol error in connection to 127.0.0.1:-9829
This is caused by the abrupt termination of the network connection by the server, which is compliant with appropriate standards and appropriate in this case where an untrusted certificate is being presented. Note that this failure mode would also be observed in the case where the client certificate fails basic certificate path validation, including the case where the certificate has expired. Appropriate management of client certificates is therefore required in production if such failures are to be avoided for expired certificates. This is a responsibility of the certificate issuer.
Testing the Other Company Client Certificate
Now run the testPresence.sh example again, but this time, enter y at the prompt for verbose curl output and select certificate 3, a user from another company:
$ ./testPresence.sh scriptDir is /tmp/agent-simulator/examples
Show curl commands and verbose curl output [n]? y certDir is /tmp/agent-simulator/certs
============================================================================
Select User to Authenticate as
============================================================================
1. bot.user1 (Valid user)
2. bot.user2 (User with no permissions)
3. bot.user3 (User from another company)
4. Imposter
3
============================================================================
Authenticate user external...
============================================================================
This time the program will run to completion without any further prompts. The figure above shows the initial prompts, and indicates that it is going to authenticate using the certificate
"external". As before, the next step is to call the authenticate API method on the Symphony servers to obtain a sessionToken
:
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> curl -v -X POST -k --cert /tmp/agent-simulator/certs/external.p12:changeit --certtype P12 https://127.0.0.1:9444/sessionauth/v1/authenticate
Administration Guide – Enterprise / Business Version 163 18-‐Apr-‐2016
* Trying 127.0.0.1...
* Connected to 127.0.0.1 (127.0.0.1) port 9444 (#0)
* Client certificate: bot.user3
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
* Server certificate: *.symphony.com
> POST /sessionauth/v1/authenticate HTTP/1.1
> Host: 127.0.0.1:9444
> User-Agent: curl/7.43.0
> Accept: */*
>
< HTTP/1.1 401 Unauthorized
< Server: Apache-Coyote/1.1
< Content-Type: application/json
< Content-Length: 74
< Date: Mon, 07 Dec 2015 01:07:14 GMT
<
{ [74 bytes data]
######################################################################## 100.0%*
Connection #0 to host 127.0.0.1 left intact
============================================================================
Call to curl failed, status 401 returned.
============================================================================
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> curl -v -X POST -k --cert /tmp/agent-simulator/certs/external.p12:changeit --certtype P12 https://127.0.0.1:9444/sessionauth/v1/authenticate
/tmp/curlTmp38115 left undeleted
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
{"code":401,"message":"Principal does not belong to certificate issuer"}
============================================================================
FAILED FAILED FAILED FAILED FAILED FAILED FAILED FAILED FAILED FAILED FAILED
============================================================================
In this case we are connecting to the server with a client certificate which has been issued by a trusted certificate authority and basic certificate path validation will therefore succeed. As previously stated, the client certificate is issued by the customer's PKI and the common name in the certificate contains a Symphony User Name. It is possible that the certificate contains a user name which is invalid in some way. In this example the user name represents a user belonging to another company, and therefore the certificate has been issued in error.
This scenario could only occur in a multi-company pod, but other similar scenarios (such as specifying a non-existent user) can occur in a private company pod.
In this case the method returns with an HTTP
401 UNAUTHORIZED
response, because the client has not been correctly authenticated. The response body includes a JSON error document containing more detailed diagnostic information.
Note that in production environments that the message will simply say that authentication has failed, as disclosing the detailed reason for the failure could be useful to an intruder.
Running The Java Examples
There is also a Java implementation of the example programs. The jar file containing the example programs and all dependent jars are provided in the lib directory of the Agent API
Simulator distribution. Scripts to launch these can be found in the examples directory.
Now run the javaPresence.sh
script:
Administration Guide – Enterprise / Business Version 164 18-‐Apr-‐2016
$ ./javaPresence.sh scriptDir is /tmp/agent-simulator/examples certDir is /tmp/agent-simulator/certs
============================================================================
Select User to Authenticate as
============================================================================
1. bot.user1 (Valid user)
2. bot.user2 (User with no permissions)
3. bot.user3 (User from another company)
4. Imposter
1
There is no prompt for verbose curl output, but the program is otherwise similar. You will be given the option to select which certificate should be used to authenticate with. Enter 1 and press return to select the valid user certificate.
Token sessionToken = cb54d7fa87eae0f6ae29f40d54772288e709bc94d8a5834f3a68f00267885febbaa7568a053f373fcd
48c089e39bbe3023c0ccfce7f4a31c7d3a73dcf2cd4f94
Token keyManagerToken =
0100d244e67932d8cfad09878fac1fdc3c715c3e2050a23b49ab7a3ddf296d257125bcfeedd8099f54 ae1a5477b2fb24b36e8ad8d9a4761d509251318c3382029fb284e6d81411009320702de7d7b1d5a64e
1f1cf7ea65ecd481f54000d2c86551383e8bd54a2f7122b4cbcdbaa569206b858226735e526c21f7f9
741db8e1b7adceba0ade46c1e82eac917231c811dd84948bd77f81e1b5dcf249d977a82677ad00f275 cad83a3ab65577531ee6d05db763
EMail Address [[email protected]] ?
User ID [206158450789] ?
The program will make the same authentication calls to the Symphony servers and the Key
Manager process and the returned tokens are displayed. You will be prompted to enter a user email address and user Id as before, press return to accept the default values.
---------------------------------------------------------------------------
Presence for user 206158450789 is AVAILABLE
0 UNDEFINED
1 AVAILABLE
2 BUSY
3 DO_NOT_DISTURB
4 ON_THE_PHONE
5 BE_RIGHT_BACK
6 AWAY
7 OFFLINE q Quit Program
Enter selection [q] ?
The program then calls the method to fetch the user's presence category and displays it.
Finally, the program main menu is displayed which allows you to choose a different status, which will then be set for the given user.
Enter selection [q] ?2
---------------------------------------------------------------------------
Presence for user 206158450789 is BUSY
0 UNDEFINED
Administration Guide – Enterprise / Business Version 165 18-‐Apr-‐2016
1 AVAILABLE
2 BUSY
3 DO_NOT_DISTURB
4 ON_THE_PHONE
5 BE_RIGHT_BACK
6 AWAY
7 OFFLINE q Quit Program
Enter selection [q] ?
Some of the presence categories displayed can be set by the system but not via the API. The
OFFLINE
status is set when the user is not connected to the system and cannot be set through the UI or API. Other categories are reserved for future use. Try to set the
OFFLINE
state by entering
7
:
Enter selection [q] ?7
Failed: status=403 com.symphony.sapi.client.ApiException: {"code":221,"message":"Category OFFLINE cannot be set, although it could be read."} at com.symphony.sapi.client.ApiClient.invokeAPI(ApiClient.java:529) at com.symphony.sapi.api.PresenceApi.v1UserUidPresencePost(PresenceApi.java:220) at com.symphony.bridge.example.java.AbstractTestClient.setPresence(AbstractTestClient
.java:79) at com.symphony.bridge.example.java.TestPresence.processMain(TestPresence.java:68) at com.symphony.bridge.example.java.AbstractTestClient.doMain(AbstractTestClient.java
:114)
$ at com.symphony.bridge.example.java.TestPresence.main(TestPresence.java:23)
You will see a stack trace displayed which includes the JSON error response and the HTTP
403
response.
The Java Example Implementation
The javaPresence.sh script just selects the certificate to be used, sets the appropriate Java system properties and invokes the application with the required classpath. The certificate set up is actually done in the javaAuthenticate.sh script: title Select User to Authenticate as while [ "$client" == "" ] do cat <<EOF
1. bot.user1 (Valid user)
2. bot.user2 (User with no permissions)
3. bot.user3 (User from another company)
4. Imposter
EOF
Administration Guide – Enterprise / Business Version 166 18-‐Apr-‐2016
read x case $x in
1)
client=client
;;
2)
client=noperms
;;
3)
client=external
;;
4)
client=imposter
;;
*) echo "Unrecognized input, enter a number"
;;
esac done clientCert= "-Djavax.net.ssl.trustStore=$certDir/server.keystore
-Djavax.net.ssl.trustStorePassword=changeit
-Djavax.net.ssl.keyStore=$certDir/$client.p12
-Djavax.net.ssl.keyStorePassword=changeit
-Djavax.net.ssl.keyStoreType=pkcs12"
The program is then launched like this: java -classpath
"$baseDir/lib/*"
$clientCert com.symphony.bridge.example.java.TestPresence
The main program is actually very simple; first it displays the menu: public class TestPresence extends AbstractUserTestClient { public static void main(String[] argv){ new TestPresence().doMain(argv);
}
@Override protected void processMain() throws ApiException { boolean done = false ; while (!done) {
Presence presence = getPresence(getUserId());
System.
out .println( "--------------------------------------------------------
-------------------" );
System.
out .println( "Presence for user " + getUserId() + " is " + presence.getCategory());
Presence.CategoryEnum newCat = null ; for ( int i = 0 ; i < Presence.CategoryEnum.
values().
length ; i++)
System.
out .println(i + " " + Presence.CategoryEnum.
values()[i]);
System.
out .println();
System.
out
.println( "q Quit Program" );
System.
out .println();
Administration Guide – Enterprise / Business Version 167 18-‐Apr-‐2016
String v = prompt( "Enter selection" , "q" );
Then is evaluates the user input to find the new category: switch (v) { case "q" :
done = true ; break ; default
: try { int i = Integer.
parseInt(v); if (i>= 0 && i<Presence.CategoryEnum.
values().
length )
newCat = Presence.CategoryEnum.
values()[i]; else
System.
err .println(
"Number out of range"
);
} catch (NumberFormatException e) {
System.
err .println( "Unrecognized input" );
}
}
Finally it calls the setPresence()
method to update the value. if (newCat != null ) {
presence.setCategory(newCat);
setPresence(getUserId(), presence);
}
Of course the real work is taking place in the applications superclass,
AbstractTestClient
. First a client object is created for each of the API server endpoints: com.symphony.sapi.client.ApiClient apiBridgeClient
= new com.symphony.sapi.client.ApiClient(); com.symphony.sapi.auth.client.ApiClient sbeClient
= new com.symphony.sapi.auth.client.ApiClient(); com.symphony.sapi.auth.client.ApiClient keyManagerClient
= new com.symphony.sapi.auth.client.ApiClient();
These are instances of classes which are generated from the Swagger API definition. Each method category defined in the API specification results in a separate API class so there are several API classes for the main
apiBridgeClient
.
AuthenticationApi sbeApi
= new
AuthenticationApi( sbeClient
);
AuthenticationApi keyManagerApi = new AuthenticationApi( keyManagerClient );
PresenceApi presenceApi = new PresenceApi( apiBridgeClient );
MessagesApi messagesApi = new MessagesApi( apiBridgeClient );
UsersApi usersApi = new UsersApi( apiBridgeClient );
StreamsApi streamsApi = new StreamsApi( apiBridgeClient );
The base URL for each server is set in the constructor: public AbstractTestClient() { apiBridgeClient .setBasePath( "https://127.0.0.1:9443/bridge" ); sbeClient .setBasePath( "https://127.0.0.1:9444/sessionauth" ); keyManagerClient .setBasePath( "https://127.0.0.1:9445/keyauth" );
}
Administration Guide – Enterprise / Business Version 168 18-‐Apr-‐2016
The authenticate() method calls the two authentication endpoints and assigns the tokens to class member variables: public void authenticate() throws com.symphony.sapi.auth.client.ApiException { sessionToken = sbeApi .v1AuthenticatePost();
System.
err .println( "Token " + sessionToken .getName() + " = " + sessionToken .getToken()); keyManagerToken = keyManagerApi .v1AuthenticatePost();
System.
err .println(
"Token "
+ keyManagerToken
.getName() +
" = "
+ keyManagerToken .getToken());
}
A set of methods then just provides access to the appropriate API object with the session tokens filled in: public Presence getPresence(String uid) throws ApiException { return presenceApi .v1UserUidPresenceGet(uid, sessionToken .getToken(), keyManagerToken .getToken());
} public Presence setPresence(String uid, Presence presence) throws ApiException { return presenceApi .v1UserUidPresencePost(uid, sessionToken .getToken(), keyManagerToken .getToken(), presence);
}
As you can see, the application level code to call the API is very simple, most of the legwork of making the API calls is done inside the generated code.
Generating API Documentation and Code Stubs
In the docs directory of the Simulator distribution you will find a copy of the yaml interface specification in two files called serviceAPI.yaml
and agentAPI.yaml
.
Open that file and copy the contents onto the clipboard. Then open a web browser and go to http://editor.swagger.io
Paste the yaml into the left hand pane of the editor and you will see documentation of the interface on the right hand pane:
Administration Guide – Enterprise / Business Version 169 18-‐Apr-‐2016
Now click on the Generate Client menu and select the language you would like to use to access the API. Further information about Swagger can be found at www/swagger.io
MessageML
When calling API methods which create messages, the text of the message may be provided in plain text (if no formatting or special entities are required) or as MessageML, which allows for the inclusion of these features.
Message XML includes the following tags:
Tag
<b>text</b>
Description
Render "text" in bold font.
<i>text</i>
<hash tag="label"/>
Render "text" in italic font.
Insert "label" as a hashtag.
<cash tag="ticker"/> Insert "ticker" as a cashtag.
<mention uid=1234/>
1
Insert an @mention for the user whose user id is 1234
<mention email="user@domain"/>
Insert an @mention for the user whose email address is user@domain
1
This form of user mention is unsupported in the current version of the API, use the email variant instead.
Administration Guide – Enterprise / Business Version 170 18-‐Apr-‐2016
<a href=“http://some.url“/>
2
Insert a hyperlink. Note that unlike an HTML anchor you cannot specify separate text to be displayed. A possibly truncated version of the URL will always be displayed. In the event that text is enclosed within the tag (e.g. <link href="http://some.url">Click Here</link>) then that text will be
IGNORED. This also applies to hash, cash and mention.
Production Deployment
The Agent process is a web application which requires a Java Runtime Environment and an installation of Apache Tomcat 8. It must be deployed on premise because it performs encryption and decryption operations on behalf of applications calling the Agent API and has access to user encryption keys.
Callers of the Agent API are required to authenticate using an X.509 identity certificate which must be issued by the customer organization. When installing the Agent the signing certificate for the customer’s PKI (including only the public key) must be added to the truststore configuration for the customer’s on premise key manager, and this certificate must also be provided to Symphony so that it can be added to the servers for the pod.
In a future release a capability in the Admin Console will be provided to place this in the direct control of the customer.
Platform Dependencies
The Agent is certified for deployment on Centos 6.5 and 7.0. It is implemented as a Java
Web Application intended for deployment on Java 7 and Tomcat 8.
Prerequisites
The Agent process is certified with version 7 update 80 of the Java Runtime, and version
8.0.26 of the Tomcat servlet container.
The Agent process relies on these components having been installed and the environment variables
JAVA_HOME
and
CATALINA_HOME
having been correctly set. The various start scripts set the value of
CATALINA_BASE to an appropriate value.
Configuration properties for the process are managed through a set of text files managed under a file hierarchy which may be configured by setting the environment variables or Java
System Properties
ATLAS_HOME
,
ATLAS_ENV
and
ATLAS_DEBUG
. A default configuration is included within the distribution in the directory atlas
.
Installation and Configuration of the Agent Server
Once all of the above prerequisites have been installed, download the Agent Simulator release from https://developers.symphony.com
The release download is called
2
The name of this tag has been changed from the previous draft of this interface definition.
Administration Guide – Enterprise / Business Version 171 18-‐Apr-‐2016
agent-${version}-standalone.tar.gz where
${version}
is a version number, take the latest available version.
This tarball should be extracted in the desired location as the user id of the process under which it is intended to execute. The distribution archive contains a single directory called agent
:
$ cd /symphony/runtime
$ tar xf ~/Downloads/agent-1.0.0-standalone.tar
$ cd agent
$ ls atlas
$ bin conf cryptolibs webapps
Atlas Configuration
The configuration parameters for the agent process are located in a set of properties files in the atlas
directory. Atlas is a tool for managing multiple configurations for applications which can be read by applications written as bash shell scripts or Java programs.
The atlas directory contains the following files and directories (some files have been omitted here for clarity) atlas
├──
apps
│
└── symphony
│
├── bin
│
│ └── createCerts.sh
│
└── conf
│
├── default
│
│ ├── agent.properties
│
│ └── atlas.properties
│ ├── env
│
│ └── local
│
│ └── agent.properties
│
└── global
│
├── agent.properties
│
├── atlas.properties
│
└── certs
│
├── 127.0.0.1.p12
│ ├── bot.user1.p12
│
├── bot.user10.p12
│
├── ca-cert-chain.pem
│
├── ca-cert.pem
│
├── server.keystore
│
└── server.truststore
├──
bin
│
├── bootstrapAtlas.sh
│
├── initAtlas.sh
│
└── listProperties.sh
└──
conf
├── default
│ └── atlas.properties
├── env
└── global
Administration Guide – Enterprise / Business Version 172 18-‐Apr-‐2016
└── atlas.properties
The atlas/bin
directory contains scripts to read a configuration. The initAtlas.sh
script is used by other scripts to read their configuration. The listProperties.sh
script reads a configuration and prints out all configured values, which is useful to see how a configuration is constructed and to debug configurations which are not working as required.
The configuration files (name
.properties
) follow the general format of Java properties files. Blank lines, and lines where the first non-whitespace character is a
# are treated as comments and ignored.
Each other line consists of a name value pair definition. The name and value are separated by an
=
character, any second and subsequent
=
character is considered part of the value.
Names may contain period characters, which is common practice for Java properties, but since shell variable names may not contain periods these are mapped to underscores when processed for shell scripts.
The value side of each line may include references to already defined values. The string
${name}
will be replaced with the value previously defined either in an earlier line in the current file, an earlier file in the current configuration, by an environment variable, or in the case of a Java program, a Java System Property. No forward references are allowed, but the three tier configuration structure allows for most configurations to be defined without the need for duplication of definitions.
The conf
directory contains a set of files which are processed for all applications. These files are empty in the provided configuration. The files and directories under conf
are processed in the same way as the application files described below.
The apps
directory contains application specific configurations and here you will find a single symphony
configuration in the provided template. Within the application configuration there are directories called default
, env
and global
. Within the env directory there can be any number of sub-directories defining configurations for various environments. In the agent distribution there is a single environment defined called local. If
ATLAS_ENV
is undefined (not specified as a Java System Property or as an environment variable) then the value default
is used as the environment name. Note that there is no default
environment defined in the supplied configuration so failure to specify an environment name will result in an error. However, the install script sets default values for
ATLAS_HOME
and
ATLAS_ENV
in the startup and shutdown scripts which it creates.
When a program reads its configuration it specifies the name of the application it is a part of, and a list of configuration names. The configuration atlas
is always included and the
API Agent also reads the agent
configuration.
When reading a configuration, Atlas will process files in the following sequence:
In each directory it will read atlas.properties
first, then agent.properties
.
The directories conf/default apps/symphony/default conf/env/${ATLAS_ENV} apps/symphony/env/${ATLAS_ENV} are processed in that order, if the same name is defined in multiple files then the later definition overwrites the earlier one. Then the directories apps/symphony/conf/global conf/global
Administration Guide – Enterprise / Business Version 173 18-‐Apr-‐2016
are processed in that order, but in this case if a value defined in a file is already defined then the earlier value prevails and the new definition is ignored.
The default values provided in the supplied configuration will need to be adapted to the environment in which it is to be installed. This can be done in situ, or you may prefer to make a separate copy of the configuration and save it for re-use. This is the approach which will be described below.
Begin by making a copy of the default configuration as a tar archive and extracting the copy into a separate location:
$ tar cf /symphony/atlas.tar atlas
$ cd /symphony
$ tar xf atlas.tar
$ ls atlas
$ cd atlas
$ export ATLAS_HOME=/symphony/atlas
$ export ATLAS_ENV=local
$
By setting the environment variable ATLAS_HOME to the location of our configuration when we install the API agent it will use this configuration in preference to the default one.
If you prefer you can create the configuration in the directory
/atlas
or create a symbolic link called
/atlas
to the actual location of your configuration and rename the environment sub-directory to default as those are the default values used if no other value is specified.
Note that the variable
ATLAS_HOME
should be defined when running the install script, even if you are using the
/atlas
default. This is to prevent the install script selecting the default configuration contained in the distribution.
Certificates and Bot Authentication
Callers of the Agent API need to use X.509 identity certificates to authenticate to
Symphony. In most cases customers will wish to use their own certificates, issued and managed through an internal Public Key Infrastructure (PKI). For testing purposes it may be useful to use a set of test certificates which are included with the API Agent distribution.
The test certificates can be found in atlas/apps/symphony/conf/global/certs
.
If you are making a production deployment you should provide a certificate signing certificate from your PKI in place of the file ca-cert.pem
, and individual bot identity certificates in place of bot.user1.p12
etc. The script used to create the test certificates is also provided in the distribution as a convenience for customers who wish to create their own test certificates.
The public key certificate (but not the corresponding private key) for the certificate signing certificate ( ca-cert.pem
) must be added to the tuststore file used by the servlet container
(Tomcat), this is described below. This certificate must also be provided to Symphony
Customer Services so that it can be installed as a trusted signing certificate in the Symphony pod
3
.
3
In the future a procedure to do this directly through the Administration Console will be provided but for the time being this is a manual process which Customer Services will assist with.
Administration Guide – Enterprise / Business Version 174 18-‐Apr-‐2016
When creating accounts for use by callers of the Agent API, the administrator should create an account via the Administration Console. We recommend the use of service accounts for this purpose. The account name of the new account should be entered as the Common Name of the subject principal in the X.509 entity certificate.
In the figure below, which is a screenshot from the Administration Console, you can see a user account has been set up for an account name bot.user1
.
If we now go to the example certificates directory and examine the certificate file bot.user1.p12
we will see the following:
$ cd atlas/apps/symphony/conf/global/certs
$ keytool -list -v -keystore bot.user1.p12 -storepass changeit -storetype pkcs12
Keystore type: PKCS12
Keystore provider: SunJSSE
Your keystore contains 1 entry
Alias name: 1
Creation date: Feb 4, 2016
Entry type: PrivateKeyEntry
Certificate chain length: 3
Certificate[1]:
Owner: C=US, OU=NOT FOR PRODUCTION USE, O=Symphony Communications LLC,
CN=bot.user1
Issuer: C=US, OU=NOT FOR PRODUCTION USE, O=Symphony Communications LLC,
CN=Disposable Test Intermediate Certificate Authority
Serial number: 3
Valid from: Wed Jan 27 12:11:03 PST 2016 until: Sat Jan 27 12:11:03 PST 2024
Certificate fingerprints:
MD5: 4B:A3:E6:A5:D1:85:99:68:40:8B:AB:35:2A:8C:69:53
SHA1: 24:7F:D9:39:C7:82:F6:59:3A:25:46:25:CD:F6:86:1A:DD:8B:CC:32
SHA256:
6C:A8:92:DB:3C:BE:4F:E6:2B:85:FA:58:48:BA:06:4C:FE:98:26:FA:8F:EE:0B:D3:15:52:98:F
F:3E:86:FF:14
Signature algorithm name: SHA256withRSA
Version: 3
Administration Guide – Enterprise / Business Version 175 18-‐Apr-‐2016
The keytool
program is a standard part of the Java Development Kit and it can be used to inspect the contents of various certificate a key storage files. There files can be protected by a password and all of the example certificates have the password changeit
.
As you can see, the owner of this certificate has the Common Name (shown as
CN
in the figure above) bot.user1
which matches the user name of the account we have created. The other elements of the principal name (C, OU, O etc.) are ignored by Symphony and can contain any values. As you can see these test certificates contain notices that they are not for production use.
When setting up the API Agent with your own certificates you will need to provide a server
SSL certificate in atlas/apps/symphony/conf/global/certs/server.keystore
and a truststore file containing the CA signing certificate in atlas/apps/symphony/conf/global/certs/server.truststore
.
If you wuish to use the supplied test certificates then the certificate configuration will work as supplied.
Customizing the Atlas Configuration
Now we can set about tailoring the configuration to our requirements. The configuration as shipped has all the Symphony components on localhost which is unlikely to be correct.
The hostname and port number of your Symphony pod is configured in atlas/apps/symphony/conf/env/local/agent.properties
: pod.https.port=8443 agent.host=localhost
#symphony.host=yourdomain.symphony.com
#keymanager.host=keymanager.your.domain
Uncomment the symphony.host
and keymanager.host
entries and enter the host names for your pod and keymanager. If the keymanager is deployed in the cloud then this will be the same as the pod URL, which is shown in the URL bar of your browser when using
Symphony.
If your keymanager is deployed on premise then you will need to obtain the host name from your network administrator.
Parameters for the API Agent are configured in atlas/conf/default
/agent.properties
: agent.shutdown.port=8006 agent.ajp.port=8016 agent.http.port=8086 agent.https.port=8446 session.auth.https.port=8444 keymanager.auth.https.port=8444 agent.host=${symphony.host}
This file defines default values for all environments, if you wish to define several environment configurations and these values need to vary by environment then create new environment configuration directories under atlas/apps/symphony/env
and copy the two
Administration Guide – Enterprise / Business Version 176 18-‐Apr-‐2016
files above to that directory and may appropriate modifications. The environment specific configuration values will take priority over the defaults.
The values in this file you will want to configure are agent.host
and agent.https.port
.
These values are used both by the agent process startup and shutdown script and may be shared with processes calling the API. You may wish to specify a fully qualified domain name for the agent process and place the Atlas configuration files on a network accessible file system, for this purpose.
Note that the agent operates over HTTPS and requires a server certificate and that the name in the server certificate must match the host name under which API callers connect.
Therefore it is highly desirable that the name used in this configuration file is the matches the server certificate deployed on the API Agent servlet container.
Once the configuration is complete, go to the bin directory in the AOU Agent distribution directory and run the install.sh
script. In this example we have copied the Atlas configuration to
/atlas
and we have created an environment configuration called nexus
.
To force the installation script to use this configuration we are setting the environment variables
ATLAS_HOME
and
ATLAS_ENV
:
$ cd /symphony/runtime/agent/bin
$ ATLAS_HOME=/atlas ATLAS_ENV=nexus ./install.sh scriptDir is /symphony/runtime/agent/bin
ATLAS_HOME is /atlas, use this config? y
ATLAS_HOME is /atlas
ATLAS_ENV is nexus
Creating directory lib
Creating directory logs
Creating directory temp
Creating directory work
$
The script asks for confirmation to proceed with the specified configuration, and once this is done the installation completes.
This process creates startup.sh
and shutdown.sh
scripts in the current directory which contain defaults for the specified environment configuration. It is not necessary to set the
ATLAS
_ environment variables each time the server is started and stopped.
If we examine the startup script we will see the following. The first section sets default values for the configuration based on the values set when running the install script:
$ cat startup.sh
#!/usr/bin/env bash
# ----------------------------------------------------------------------------
# Copyright (C) 2015 - 2016
# Symphony Communication Services LLC
# All Rights Reserved
# ----------------------------------------------------------------------------
# The information contained herein is proprietary and confidential, and may not
# be duplicated or redistributed in any form without express written consent of
# Symphony Communication Services LLC
# ----------------------------------------------------------------------------- if test "$JAVA_HOME" == "" then
Administration Guide – Enterprise / Business Version 177 18-‐Apr-‐2016
export
JAVA_HOME="/Library/Java/JavaVirtualMachines/jdk1.7.0_80.jdk/Contents/Home" fi if test "$CATALINA_HOME" == "" then
export CATALINA_HOME="/symphony/apache/apache-tomcat-8.0.26" fi if test "$ATLAS_HOME" == "" then
export ATLAS_HOME="/atlas" fi if test "$ATLAS_ENV" == "" then
export ATLAS_ENV="nexus" fi
Then the Atlas configuration is loaded and the standard Tomcat startup script is called from
CATALINA_HOME
with configuration parameters taken from the loaded Atlas config:
. $ATLAS_HOME/bin/initAtlas.sh symphony agent if ! setAtlasConfigDir certDir certs then
echo No certs directory in Atlas Symphony Config >&2
exit 1 fi
CATALINA_BASE="/symphony/runtime/agent" JAVA_OPTS="-
Dshutdown.port=${agent_shutdown_port}
-Dajp.port=${agent_ajp_port}
-Dhttp.port=${agent_http_port}
-Dhttps.port=${agent_https_port}
-Dkey.store=$certDir/server.keystore
-Dtrust.store=$certDir/server.truststore
-Djava.library.path=/symphony/runtime/agent/cryptolibs
-Djavax.net.ssl.trustStore=$certDir/server.truststore
-Djavax.net.ssl.trustStorePassword=changeit
-DXjavax.net.debug=all
" $CATALINA_HOME/bin/startup.sh "$@"
$
You may wish to run the Atlas listProperties.sh script to see how the configuration is constructed and what the final values of the variables used above are in your environment.
The Atlas utilities can be found in atlas/bin
in the distribution directory, which in this example, as we said above, we have copied to
/atlas
. It is necessary to tell the listProperties script which application configuration to load (as command line arguments) as well as which environment to select and the location of the Atlas home directory (as environment variables):
$ ATLAS_HOME=/atlas ATLAS_ENV=nexus sh /atlas/bin/listProperties.sh symphony agent
List Properties scriptDir is /atlas/bin
Administration Guide – Enterprise / Business Version 178 18-‐Apr-‐2016
ATLAS_DEBUG is true
------------------------------------------------------- loading config from /atlas/conf/default/atlas.properties...
ATLAS_DEBUG is true
------------------------------------------------------- loading config from /atlas/apps/symphony/conf/default/atlas.properties... pod_https_port = 443 symphony_host = localhost.symphony.com keymanager_host = localhost.symphony.com
ATLAS_DEBUG is true
------------------------------------------------------- loading config from /atlas/apps/symphony/conf/default/agent.properties... agent_shutdown_port = 8006 agent_ajp_port = 8016 agent_http_port = 8086 agent_https_port = 8446 session_auth_https_port = 8444 keymanager_auth_https_port = 8444 agent_host = ${symphony_host}
ATLAS_DEBUG is true
------------------------------------------------------- loading config from /atlas/apps/symphony/conf/env/nexus/atlas.properties... symphony_host = your.host.name keymanager_host = your.host.name
ATLAS_DEBUG is true
------------------------------------------------------- loading config from /atlas/apps/symphony/conf/env/nexus/agent.properties... agent_host = localhost keymanager_auth_https_port = 8444 session_auth_https_port = 8444
ATLAS_DEBUG is true
------------------------------------------------------- loading config from /atlas/apps/symphony/conf/global/atlas.properties... symphony_url = https://${symphony_host}:${pod_https_port} keymanager_url = https://${keymanager_host}:${pod_https_port}/relay login_url = ${symphony_url}/login
ATLAS_DEBUG is true
------------------------------------------------------- loading config from /atlas/apps/symphony/conf/global/agent.properties... agent_url = https://${agent_host}:${agent_https_port}/agent pod_url = https://${agent_host}:${agent_https_port}/pod session_auth_url = https://${symphony_host}:${session_auth_https_port}/sessionauth keymanager_auth_url = https://${keymanager_host}:${keymanager_auth_https_port}/keyauth
ATLAS_DEBUG is true
------------------------------------------------------- loading config from /atlas/conf/global/atlas.properties...
Environment =================================================================
ATLAS_DEBUG=true
ATLAS_ENV=nexus
ATLAS_HOME=/atlas
CATALINA_HOME=/symphony/apache/apache-tomcat-8.0.26
HOME=/Users/bruce.skingle
JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.7.0_80.jdk/Contents/Home
LANG=en_US.UTF-8
LOGNAME=bruce.skingle
MAVEN_HOME=/symphony/apache/apache-maven-3.3.3
PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/symphony/apache/apache-maven-
3.3.3/bin
PWD=/symphony/runtime/agent/bin
SHELL=/bin/bash
SHLVL=2
Administration Guide – Enterprise / Business Version 179 18-‐Apr-‐2016
TERM=xterm-256color
TERM_PROGRAM=Apple_Terminal
USER=bruce.skingle
XPC_FLAGS=0x0
XPC_SERVICE_NAME=0
_=/usr/bin/env agent_ajp_port=8016 agent_host=localhost agent_http_port=8086 agent_https_port=8446 agent_shutdown_port=8006 agent_url=https://localhost:8446/agent keymanager_auth_https_port=8444 keymanager_auth_url=https://your.host.name:8444/keyauth keymanager_host=your.host.name keymanager_url=https://your.host.name:443/relay login_url=https://your.host.name:443/login pod_https_port=443 pod_url=https://localhost:8446/pod session_auth_https_port=8444 session_auth_url=https://your.host.name:8444/sessionauth symphony_host=your.host.name symphony_url=https://your.host.name:443
=============================================================================
$
This script lists the values being assigned from each file in the order in which they are processed and finishes by displaying the contents of the environment which shows the final values resolved from the whole configuration.
If there are errors in the configuration you can edit the various properties files in place, there is no need to re-run the installation script after making changes to the configuration. When you are happy that the configuration is correct, go to the bin directory within the install directory and run the startup script:
$ ./startup.sh
Using CATALINA_BASE: /symphony/runtime/agent
Using CATALINA_HOME: /symphony/apache/apache-tomcat-8.0.26
Using CATALINA_TMPDIR: /symphony/runtime/agent/temp
Using JRE_HOME:
/Library/Java/JavaVirtualMachines/jdk1.7.0_80.jdk/Contents/Home
Using CLASSPATH: /symphony/apache/apache-tomcat-
8.0.26/bin/bootstrap.jar:/symphony/apache/apache-tomcat-8.0.26/bin/tomcat-juli.jar
Tomcat started.
$
Once the server is started you can watch the contents of the log file (which can be found in logs/catalina.out
directory of the installation) by running the taillog.sh script:
$ ./taillog.sh
[localhost-startStop-1] SbeSessionManager ? - API Agent configured. Symphony is at https://your.host.name:443
[localhost-startStop-1] V1PodApi ? - API Implementation com.symphony.agent.pod.V1PodApi started.
[localhost-startStop-1] ProviderInitServlet ? - Pod API configured from Atlas.
[localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployWAR Deployment of web application archive /Users/bruce.skingle/symphony/runtime/agent/webapps/pod.war has finished in 2,139 ms
[main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["http-nio-8086"]
Administration Guide – Enterprise / Business Version 180 18-‐Apr-‐2016
[main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["http-nio-8446"]
[main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["ajp-nio-8016"]
[main] org.apache.catalina.startup.Catalina.start Server startup in 4810 ms
The log file contains detail about the Atlas configuration being loaded and should end with a line which says
Server startup in 4810 ms
, although the time will vary.
Testing the Agent Server using the Simulator Example Programs
If you have already installed the Agent API Simulator, as described above then go to the examples directory in the simulator install. If you have not done so then the following example shows how to install the download file (which can be obtained from developers.symphony.com
). This process is explained in more detail in section Agent
Simulator Installation on page 150.
$ cd /symphony/runtime/
$ tar xf agent-simulator-1.0.0-bin.tar.gz
$ cd agent-simulator/bin
$ ./install.sh scriptDir is /symphony/runtime/agent-simulator/bin
The Agent API Simulator executes as three tomcat instances
This script can be configured to set the TCP ports used from a base value X.
The recommended and default base value is 9.
The following ports will be used (and must be available for use):
X006 API Agent Catalina shutdown port
X016 Catalina AJP/1.3 port
X086 HTTP service port
X446 SSL service port
X004 Pod Catalina shutdown port
X014 Catalina AJP/1.3 port
X084 HTTP service port
X444 SSL service port
X005 Key Manager Catalina shutdown port
X015 Catalina AJP/1.3 port
X085 HTTP service port
X445 SSL service port
Enter base port number,
enter 9 to set the API Bridge SSL port to 9443
enter 11 to set the API Bridge SSL port to 11443
8
PORT_BASE is 8
JAVA_HOME is /Library/Java/JavaVirtualMachines/jdk1.7.0_80.jdk/Contents/Home
CATALINA_HOME is /symphony/apache/apache-tomcat-8.0.26 baseDir is /symphony/runtime/agent-simulator
Type y to proceed? y
Creating certificates...
<some output omitted>
$ cd /symphony/runtime/agent-simulator/examples/
Administration Guide – Enterprise / Business Version 181 18-‐Apr-‐2016
We can now use the javaIM.sh example program to create an IM and send a message.
For this example we have created a second user account called bot.user2
.
As before, we need to specified the ATLAS configuration home and the environment we are using:
ATLAS_HOME=/atlas ATLAS_ENV=nexus ./javaIM.sh scriptDir is /symphony/runtime/agent-simulator/examples
/symphony/runtime/agent-simulator/examples/javaAuthenticate.sh: line 16: title: command not found
Enter user number to authenticate as.
User 0 is an imposter.
When using the API simulator
User 1 is a Valid user
User 2 is a User with no permissions
User 3 is a User from another company
Enter user number? [1]
1
The example program gives us a choice of user to authenticate as, we will select
1
which will pick up the certificate in the file bot.user1.p12
which is linked to the bot.user1
account.
We will then see a number of lines of log data (which is written to the standard error by the default log4j configuration embedded in the sample program) we will see the result of the example program authenticating using the bot.user1 certificate:
Token sessionToken =
84d0a5ad0faeea8eb98c0f144f5cea52a5eefccb181c56f4d92e2140f0abfa4966fe2dd83cc1c0cd21 b8bbdefbcc3e1926c6eb62576b441380d2ae006ca9d565
Token keyManagerToken =
010008e589ad28329dca2ce2263adfa6710934501a2156a2f5eccf477e9f4577df9696fbfc597b3a97 b0d9b40c9fe14eccda68bd1ade89bf9b87ba34bfaab391c4e08d3031f7df94820243bb51c82f83aaab
87ff526f0c932bb496843ac4285511be034b7957f9013fb28bb230404c6cf1e7c5c8a23591f4f91c9e
7a58cf3159160a9ec568d3afaf7a0b393654b366e556ecff60266e659cd6ab6a512e90cfa3ad26adc3
92c283373ffc7bf777a223995e00
EMail Address [[email protected]] ?
The program then prompts us to enter an email address to look up a user, since we have created a user called bot.user2
and given that user an email address at example.com
we can just hit
RETURN
to accept the indicated default value. We can also accept the provided user ID value which is found by looking up the user email address. The program then finds or creates an IM session between bot.user1
and bot.user2
and displays the thread ID of that IM session and displays a menu:
EMail Address [[email protected]] ?
Email address not found
User ID [7627861917906] ?
Stream ID is c7YlL3X3egl07oD9VNhphX___q2Ep2dRdA
---------------------------------------------------------------------------
1 Plain Text
Administration Guide – Enterprise / Business Version 182 18-‐Apr-‐2016
2 MESSAGEML q Quit Program
Enter selection [q] ?
If we select
2
to enter a formatted message in messageML format the program offers a default message which we will accept by pressing
RETURN
:
Enter selection [q] ?2
Enter message [<messageML>Hello <b>World!</b> This is a message about the <hash tag="AgentAPI"/></messageML>] ?
---------------------------------------------------------------------------
1 Plain Text
2 MESSAGEML q Quit Program
Enter selection [q] ?
This message is then sent and the menu redisplayed. If we go to the Sympjhony UI and log in as bot.user2 we will see the conversation together with the message:
As you can see, the formatting specified in the MessageML has bee rendered and the string
AgentAPI has been entered as a Hashtag.
BULK MANAGE USERS (CSV Import)
You can use the BULK MANAGE USERS 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 USERS 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.
Administration Guide – Enterprise / Business Version 183 18-‐Apr-‐2016
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 USERS 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.
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,<space>Fibonacci
2. You will need quotes when importing fields that contain commas
Example: “Department of IT, Networking and Communications”
Administration Guide – Enterprise / Business Version 184 18-‐Apr-‐2016
And you should make sure the quote character is the ASCII 34 (22Hex) symbol rather than your word processor’s quotation marks, which will be interpreted as part of the field, rather than as a CSV delimiter. To illustrate this challenge -‐ I am typing this document in
Word, which intelligently displays hyphenation marks whenever I press the quote symbol on my keyboard. This of course is not what I want for my examples, so I have to manually enter the ASCII symbol <Quotation Mark, UTF-8: 22> which delivers " rather than
“.
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
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
Administration Guide – Enterprise / Business Version 185 18-‐Apr-‐2016
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
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 <null>
(if no password had been set).
2. Manually set a new password: Type in a valid password string in the password field.
3. Generate a set password email: enter “SEND_EMAIL” in the password field.
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.
Administration Guide – Enterprise / Business Version 186 18-‐Apr-‐2016
More about SEND_EMAIL
It’s worth spending a little more time discussing the “SEND_EMAIL” instruction in order to avoid undesired outcomes.
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 187 18-‐Apr-‐2016
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 188 18-‐Apr-‐2016
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 189 18-‐Apr-‐2016
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 reauthenticate 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 190 18-‐Apr-‐2016
Audit Trail
Audit trails are used to display a change history for a specific user. You select a user from the MANAGE USERS 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 191 18-‐Apr-‐2016
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:
The values for the Audit Trail fields are shown in the table below:
Administration Guide – Enterprise / Business Version 192 18-‐Apr-‐2016
Date Action
User created
Logged in
Logged out
Triggered password reset
Reset password
Feature Entitlement Change
<date/time stamp>
Deactivate
Activate
User profile info updated
Attribute
Type of conversation
New Value Old Value
Action performed by
Allowed File Types
Allow File Sharing
Access Twitter Content
Allow Users To Have Delegates
Status
Status
Username
Display Name
First Name
Last Name
Email Address
Location
Title
Job Function
Department
Division
<link to latest avatar>
<value(s)>
Inactive
<value>
<value(s)> on/off on/off on/off on/off
Inactive
Active
<value> <username>
Avatar
Asset Class
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 193 18-‐Apr-‐2016
Administration Guide – Enterprise / Business Version 194 18-‐Apr-‐2016
Download
Public link updated
The public link to your chat has been updated. You may view and manage your chat links after registration here.
Document public link
Advertisement
Key features
Secure communication and workflow platform
Seamless exchange of high value content
Connect users to their community
Improve workplace productivity
Maintain organizational compliance
Cloud-based platform
Frequently asked questions
Symphony is a cloud-based, secure communication and workflow platform designed to seamlessly exchange high value content and information, connect users to their community and improve workplace productivity through collaboration while maintaining organizational compliance.
This is an Administration Guide.
You can log into the Admin Portal by entering the URL that was communicated to you along with your account details.
Symphony provides a hierarchy of roles for provisioning, managing and supporting your service - we provide full details on role management in the Roles section.
You should have the latest version of the Google Chrome browser running on Windows, Mac or Chromebook computers or Internet Explorer (IE) 11.
