LiveView Server System Configuration

LiveView can be configured to verify the identity of clients (authentication) and ensure that authenticated clients have permission to access the requested LiveView resources (authorization).

LiveView authentication and authorization, hereafter referred to as simply authentication, is configured through a properties file, liveview.properties, located in your LiveView project's top-level directory. This file allows you to enable authentication, specify a "security realm," and configure realm-specific attributes. The two security realms are currently supported:

The LiveView Authentication and Authorization sample provides template liveview.properties and liveview.auth.properties files that can be used as the basis for enabling authentication in your LiveView application. To load and run the project, follow the steps in the sample's README.txt file installed in STREAMBASE_HOME/liveview/sample/lv-auth.

When LiveView authentication is enabled, a LiveView client identifies itself to the server with a username and password. These credentials can be included in a LiveView URI by placing them between the protocol field and server name in the URI. For example:

lv://myusername:myPassword@localhost

Note that a colon (:) delimits the username and password, while an at sign (@) delimits the username/password and server name.

The template liveview.properties file in the LiveView Authentication sample contains a section for each of the two security realms:

To enable authentication, uncomment the lines within liveview.properties pertaining to your chosen security realm. If using a properties file realm, template values are provided that allow the sample to be run out-of-the-box. For Active Directory, replace the template values with your site-specific Active Directory values such as URL, system username and password, or other values.

Passwords within liveview.properties and liveview.auth.properties can be stored as either clear or enciphered text. Encipher a password as follows:

sbcipher -c "mypassword"
cA8lR8fz+XBf0QaVP0jxTO6LFCWQhL2PagLXTEVF9RFEB6nkFQB9MXKea7qW7+3IhBgXBtxqhkNx0FUPE2jAJw==

Replace the clear text password in liveview.properties, liveview.auth.properties, or sbd.sbconf with the enciphered text returned by sbcipher. For example:

liveview.security.auth.active.dir.password=cA8lR8fz+XBf0QaVP0jxTO6LFCWQhL2PagLXTEVF9RFEB6nk
FQB9MXKea7qW7+3IhBgXBtxqhkNx0FUPE2jAJw==

Each LiveView user can have one or more role. The mapping of users to roles depends upon the configured realm. When using a property file, this mapping is contained in liveview.auth.properties:

# LiveView user-to-role mapping
#user.<name> = <password>,<role1>,<role2>,...
user.lvmanager = lvmanager,LVAdmin
user.lvguest = lvguest,LVUser
user.lvinternal = lvinternal,LVIntern

In the example above, there are three users: lvmanager, lvguest, and lvinternal, which have roles of LVAdmin, LVUser, and LVIntern, respectively. When using Active Directory, user-to-role mapping is retrieved from the Active Directory server using, by default, the memberOf attribute. The Active Directory attribute used for user-to-role mapping can be changed with the liveview.security.auth.active.dir.group.membership.attr property in liveview.properties.

Each role can be assigned one or more permissions, some of which can be hierarchical. Users with multiple roles inherit the permissions from all assigned roles. Role-to-permission mapping is contained in liveview.auth.properties:

# LiveView role-to-permission mapping
#role.<name> = <permission1>,<permission2>,...
role.LVAdmin = *
role.LVUser = connect, table:list, table:manage, table:query:Items, table:publish:Items, 
  table:delete:Items, alert:list, alert:set, alert:delete, session:kill, query:kill, 
  publisher:kill
role.LVIntern = connect, table:query:*

The following table lists the available permissions and their use within LiveView.

Several internal LiveView components are required to make requests to access LiveView server resources. When authentication is enabled, these internal requests must be made in the context of a valid LiveView user configured with the appropriate permissions. A special role, LVInternal, is available to satisfy this requirement. Two system properties, liveview.internal.username and liveview.internal.password, specify the credentials of the internal LiveView user configured with the LVInternal role. The LiveView Authentication/Authorization Sample sets the internal user's credentials in a StreamBase configuration file, sbd.sbconf. Enciphered Passwords describes how to encipher passwords, including that for the internal user, for added security.

Changes to users, roles, and permissions in liveview.auth.properties are recognized dynamically by LiveView. By default, changes are processed within 1 second of this file being saved. The liveview.security.auth.reload.interval.seconds property in liveview.properties can be used to change the interval, in seconds, that LiveView uses to detect changes.

When authentication is enabled, Live Datamart caches authentication information for all users. This caching reduces the load on the authentication authority. By default, cached authentication expires in 15 minutes. Caching parameters are configurable, as shown below.

Set caching in the following property to true enables; false disables.

<sysproperty name="liveview.security.cache.enabled" value="false"/>

Set the least recently used (LRU) cache size, where -1 disables the size limit. Default = 10000.

<sysproperty name="liveview.security.cache.size" value="10000"/>

Set the time to live property, where -1 disables TTL. Default = 900000 milliseconds (15 minutes).

<sysproperty name="liveview.security.cache.ttl" value="900000"/>

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

To use SSL, configure LiveView server to listen on an SSL port, and direct LiveView clients to use SSL-enabled connections to that port. When SSL is enabled, the LiveView server, by default, listens on both a non-SSL port and an SSL port. To configure the server to listen on an SSL port only, set the liveview.ssl.only property to true, either in your LiveView project's liveview.properties or StreamBase configuration (sbd.sbconf) file.

SSL is enabled in the LiveView server by setting the liveview.ssl.port property in one of three ways:

When SSL is enabled, the LiveView server requires a Java keystore and password to identify itself to LiveView clients, and a Java truststore and password for internal LiveView components that make client requests to the LiveView server. The LiveView Authentication and Authorization sample provides a prepopulated keystore file that is used for both roles, and is configured within the sample's StreamBase configuration file, sbd.sbconf, as follows:

<sysproperty name="liveview.keystore" value="mykeystore"/>
<sysproperty name="liveview.keystore.password" value="mypassword"/>
<sysproperty name="javax.net.ssl.trustStore" value="mykeystore"/>
<sysproperty name="javax.net.ssl.trustStorePassword" value="mypassword"/>

Your site may have specific requirements for the protocols and cipher suites used in establishing secure connections. Two system properties are available for this: one to exclude specific protocols and another to exclude cipher suites. Each property contains a comma-delimited list of protocols or cipher suites to exclude, and the cipher suite-related property can contain regular expressions. Following are example uses of the properties in the StreamBase configuration file, sbd.sbconf:

<sysproperty name="liveview.excluded.protocols" 
  value="SSLv2,SSLv3,TLSv1,TLSv1.1"/>
<sysproperty name="liveview.excluded.cipher.suites" 
  value=".*_DHE_.*"/>

If you want to enable two-way SSL, add the following line to your liveview.properties file:

liveview.security.auth.filter=x509

and set the following properties in your sbd.sbconf file:

<sysproperty name="liveview.security.auth.requireX509" value="true" />
<sysproperty name="javax.net.ssl.keyStore" value="internalkeystore.jks"/>
<sysproperty name="javax.net.ssl.keyStorePassword" value="internalkeystorepassword"/>

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