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).

Live Datamart 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 FileNewStreamBase 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.

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.

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 Live Datamart 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 = "secret1ve"
  }
}

You can provide an enciphered string for the password's value, as generated with the sbcipher 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/+AMltwstrNSLbGUmA1
  YBvEq+UUkJ/Sxe5jOLUO2oax1KypNRw=="

Local Realm Configuration

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

Enable Authentication

In a configuration file with HOCON type ldmengine, enable authentication by setting authenticateUsers to true. The following example of this configuration type enables authentication but also specifies the JVM argument settings that TIBCO recommends as a minimum for LiveView projects.

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

configuration = {
  LDMEngine = {
    jvmArgs =
      [
        "-Xmx3g"
        "-Xms512m"
        "-XX:+UseG1GC"
        "-XX:MaxGCPauseMillis=500"
        "-XX:ConcGCThreads=1"
      ]
      ldm = {
        authenticateUsers = true
      }
  }
}

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 = {
    apiAccessPrincipals = [
      {
        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 configuration class RoleToPrivlegeMappings. Notice that this configuration type is the same security HOCON type as in the Local Users file described previously, but has a different configuration class (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 Live Datamart.

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.

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 = "secret1ve"
  }
}

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

LDAP Realm Configuration

Configure an LDAP security realm by adding and editing four HOCON configuration files. Three of these files are the same as for the local security realm described in the previous section.

Enable Authentication

Enable authentication a configuration file with HOCON type ldmengine, by setting authenticateUsers to true. See Enable Authentication above for an example.

Define LDAP Configuration

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

name = "ldaprealm"
version = "1.0.0"
type = "com.tibco.ep.streambase.configuration.ldapauthrealm"

configuration = {
  LDAPAuthenticationRealm = {
    connectorFactoryClassName = "com.mycompany.mylocation"
    transformPrincipal = {
      searchRegexp = "xyz"
      replaceRegexp = "abc"
    }
    serverConnectAlgorithm = "round-robin"
    servers = [
      {
        authenticationCredentials = {
          userName = "cn=SBLDAPUser,cn=Users,dc=ldap,dc=example,dc=com"
          password = "secret"
        }
        host = "ldap.example.com"
        portNumber = 390
        secure= true
        principalRoot = "o=yourcompany/ou=yourdepartment"
        principalSearch = "cn={0}"
        roleRoot = "o=yourcompany/ou=yourdepartment"
        roleSearch = "cn={0}"
        roleAttribute = "memberOf"
      }
    ]
  }
}
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 Live Datamart 10.x, where applicable. For comparison, the second table lists the pre-10.x LiveView permissions.

Privilege Description
API access privileges
APIConnect Maps to the Live Datamart connect privilege
Stream-related privileges, mapped to the corresponding StreamBase and Live Datamart privileges
StreamEnqueue Maps to the StreamBase Enqueue privilege and the Live Datamart tuple:send privilege
StreamDequeue Maps to the StreamBase Dequeue 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
LiveViewAlertList Maps to the LiveView alert:list privilege
LiveViewAlertSet Maps to the LiveView alert:set privilege
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
LiveViewAlertActionOSCommand Maps to the LiveView alertaction:oscmd privilege
LiveViewAlertActionPublish Maps to the LiveView alertaction:publish privilege
LiveViewAlertActionSendTuple Maps to the LiveView alertaction:sendtuple privilege
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
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
LiveViewWebCardCreate Maps to the LiveView Web card:create privilege
LiveViewWebDashboardCreate Maps to the LiveView Web dashboard:create privilege
LiveViewWebLinkageCreate Maps to the LiveView Web linkage:create privilege
LiveViewWebPageCreate Maps to the LiveView Web page:create privilege

For reference, the following table lists LiveView permissions in Live Datamart 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.
ccquery Allows querying that have calculated columns in projection 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.

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. The third element is unused.
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. The third element is unused.
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. You can provide an enciphered string for a password's value, as generated with the sbcipher command; you must prefix #! to the generated string.

  • streamBaseUserName: The user name 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; you must prefix #! to the generated string.

name = "ldm-internal-creds-01"
version = "1.0.0"
type = "com.tibco.ep.ldm.configuration.ldminternalcredentials"
configuration = {
  InternalCredentials = {
    ldmInternalUserName = "lvintern"
    ldmInternalPassword = "secret1ve"

    streamBaseAdminUserName = "sbAdminUser"
    streamBaseAdminPassword = "sbAdminPassword"
    streamBaseUserName = "sbUser"
    streamBasePassword = "sbPassword"
  }
}