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/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 these steps:

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, e.g.,

liveview.security.auth.active.dir.password=cA8lR8fz+XBf0QaVP0jxTO6LFCWQhL2PagLXTEVF9RFEB6nkFQB9MXKea7qW7+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
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.

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

To use SSL, configure LiveView server to listen on an SSL port, and direct LiveView clients 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/Authorization sample provides a pre-populated keystore file that is used for both roles and is configured within the sample's StreamBase configuration file, sbd.sbconf, as follows:

<java-vm>
    <param name="jvm-args" value="
        -Dliveview.keystore=mykeystore
        -Dliveview.keystore.password=mypassword
        -Djavax.net.ssl.trustStore=mykeystore
        -Djavax.net.ssl.trustStorePassword=mypassword
    "/>
</java-vm>