Reference for DTM Security Configuration

Overview

This article provides a reference for writing a DTM Security HOCON configuration file.

Included are configuration examples for:

  • Trusted hosts

  • Local Authentication

  • Role to Privileges Mappings

Each security configuration can reside in its own HOCON file using the security configuration type. Alternatively, each type can be embedded in the same file.

Required Header Lines

Each configuration file must contain the following header lines, typically found at the beginning of each file:

name

Specifies an arbitrary, case-sensitive string to name this configuration, which must be unique among other files with the same type, if any. Configuration files can refer to each other by this name. Select a name that reminds you of this configuration's type and purpose. For example:

name = "mysecuritysettings"
version

Specifies an arbitrary version number that you can use to keep track of file versions for this configuration type in your development project. The maintenance of version numbers is under user control; StreamBase does not compare versions when loading configuration files during the fragment launch process. The version number is a string value, and can contain any combination of characters and numbers. For example:

version = "1.0.0"
type

This essential setting specifies the unique HOCON configuration type described on this page.

type = "com.tibco.ep.dtm.configuration.security"

The header lines taken together constitute a unique signature for each HOCON file in a project's configurations folder. Each project's configurations folder can contain only one file with the same signature.

In addition, the configuration top-level element is the same for all HOCON file types.

configuration

On a line below the header element lines, enter the word configuration followed by an open brace. The configuration element is a sibling of the name, version, and type elements, and serves as a wrapper around this type's elements described below. The file must end with the matching close brace.

configuration = {
...
...
}

HOCON Elements Explained

Below shows the configuration's HOCON elements, its name-values, usage, and syntax example, where applicable.

Trusted Hosts

The default local authentication source in a node supports the configuration of trusted hosts, which allows for expedited authentication of principals when the authentication request originates from a network connection from a configured trusted host. Authentication from a trusted host passes without consideration for credentials. That is, if the authentication request originates from a trusted host, Distributed Transactional Memory trusts the host-based authentication mechanism (for example, a UNIX login) to have verified the identity of the principal.

TrustedHosts

A list of hosts from which users do not need to authenticate when executing administrative commands. Hosts must be in an array.

Hosts

String. The host names (fully qualified domain name, or simple name).

For example:

hosts = [
"a.tibco.com" 
"b.tibco.com" 
"c.tibco.com" 
]

Local Authentication

When configured for local realm authentication, the user, password, and role information is stored directly in the configuration file.

LocalAuthenticationRealm

Defines a local authentication realm, containing one or more administrator and API access principals.

administratorPrincipals

An array of administrator principals. This name-value pair is optional and has no default value.

userName

This name-value pair is required and cannot be an empty string.

For example:

userName = "FredTheAdministrator"
encryptedPassword

Principal's one-way-hashed password, as returned by the epadmin export security command.

For example:

encryptedPassword = "LKJALISJDOIQUWEOIAJSLKDJALSJDL"
roles

Roles to which the principal has access. At least one list member is required.

Default roles:

  • "BasicUser"

  • "StreamBaseSuperuser"

  • "admin"

passwordExpirationPeriodDays

Password expiration time in days. This name-value pair is optional and its default value is 0, meaning the password never expires.

For example:

passwordExpirationPeriodDays = 12
passwordAlwaysRequired

Whether a credential is always required. If true, the principal must always present a credential during authentication, and cannot use the trusted host facility. This name-value pair is optional and its default value is false.

For example:

passwordAlwaysRequired = true
trustedHostAccessOnly

Whether the principal may only be authenticated when connecting from a trusted host.

For example:

trustedHostAccessOnly = false
apiAccessPrincipals

An array of API access principals in this realm. This name-value pair is optional and has no default value.

userName

String. The name of the principal. This name-value pair is required and cannot be an empty.

For example:

userName = "bob"
password

String. The principal's password. You can provide an enciphered string for the value; generate the enciphered string with the sbcipher command and prefix #! to the generated string. This name-value pair is required.

For example:

password = "secret2"
roles

String. The roles to which this principal belongs, if any. Each role is an arbitrary text string, which can be bound to various privileges in a role-to-privileges mapping object. This name-value pair is optional. If present, the array must contain at least one element.

For example:

roles = [ "BasicUser" ]

Role to Privileges Mappings

RoleToPrivilegeMappings

A description of general privileges associated with roles. Each privilege has an associated resource; a privilege defines what you can do, and its associated resource defines what you can do it.

privileges

An associative array of privileges keyed by role.

admin

String. Role name example.

privilege

The privilege's type. This name-value pair is required.

For example:

privilege = "AdminRunCommand"
streamBaseSuperuser

String. Role name example.

privilege

The privilege's type. This name-value pair is required.

For example:

privilege = "StreamEnqueue"
resource

String. The resource to which the privilege applies. For example, if the privilege allows writing to an event queue, the resource might be the queue name, or a regular expression that matches multiple queue names. If the privilege doesn't apply to a resource, this name-value pair can be left null. This name-value pair is optional and has no default value.

For example:

resource = "default.InputStream1"
LDMUserAll

String. Role name example.

A role must be assigned at least one privilege. A resource can be assigned to a privilege unless otherwise noted. StreamBase 10 uses HOCON to replace Live Datamart users, roles, and privileges settings that were previously configured in liveview.properties and liveview.auth.properties files in StreamBase 7.

privilege

The privilege type that maps to the role. This name-value pair is required.

The following table describes the available Live Datamart privileges that you can assign. The description column maps HOCON-configured privileges to their StreamBase 7 equivalents, where applicable.

The examples below the table describe possible Live Datamart and LiveView Web user roles with privileges and resources assigned to those roles.

Privilege Description
API access privileges  
API_CONNECT 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

The example below shows a Live Datamart user role, LVAdmin, with all Live Datamart privileges. This is equivalent to configuring the liveview.auth.properties file to role.LVAdmin = * in StreamBase 7.

LVAdmin = [
  {
  privilege = "LiveViewAll"
  }
]

For those familiar with StreamBase 7, recall that several internal LiveView components were required to make requests to access LiveView server resources, by setting LiveView properties files. When authentication was enabled, for example, these internal requests had to be made in the context of a valid LiveView user configured with the appropriate permissions. A special role, LVInternal, satisfied this requirement.

In StreamBase 10, instead of configuring LiveView properties files, create a Live Datamart user role, LVInternal, and map privileges to the role to perform internal LiveView user functions similar to those in StreamBase 7.

For example:

LVInternal = [
  {
    privilege = "APIConnect"
  }
  {
    privilege = "LiveViewShutdown"
  }
  {
    privilege = "LiveViewTableQuery"
  }
  {
    privilege = "LiveViewTablePublish"
    resource = "LVAlerts"
   }
   {
    privilege = "LiveViewTableDelete"
    resource = "ItemsSales"
   }
   {
    privilege = "LiveViewTableManage"
   }
   {
    privilege = "LiveViewWorkspaceAll"
   }
  ]

The following example shows a Live Datamart user role, LVUser, assigned Live Datamart and LiveView Web privileges:

LVUser = [
  {
    privilege = "APIConnect"
  }
  {
    privilege = "LiveViewTableList"
  }
  {
    privilege = "LiveViewTableManage"
  }
  {
    privilege = "LiveViewTableAll"
    resource = "ItemsSales"
  }
  {
    privilege = "LiveViewTableQuery"
  }
  {
    privilege = "LiveViewAlertList"
  }
  {
    privilege = "LiveViewAlertSet"
    resource = "ItemsSales"
  }
  {
    privilege = "LiveViewAlertDelete"
  }
  {
    privilege = "LiveViewAlertActionPublish"
    resource = "ItemsSales"
  }
  {
    privilege = "LiveViewAlertActionEmail"
    resource = "ItemsSales"
  }
  {
    privilege = "LiveViewAlertActionSendTuple"
    resource = "ItemsSales"
  }
  {
    privilege = "LiveViewTupleInfo"
    resource = "ItemsSales.DataIn"
  }
  {
    privilege = "LiveViewTupleSend"
    resource = "ItemsSales.DataIn"
  }
  {
    privilege = "LiveViewWorkspaceGet"
    resource = "Auth Sample"
  }
  {
    privilege = "LiveViewWebCardCreate"
  }
  {
    privilege = "LiveViewWebDashboardCreate"
  }
  {
    privilege = "LiveViewWebLinkageCreate"
  }
  {
    privilege = "LiveViewWebPageCreate"
  }

 ]

The following example shows a Live Datamart user role, LVGuest, assigned Live Datamart privileges:

LVGuest = [
  {
    privilege = "APIConnect"
  }
  {
    privilege = "LiveViewTableList"
  }
  {
    privilege = "LiveViewTableManage"
  }
  {
    privilege = "LiveViewTableAll"
    resource = "ItemsSales"
  }
  {
    privilege = "LiveViewTableQuery"
  }
  {
    privilege = "LiveViewAlertList"
  }
  {
    privilege = "LiveViewAlertSet"
    resource = "ItemsSales"
  }
  {
    privilege = "LiveViewAlertDelete"
  }
  {
    privilege = "LiveViewAlertActionPublish"
    resource = "ItemsSales"
  }
  {
    privilege = "LiveViewAlertActionEmail"
    resource = "ItemsSales"
  }
  {
    privilege = "LiveViewAlertActionSendTuple"
    resource = "ItemsSales"
  }
  {
    privilege = "LiveViewTupleInfo"
    resource = "ItemsSales.DataIn"
  }
  {
    privilege = "LiveViewTupleSend"
    resource = "ItemsSales.DataIn"
  }
  {
    privilege = "LiveViewWorkspaceGet"
    resource = "Auth Sample"
  }
 ]

The following example shows a LiveView Web user role, LVWebUser, assigned the following privileges:

LVWebUser = [
  {
    privilege = "LiveViewWebCardCreate"
  }
  {
    privilege = "LiveViewWebDashboardCreate"
  }
  {
    privilege = "LiveViewWebLinkageCreate"
  }
  {
    privilege = "LiveViewWebPageCreate"
  }
 ]
resource

String. The resource to which the privilege applies. If the privilege doesn't apply to a resource, this name-value pair can be left null. This name-value pair is optional and has no default value.

For example:

resource = "myTable"
basicUser

String. Role name example.

privilege

The privilege's type. This name-value pair is required.

For example:

privilege = "StreamEnqueue"
privilege = "StreamDequeue"
resource

String. The resource to which the privilege applies. For example, if the privilege allows writing to an event queue, the resource might be the queue name, or a regular expression that matches multiple queue names. If the privilege does not apply to a resource, this name-value pair can be left null. This name-value pair is optional and has no default value.

For example:

resource = "default.InputStream1"
resource = "default.OutputStream1"

HOCON Configuration File Samples

The following are snippets of the three subtypes supported using the com.tibco.ep.dtm.configuration.security type.

Trusted Hosts Sample

The following is a sample TrustedHosts configuration file.

name = "my-hosts"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {

  TrustedHosts = {
    hosts = [
      "a.tibco.com"
      "b.tibco.com"
      "c.tibco.com"
    ]
  }
}

Local Authentication

The following is a sample local authentication configuration file for StreamBase.

name = "localrealm1"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  LocalAuthenticationRealm = {
    administratorPrincipals = [
      {
        userName = "FredTheAdministrator"       
        encryptedPassword = "LKJALISJDOIQUWEOIAJSLKDJALSJDL"     
        roles = [
          "BasicUser"
          "StreamBaseSuperuser"
          "admin"
        ]   
        passwordExpirationPeriodDays = 12   
        passwordAlwaysRequired = true       
        trustedHostAccessOnly = false
      }
    ]
    apiAccessPrincipals = [
      {  
        userName = "bob"   
        password ="secret2"    
        roles = [ "BasicUser" ]
      }
    ]
  }
}

The following is a sample local authentication configuration file for Live Datamart.

name = "localrealm"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  LocalAuthenticationRealm = {
    apiAccessPrincipals = [
      {
        userName = "admin"
        password ="admin"
        roles = [ "LVAdmin" ]
      }
      {
        userName = "lvintern"
        password ="lvintern"
        roles = [ "LVInternal" ]
      }
      {
        userName = "guest"
        password ="guest"
        roles = [ "LVGuest" ]
      }
      {
        userName = "tester"
        password ="tester"
        roles = [ "LVUser" ]
      }
    ]
  }
}

Role to Privileges Mappings

The following is a sample RoleToPrivilegeMappings configuration file that includes StreamBase, Live Datamart, and LiveView Web configuration.

name = "my-RoleToPrivilegeMappings"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  RoleToPrivilegeMappings = {
    privileges = {
      AdministratorSpecificCommands = [
        {
          privilege = "AdminRunCommand"
          resource = "breakpointplugin::Plugin::continueCommand"
        }
        {
          privilege = "AdminRunCommand"
          resource = "security::SecurityPlugin::display"
        }
      ]
      StreamBaseSuperuser = [
        { 
          privilege = "StreamEnqueue"
          resource = "default.InputStream1"
        }
      ]
      StreamBaseBasicUser = [
        {
          privilege = "StreamEnqueue"
          resource = "default.InputStream1"
        }
        {
          privilege = "StreamDequeue"
          resource = "default.OutputStream1"
        }
      ]
      AnotherAdminUser = [
        {
          privilege = "StreamEnqueue"
          resource = "default.InputStream1"
        }
        {
          privilege = "APIConnect"
        }
      ]
      LDMUserAll = [
        {
          privilege = "LiveViewAlertAll"
          resource = "alertName1"
        }
        {
          privilege = "LiveViewTupleAll"
          resource = "mySchema1"
        }
        {
          privilege = "LiveViewTableAll"
          resource = "myTable1"
        }
        {
          privilege = "LiveViewAlertActionAll"
          resource = "alertName2"
        }
        {
          privilege = "LiveViewWorkspaceAll"
          resource = "wsName1"
        }
      ]
      LDMUserAll2 = [
        {
          privilege = "LiveViewAll"
        }
      ]
      LDMUserEach = [
        {
          privilege = "LiveViewShutdown"
        }
        {
          privilege = "LiveViewTableList"
          resource = "myTable"
        }
        {
          privilege = "LiveViewTableDelete"
          resource = "myTable"
        }
        {
          privilege = "LiveViewTableManage"
          resource = "myTable"
        }
        {
          privilege = "LiveViewTableQuery"
          resource = "myTable"
        }
        {
          privilege = "LiveViewTablePublish"
          resource = "myTable"
        }
        {
          privilege = "LiveViewAlertDelete"
          resource = "alertName"
        }
        {
          privilege = "LiveViewAlertSet"
          resource = "alertName"
        }
        {
          privilege = "LiveViewAlertList"
          resource = "alertName"
        }
        {
          privilege = "LiveViewWorkspaceGet"
          resource = "wsName"
        }
        {
          privilege = "LiveViewWorkspaceSet"
          resource = "wsName"
        }
        {
          privilege = "LiveViewWorkspaceDelete"
          resource = "wsName"
        }
        {
          privilege = "LiveViewTupleInfo"
          resource = "stream1"
        }
        {
          privilege = "LiveViewTupleSend"
          resource = "stream2"
        }
        {
          privilege = "LiveViewAlertActionDelete"
          resource = "alert1"
        }
        {
          privilege = "LiveViewAlertActionEmail"
          resource = "alert1"
        }
        {
          privilege = "LiveViewAlertActionJava"
          resource = "alert1"
        }
        {
          privilege = "LiveViewAlertActionOSCommand"
          resource = "alert1"
        }
        {
          privilege = "LiveViewAlertActionPublish"
          resource = "alert1"
        }
        {
          privilege = "LiveViewAlertActionSendTuple"
          resource = "alert1"
        }
        {
          privilege = "LiveViewWebCardCreate"
        }
        {
          privilege = "LiveViewWebDashboardCreate"
        }
        {
          privilege = "LiveViewWebLinkageCreate"
        }
        {
          privilege = "LiveViewWebPageCreate"
        }
      ]
    }
  }
}

The following is a sample RoleToPrivilegeMappings configuration file that includes only Live Datamart and LiveView Web configuration.

name = "my-role-mappings"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  RoleToPrivilegeMappings = {
    privileges = {
      LVAdmin = [
        {
          privilege = "LiveViewAll"
        }
      ]
      LVInternal = [
        {
          privilege = "APIConnect"
        }
        {
          privilege = "LiveViewShutdown"
        }
        {
          privilege = "LiveViewTableQuery"
        }
        {
          privilege = "LiveViewTablePublish"
          resource = "LVAlerts"
        }
        {
          privilege = "LiveViewTableDelete"
          resource = "ItemsSales"
        }
        {
          privilege = "LiveViewTableManage"
        }
        {
          privilege = "LiveViewWorkspaceAll"
        }
      ]
      LVUser = [
        {
          privilege = "APIConnect"
        }
        {
          privilege = "LiveViewTableList"
        }
        {
          privilege = "LiveViewTableManage"
        }
        {
          privilege = "LiveViewTableAll"
          resource = "ItemsSales"
        }
        {
          privilege = "LiveViewTableQuery"
        }
        {
          privilege = "LiveViewAlertList"
        }
        {
          privilege = "LiveViewAlertSet"
          resource = "ItemsSales"
        }
        {
          privilege = "LiveViewAlertDelete"
        }
        {
          privilege = "LiveViewAlertActionPublish"
          resource = "ItemsSales"
        }
        {
          privilege = "LiveViewAlertActionEmail"
          resource = "ItemsSales"
        }
        {
          privilege = "LiveViewAlertActionSendTuple"
          resource = "ItemsSales"
        }
        {
          privilege = "LiveViewTupleInfo"
          resource = "ItemsSales.DataIn"
        }
        {
          privilege = "LiveViewTupleSend"
          resource = "ItemsSales.DataIn"
        }
        {
          privilege = "LiveViewWorkspaceGet"
          resource = "Auth Sample"
        }
        {
          privilege = "LiveViewWebCardCreate"
        }
        {
          privilege = "LiveViewWebDashboardCreate"
        }
        {
          privilege = "LiveViewWebLinkageCreate"
        }
        {
          privilege = "LiveViewWebPageCreate"
        }
      ]
      LVGuest = [
        {
          privilege = "APIConnect"
        }
        {
          privilege = "LiveViewTableList"
        }
        {
          privilege = "LiveViewTableManage"
        }
        {
          privilege = "LiveViewTableAll"
          resource = "ItemsSales"
        }
        {
          privilege = "LiveViewTableQuery"
        }
        {
          privilege = "LiveViewAlertList"
        }
        {
          privilege = "LiveViewAlertSet"
          resource = "ItemsSales"
        }
        {
          privilege = "LiveViewAlertDelete"
        }
        {
          privilege = "LiveViewAlertActionPublish"
          resource = "ItemsSales"
        }
        {
          privilege = "LiveViewAlertActionEmail"
          resource = "ItemsSales"
        }
        {
          privilege = "LiveViewAlertActionSendTuple"
          resource = "ItemsSales"
        }
        {
          privilege = "LiveViewTupleInfo"
          resource = "ItemsSales.DataIn"
        }
        {
          privilege = "LiveViewTupleSend"
          resource = "ItemsSales.DataIn"
        }
        {
          privilege = "LiveViewWorkspaceGet"
          resource = "Auth Sample"
        }
      ]
    }
  }
}