LiveView Authentication and Authorization

Contents

Introduction
Usernames and Passwords in LiveView URIs
Enciphered Passwords
Realm Configuration
LiveView Roles
LiveView Permissions
Internal LiveView User and Role
Dynamic Changes to Users, Roles, and Permissions
Caching User Authentication Information
Using StreamBase Authentication with LiveView

This article describes how to configure your LiveView server to use authentication and authorization controls that are managed directly by the LiveView server, or by an associated StreamBase server, or by using an LDAP-compliant security realm such as an Active Directory realm.

Introduction

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. Two security realms are currently supported:

Local authentication realm

Users, passwords, roles, and permissions are configured in a second properties file, liveview.auth.properties, located in your LiveView project's top-level directory.

LDAP server, including Active Directory

Users, groups, and roles are retrieved from an LDAP-compliant server, including Active Directory servers, while the mapping of roles to LiveView permissions is specified in liveview.auth.properties.

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.

Usernames and Passwords in LiveView URIs

When local or LDAP 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://username:password@localhost:port

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

Enciphered Passwords

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

sbcipher -c "secret1ve"
MeQxOjzFAR2MRKoyrA5x8pQYRwrGWc7FkOw2/+AMltwstrNSLbGUmA1YBvEq+UUkJ/Sxe5jOLUO2oax1KypNRw==

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=MeQxOjzFAR2MRKoyrA5x8pQYRwrGWc7F
kOw2/+AMltwstrNSLbGUmA1YBvEq+UUkJ/Sxe5jOLUO2oax1KypNRw==

The example above is broken into two lines for clarity.

Realm Configuration

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

  • Properties File:

    # Properties file authentication and authorization
#
# Uncomment these lines to enable authentication/authorization using a 
# properties file.
#
liveview.security.auth.filter=authcBasicLiveView
liveview.security.auth.realm=properties
liveview.security.auth.properties.file=liveview.auth.properties
liveview.security.auth.send.authcBasic.header=true
liveview.security.auth.authcBasic.scheme=BASIC
#

  • LDAP or Active Directory:

    # Active Directory (LDAP) authentication and authorization
#
# Uncomment these lines, but don't change their values, to enable 
# authentication/authorization using Active Directory.
#   
# The authentication filter that processes incoming requests to the LiveView 
# server.
#liveview.security.auth.filter=authcBasicLiveView
#
# The realm to use for Active Directory for authentication/authorization.
#liveview.security.auth.realm=activeDirectory
#
# Authentication information is conveyed in an HTTP basic authentication header
#liveview.security.auth.send.authcBasic.header=true
#liveview.security.auth.authcBasic.scheme=BASIC
#
#
# Uncomment these lines and provide your site-specific Active Directory values. 
# The password below can be enciphered using the sbcipher utility. Refer to the 
# Enciphered Passwords Section of the LiveView Server System Configuration Guide 
# for details.
#
# The name of a second properties file that defines role-to-permission mapping
#liveview.security.auth.properties.file=liveview.auth.properties
#
# The URL of your Active Directory server
#liveview.security.auth.active.dir.url=ldap://adserver.mycompany.com
#
# The distinguished name and password of the Active Directory account used to query 
# the Active Directory server 
#liveview.security.auth.active.dir.username=CN=Administrator,CN=Users,DC=mycompany,DC=com
#liveview.security.auth.active.dir.password=mypassword
#
# The distinguished name of the location within the Active Directory to search for users, 
# also used for searching for groups if the liveview.security.auth.active.dir.search.base.
# groups # property is commented out
#liveview.security.auth.active.dir.search.base=CN=Users,DC=mycompany,DC=com
#
# The distinguished name of the location within the Active Directory to search for groups 
#liveview.security.auth.active.dir.search.base.groups=CN=Groups,DC=mycompany,DC=com
#
# The name of the LDAP attribute used for user-to-group membership
#liveview.security.auth.active.dir.group.membership.attr=memberOf
#
# An optional suffix to concatenate to usernames in searching for user accounts
#liveview.security.auth.active.dir.principal.suffix=mysuffix
#
# The LDAP attribute used in searching for user accounts
#liveview.security.auth.active.dir.user.search.attr=cn

To enable authentication, uncomment the lines in 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 or Unix LDAP, replace the template values with your site-specific LDAP values such as URL, system username and password.

LiveView Roles

Each LiveView user can have one or more role. The mapping of users to roles depends on 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:*

LiveView Permissions

The following table lists the available permissions and their use within LiveView. The general syntax for permission expressions is: 

permission:operation

or

permission:operation:resource

where resource is the name of a table, stream, or workspace that restricts the permission to that named resource.

In all permission expressions, a single asterisk can be used to specify all operations or all resources. If a second or third position is empty, it is interpreted the same as an explicit asterisk. Thus, the following three statements specify the same permission:

permission:*:*
permission:*
permission
Permission Description
* Grants full access to all resources on this LiveView server. This permission is typically granted only to LiveView administrators.
connect Allows a user or role to connect to the current LiveView server.
shutdown Grants the ability to shut down the LiveView server. Typically granted only to LiveView administrators.
publisher[:operation]
 

Grants the ability to kill LiveView client publishers.

kill Grants the ability to kill LiveView publishers. Typically granted only to LiveView administrators.
* Effectively an alias for the line above.
query[:operation]
 

This permission controls the ability to kill LiveView client queries.

kill Grants the ability to kill LiveView queries. Typically granted only to LiveView administrators.
* Effectively an alias for the line above.
session[:operation]
 

This permission controls the ability to prevent new client connections to the current server instance.

kill Grants the ability to prevent new client connections. Typically granted only to LiveView administrators.
* Effectively an alias for the line above.
sbinfo[:operation]
 

This permission controls access to StreamBase stream information.

get Grants the ability to retrieve the set of StreamBase streams available to use.
* Effectively an alias for the line above.
table[:operation[:tablename]]
 

This permission controls access to LiveView tables. The second element specifies the table operation as follows:

* Allows all operations on the specified tables.
list Grants the ability to list a set of configured LiveView tables. Permission to list an individual table can be enabled with a syntax such as table:list:table-name.
query Grants the ability to query and list the specified tables.
ccquery Grants the ability to query tables that have calculated columns in their projection and to list the specified tables.
publish Grants the ability to publish to the specified tables.
delete Grants the ability to delete records from the specified tables.
manage Grants permission for LiveView tables to be managed via table providers.
add Grants the ability to add data layer LiveView tables.
remove Grants the ability to remove data layer LiveView tables.

If the tablename element is absent or contains *, the permission applies to all LiveView tables.

tuple[:operation[:streamname]]
 

This permission controls access over the ability to send tuples from LiveView clients to StreamBase applications. The second element specifies the tuple operation as follows:

* Allows all operations on the specified streams.
info Grants the ability to retrieve schemas associated the specified streams.
send Grants the ability to send tuples to the specified streams.

If the streamname is absent, or contains *, the permission applies to all LiveView streams.

alert[:operation[:tablename]]
 

This permission controls access to LiveView query-based alerts. The second element specifies the alert operation as follows:

* Allows all alert operations.
list Grants the ability to retrieve the set of configured alerts. The tablename element is not used.
set Grants the ability to add or modify alert rules on the specified tables. If the tablename element is absent, or contains *, the permission applies to all LiveView tables.
delete Grants the ability to delete alert rules. The tablename element is not used.
alert[:operation]
 

This permission controls access to LiveView cron-based alerts. The second element specifies the alert operation as follows:

* Allows all alert operations.
list Grants the ability to retrieve the set of configured alerts.
set Grants the ability to add or modify alert rules on the specified tables.
delete Grants the ability to delete alert rules.
alertaction[:type[:tablename]]
 

This permission controls access to adding LiveView alert actions. The second element specifies the type of alert action as follows:

* Grants the ability to add all types of alert actions.
email Grants the ability to add an alert action that sends an email message to specified user names.
java Grants the ability to add an alert action that executes Java code.
oscmd Grants the ability to add an alert action that executes an operating system command.
publish Grants the ability to add an alert action that publishes the alert to a LiveView table.
sendtuple Grants the ability to add an alert action that sends a tuple to a StreamBase stream.
delete Grants the ability to add an alert action that deletes rows from a LiveView table.

If the tablename element is absent or contains *, the permission applies to all LiveView tables.

workspace[:operation[:workspacename]]
 

This permission controls access to workspaces stored on a LiveView server by the TIBCO LiveView Desktop™ client or the LiveView Desktop™ Workspace Manager. The second element specifies the workspace operation as follows:

* Allows all workspace operations.
get Grants the ability to list available workspaces and to download individual workspaces from the LiveView server.
set Grants the ability to upload new workspaces to the LiveView server and to modify existing workspaces.
delete Grants the ability to delete workspaces from the LiveView server.

If the workspacename element is absent or contains *, the permission applies to all LiveView Desktop workspaces on the current server.

permission:create[:resourcename]
The following four lines describe permissions grantable on LiveView Server to create the fundamental features of the LiveView Web client. Further and more granular permissions can be configured using LiveView Web's own permission system as described in the TIBCO LiveView Web™ documentation.
dashboard:create Allows a user or role to create LiveView Web dashboards.
page:create Allows a user or role to create LiveView Web pages.
card:create Allows a user or role to create LiveView Web cards.
linkage:create Allows a user or role to create LiveView Web links between cards.

Internal LiveView User and Role

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 name 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 and Authorization Sample sets the internal user's credentials in a StreamBase configuration file, sbd.sbconf. Enciphered Passwords describes how to encipher passwords, including the one for the internal user, for added security.

Note

The LiveView username and password are not honored for X.509 authentication. You must separately configure x509 authentication for the internal user. See Using SSL with LiveView Server.

Dynamic Changes to Users, Roles, and Permissions

Changes to users, roles, and permissions in liveview.auth.properties are recognized dynamically by LiveView. By default, changes are processed within one 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.

Caching User Authentication Information

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"/>

Using StreamBase Authentication with LiveView

If you are using authentication to protect your StreamBase environment from unintended use, you must configure your LiveView projects to work with the authentication-enabled StreamBase server.

To enable LiveView to run with a StreamBase server on which authentication is enabled, you must set four LiveView system properties:

  • streamBaseAdminUserName: The username of a StreamBase user that has the LVAdmin role in the StreamBase server's configuration.

  • streamBaseAdminPassword: The password of the administration-enabled StreamBase user. You can provide an enciphered string for a password's value, as generated with the sbcipher command.

  • streamBaseUserName: The username of a StreamBase user without administrative privileges.

  • streamBasePassword: The password of the StreamBase user without administrative privileges. You can provide an enciphered string for a password's value, as generated with the sbcipher command.

The following StreamBase configuration file, placed in the top-level of the project directory, enables StreamBase authentication (using the parameters under the <authentication> tag) and allows LiveView Server to run with the authentication-enabled StreamBase server (using the systems properties under the <java-vm> element): 

<?xml version="1.0"?>

<streambase-configuration xmlns:xi="http://www.w3.org/2001/XInclude"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.streambase.com/schemas/sbconf/">

    <authentication>
        <param name="enabled" value="true"/>
        <param name="type" value="sb-password-file"/>
        <param name="filepath" value="./sbpasswd"/>
    </authentication>
    
    <java-vm> 
        <sysproperty name="liveview.streambase.admin.username" value="sbmanager" /> 
        <sysproperty name="liveview.streambase.admin.password" value="sbmanager" />
        <sysproperty name="liveview.streambase.user.username" value="sbtest" /> 
        <sysproperty name="liveview.streambase.user.password" value="sbtest" />
    </java-vm>

To match this configuration create the users as follows:

sbuseradmin -f sbpasswd --add -n sbmanager -p sbmanager -r SBAdmin
sbuseradmin -f sbpasswd --add -n sbtest -p sbtest -r SBUser

To encipher the passwords in this configuration, for each password run the following commands (commands shown on multiple lines for clarity): 

sbcipher -c "sbmanager" 
  mF4Tooh8qipplnZwa6PN3qLhuxAosmGBpxriEmhVVuqWphq+rXBybWV6XfxZUgMW
  wUvmcqtiy5UcbIVlMCswLw==

sbcipher -c "sbtest"
  KX4vUpjZgQfav3gHujZ08jqeJtvJFX+WyNu4nzX4TBhGErDVDGRfHjKI7yXn/jW4
  OXx4Bei7hXlGxjKAg0hTmw==

Now, replace the password properties with these values:

<sysproperty name="liveview.streambase.admin.password" 
value="mF4Tooh8qipplnZwa6PN3qLhuxAosmGBpxriEmhVVuqWphq+rXBybWV6XfxZUgMW
wUvmcqtiy5UcbIVlMCswLw==" />

<sysproperty name="liveview.streambase.user.password" 
value="KX4vUpjZgQfav3gHujZ08jqeJtvJFX+WyNu4nzX4TBhGErDVDGRfHjKI7yXn/jW4
OXx4Bei7hXlGxjKAg0hTmw==" />