Using TLS/SSL with LiveView Server

Network traffic between LiveView clients and the server can run over a secure connection by enabling TLS for LiveView. This is particularly important when authentication is enabled and user names and passwords are sent over the wire.

To use TLS, configure LiveView server to listen on an TLS port, and direct LiveView clients to use TLS-enabled connections to that port. TLS client connections include:

The following describes the need for truststore and keystore specifications:

The internal truststore holds the certificates used by the server in making internal requests to other server components.

To enable TLS, create and edit configuration files that have the following HOCON types. StreamBase Studio provides a HOCON editor invoked from the File → New → StreamBase HOCON File menu. All HOCON format configuration files must be placed in the src/main/configurations folder of your LiveView project in the Project Explorer view of StreamBase Studio. For further information about the HOCON file format and syntax, see the Configuration Guide.

Consider the following when configuring TLS for LiveView:

Use a HOCON configuration file of type ldmclientapilistener to define the authentication realm and set your TLS port.

name = "enableTLS"
version = "1.0.0"
type = "com.tibco.ep.ldm.configuration.ldmclientapilistener"
configuration = {
  ClientAPIListener = {
    portNumber = 10443    
    authenticationRealmName = "authRealm"
    secureCommunicationProfileName = "my-secure-communication-client-profile"
  }
}

Use a configuration file of HOCON type security to identify the keystore file and its password. Each profile has a unique name across all server and client profile types; the name serves as a reference target from other configurations wishing to enable secure communication.

The following is a sample that configures a secure communication profile for a client endpoint. A secure communication profile configuration object contains settings used to secure client-side transport connections (for example, to external services such as LDAP). Profiles are named and then referenced as needed by other configurations needing secure communication.

name = "mycommunicationsettings"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  SecureCommunicationClientProfile = {
    name = "my-profile"
    keyStore = "/absolute/path/myKeyStore.jks"
    keyStorePassword = "secret"
    keyPassword = "anothersecret"
    keyStoreType = "JKS"
    trustStore = "/absolute/path/myTrustStore.jks"
    trustStorePassword = "athirdsecret"
    trustStoreType = "JKS"
    requireClientAuthentication = false
  }
}

This server profile is for the Live Datamart API listener. For TLS with client certificate authentication, the profile contains a trust store used to validate incoming server certificates. Also, if you enable TLS on a LiveView server, you need both the SecureCommunicationClientProfile and the SecureCommunicationServerProfile configured. This is due to the server and client certificates having different attributes, and CAs do not issue a single certificate appropriate for both client and server use.

name = "mycommunicationsettings"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  SecureCommunicationServerProfile = {
    name = "my-profile"
    keyStore = "/absolute/path/myKeyStore.jks"
    keyStorePassword = "secret"
    keyPassword = "anothersecret"
    keyStoreType = "JKS"
    trustStore = "/absolute/path/myTrustStore.jks"
    trustStorePassword = "athirdsecret"
    trustStoreType = "JKS"
    requireClientAuthentication = false
    userNameObjectIdentifierSearchPath = [ "userID", "CN", "1.2.3.4", "DN" ]
  }
}

Use a configuration file of HOCON type ldmengine to specify the following parameters:

The certificate that is used by your server is selected automatically based on your hostname. If you get errors trying to find the certificate for your hostname, you can specify this (for example, if the hostname the Live Datamart server tried to find is incorrect).

You can specify the name of the server (as expected in the DN field of the certificate) using the liveview.ssl.hostname system property.

name= "engine for security"
version= "1.0.0"
type= "com.tibco.ep.ldm.configuration.ldmengine"

configuration = {
  LDMEngine = {
    systemProperties = {
      "liveview.ssl.hostname" = "localhost" 
    }
  }
}

The server keystore (which is specified in the SecureCommunicationServerProfile keyStore property) requires:

The server truststore (specified in the SecureCommunicationServerProfile trustStore property) requires:

The client truststore (specified in the SecureCommunicationClientProfile trustStore property) requires:

If X.509 support is enabled, X.509 authentication is required for all connections, including from the LiveView internal user. Therefore, you must provide keys for the internal user as well. For X.509 authentication only, the client profile keystore (SecureCommunicationClientProfile keyStore property) requires:

To enable TLS with client certificate authentication:

The internal keystore holds the client certificates used by the server in making internal requests to other server components.

Note that enabling TLS only applies to authentication, not authorization. You will also need an authorization scheme (whether for LDAP or basic authorization) configured in a configuration file of type HOCON (the file type will vary based on your desired setup).

When fine-tuning TLS client certificate configurations, TIBCO recommends setting up the lookup object identifiers (OIDs) — or their more name-friendly name-value pairs — in a configuration file of type SecureCommunicationServerProfile. OIDs are used to pull the username for authorization out of the certificates. An OID is a numeric value that identifies the application or service for which a certificate is used.

If possible, use only one OID as shown in the section below. Setting these properties incorrectly may lead to security vulnerabilities.

  userNameObjectIdentifierSearchPath = [
    "emailAddress",
    "userID",
    "CN",
    "DN"
  ]

"liveview.security.auth.X509.internal.principal"="localhost"

"liveview.security.auth.X509.internal.user"="lvintern"

name= "engine for security"
version= "1.0.0"
type= "com.tibco.ep.ldm.configuration.ldmengine"

configuration = {
  LDMEngine = {
    systemProperties = {
      "liveview.web.pstore.type" = "h2"
      "liveview.ssl.hostname" = "localhost" 
      "liveview.security.auth.X509.internal.principal"="localhost"
      "liveview.security.auth.X509.internal.user"="lvintern"
     }
      jvmArgs = [
      "-Xmx1024m"
      "-Xms512m"
      "-XX:MaxPermSize=768m"
    ]
  }
}