Contents
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.
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 Configuration Guide.
→ → . For further information about the HOCON file format and syntax, see theThese 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.
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.
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 = "secret1" } }
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/+AMltwstr NSLbGUmA1YBvEq+UUkJ/Sxe5jOLUO2oax1KypNRw=="
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 Live Datamart.
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 } ] } }
Refer to Using TLS/SSL with LiveView Server for instructions on how to enable TLS for LiveView.
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" ] } ] } }
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.
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.
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" } }
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.web.pstore.type" = "h2" "liveview.ssl.hostname" = "localhost" } jvmArgs = [ "-Xmx1024m" "-Xms512m" "-XX:MaxPermSize=768m" ] } }
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 typeldminternalcredentials
. See Internal User Credentials above for an example.
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 |
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 |
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 |
LiveViewTableCCQuery | Maps to the LiveView table:ccquery privilege |
LiveViewTableAdd | Maps to the LiveView table:add privilege |
LiveViewTableRemove | Maps to the LiveView table:remove 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 | |
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 using lv-client into the LiveView server |
LiveViewMetadataExport | Enables exporting data using lv-client from the LiveView server |
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:
|
||||||||||||||||||
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:
|
||||||||||||||||||
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:
|
||||||||||||||||||
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:
If the third element is absent, or contains |
||||||||||||||||||
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:
If the third element is absent, or contains |
||||||||||||||||||
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:
|
||||||||||||||||||
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:
|
||||||||||||||||||
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:
|
||||||||||||||||||
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:
|
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 = "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" } }