LiveView Authentication and Authorization

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 number of configuration files in HOCON format. StreamBase Studio provides a configuration editor invoked from File>New>StreamBase HOCON Configuration File. For further information about the HOCON file format and syntax, see the Configuration Guide.

These configuration files allow you to enable authentication, specify a security realm, and configure realm-specific attributes. Two security realms are currently supported:

Local authentication realm

User names, passwords, roles, and permissions are configured in several HOCON configuration files placed in a folder in the LiveView project. This authentication realm is thus local to the LiveView server launched from that LiveView project folder.

All nodes in the cluster must have an internal credential user name and password configured that all other nodes in the cluster know about, will accept, and have the entitlements necessary to carry out the tasks associated with peer recovery (if being used) and Table Group participation.

LDAP server, including Active Directory

User names, 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 a HOCON configuration file.

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.

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

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

Note

As of 10.5.0, LiveView client connections require that you provide an actual password in URIs when authentication is enabled. Connections no longer accept enciphered passwords in URIs.

Enciphered Passwords

Passwords can be stored as clear text or enciphered text in any HOCON configuration file that calls for a password element. In the following example, the LiveView internal user's password is stored in clear text:

name = "ldm-internal-credentials"
version = "1.0.0"
type = "com.tibco.ep.ldm.configuration.ldminternalcredentials"
configuration = {
  InternalCredentials = {
    ldmInternalUserName = "lvintern"
    ldmInternalPassword = "secret1"
  }
}

You can provide an enciphered string for the password's value, as generated with the epadmin encrypt secret command; you must prefix #! to the generated string. The following shows an enciphered password, broken onto two lines for clarity. In the actual configuration file, the enciphered password is entered as one long string.

"ldmInternalPassword" = "#!MeQxOjzFAR2MRKoyrA5x8pQYRwrGWc7FkOw2/+AMltwstr
  NSLbGUmA1YBvEq+UUkJ/Sxe5jOLUO2oax1KypNRw=="

Local Realm Configuration

Configure a local security realm by adding and editing the following HOCON configuration files. The example configuration files in this section are adapted from the LiveView Authentication sample shipped with LiveView.

name = "localrealm1"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  LocalAuthenticationRealm = {
    principals = [
      {
        userName = "Administrator"
        hashedPassword = "#!M5DSWylszg5aA9AK29MOiaDLq7SMqmTor
         +nW3qURTrT9E9eqJfTPyyUudCK34nhXHE53PXK6pregp4MW8qrueg=="
        roles = [
          "BasicUser"
          "StreamBaseSuperuser"
          "admin"
        ]
        passwordExpirationPeriodDays = 12
        passwordAlwaysRequired = true
        trustedHostAccessOnly = false
      }
    ]
  }
}

Enable TLS/SSL

Refer to Using TLS/SSL with LiveView Server for instructions on how to enable TLS for LiveView.

Define Local Users

Configure user names, passwords, and roles for each user in a configuration file with HOCON type security using configuration class LocalAuthenticationRealm. The role names are defined in a separate file discussed below; the spelling of role names in this file must exactly match those in the role definition file.

name = "localrealmusers"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"

configuration = {
  LocalAuthenticationRealm = {
    Principals = [
      {
        userName = "admin"
        password ="admin"
        roles = [ "LVAdmin" ]
      }
      {
        userName = "lvintern"
        password = "secret1ve"
        roles = [ "LVInternal" ]
      }
      {
        userName = "guest"
        password = "guest"
        roles = [ "LVGuest" ]
      }
      {
        userName = "tester"
        password = "tester"
        roles = [ "LVUser" ]
      }
    ]
  }
}

Role to Privilege Mappings

Configure the mapping of roles to LiveView privileges in a configuration file with HOCON type security using the root object, RoleToPrivlegeMappings. Notice that this configuration type is the same security HOCON type as in the Local Users file described previously, but has a different root object (which is the first keyword after configuration). For this reason, the Role settings can optionally go into a separate HOCON file; it would also be valid to place both configuration classes in the same file.

LiveView privilege names are shown in the LiveView Privileges section below. Each role can be assigned one or more privilege settings. User names with multiple roles inherit the privilege settings from all assigned roles.

A privilege specification without a resource entry means that the specified privilege applies to all features of the LiveView server. A resource line restricts the associated privilege to the specified resource, such as to a named table in this LiveView project, or to the input stream of a table.

The following example is abbreviated from the roleMappings.conf file provided in the LiveView Authentication sample shipped with LiveView.

name = "role-priv-mappings"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"

configuration = {
  RoleToPrivilegeMappings = {
    privileges = {
      LVAdmin = [
        {
          privilege = "LiveViewAll"
        }
      ]
      LVInternal = [
        {
          privilege = "APIConnect"
        }
        {
          privilege = "LiveViewShutdown"
        }
      ...
      ]
      LVUser = [
        {
          privilege = "APIConnect"
        }
        {
          privilege = "LiveViewTableList"
        }
        {
          privilege = "LiveViewTableManage"
        }
        {
          privilege = "LiveViewTableAll"
          resource = "ItemsSales"
        }
        ...
        {
          privilege = "LiveViewTupleInfo"
          resource = "ItemsSales.DataIn"
        }
        {
          privilege = "LiveViewTupleSend"
          resource = "ItemsSales.DataIn"
        }
      ]
      LVGuest = [
        {
          privilege = "APIConnect"
        }
        {
          privilege = "LiveViewTableList"
        }
      ...
      ]
    }
  }
}

The privilege group names LVAdmin, LVUser, and LVGuest are only examples and are not required. You can use any set of group names with any granularity of privilege groupings required by your site. TIBCO recommends continuing to use LVInternal as the group to contain privilege settings for the internal LiveView user name.

Setting Row Level Security for LiveView Tables

LiveView supports restricting access to specified rows in LiveView tables for a given user. Setting the privilege LiveViewRowLevelAccess affects alert queries, LiveView queries, and delete alert actions.

Setting row level security (RLS) is largely similar to setting other LiveView privileges as described in Role to Privilege Mappings with one exception: the resource must be specified within triple quotes.

You can specify multiple objects for RLS within the configuration file using the following rules:

  • each object must contain exactly one table and one predicate

  • the predicate must be an array of strings

  • each string represents a predicate for the specified table

In the following example, a user LVUserRLS is restricted to viewing a category toy in table ItemSales. Other resources and privileges are shown here for context only.

name = "role-priv-mappings"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"

configuration = {
  RoleToPrivilegeMappings = {
    privileges = {
      LVUserRLS = [
        {
          privilege = " ... "
          resource = " ... "
        }
          privilege = "LiveViewRowLevelAccess"
            resource = 
              """
                [{ table = "ItemsSales"
                   predicate = ["category=='toy'"]
                }]
              """
      ]
    }
  }
}

Note that, even with RLS enabled, it is possible to leak information through alert actions. It is important to be aware of this when sensitive information is in play.

For example, an LVAdmin user could write an alert rule on a table LVUserRLS is not allowed to see. When the alert fires, LVAdmin could conceivably send an email to LVUserRLS with the payload of the alert tuple — thereby sharing information about a forbidden row. Or similarly, publish the alert tuple payload to the LVAlerts system table, or some other table LVUserRLS has privilege to see.

Generally, it is unlikely RLS can prevent all information leakage from alert actions. It is therefore up to the users writing the alerts to be aware of what information they do not wish to share. Also, to take advantage of reduced information leakage in a high availability cluster, you must configure RLS identically on all LiveView engines, including the front ends.

Internal User Credentials

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.

To designate a user name as the internal user with the LVInternal role, use a configuration file with HOCON type ldminternalcredentials.

name = "ldm-internal-user-credentials"
version = "1.0.0"
type = "com.tibco.ep.ldm.configuration.ldminternalcredentials"

configuration = {
  InternalCredentials = {
    ldmInternalUserName = "lvintern"
    ldmInternalPassword = "secret1"
  }
}

See Enciphered Passwords above for the supported way to encipher the internal user's password for added security.

Client API Listener

A configuration file of HOCON type ldmclientapilistener defines the authentication realm associated with this listener, indicating that user authentication is to be performed for requests handled by this listener. This file also configures the TCP port for the LiveView client API to listen on.

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

LiveView Project Settings

Although not strictly required, you can use a configuration file of HOCON type ldmengine to specify the JVM argument settings that TIBCO recommends as a minimum for LiveView projects.

name= "engineforsecurity"
version= "1.0.0"
type= "com.tibco.ep.ldm.configuration.ldmengine"
configuration = {
  LDMEngine = {
    systemProperties = {
      "liveview.ssl.hostname" = "localhost"   
     }
      jvmArgs = [
      "-Xmx1024m"
      "-Xms512m"
      "-XX:MaxPermSize=768m"
     ]
  }
}

LDAP Realm Configuration

Configure an LDAP security realm by adding and editing the following HOCON configuration files.

Define LDAP Configuration

Configure your LDAP environment with a configuration file of type security. These are site-specific settings, so the following example can provide only general guidelines.

name = "ldaprealm"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  LDAPAuthenticationRealm = {
    name = "ldap-authentication-realm"
    servers = [
      {
        systemPrincipal = "CN=lvintern,OU=Users,dc=example,dc=com"
        systemPassword = "lvintern"
        secureCommunicationProfileName = "secure-client"
        host = "localhost"
        portNumber = 389
        principalSearchRoots = [
          "OU=Users,DC=example,DC=com",
        ]
        principalSearchFilter="cn={0}"
        roleSearchRoots = [
          "OU=Roles,DC=example,DC=com"
        ]
        roleSearchFilter = "roleOccupant={1}"
      }
    ]
  }
}
Role to Privilege Mappings

Configure the mapping of roles to LiveView privileges in a configuration file with HOCON type security using configuration class RoleToPrivlegeMappings.

The only difference in mappings for the LDAP realm and the local realm mapping example in Role to Privilege Mappings above is that the names of the privilege groups are returned from the LDAP server. Thus, your role to privilege mappings file would contain the LDAP name of your LiveView user group instead of LVUser, and the LDAP names of groups that you want to assign privileges equivalent to LVAdmin and LVGuest, as shown in the local realm mappings file.

Internal User Credentials

To designate a user name as the internal user with the LVInternal role, use a configuration file with HOCON type ldminternalcredentials. See Internal User Credentials above for an example.

LiveView Privilege Settings

The first table below lists the available LiveView privileges defined in the security HOCON file type, and shows their equivalent permissions used prior to LiveView 10.x, where applicable. For comparison, the second table lists the pre-10.x permissions except where noted.

Privilege Description
API access privileges
APIConnect Maps to the LiveView connect privilege
Stream-related privileges, mapped to the corresponding StreamBase and LiveView privileges
StreamEnqueue Maps to the StreamBase Enqueue privilege and the LiveView tuple:send privilege
StreamDequeue Maps to the StreamBase Dequeue privilege
LiveViewSBStreamInfoRetrieve Maps to the LiveView sbinfo:get privilege
LiveView administrative privileges
LiveViewPublisherKill Maps to the LiveView publisher:kill privilege
LiveViewQueryKill Maps to the LiveView query:kill privilege
LiveViewSessionKill Maps to the LiveView session:kill privilege
LiveViewAll LiveView table full ("*") privileges
LiveViewShutdown LiveView server shutdown privileges
LiveView table alert privileges
LiveViewAlertAll Maps to the LiveView alert.* privilege
LiveViewAlertDelete Maps to the LiveView alert:delete privilege. If no resource is specified, or contains *, the privilege applies to all LiveView tables.
LiveViewAlertDeleteSelf

Allows deleting alert rules that were created by the logged-in user only. If a resource is specified, then the privilege applies to alert rules associated with the specified table only.

This privilege does not have a pre-10.x equivalent.

LiveViewAlertList Maps to the LiveView alert:list privilege. If no resource is specified, or contains *, the privilege applies to all LiveView tables.
LiveViewAlertListSelf

Allows retrieving the set of configured alerts created by the logged-in user only. If a table resource is specified, this privilege applies to alert rules associated with that specific table only.

This privilege does not have a pre-10.x equivalent.

LiveViewAlertSet Maps to the LiveView alert:set privilege. If no resource is specified, or contains *, the privilege applies to all LiveView tables.
LiveViewAlertSetSelf

Allows adding or modifying alert rules on the specified tables that were created by the logged-in user only. If no resource is specified, or contains *, the privilege applies to all LiveView tables.

This privilege does not have a pre-10.x equivalent.

LiveViewAlertActionAll Maps to the LiveView alertaction:* privilege
LiveViewAlertActionDelete Maps to the LiveView alertaction:delete privilege
LiveViewAlertActionEmail Maps to the LiveView alertaction:email privilege
LiveViewAlertActionJava Maps to the LiveView alertaction:java privilege
LiveViewAlertActionPublish Enables publishing to the LiveView Alerts table.
LiveViewAlertActionOSCommand Maps to the LiveView alertaction:oscmd privilege
LiveViewAlertActionLVPublish Maps to the LiveView alertaction:publish privilege. Enables publishing to a configurable LV table on a configurable server URL.
LiveViewAlertActionSendTuple Maps to the LiveView alertaction:sendtuple privilege
LiveViewAlertActionInvokeHTTP Allows calling a REST endpoint using the HTTP protocol. This privilege does not have a pre-10.x equivalent.

Note

Specifying a resource called __CronAlertsOnly filters cron-based alert rules. For example, for a role called LVUser, the privilege of LiveViewAlertListSelf for resource __CronAlertsOnly would allow LVUser to list alert rules created by that role that are cron-based alert rules. Also, notice that this resource requires two underscores (__).

LiveViewAlertGroupSet Allows setting cluster-wide LiveView alert groups on a specific alert rule. This privilege does not have a pre-10.x equivalent.
LiveViewAlertGroupGet Allows getting cluster-wide LiveView alert groups on a specific alert rule. This privilege does not have a pre-10.x equivalent.
LiveViewAlertGroupAll Allows access to all available alert groups in the cluster. This privilege does not have a pre-10.x equivalent.
LiveViewClusterManageAlert Used for clustermanage lv-client command. Affects the target for managing alerts, where the resource is the action. This privilege does not have a pre-10.x equivalent.
LiveViewClusterManageAll Allows alert group management for LiveView cluster. Affects the target for managing alerts, where the resource is the action. This privilege does not have a pre-10.x equivalent.
LiveView table management privileges
LiveViewTableAll Maps to the LiveView table:* privilege
LiveViewTableDelete Maps to the LiveView table:delete privilege
LiveViewTableList Maps to the LiveView table:list privilege
LiveViewTableManage Maps to the LiveView table:manage privilege
LiveViewTableQuery Maps to the LiveView table:query privilege
LiveViewTablePublish Maps to the LiveView table:publish privilege
LiveViewTableAdd Maps to the LiveView table:add privilege
LiveViewTableRemove Maps to the LiveView table:remove privilege
LiveViewRowLevelAccess Restricts display to specified table+row for the designated user. Setting this privilege affects alert queries, LiveView queries, and delete alert actions.
LiveView tuple management privileges
LiveViewTupleAll Maps to the LiveView tuple:* privilege
LiveViewTupleInfo Maps to the LiveView tuple:info privilege
LiveViewTupleSend Maps to the LiveView tuple:send privilege
LiveView workspace management privileges
LiveViewWorkspaceAll Maps to the LiveView workspace:* privilege
LiveViewWorkspaceDelete Maps to the LiveView workspace:delete privilege
LiveViewWorkspaceGet Maps to the LiveView workspace:get privilege
LiveViewWorkspaceSet Maps to the LiveView workspace:set privilege
LiveView Web privileges
LiveViewWebDashboardCreate Maps to the LiveView Web dashboard:create privilege
LiveViewWebPageCreate Maps to the LiveView Web page:create privilege
LiveViewWebCardCreate Maps to the LiveView Web card:create privilege
LiveViewWebLinkageCreate Maps to the LiveView Web linkage:create privilege
LiveView metadata store privileges
LiveViewMetadataImport Enables importing data into the LiveView server
LiveViewMetadataExport Enables exporting data from the LiveView server

Note

LiveViewMetadataImport and LiveViewMetadataExport settings are highly sensitive privileges and care should be used in assigning them to appropriate users. TIBCO recommends assigning these privileges to an administrator. Users with LiveViewMetadataExport privileges can view all alerts, workspace, (and so on) information in the export file. This is true even if the user with LiveViewMetadataExport privileges could not see any of this information via client API calls.

For reference, the following table lists LiveView permissions in LiveView releases before 10.x:

Permission Description
* Allows full access to all LiveView resources.
connect Allows a user to connect to LiveView.
publisher[:<operation>]

This hierarchical permission controls the ability to kill LiveView client publishers. It contains between one and two elements delimited with colons. The second element specifies the tuple operation as follows:

* Allows all operations on the specified streams.
kill Allows killing of LiveView Publishers.
query[:<operation>]

This hierarchical permission controls the ability to kill LiveView client queries. It contains between one and two elements delimited with colons. The second element specifies the tuple operation as follows:

* Allows all operations on the specified streams.
kill Allows killing of LiveView queries.
session[:<operation>]

This hierarchical permission controls the ability to control whether new client connections are allowed to the current server instance. It contains between one and two elements delimited with colons. The second element specifies the tuple operation as follows:

* Allows all operations on the specified streams.
kill Allows the prevention of new client connections.
shutdown Allows a user to shut down the LiveView server. This permission is typically granted only to LiveView administrators.
table[:<operation>[:<table-name>]]

This hierarchical permission controls access to LiveView tables. It contains between one and three elements delimited with colons. The second element specifies the table operation as follows:

* Allows all operations on the specified tables.
list Allows listing the set of configured LiveView tables. The third element is unused. Listing selected tables can be enabled with the list:table:<table-name> permission.
query Allows querying and listing the specified tables.
publish Allows publishing to the specified tables.
delete Allows deleting records from the specified tables.
manage Allows LiveView tables to be managed via table providers.
add Allows adding data layer LiveView tables
remove Allows removing data layer LiveView tables

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

tuple[:<operation>[:<stream-name>]]

This hierarchical permission controls access to sending tuples from LiveView clients to StreamBase applications. It contains between one and three elements delimited with colons. The second element specifies the tuple operation as follows:

* Allows all operations on the specified streams.
info Allows retrieving schemas associated the specified streams.
send Allows sending tuples to the specified streams.

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

sbinfo[:<operation>]

This hierarchical permission controls access to getting StreamBase stream information. It contains between one and two elements delimited with colons. The second element specifies the type of action as follows:

* Allows all StreamBase information operations.
get Allows retrieving the set of StreamBase streams available to use.
alert[:<operation>[:<table-name>]]

This hierarchical permission controls access to LiveView alerts. It contains between one and three elements delimited with colons. The second element specifies the alert operation as follows:

* Allows all alert operations.
list Allows retrieving the set of configured alerts on the specified tables. If the third element is absent, or contains *, the permission applies to all LiveView tables.
set Allows adding or modifying alert rules on the specified tables. If the third element is absent, or contains *, the permission applies to all LiveView tables.
delete Allows deleting alert rules on the specified tables. If the third element is absent, or contains *, the permission applies to all LiveView tables.
alertaction[:<type>[:<table-name>]]

This hierarchical permission controls access to adding LiveView alerts actions. It contains between one and three elements delimited with colons. The second element specifies the type of alert action as follows:

* Allows adding all types of alert actions.
email Allows adding an alert action that sends an email message to specified username (or usernames).
java Allows adding an alert action that executes Java code.
oscmd Allows adding an alert action that executes an operating system command.
publish Allows adding an alert action that publishes the alert to a LiveView table.
sendtuple Allows adding an alert action that sends a tuple to a StreamBase stream.
delete Allows adding an alert action that deletes rows from a LiveView table.
workspace[:<operation>[:<workspace-name>]]

This hierarchical permission controls access to LiveView workspaces. It contains between one and three elements delimited with a colon. The second element specifies the workspace operation as follows:

* Allows all workspace operations.
get Allows listing available workspaces and downloading individual workspaces from the LiveView server.
set Allows uploading new workspaces to the LiveView server and modifying existing workspaces.
delete Allows deleting workspaces from the LiveView server.

Using StreamBase Authentication with LiveView

If you are using authentication to protect your StreamBase server 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, configure the following name-value pairs in a configuration file of HOCON type ldminternalcredentials:

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

  • streamBaseAdminPassword: The password of the administration-enabled StreamBase user. This property is encryptable as part of the node-level secrecy system described in Encrypting Sensitive Configuration Data.

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

  • streamBasePassword: The password of the StreamBase user without administrative privileges. This property is encryptable as part of the node-level secrecy system described in Encrypting Sensitive Configuration Data.

name = "my-ldm-internal-credentials"
version = "1.0.0"
type = "com.tibco.ep.ldm.configuration.ldminternalcredentials"
configuration = {
  InternalCredentials = {
    associatedWithEngines = [ "javaengine", "otherengine[0-9]" ]
    ldmInternalUserName = "adminUser"
    ldmInternalPassword = "secret"
    ldmSecureInternalCommunicationProfileName = "my-secure-client-profile"

    streamBaseAdminUserName = "adminUser"
    streamBaseAdminPassword = "adminPassword"
    streamBaseUserName = "sbUser"
    streamBasePassword = "sbPassword"
  }
}

Trusted Host Configuration

You must set up Trusted Hosts configuration under two circumstances:

  • For a cluster of more than one LiveView server, so that the service layer can communicate with the data layer.

  • If configured for peer recovery, so that peer data layers can communicate with each other.

This is true for all security realms. Make sure your realm's configuration file has these settings:

requireTrustedHostMembership = true
requirePassword = false

Then set up a TrustedHosts configuration that ensures all of your service layer and data layer hosts and networks are authorized to communicate with each other. For example:

name = "trustedHostRealm"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  TrustedHosts = {
    hosts = 
      [
        "*.lvsubnet.example.com", 
        "172.16.12.42", 
        "172.16.42.0/23" 
      ]
  }
}

Important

Do not configure a trusted host configuration for your service layer fragment without a thorough security review. In general, make these settings only for your data layer fragments.

See the StreamBase Security Model section of the StreamBase Administration Guide for an overview of the security configuration settings.