Revision as of 21:05, December 20, 2016 by Sschlich (talk | contribs) (Update with the copy of version: DRAFT)
Jump to: navigation, search

Configuring Security

Web Services adheres to the standards described in the Open Web Application Security Project (OWASP) Top 10 — see the OWASP website for details about the Top 10 — and has adopted several methods of ensuring security, for example:

  • Errors are logged locally to prevent information leakage through API requests.
  • User sessions have a timeout option.
  • Cross Site Request Forgery Protection

Read on for details about the additional security configurations that Interaction Recording Web Services includes.

Transport Layer Security (TLS)

Complete the procedures below to configure TLS between Interaction Recording Web Services and Configuration Server and for connections with Cassandra.

Configuring TLS between Interaction Recording Web Services and Configuration Server

Interaction Recording Web Services can use a secured Transport Layer Security (TLS) connection mechanism to connect to Configuration Server. When configured, Interaction Recording Web Services connects to a secure port on Configuration Server, verifies the server's authority, and encrypts/decrypts network traffic. You can configure secured connections to Configuration Server in the following ways:

Prerequisites

Before configuring Interaction Recording Web Services, make sure the Configuration Server secure port is configured as described in Introduction to Genesys Transport Layer Security in the Genesys Security Deployment Guide and that all certificates for server host and the certificate authority are configured and available.

Minimal Configuration

Interaction Recording Web Services does not check the server's certificate against the Certificate Authority, but all traffic is encrypted. To configure Interaction Recording Web Services with minimal configuration, all you need to do is configure a connection to a secured port on Configuration Server. You can do this using either of the following methods:

  • For the initial connection to Configuration Server, set the tlsEnabled option to true in the onPremiseSettings section of the application.yaml file. This creates a secured connection to Configuration Server the first time Interaction Recording Web Services starts.
  • For an environment that is already configured with Configuration Manager synchronization enabled, you can make changes with Configuration Manager as described in the Genesys Security Deployment Guide. These changes are synchronized back to the Cassandra database from Configuration Manager.

Validate the Certificate Against the CA

In order to support the client-side certificate check, Interaction Recording Web Services needs the public key for the Certificate Authority (CA). Interaction Recording Web Services supports the PEM and JKS key storage formats, but recommends using JKS because it's compatible with both Cassandra and HTTPS.

Complete the steps below to validate the certificate against the CA.

Important
The steps described in this procedure are meant to be an example for developers and should not be used in production. For a production environment, you should follow your own company's security policies for creating and signing certificates.

Start

  1. If you plan to use a JKS file, you can generate if from a PEM file by importing the PEM certificate, as shown here: 
    keytool -importcert -file ca_cert.pem -keystore ca_cert.jks
  2. Once you have the ca_cert.jks file, place it in a location available from your Interaction Recording Web Services host, such as:
    • A local folder on the Interaction Recording Web Services host
    • A network share
  3. Configure the following options in the serverSettings section of the application.yaml file:
    • For a PEM file, set caCertificate to the location of the file. For example: 
      caCertificate: /opt/ca_cert.pem
    • For a JKS file, set caCertificate to the location of the file and set jksPassword to the password for the key storage. For example: 
      caCertificate: /opt/ca_cert.jks
jksPassword: pa$$word

End

Configuring TLS for Connections with Cassandra

Genesys supports Transport Layer Security (TLS) for connections from Interaction Recording Web Services to Cassandra and between Cassandra nodes. You can configure secured connections for the following scenarios:

Secure Connections from Interaction Recording Web Services to Cassandra

Prerequisites

Complete the following steps to configure TLS for connections from Interaction Recording Web Services to Cassandra.

Important
The steps described in this procedure are meant to be an example for developers and should not be used in production. For a production environment, you should follow your own company's security policies for creating and signing certificates.

Start

  1. Create the server-side keystore with a self-signed certificate and the client-side truststore — which contains the public part of server certificate — with the following commands: 
    #!/bin/bash
#generate keypair
keytool -genkeypair -alias cassandra -keyalg RSA -keysize 1024 -dname
"CN=<Cassandra node hostname>, OU=Test, O=Test Ltd, C=US" -keystore
server.jks
-storepass password -keypass password
#export certificate
keytool -exportcert -alias cassandra -file client.pem -keystore
server.jks -storepass password -rfc
#create client truststore and import certificate
keytool -importcert -alias cassandra -file client.pem -keystore
client.jks -storepass password -noprompt
  2. Create a self-signed root authority, use it to sign the server certificate, store it to server.jks and create the client-side truststore, which trusts all certificates signed with root authority. Run the following commands: 
    #!/bin/sh

#generate self-signed root certificate
keytool -genkeypair -alias root -keyalg RSA -keysize 1024 -validity 3650 -dname "CN=TestRoot, OU=Dev, O=Company, C=US" -keystore root.jks 
-storepass password -keypass password

#export root certificate
keytool -exportcert -alias root -file root.crt -keystore root.jks -storepass password

#generate server-side certificate 
keytool -genkeypair -alias server -keyalg RSA -keysize 1024 -validity 3650 -dname "CN=TestServer, OU=Dev, O=Company, C=US" 
-keystore server.jks -storepass password -keypass password

#create the sign request for server certificate
keytool -certreq -alias server -keystore server.jks -file server.csr -storepass password -keypass password

#export private key of root auth: need later for signing the server certificate
keytool -v -importkeystore -srckeystore root.jks -srcalias root -destkeystore root.p12 -deststoretype PKCS12 -noprompt 
-destkeypass password -srckeypass password -destalias root -srcstorepass password -deststorepass password

openssl pkcs12 -in root.p12 -out private.pem -password pass:password -passin pass:password -passout pass:password
rm root.p12

#sign the certificate
openssl  x509  -req  -CA   private.pem  -in server.csr -out server.crt  -days 3650  -CAcreateserial -passin pass:password
rm private.pem
rm private.srl
rm server.csr

#import root certificate to client side trust store
keytool -importcert -alias root -file root.crt -keystore client.jks -storepass password -noprompt

#import root certificate to server side key store
keytool -importcert -alias root -file root.crt -keystore server.jks -storepass password -noprompt
rm root.crt

#import certificate sign reply into server-side keystore
keytool -import -trustcacerts -alias server -file server.crt -keystore server.jks -storepass password -keypass password
rm server.crt
  3. Configure Cassandra to use your generated certificates for the client connection by setting the client_encryption_options in the cassandra.yaml file. For example: 
    client_encryption_options:
    enabled: true
    keystore: <absolute path to server.jks file>
    keystore_password: password 
    #the password specified in while creating storage
    # For the purpose of the demo the default settings were used.
    # More advanced defaults below:
    #protocol: TLS
    #algorithm: SunX509
    #store_type: JKS
    #cipher_suites: [TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA]
    Important
    To enable support for encryption, you must have the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction installed.
  4. Confirm the Cassandra nodes can start successfully:
    1. Edit the conf/log4j-server.properties file and uncomment the following line: 
      log4j.logger.org.apache.cassandra=DEBUG
    2. Start Cassandra and check the logs. If the configuration was successful, you shouldn't see any errors.
    3. Edit the conf/log4j-server.properties file and comment the following line to disable the functionality: 
      log4j.logger.org.apache.cassandra=DEBUG
    4. Check that SSL-to-client is working successfully using cqlsh: Confirm that unsecured connections aren't possible by starting cqlsh locally—this forces it to connect to the Cassandra instance running on localhost. You should expect to see the exception in the cqlsh output. 
      cqlsh `hostname`
      • Confirm that secured connections are possible by configuring cqlsh with SSL encryption:

      Create a pem key which will be used in the .cqlshrc file: 

      // Create PEM for client
keytool -importkeystore -alias cassandra -srckeystore
server.jks -destkeystore server.p12 -deststoretype PKCS12
openssl pkcs12 -in server.p12 -out client.pem -nodes
      • Create a .cassandra/cqlshrc file in your home or client program directory. The following settings must be added to the file.

      When validate is enabled, the host in the certificate is compared to the host of the machine that it is connected to verify that the certificate is trusted. 

      [connection]
hostname = <hostname of Cassandra node>
port = 9042
factory = cqlshlib.ssl.ssl_transport_factory

[ssl]
certfile = /path/to/client.pem
# Optional, true by default
validate = true
      • Verify that you can connect to Cassandra using cqlsh:
      $ cqlsh --ssl
Connected to HTCC Cassandra Cluster at
ci-vm378.us.int.genesyslab.com:9042.
[cqlsh 5.0.1 | Cassandra 2.2.3 | CQL spec 3.3.1 | Native
protocol v4]
Use HELP for help.
      • Configure Interaction Recording Web Services to use SSL with Cassandra.
      On each Interaction Recording Web Services node, edit the application.yaml.

      application.yaml 

      cassandraCluster:
  useSSL: true
  trustStore: /path/to/client.jks
  truststorePassword: password

      Restart each Interaction Recording Web Services node: 

      service gir restart

End


Secure Connections between Cassandra Nodes

When you enable SSL for connections between Cassandra nodes, you ensure that communication between nodes in the Cassandra cluster is encrypted, and that only other authorized Cassandra nodes can join the cluster.

The steps below show you how to create a single certificate to be used by all Cassandra nodes in the cluster. This simplifies cluster management because you don't need to generate a new certificate each time you add a new node to the cluster, which means you don't need to restart all nodes to load the new certificate.

Important
The steps described in this procedure are meant to be an example for developers and should not be used in production. For a production environment, you should follow your own company's security policies for creating and signing certificates.

Start

  1. Generate a keystore and truststore. See Step 1 of Secure Connections from Interaction Recording Web Services to Cassandra for details.
  2. On each Cassandra node in the cluster, set server_encryption_options in the cassandra.yaml file. For example: 
    server_encryption_options:
    internode_encryption: all
    keystore: <absolute path to keystore >
    keystore_password: <keystore password - somePassword in our sample>
    truststore: <absolute path to trustore>
    truststore_password: <truststore password - somePassword in our sample>
  3. Check the Cassandra logs. If the configuration was successful, you shouldn't see any errors.

End

CSRF Protection

Interaction Recording Web Services provides protection against Cross Site Request Forgery (CSRF) attacks. For general information and background on CSRF, see the OWASP CSRF Prevention Cheat Sheet.

To set up Cross Site Request Forgery protection, set the following options in the serverSettings section of the application.yaml file on each of your Interaction Recording Web Services nodes:

  • enableCsrfProtection — determines whether CSRF protection is enabled on the Web Services node.
  • crossOriginSettings — specifies the configuration for cross-origin resource sharing in Interaction Recording Web Services. Make sure this option has the *exposedHeaders* setting with a value that includes X-CSRF-HEADER,X-CSRF-TOKEN.

For example, your configuration might look like this: 

enableCsrfProtection: true
crossOriginSettings:
    corsFilterCacheTimeToLive: 120
    allowedOrigins: http://*.genesys.com, http://*.genesyslab.com 
    allowedMethods: GET,POST,PUT,DELETE,OPTIONS
    allowedHeaders: "X-Requested-With,Content-Type,Accept,​Origin,Cookie,authorization,ssid,surl,​ContactCenterId"
    allowCredentials: true
    exposedHeaders: "X-CSRF-HEADER,X-CSRF-TOKEN"

For more information about CSRF protection in the Interaction Recording Web Services API, see Cross Site Request Forgery Protection.

CORS Filter

Interaction Recording Web Services supports Cross-Origin Resource Sharing (CORS) filter, which allows applications to request resources from another domain. For general information and background on CORS, see Cross-Origin Resource Sharing.

To set up Cross-Origin Resource Sharing, make sure you set the crossOriginSettings option in the serverSettings section of the application.yaml file on each of your Interaction Recording Web Services nodes . It specifies the configuration for cross-origin resource sharing in Interaction Recording Web Services. Make sure this option has the exposedHeaders setting with a value that includes X-CSRF-HEADER,X-CSRF-TOKEN.

For example, your configuration might look like this: 

crossOriginSettings:
    corsFilterCacheTimeToLive: 120
    allowedOrigins: http://*.genesys.com, http://*.genesyslab.com
    allowedMethods: GET,POST,PUT,DELETE,OPTIONS
    allowedHeaders: "X-Requested-With,Content-Type,Accept,Origin,Cookie,authorization,ssid,surl,ContactCenterId,X-CSRF-TOKEN"
    allowCredentials: true
    exposedHeaders: "X-CSRF-HEADER,X-CSRF-TOKEN"

For more information about CORS in the Interaction Recording Web Services API, see Cross-Origin Resource Sharing.

Interaction Recording Web Services Authentication Flow

Interaction Recording Web Services provides authentication in the following sequence:

1. Configuration Server (CME) Authentication

  • Enters here if a request contains basic authentication header and CME authentication is enabled for this contact center.
  • If successful, user is authenticated and execution flow proceeds to the authorization stage.
  • If authentication headers are not present, CME authentication is disabled, or authentication fails, execution flow proceeds to the next step.

2. Interaction Recording Web Services Authentication

  • Enters here if a request contains basic authentication header.
  • If successful, user is authenticated and execution flow proceeds to the authorization stage.
  • If authentication headers are not present or authentication fails, execution flow proceeds to the next step.

Next Step

Comments or questions about this documentation? Contact us for support!