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.
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.
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.
During the creation of your pod (your company’s dedicated Symphony cloud service) we provisioned the following items:
The FQDN (domain name) for your pod
The associated IP address range
The credentials for your Super Admin account
Credentials for the Super Compliance Officer account
You should have received all of the relevant details in an email from Symphony Global Services.
Super Compliance Officers receive their credentials separately
Please locate this email and follow the instructions it contains.
You should have the latest version of the Google Chrome browser running on Windows, Mac or Chromebook computers or Internet Explorer (IE) 11.
The Symphony client needs to have access to various components located outside your Firewall.
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.
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:
<OrgName>-tools.symphony.com port 22
We use Amazon Simple Email Service (Amazon SES) to send application transaction emails.
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
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
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
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.
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.
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:
Click on the Go to AC portal option located at the bottom of the General options tab.
You will now access the Admin portal. The left navigation bar shows the high-level features available in the admin portal:
Moving the mouse over the admin’s name (located on the top right corner) will display:
Logout Note that for security reasons, your account will be logged out automatically after ten minutes of inactivity.
Symphony this is your personal end-user Symphony account.
Help a fully indexed version of this Admin Guide in electronic form (see screenshot below)
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.
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:
Things to notice:
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
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.
Email The email address is required and must be unique across all active accounts.
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.
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:
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.
Have Symphony generate a password for you – you’ll then need to copy and communicate it to the user.
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:
Username*
Display name*
Surname*
First name*
Email address*
Password*
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).
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.
Depending on what you selected, you’ll see one of the following:
Email Link:
Password set manually:
If you entered an invalid password:
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:
The username is the name you assigned when you created the account. Please make sure to communicate to the user what their username is.
When the user logs into the client for the first time, they will be presented with a list of contacts pre-populated from the choices you or other admins made when assigning users to departments and divisions. The user can select the contacts to add from this list and they will be added to their IM list in the left navigation panel.
Similarly, a second screen will display pre-populated topic filters that are generated from the asset classes and industries that you selected for each user. They can select the specific topics that are of interest and these will be added to their FILTERS list in the left navigation panel.
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.
Users can change their password themselves by clicking on the Forgot Password? link on the login page.
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:
Select MANAGE USERS
Click once on the user you want to manage
Select Account Security
Select Assign New Password or Send Link via Email
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 re-authenticate to login.
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.
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:
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)
SafeNet Luna SA 7000 HSMs running on the customer premises
CloudHSM an Amazon Web Service that uses the SafeNet Luna SA 7000
| Symphony Software SM | AWS CloudHSM | Luna SA 7000 HSM | |
|---|---|---|---|
| Hardware protection | No | Tampering will cause immediate deletion of keys | Tampering will cause immediate deletion of keys |
| Network protection | No | Disconnection will cause immediate deletion of keys | Disconnection will cause immediate deletion of keys |
| Key Generation | Software-based | Hardware-based | Hardware-based |
| HA Architecture | Requires external LB or DNS failover | Enabled through HSM Client software | |
| Access Control | Password-based | Password-based FIPS 140-2 |
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 service | Luna SA 7000 Hardware |
| Commercialization | Included with the Key Manager download – no additional charge | 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.
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.
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:
Three primary components are involved in encrypting and decrypting customer content:
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.
Please review each of the deployment options shown below to determine which will be appropriate for your organization:
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.
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.
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.
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.
This section provides guidance on where, on your corporate network, to install the Key Managers and HSMs.
Considerations:
Who will manage these devices in the future?
Whether a physical access is required in order to back up the keys
How firmware and software upgrades will be deployed?
Will backup power be available?
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:
in the same physical location (Each Key Manager and HSM should be close to each other)
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?
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.
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.
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)
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
Copy this package to the server where you will run KeyManager and unzip it. UnlimitedJCEPolicyJDK7.zip contains 3 files
local_policy.jar
README.txt
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
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 Serial # Label ==== ======== ===== 1 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):
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:
"enablekeymanagersession" : "true", "sessionencryptionkey": "kxHpEh3ddcjNrxOXpuSbR5fvNUh8yl21/mmS5W
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
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”.
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:
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 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
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.
The following command can be used to update an rpm:
and the following command can be used to verify that software was installed:
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)
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 +)
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.
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
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
local_policy.jar
README.txt
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
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.
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
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.
To import the full chain of trust into the tomcat.keystore perform the following steps
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
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
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
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:
[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:
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.
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", "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"
}
}
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",
Administration Guide – Enterprise / Business Version 33 23-May-2016
"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"
}
}
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
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.
You should also be able to navigate to the resultDir folder and see that the *.jck file has been created.
It is important to put the *.jck file that was created into the /data/tomcat/config directory.
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.
It is NOT currently possible to share Tomcat containers with other Symphony applications such as the Content Export Bridge.
Be aware that the Tomcat configuration is also different depending on whether you are installing the Software SM or full HSM from Safenet.
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/tomcat-juli.jar \ -Dcatalina.base=$CATALINA_BASE \ -Dcatalina.home=$CATALINA_BASE \ -Djava.io.tmpdir=$CATALINA_BASE/temp \ -Dsession.cookie.domain=.pubmy.mykeymanager.com \ -Daccess.control.allow.origin=symphony.com,mykeymanager.com \ -Djava.library.path=$CATALINA_BASE/native/ \ -Djavax.net.ssl.keyStore=$DATA_BASE/certs/tomcat.keystore \ -Djavax.net.ssl.keyStorePassword=password \ -Djavax.net.ssl.trustStore=$DATA_BASE/certs/tomcat.keystore \ -Djavax.net.ssl.trustStorePassword=password \ -Dserver.port=8443 \ -Dajp.port=8009 \ -Dserver.command.port=8005 \ -Ddisable.ib=true \ -Dhost.name=host.domain.com \ -Dmax.threads=3000" PATH=$JAVA_HOME/bin:$JAVA_HOME/jre:$PATH
If using a proxy to access the KeyManager than the following line should be added to /data/tomcat/config/environment.sh – change <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.
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", "idp.signingcertificate": "sso-<env>.symphony.com.cer", "ssoenabled": "false"
},
"sessionmanagement": {
"enablekeymanagersession": "false", "sessionencryptionkey": "session_encryption_key"
}
}
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"
}
}
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 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.
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
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
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.
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 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.
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 RSA (1024-4096 bit), PKCS #1 v1.5, OAEP PKCS#1 v2.0 • Diffie-Hellman (1024 bit) |
|
Suite B Algorithm Support |
ECC Support • ECDSA • ECC Brainpool Curves (named and user-defined) |
|
Digital Signing |
RSA (1024-4096-bit), DSA (1024-bit), PKCS #1 v1.5 |
|
Symmetric Key Algorithms |
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 |
-20°C to +65°C |
|
Power Requirements |
+5V@3A Max; [email protected] Max (FIPS Level 3 only) |
|
Dimensions |
4.1” by 7.88” |
|
Connectivity |
PCI-X r1.0b |
|
PCI Module |
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 |
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 |
908-000095-004-000 |
LUNA SA 7000 REMOTE PED BNDL (2 HSMP,CL,SW 5.3.5,FW 6.2.1/6.10.2,REMOTE PED,20 PED KEYS,BACKUP HSM) |
$36,500.00 |
$24,436.75 |
$24,436.75 |
|
1 |
908-000071-004-000 |
Luna SA 7000 PED-Auth,2 HSMP,CL,SW V5.3.5,FW6.2.1/6.10.2) |
$29,500.00 |
$19,750.25 |
$19,750.25 |
|
4 |
912-00004-901-000 |
POWER CORD,110 VAC,USA,ROHS |
$25.00 |
$16.74 |
$66.96 |
|
1 |
020-160005-021-000 |
Professional Services quickstart,HSM,LUNA EFT,3RD PARTY PAYMENT HSM Key migration,one site, incl travel |
$11,500.00 |
$10,660.50 |
$10,660.50 |
|
1 |
020-160001-014-000 |
Three year of Plus maintenance service 17% of product list price |
$33,660.00 |
$33,660.00 |
$62,500.20 |
|
|
$88,641.42 |
||||
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.
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.
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 servers can be connected to a single HSM or to a High Availability group made up of multiple HSMs. Please review the diagram below:
We show the on-premises key infrastructure in relationship to the other on-premises components and clients below:
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.
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.
Configuration of the Luna SA consists of the following steps:
Configure Luna SA for your network
Initialize the HSM and adjust polices
Create a partition and adjust policies
Set up a network trust link to a client
Assign a registered client to the partition
Use the partition from the client
Before you begin, gather the following information and write it down:
Appliance Admin password
Network Parameters
Network Address (IP)
Hostname
Domain Name*
Default Gateway
DNS Name Server*
Search Domain*
Subnet Mask
HSM Label
Domain PW
Security Officer PIN (optional)/PW
Partition Name
Partition User PIN (optional)
Partition Password
* Only required if using DNS. Have your network administrator add an entry to your company’s DNS for the Luna SA.
Partition Password will be generated later, by the Luna PED. You will need to record it at that time for your Clients to use
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.
Connect to DB9 serial port with a terminal emulation (in this case Serial).
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:
Speed (baud): 115200
Data bits: 8
Stop bits: 1
Parity: None
VT-100 terminal emulation
Hardware flow control
(You may need to press [ENTER] several times to initiate the session)
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.
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:
Log in as admin and enter the Safenet factory password:
Local_host login: admin
Password: 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,-_!@#$%&*...)
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.
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.
The structure of the network configuration command is shown below:
lunash:> net interface static -device <NetDevice> -ip <NetDeviceIP> -netmask <NetMaskIP> -gateway <GatewayIP>
lunash:> net i static -dev eth0 -ip 192.168.159.30 -n 255.255.255.0 -g 192.168.159.1
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.
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>
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.
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.
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 on the touchpad). Have a set of PED keys available.
Type the 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>
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.
Stop all applications and services that are using the HSM.
Download the Luna SA appliance software upgrade packages from the following links
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>:
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
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>
Reboot the HSM appliance with the following command:
lunash:> sysconf appliance reboot
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.
The SafeNet Luna SA 7000 uses partitions to store keys.
Every physical partition has to have a unique name and the same password
Every Key Manager server has to be connected to one(and only one) physical partition
Key Managers can share physical partitions
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
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.
(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
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>
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.
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)
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
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…
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
For example
$> sudo chown ivan:admins /etc/Chrystoki.conf $> sudo chown -R ivan:admins /usr/safenet/lunaclient/
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.
Open a terminal window on the Client, and change directory to 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.
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
Now you can confirm whether the server has been added by using the following command:
$:> ./vtl listservers
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 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:
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.
Now you should confirm whether the client has been registered using the following command and you will see a list of registered clients.
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.
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.
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.
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
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.
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:
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.
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.
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
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.
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.
Before we begin, it’s worth discussing the various roles available in Symphony:
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.
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.
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.
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 CO/SCO/A will not be in the business of even triggering a password rest. Hence this is blocked too.
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.
Super Compliance Officers will be able to manage and grant additional entitlements to standard Compliance Officers (COs):
Can monitor wall posts
Can monitor chats
Select BROWSE ACCOUNTS in the left Nav. Then filter the list by role and select compliance officers. Find the compliance officer who will be granted the additional entitlements and display their user details by clicking on their record in the list. Then use the Role section to grant the additional entitlements (see screenshot below):
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.
First Name
Last Name
Location
Division
Department
Last login
Date Created
Date Updated
Role
Status: Active and inactive users
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.
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:
To edit a user:
Select MANAGE USERS from the Admin menu and then highlight the user we want to manage:
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.
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.
To promote a user to admin:
Click on the Account Settings tab.
Select the Administrator box.
To change 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.
Service User accounts are used by applications. They leverage the Symphony APIs to interact with your Symphony Pod – either to automate administration or for value-added applications. One important use case for service user accounts is LDAP Synchronization which requires a service user account in combination with the directory bridge server.
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.
For LDAP Sync: When configuring the service account to support LDAP Sync you must configure it as an Admin role.
Once the fields have been entered as described above, press the CREATE button located at the bottom of the form. This will generate a security key. You should immediately copy the security key.
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.
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.
When you first deploy your pod, three features are activated by default, meaning that whenever you create new users they are authorized to:
Delegate: Allow another user to POST on their behalf (deactivated by default)
Share Files internally
Communicate and share files externally
Allow users to create public rooms
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 might be time-consuming for larger implementations and FEATURE ENTITLEMENTS provides additional flexibility for controlling these three features at a system-wide level.
In this section we describe the various combinations for configuring feature entitlement using two dropdown boxes:
Disable for entire pod?
Disable for entire pod
Manage at user level
Assign to new users by default?
Yes
No
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 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:
First decide whether you need to disable any of these features
Inform any existing users that you are about to disable the feature
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):
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.
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.
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:
First decide which features will be enabled by default
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
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.
You can still toggle this feature for individual users with the MANAGE USERS option (see section entitled “Making changes to an individual user”)
The screen extract below shows the relevant settings for activating Twitter content for all new users.
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.
First decide which features you want to set exclusively by setting the feature for each user manually
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
Select No in the next column under the heading Assign to new users by default?
You can enable this setting for individual users with the MANAGE USERS option (see section below)
Admins can control whether users will be able to communicate externally by default. There are important regulatory compliance issues to consider when activating this feature at the company level. Some regulated organizations will prefer to enable this feature at the user level which we describe in a section below.
If a user is granted either:
Can chat in external IM/MIMs
Can chat in private external rooms
Then they will be visible in searches by external users and will also be able to search for and communicate with external users.
Both participants must have External communications activated by their respective admins for this feature to work.
Users must first request a connection with an external user before being able to communicate with them. Two additional entitlements are available for controlling external communications:
Can send files externally
Require user warning for external communications
Details on how to use external communications are provided in the user guide. You can also ensure that users will receive a warning whenever they initiate external communications using:
Require user warning for external communications
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:
Enable the “Can Send Files” feature following the instructions above
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
.jpg, .jpeg
Will also allow .JPG and .JPEG extensions.
An empty “Allowed file types” field is equivalent to disabling the “Can send files” feature.
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:
There is currently no way to set entitlement features at the point of creating the account (either directly using the CREATE A USER option or indirectly using the BULK MANAGE 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.
An additional entitlement has been added to prevent information from being displayed on the iPhone lock screen. This option is displayed as a new feature entitlement setting:
Hide chat and usernames in mobile notification
Users can be blocked from communicating with or receiving communications from unaffiliated users (public users) using the BLACKLIST option in the left Nav. The admin can set this feature by selecting MANAGE BLACKLIST from the left Nav.
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.
Select DOWNLOADS from the left nav. of the Admin Portal. Click on Desktop client for Windows to download the 32-bit version.
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.
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:
Login into the Admin Portal of your private pod
Select the DOWNLOAD option in the left nav.
Select the Desktop client for Windows (this is an MSI file - first download it)
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.
If the installation is successful, a shortcut is added to the Windows desktop
Right click on the shortcut and display Properties
Locate the installation path
Copy Symphony.pgx located under your <install path>/minuet/symphony/bin/apps to a temp location such as c:\temp
Navigate to your temp folder and rename Symphony.pgx to Symphony.zip (Windows may ask you to confirm the renaming of the file extension)
Unzip the Symphony.zip file and you will see a new Symphony folder
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
Inside the Symphony folder, select all files and right click, select Send to -> Compressed (zipped) folder, and name the file Symphony.zip
Rename Symphony.zip to Symphony.pgx (Again, Windows may ask for confirmation)
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.
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
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.
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.
Before you configure SSO, you should obtain the following information:
IdP entity ID
IdP SSO endpoint
IdP signing certificate (this will be a file)
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.
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.
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.
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.
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:
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.
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.
Admins must have a password to log in to the Admin portal even when SSO has been enabled for the pod.
In the future, if you decide to revert to manual passwords, you can select Configure SSO again and will see the following:
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.
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 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:
Log into the Admin Portal and create a user and select Service Account (see the section on managing Service Accounts)
Copy the system-generated security key (you will need this for configuring your Directory Bridge
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.
Install a Linux RHEL server (virtual or physical)
Follow the installation instructions below
Unzip the distribution
Run setup, following the instruction below
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
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
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.
Define similar mappings for Feature Entitlement (including roles such as Admins)
Synchronize your directories – LDAP server to the Symphony Pod via the Directory Bridge
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.
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.
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.
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
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
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.
RAM: 4 GB gigabytes
Hard drive: logs will require 250 MB.
Processors: 4
Operating System: Linux RHEL Fedora 2015.03 (This AWS supported OS has been validated by Symphony)
JVM: Java 7 Standard Edition, Enterprise Edition - a Java development kit (JDK) is recommended
JVM 64-bit is recommended
Virtual Servers: both on-premises and cloud-hosted are supported
Before beginning the installation process, gather the following information:
LDAP source system info
The host and port of the LDAP system.
The DN and password of the LDAP user that LDAP Sync will use to connect to the LDAP source system.
The base DN for all user and group entries that LDAP Sync will need to access
The base DN for user entries
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.
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.
Symphony info
The username and key for the Symphony service user that will be used to access the Symphony APIs
The base path to the Symphony APIs. This will be something like "https://mycompany.symphony.com".
Sync configuration info
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.
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” is effectively the list of all active Symphony users. A user account will be Activated when the account is added to this group and Deactivated if it is then removed. Adding the account name back into the group will Reactivate the account.
Mapping the group used in your corporate directory to the “Symphony Users Group” is accomplished by editing directorybridge.properties file – see step 13 below.
The following table lists what happens when the Symphony “Symphony Users Group” is or is NOT enabled:
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.
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.
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.
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
The stability of Directory Bridge declines when there are more than 1000 users created manually in Symphony who don't also exist and are not mapped to accounts in the corporate directory system. We recommend either deactivating the manually created Symphony users to bring the number of manually created users below 1000 or including those users in the LDAP sync’ed users.
When the admin simultaneously removes a user from a group and adds the same user to another group then the user does not get removed from the first group. In order to avoid this occurrence, admins should first apply one change (removing the user from the first group) and then applying the second change (adding the user to the second group).
When a group is mapped to two roles in the same category (ADMIN/SUPER_ADMIN or L1_SUPPORT/L2_SUPPORT) 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'
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.
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.
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.
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.
$gt; sudo rpm --install <file>
This will create user symphonyldapsync, install the software at /opt/DirectoryBridge, which we will hereafter refer to as $syncroot.
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>
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 |
Stores the physical backup files used with the backup command-line tool |
|
bat |
Stores Windows-based command-line tools for the Identity Data Store |
|
bin |
Stores UNIX/Linux-based command-line tools for the Identity Data Store |
|
classes |
Stores any external classes for server extensions |
|
config |
Stores the configuration files for the backends (admin, config) as well as the directories for messages, schema, tools, and updates |
|
db |
Stores the Oracle Berkeley Java Edition database files for the Identity Data Store |
|
docs |
Provides the release notes, Configuration Reference file and a basic Getting Started Guide (HTML) |
|
import-tmp |
Stores temporary imported items |
|
ldif |
Stores any LDIF files that you may have created or imported |
|
legal-notices |
Stores any legal notices for dependent software used with the Identity Data Store |
|
lib |
Stores any scripts, jar, and library files needed for the server and its extensions |
|
locks |
Stores any lock files in the backends |
|
logs |
Stores log files for the Identity Data Store |
|
resource |
Stores the MIB files for SNMP |
|
revert-update |
The revert-update tool for UNIX/Linux systems |
|
revert-update.bat |
The revert-update tool for Windows systems |
|
setup |
The setup tool for UNIX/Linux systems |
|
setup.bat |
The setup tool for Windows systems |
|
uninstall |
The uninstall tool for UNIX/Linux systems |
|
uninstall.bat |
The uninstall tool for Windows systems |
|
update |
The update tool for UNIX/Linux systems |
|
update.bat |
The update tool for Windows systems |
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
From $syncroot, run $> ./setup
This will launch a series of prompts. Some of them will be prepopulated with a default answer (shown within square brackets). To accept a default, simply press “enter” or “return” (depending on your keyboard). For a simple installation, we recommend that you accept the default value for each prompt as shown in the dialogue below (these settings can be changed later).
Do you accept the terms of this license? Enter 'yes' to accept, 'no' to reject, or press ENTER to display the next page of the license [yes] Would you like to add this server to an existing Identity Data Sync Server topology? (yes / no) [no] Enter the fully qualified host name or IP address of the local host [xx.xx.xx.xx] Create the initial root user DN for the Identity Data Sync Server [cn=Directory Manager] Create a password for the initial root user: [Enter your password] Re-enter the password for confirmation: [Enter your password] On which port should the Identity Data Sync Server accept connections from LDAP clients? [XXXX<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 Roos User DN: cn=Directory Manager LDAP Listener Port: 4389 The Identity Data Sync Server will be started after configuration What would you like to do? 1) Set up the server with the parameters above 2) Provide the setup parameters again 3) Cancel the setup Enter option [1] Configuring Identity Data Sync Server ..... Done Starting Identity Data Sync Server ..... Done This server is now ready for configuration. What would you like to do? 1) Start 'create-sync-pipe-config' to configure synchronization between two sets of servers 2) Start 'dsconfig' to edit the configuration 3) Quit
At this point, choose quit: 3
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 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
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"
Create the primary elements of configuration by running the following script using your own version of the example we displayed in section 6 above:
$> syncroot/bin/create-pipes.sh ../config/ldapsync.properties
Be sure to look at the output to ensure that all operations were successful. If any operation failed, then undo the script by running:
$> syncroot/bin/delete-pipes.sh ../config/ldapsync.properties
If all goes well then the following output will be displayed.
Creating external servers The Active Directory External Server was created successfully Creating sync source plugin The Third Party LDAP Sync Source Plugin was created successfully Creating sync source The Active Directory Sync Source was created successfully Creating sync destination for users The Third Party Sync Destination was created successfully Creating sync destination for groups The Third Party Sync Destination was created successfully Creating sync pipe for users The Sync Pipe was created successfully Creating sync pipe for groups The Sync Pipe was created successfully Creating sync class for users The Sync Class was created successfully Creating sync class for groups The Sync Class was created successfully Finished.
Until LDAP Sync is confirmed to be running smoothly, it is recommended that debug logging be enabled. Do this via the following command:
$>./dsconfig -n --bindDN "cn=Directory Manager" --bindPassword NotReallyThePassword set-log-publisher-prop --publisher-name "Server SDK Extension Debug Logger" --set enabled:true
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 othe LDAP server above – these are the ones who will be synchronized with your Symphony accounts
$gt; /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 --port 1389 -n --set include-base-dn:cn=Users,dc=fakecorp,dc=local --add "include-filter:(useraram=symphonyusers)"
Now we are ready to start synchronizing data. Please note that by default LDAP Sync will start at the beginning of the source LDAP system's changelog. For many enterprise LDAP systems, the changelog is extremely long. In such cases, LDAP Sync may take a long time time to work its way through all of the changes. This is especially true if many of the entries in the changelog are not of interest to LDAP Sync. Therefore, it is recommended that we first use LDAP Sync's resync utility to take care of historical data, and then configure LDAP Sync to start at the end of the changelog (before enabling real-time synchronization).
To do this, start by setting the starting point of each sync pipe as follows (as always, run from $syncroot) and use the password you entered for LDAP_SYNC_PASS above.
$> ./realtime-sync set-startpoint --end-of-changelog --pipe-name "Users to Symphony Sync Pipe" --bindDN "cn=Directory Manager" --bindPassword NotReallyThePassword --port XXXX ß - default port number from setup $> ./realtime-sync set-startpoint --end-of-changelog --pipe-name "Groups to Symphony Sync Pipe" --bindDN "cn=Directory Manager" --bindPassword NotReallyThePassword --port XXXXß- default port number from setup
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
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" --searchScope sub '(userparam=SymphonyUsers)' dn > entriesToSync.ldif
Note the use of --simplePageSize 1000. If the source LDAP system has a lower limit on the number of entries returned by an LDAP search, then a lower page size should be used. If all goes well, a file named entriesToSync.ldif will be created with contents similar to this:
dn: CN=Ruth Reynolds,CN=Users,DC=fakecorp,DC=local dn: CN=Super Man,CN=Users,DC=fakecorp,DC=local 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
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 ldap-memberof-attr=memberOf
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.
Disabling and Creating IB groups directly using LDAP sync is not currently supported.
Edit the file groupMappings.json and enter the name of your Symphony service (replacing fakecorp in the example file).
[
{
"dn": "CN=ComplianceOfficers,CN=Users,DC=fakecorp,DC=local",
"roles": ["COMPLIANCE_OFFICER"]
},
{
"dn": "CN=SuperComplianceOfficers,CN=Users,DC=fakecorp,DC=local",
"roles": ["SUPER_COMPLIANCE_OFFICER"]
},
{
"dn": "CN=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"]
}
]
Configure LDAP Sync user attribute mappings by first copying the example file:
$>cp userAttributeMappings-example.json userAttributeMappings.json
[
{
"symphony": "deptName",
"ldap": "department"
},
{
"symphony": "divName",
"ldap": "division"
},
{
"symphony": "location",
"ldap": "l"
},
{
"symphony": "givenName",
"ldap": "givenName"
}
]
The full list of “to-attribute” values is provided in the table below:
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
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.
Use the file generated in the previous step as an argument to the resync utility, as follows.
$> ./resync --sourceInputFile entriesToSync.ldif --pipe-name "Users to Symphony Sync Pipe"
This will produce information concluding with a status summary similar to the one shown below:
Status after completing all passes [09/Apr/2015:12:38:10 -0400] -------------------------------- Source entries retrieved 18 Entries in-sync 11 Entries dropped due to error 7 Duration (seconds) 25 Resync completed in 25 s. 11 entries were in-sync, 0 entries were modified, 0 entries were created, 0 entries are still out-of-sync, 0 entries are still missing, and 7 entries could not be processed due to an error
As documented in ./resync --help, ./resync log files can be found in $syncroot/logs/tools.
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
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.
Symphony’s LDAP Sync implementation has been designed to be “forward looking.” It cannot for example be used to delete accounts that have already been created. Such accounts should be deactivated rather than deleted and we provide an example below on how to configure ldap-user-deactivation.
A lot of flexibility is provided with the Directory Bridge and supporting utilities. However, care has been taken to ensure that the configuration settings described in this chapter prevent the bulk loading of your entire LDAP directory. If this did occur, as we state in the previous paragraph none of those accounts (even dormant ones) could be deleted from Symphony. If this is unclear, please review the installation instructions above (particularly step 10).
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
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.
During the initial configuration steps described above, we explained that entitlements are configured by updating the file groupMappings.json
These group mappings are used to configure:
Roles: SUPER_ADMINISTRATOR, ADMINISTRATOR, SUPER_COMPLIANCE_OFFICER, COMPLIANCE_OFFICER, L1_SUPPORT, L2_SUPPORT - Symphony Roles Available for Mapping to LDAP Groups (Please refer to the Roles section of the Admin Guide for details of what each role can do)
Feature Entitlements: sendFilesEnabled, delegatesEnabled, isExternalIMEnabled, isExternalRoomEnabled, canShareFilesExternally
InfoBarrier group membership: IB Name and ID number as listed in AC portal
Note that we were previously referring to “External Communications” using an internal code name: “Cross Pod”. We have changed the entitlement name as shown in the list above but will continue to support the previous entitlement name:
New Entitlement Names: isExternalIMEnabled, isExternalRoomEnabled,
Replaces: isCrossPodEnabled
We advise customers to move to the new entitlement name in order to avoid unwanted issues if support for the old entitlement name is dropped in the future.
At least one of these two new entitlements must be set for a user to appear in the global directory and be able to communicate externally.
In the example below we are still using the company “Fakecorp” which should be changed to your own company name. We show how to assign two roles: ADMINISTRATOR and COMPLIANCE OFFICER, how to grant the right to send files and finally how to configure Information barrier group membership.
[
{
"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"]
}
]
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.
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.
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.
A full list of the arguments supported by each Sync Destination follows.
The following table contains Sync Destination arguments that are common to all sync pipes (i.e. users, user entitlements, and distribution lists). These values are configured in the directorybridge.properties file.
Attribute maps are used to convert entries in the source LDAP system to entries that can be fed as input to Symphony REST API calls.
The following image illustrates an attribute map for users.
The full list of "to-attribute" values that are accepted for Symphony users are as follows.
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.
A Sync Class defines how a type of LDAP entry is synchronized. The following image illustrates a Sync Class for users.
Of particular interest here are "include-base-dn", "include-filter", and "attribute-map". The others are covered in detail in the admin guide. "include-base-dn" specifies the base DNs for the branches of the Sync Source that can be in this Sync Class. In the example above, "cn=Users,dc=fakecorp,dc=local" specifies a branch of the directory that will be included for user synchronization. "include-filter" contains a set of filters that define the source entries that should be included in this Sync Class. In the above example, only directory entries that have "person" as a value for the attribute "objectClass" shall be synchronized. For more information about "attribute-map" please refer to the corresponding section of this article.
The following image illustrates a Sync Class for groups.
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).
A Sync Source defines the source of a Sync Pipe, where changes to be synchronized are detected.
Sync Sources are defined with references to External Servers. The following image shows an External Server that corresponds to the above Sync Source.
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).
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.
The first task is to install a host computer for the Key Manager and Software SM.
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
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
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.
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.
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.
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.
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.
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
Please edit the Tomcat environment.sh file and customize it for your specific installation. This file is identical to the environment.sh file used by the Key Manager and certain lines highlighted below will need to be deleted. Please carefully review the example file below.
$> vi /data/tomcat/conf/environment.sh
#!/usr/bin/env bash DATA_BASE="/data/tomcat/" CATALINA_BASE="/opt/tomcat/" JAVA_HOME="/usr/java/jdk1.7.0_79" //Update with your java path CATALINA_OPTS="-server -Xms5048m -Xmx5048m -XX:MaxPermSize=256m \ -Djava.util.logging.config.file=$CATALINA_BASE/conf/logging.properties \ -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager \ -Dlog4j.configuration=file:$DATA_BASE/config/log4j.xml \ -Djava.endorsed.dirs=$CATALINA_BASE/endorsed \ -classpath $CATALINA_BASE/bin/bootstrap.jar:$CATALINA_BASE/bin/tomcat-juli.jar \ -Dcatalina.base=$CATALINA_BASE \ -Dcatalina.home=$CATALINA_BASE \ -Djava.io.tmpdir=$CATALINA_BASE/temp \ -Dsession.cookie.domain=.pubmy.mykeymanager.com \ -Daccess.control.allow.origin=podId.yourdomain.com,keymanager.yourdomain.com \ // pls change the first value to your domain url, and the second value to your on-prem keymanager -Djava.library.path=$CATALINA_BASE/native/ \ // The crypto lib compatible with your os version -Djavax.net.ssl.keyStore=$DATA_BASE/certs/keystore \ // we create an empty keystore for you, please make sure you replace this when you deploy to production -Djavax.net.ssl.keyStorePassword=password \ // and your keystore password -Djavax.net.ssl.trustStore=$DATA_BASE/certs/truststore \ //delete this line for CE Bridge -Djavax.net.ssl.trustStorePassword=changeit \ //delete this line for CEB -Dcom.symphony.keymanager.sdk.maxtotalconnections=2000 \ //delete this line for CEB -Dcom.symphony.keymanager.sdk.maxconnectionsperroute=1000 \ //delete this line for CEB -Dserver.bot.port=8444 \ //delete this line for CEB -Dserver.port=8443 \ -Dajp.port=8009 \ //delete this line for CEB -Dserver.command.port=8005 \ //delete this line for CEB -Dmax.threads=4000” \ -Dhost.name=change.it.to.full.server.host.name" //delete this line for CEB -Dceb.config.path=/opt/tomcat/symphony_cecs \ //optional, the folder containing the configuration.prepertites and key folderDproxy.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 podID-keymanager.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
Locate the Content Export Bridge RPM file downloaded earlier and begin the installation:
$> sudo rpm -ivh --prefix=/opt/tomcat --replacefiles
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
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).
Download sample tomcat http://mirror.cc.columbia.edu/pub/software/apache/tomcat/tomcat-7/v7.0.63/bin/apache-tomcat-7.0.63.zip
Unzip the package
Assuming you already set up unzip (otherwise: $> sudo yum install unzip)
$> sudo unzip -d [tomcat folder]
Add permission
$> cd [tomcat folder]/bin $> sudo chmod 755 *.sh
Create setenv.sh under bin folder containing the following information:
#[correct it if needed! It should be the tomcat folder] #[correct it if needed! It should be the jdk folder] CATALINA_OPTS="-server -Xms1024m -Xmx2048m -XX:MaxPermSize=256m \ -Djava.util.logging.config.file=$CATALINA_BASE/conf/logging.properties \ -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager \ -Djava.endorsed.dirs=$CATALINA_BASE/endorsed \ -classpath $CATALINA_BASE/bin/bootstrap.jar:$CATALINA_BASE/bin/tomcat-juli.jar \ -Dcatalina.base=$CATALINA_BASE \ -Dcatalina.home=$CATALINA_BASE \ -Djava.io.tmpdir=$CATALINA_BASE/temp \ -Djava.library.path=$CATALINA_BASE/native/ " PATH=$JAVA_HOME/bin:$JAVA_HOME/bin/jre:$PATH
Create the tomcat user and tomcat group
$> sudo useradd -U tomcat
Start Tomcat for your Content Export Bridge (CEB)
$> sudo ./startup.sh
If you already have a working Tomcat configuration, you can start here. First log into the Symphony Admin portal and select Download from the left Nav. and then select the Content Export Bridge rpm file.
Unzip the file and install the rpm (the rpm filename may have a different version number than the one shown below and prefix refers to the tomcat path)
$> sudo rpm -ivh --prefix=/opt/tomcat--replacefiles symphony-external-ceservice-centos70-0.14.0-45.x86_64.rpm
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
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
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 single-cecservice-0.0.1-0.x86_64.rpm
and then start the Content Export Bridge again:
$> sudo service tomcat start
To uninstall the Content Export Bridge:
$> sudo rpm -e cecservice
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.
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.
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.
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:
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:
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.
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:
02:00 hrs. UTC
04:00 hrs. UTC
06:00 hrs. UTC
the next job to run would be at 08:00 hrs. UTC
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:
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.
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.
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:
How smaller frequencies can be used to move the start time to a later time
How partial exports can be interrupted mid-way to reset the start time to the last completed export time
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 Actianceformat.
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.
There is currently no facility to cancel an export once the process is initiated.
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
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
<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
Total number of EML files
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-<Content- startdate+time(UTC)>_ContentStopDateUTC-<Content- stopdate+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
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:
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.
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.
The timestamp used for content export is in the form HH:MM:SS:mm where mm represents milliseconds.
The following information is exported:
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.
A message may have been sent to an IM conversation, chat room or a wall post.
Old messages are messages that were created before the current 24-hr time range. Symphony tracks who read the message during the time range and sends the “Read by” information that relates to those read events. Previously reported “Read by” information is not repeated, only the new “Read by” information.
The following data is provided:
Attachments (any kind of file)
ReadBy: list of users who have read the message within the time range
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
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.
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>
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.
The timestamp used for content export is in the form HH:MM:SS:mm where mm represents milliseconds.
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
A file entitled results.json is now included in each content export and will include the value “SUCCESS” if:
Download was successful
Decryption was successful
File matched what was sent
A file entitled Message_Counts.CSV is now included in each content export and shows summary usage data for each user on the Pod.
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.
An upgrade facility has been implemented enabling customers to implement blasts v2 on their own schedule based on when they upgrade to the 1.38.0 version of the Content Export Bridge. This facility is being provided because previous versions of the Content Export Bridge (CEB) do NOT support the file attachment feature being made available in this release.
Customers should not Upgrade to Blasts v2 until they have downloaded and deployed CEB v1.38. Once this version is active, Admins can select UPDATE from the left Nav. to activate Blasts v2 (including file attachments and external communications).
While customers continue to use Blast v1, any blasts from external contacts containing attachments will be downgraded to blast v1 functionality – without support for attachments.
The XML schema below provides the latest description of the information and format of the Symphony content export.
<?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> <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" /> </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" /> <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> </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> <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>
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.
Compliance features are listed in the left Nav:
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:
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.
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
Unicode characters can be entered as regular expressions. For example, the expression to filter a Unicode character 877e would be: /[\u877e]+/
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
Select an IB Group from the list:
Block members of the IB group from communicating with another group:
When the owner of a room is removed because of a new Information Barrier policy or because of a change to their external communications entitlement. The room will continue after the lone owner is removed by promoting the oldest member who is free of an IB or Entitlement constraint to owner.
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.
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.
Admins and Compliance officers can use the All Rooms option in the left Nav. to display a list of rooms created their users. The table includes a Scope tab showing either Internal or External, Member count, whether the room is enabled, the company that created the room and the room creator as well as basic information about activity and status (see the screenshot below for the complete list). More complete searching and sorting options will be delivered in a later release.
The SCO and CO’s with appropriate entitlement will be able to display a room or wall post (per user) and monitor it in real time. First select ALL ROOMS from the left Nav (see above). Then display the room details by clicking on the room from the list and selecting the Monitor Room button located top right of the room details (shown in the screenshot below).
Here is an example of a room monitor in progress:
SCO and CO’s will be prompted to provide an explanation for their session and the description and relevant statistics related to the session will be logged and searchable in the audit trail.
Select SCO/CO SESSION LOG and a list of logins will be displayed as shown below:
Select the username and then Audit Trail from the user detail screen. Each login will be accompanied by an explanation based on what was entered when the compliance officer logged in.
This section is an extract from information provided on the Symphony developer site:
https://developers.symphony.com
The Symphony REST API lets you build tools and applications on top of Symphony's secure messaging platform:
Use the Pod API to build tools to manage Symphony for your organization. Pod API endpoints don't require encryption or decryption of content and include operations such as managing chat rooms or users.
Use the Agent API to build applications that send and receive messages and content. Agent API endpoints require an on-premises Agent installation to encrypt and decrypt content.
The Client Embedding API lets developers extend the UI for the Symphony desktop client to interface with third-party applications. It is exposed as a localhost WebSocket server which serves as a channel for sending and receiving JSON messages.
Developers can use the Client Embedding API to add UI elements to Symphony, which enables Symphony to communicate with third-party applications. Communication between Symphony and other applications allows Symphony users to access these applications from the desktop client and vice-versa. The Client Embedding API also lets Symphony receive and display announcements from these applications.
The Client Extension API lets developers extend the functionality of the Symphony client by creating standalone applications. It also includes methods for adding items to the left navigation and adding buttons and interactions to the user interface.
Symphony provides APIs for Extending and Enriching the symphony experience with new functionality and 3rd–party content. Three partners (Dow Jones, S&P Capital IQ and Selerity) are currently providing free versions of their applications to Symphony users and these as well as any in-house applications developed using the Symphony API’s can be activated using the APP MANAGEMENT option located in the left Nav of the Admin Portal.
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.
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.
The next step is to entitle your users to see, install and use the application. The steps described in this section are also applicable to 3rd-party applications such as the ones described at the beginning of this section. You can either manage App Entitlement for all users at once (system-wide settings) or at the individual user level.
To manage at a system-wide level either click on the App Entitlements link in the APP MANAGEMENTscreen (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:
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:
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:
Once an application partner has registered a premium app, it can be allocated and installed for users by the Pod Administrator. Users will either see the new App in the App Store from where they can install it, or the admin may prefer to have it installed automatically for their users. This can be configured using the APP MANAGEMENToption in the left Nav. of the admin portal.
In the screenshot below, we show a list of APPLICATIONS being assigned to a specific user. Standard applications are free, whereas Premium applications require a subscription.
When using the APP MANAGEMENT option, the admin can also display their current balance:
Licenses used
Licenses remaining (balance)
Total Licenses (used and remaining)
Audit trails are available to track when applications are assigned to users. The following events are tracked:
App enabled/disabled
Licenses granted/removed for a product
App installation changed - automatic/manual
App visibility changed - visible/hidden
The audit trail displays, for each event:
Date of event
Initiator (internal user, or publisher)
Product impacted
User impacted (for installs and subscriptions)
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.
Here’s a quick summary of the steps you’ll use:
Select the BULK MANAGE USERS option.
Obtain the CSV template.
Load the CSV file into a spreadsheet or other editor.
Enter user information in CSV format.
Save your updates (be careful to save as a CSV file).
Drag and drop your CSV file into the drag and drop zone on the Symphony Admin portal.
The CSV file will be validated.
Press Import.
A further verification will be carried out on the file contents.
View the report and fix any errors encountered.
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.
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:
Eliminate leading or trailing spaces as these will be interpreted as belonging to the field and that might not be what you want:
Leonardo,Fibonacci rather than Leonardo,<space>Fibonacci
You will need quotes when importing fields that contain commas
“Department of IT, Networking and Communications”
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 “.
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).
In this section we’ll focus specifically on the password field. So while it is acceptable to create and update other optional fields at the same time, our examples will be limited to password actions.
Creating Users: When we create a user with the CSV import process, we have two options:
Password: We can either type in a valid password manually (15 characters minimum, uses upper and lower case, includes a number and includes a special character).
SEND_EMAIL: Enter “SEND_EMAIL” in which case Symphony will generate an email prompting that user to Set password. This second option avoids the burden of coming up with valid passwords on behalf of your users and communicating these passwords to them – and equally importantly, the need to secure or preferably delete the CSV file after use.
companyUserId,surname,firstName,prettyName,emailAddress,password LBonacci,Bonacci,Leonardo,Leo Bonacci,[email protected],First7Fibonacci#s
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:
No change to the password: Leave the password field with one or more asterisks, or <null> (if no password had been set).
Manually set a new password: Type in a valid password string in the password field.
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.
It’s worth spending a little more time discussing the “SEND_EMAIL” instruction in order to avoid undesired outcomes.
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:
Active for 24 hours: The set password link is active for 24 hours and then expires.
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.
Use the Admin Portal: Use the admin portal to trigger the set password email if you need to override the two rules above.
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.
Symphony will process the CSV file and once completed, will provide a link to a report as follows:
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
Follow these steps when resolving import errors to avoid any unforeseen impact on the users who were successfully processed.
Most such situations have been anticipated but they will still generate error messages when you try to process previously imported rows.
Edit the CSV file and remove the successfully created users.
Fix the remaining error records (the import report provides some guidance on where problems may exist).
Save and re-upload the CSV file.
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.
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.
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.
There is no explicit way to deactive an account using the CSV important process. Changing a password to something unknown by the user will not have an immediate effect on that user – it really depends on the duration of the user’s current session (Symphony uses a 20-hour session time span). Once their timespan has elapsed, that user would be asked to re-authenticate which they would not be able to do until you communicate their password to them.
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.
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.
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:
Date and timestamp of the event – in mm-dd-yy hh:mm format
Action
Attribute – if any
New value
Old value
Changed by
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:
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:
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):
<?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>
<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"/>
</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"/>
<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>
</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="conversationScope" minOccurs="0"/>
<xs:element type="xs:string" name="owningCompanyName" 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>
<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.4.0"/>
</xs:complexType>
</xs:schema>