Runtime Security Configuration

Contents

Overview
Required Header Lines
Local Authentication Realm
LDAP Authentication Realm
Open ID Connect Authentication Realm
Kerberos Authentication Realm
PrivilegeSettingsGroup
Role to Privilege Mappings
Secure Communication Client Profile
Secure Communication Server Profile
Trusted Hosts
Deprecated Security Features

Overview

This article provides a reference for writing a StreamBase Runtime security configuration file where the HOCON type is com.tibco.ep.dtm.configuration.security.

The root objects in this configuration type are:

Local Authentication Realms
LDAP Authentication Realms
Open ID Connect Authentication Realms
Kerberos Authentication Realms
Privilege Settings Groups
Role-to-Privileges Mappings
Secure Communication Client Profiles
Secure Communication Server Profiles
Trusted Hosts
Local Admin Authentication Realms (Deprecated)

Use the contents menu above to open the root object section of interest.

Each root object can reside in its own configuration file of this configuration type. As an alternative, each root object can be embedded in the same file of this type.

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 = "sbsecurity"
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 three 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.

The top-level configuration object defines the configuration envelope the same way for all HOCON file types.

configuration

On a line below the header lines, enter the word configuration followed by an open brace. The configuration object is a sibling of the name, version, and type identifiers, and serves to define the configuration envelope around this type's objects as described on this page. The file must end with the matching close brace. 

configuration = {
...
...
}

Local Authentication Realm

The local authentication realm contains local user, password, and role information for authenticating StreamBase EventFlow and LiveView users.

LocalAuthenticationRealm

Defines a local authentication realm, containing one or more principals.

name

String. The name of this realm, unique across all authentication realms. This property is required. For example: 

name = "my-realm"
requireTrustedHostMembership

Bool. If set to true, all incoming requests authenticated by this realm are rejected unless they come from a trusted host. This property is optional and its default value is false.

For example: 

requireTrustedHostMembership = false
allowSecureCommunicationClientAuthentication

Bool. If set to true, incoming requests using secure communication with client authentication are automatically authenticated without a password required. This property is optional and its default value is false.

For example: 

allowSecureCommunicationClientAuthentication = true
failedLoginLockoutDurationMinutes

The number of minutes a user's account remains locked after exceeding the lockout threshold. A value of zero means the account remains locked until manually unlocked by an administrator. This property is optional and its default value is zero. See Number of Login Attempts Feature for further information on this and the next property.

For example: 

failedLoginLockoutDurationMinutes = 15
failedLoginLockoutThreshold

The number of consecutive failed login attempts required before a user's account is locked. A value of zero allows an unlimited number of attempts. This property is optional and its default value is zero.

For example: 

failedLoginLockoutThreshold = 5
requirePassword

Bool. If set to true, incoming requests not automatically authenticated with secure communication client authentication always require a password. If set to false, a password is not required if the request comes from a trusted host. This property is optional and its default value is true.

Caution

The default value for this object in a customer-activated LocalAuthRealm configuration is true. However, the value for this object in the set of initial security defaults is false. Thus, if you activate a new LocalAuthRealm configuration for a node currently using the default security settings, you can lock yourself out of the realm. See the cautions on the Default Security Configuration page.

For example: 

requirePassword = false
principals

Deprecated. Instead, use initialPrincipals.

initialPrincipals

Initial principal set, used once to populate the realm when it is first created on a node. Ignored afterwards and in subsequent versions. This array is optional and has no default value.

userName

The name of the principal. This property is required and cannot be an empty string. For example: 

userName = "SomeUser"
password

String. The principal's password, either clear text or enciphered. This required property is encryptable as part of the node-level secrecy system described in Encrypting Sensitive Configuration Data.

For example: 

password ="secret2"
passwordExpirationPeriodDays

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

For example: 

passwordExpirationPeriodDays = 180
locked

Bool. Account lock status. True means the account is locked and attempts to use it for authentication will fail. False means the account is not locked. This property is optional and its default value is false. See Account Lock Features for a discussion of locked user accounts.

For example: 

locked = false
roles

The roles to which this principal belongs. Each role is an arbitrary text string, which can be bound to various privileges in a role-to-privileges mapping object. This property is required and the array must contain at least one element.

For example: 

roles = [ "BasicUser" ]

Examples, Local Authentication Realm

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

name = "localrealmSB"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  LocalAuthenticationRealm = {
    name = "my-realm"
    requireTrustedHostMembership = false
    allowSecureCommunicationClientAuthentication = false
    failedLoginLockoutThreshold = 5
    failedLoginLockoutDurationMinutes = 15
    requirePassword = false
    initialPrincipals = [
      {
        userName = "SomeUser"
        password ="secret2"
        passwordExpirationPeriodDays = 180
        locked = false
        roles = [ "BasicUser" ]
      }
    ]
  }
}

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

name = "localRealmLDM"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  LocalAuthenticationRealm = {
    name = "authRealm"
    initialPrincipals = [
      {
        userName = "admin"
        password ="admin"
        roles = [ "LVAdmin" ]
      }
      {
        userName = "lvintern"
        password ="lvintern"
        roles = [ "LVInternal" ]
      }
      {
        userName = "guest"
        password ="guest"
        roles = [ "LVGuest" ]
      }
      {
        userName = "tester"
        password ="tester"
        roles = [ "LVUser" ]
      }
      {
        userName = "client"
        password ="client"
        roles = [ "LVUser" ]
      }     
    ]
  }
  SecureCommunicationServerProfile = {
    keyStore = "C:/Users/sbuser/Desktop/AddOns/SSL/X509/serverkeystore.jks"
    keyStorePassword = "changeit"
    keyStoreType = "JKS"
    keyPassword = "changeit"
    name = "serverprofile"
    requireClientAuthentication = true
    trustStore = "C:/Users/sbuser/Desktop/AddOns/SSL/X509/truststore.jks"
    trustStorePassword = "changeit"
    trustStoreType = "JKS"
    userNameObjectIdentifierSearchPath = [ "emailAddress", "CN", "DN" ]
  }
  SecureCommunicationClientProfile = {
    name = "clientprofile"
    keyStore = "C:/Users/sbuser/Desktop/AddOns/SSL/X509/serverkeystore.jks"
    keyStorePassword = "changeit"
    keyStoreType = "JKS"
    keyPassword = "changeit"
    requireClientAuthentication = true
    trustStore = "C:/Users/sbuser/Desktop/AddOns/SSL/X509/truststore.jks"
    trustStorePassword = "changeit"
    trustStoreType = "JKS"
  }
}

LDAP Authentication Realm

This configuration type defines a single LDAP authentication realm. The realm can contain multiple servers for redundancy to authenticate StreamBase or LiveView users and check the roles to which those users belong. StreamBase and LiveView roles are defined in a RoleToPrivilegeMappings configuration file, which must accompany your LDAP authentication realm configuration to map LDAP group names to StreamBase role names.

LDAP configuration is separate from the base engine configuration and can therefore be managed separately without having to recreate an application archive and redeploy the application.

LDAP configuration is described in more depth in LDAP Authentication Realm in the StreamBase Admin Guide.

LDAPAuthenticationRealm

A single LDAP authentication realm. The realm can contain multiple servers for redundancy.

name

String. The name of this realm, unique across all authentication realms. This property is required. For example: 

name = "my-realm"
requireTrustedHostMembership

Bool. If set to true, all incoming requests authenticated by this realm are rejected unless they come from a trusted host. This property is optional and its default value is false. For example: 

requireTrustedHostMembership = false
allowSecureCommunicationClientAuthentication

Bool. If set to true, incoming requests using secure communication with client authentication are automatically authenticated without a password required. This property is optional and its default value is false. For example: 

allowSecureCommunicationClientAuthentication = true
requirePassword

Bool. If set to true, incoming requests not automatically authenticated with secure communication client authentication always require a password. If set to false, a password is not required if the request comes from a trusted host. This property is optional and its default value is false. For example: 

requirePassword = false
servers

An array of one or more LDAP servers that authenticate principals in this LDAP realm. This array is required, and at least one server is required in the list.

host

String. The LDAP server's host name. This property is optional and its default value is localhost. For example: 

host = "ldap.example.com"
portNumber

Int between 1 and 65535. The LDAP server's portNumber number. This property is optional and its default value is 389. For example: 

portNumber = 390
systemPrincipal

String. The principal used by the authentication system to log in to the LDAP server and query for principal or role information. This property is required. For example: 

systemPrincipal = "cn=SBLDAPUser,cn=Users,dc=ldap,dc=example,dc=com"
systemPassword

String. The password used by the authentication system to log in to the LDAP server. This required property is encryptable as part of the node-level secrecy system described in Encrypting Sensitive Configuration Data. For example: 

password = "secret"
secureCommunicationProfileName

String. Name of a secure communication client profile to use when configuring secure communications with an LDAP server. This property is optional and has no default value.

If present, this profile must be used when setting the ldmSecureInternalCommunicationProfileName property in LiveView Internal Credentials Configuration file or the secureCommunicationProfileName property in LiveView Client API Listener Configuration file.

If not present, LDAP connections do not use secure communication.

For example: 

secureCommunicationProfileName = "my-secure-comm-client-profile"
principalAuthenticationAlgorithm

String. The type of principal authentication to perform. This property is optional and its default value is BIND. Values accepted are:

BIND authenticates principals by connecting to the LDAP server using the principal name and credentials.

LOCAL_PASSWORD_COMPARE authenticates principals by connecting to the LDAP server using the system principal, searching for the user, retrieving its principalPasswordAttribute, and comparing locally with the principal's credentials.

REMOTE_PASSWORD_COMPARE is the same as local except that the comparison is performed at the server.

For example: 

principalAuthenticationAlgorithm = LOCAL_PASSWORD_COMPARE
principalSearchRoots

An array of search root Distinguished Names that are searched for a provided username. This property is required and must contain at least one element. This property is required and must contain at least one element. For example: 

principalSearchRoots = [ "ou=People,dc=example,dc=com" ]
principalSearchFilter

String. A filter applied to each of the principal search roots to help narrow the search, if necessary. The filter is a string in LDAP search format that permits two substitution variables, {0} for the username, and {1} for the user's DN. The default value is CN={0}, which specifies that the CN common name value for the user of interest is the provided username. For example: 

principalSearchFilter = "CN={0}"
principalPasswordAttribute

String. The name of the LDAP user object attribute containing the user's password. This property is optional and its default value is userPassword. Your LDAP server's DIT may specify a different attribute to contain the password. For example: 

principalPasswordAttribute = "password"
roleSearchRoots

An array of search root Distinguished Names that are searched for LDAP group names to be returned for the specified username. If not specified, the user search roots are used instead, which may be appropriate for your LDAP server's DIT configuration. This property is optional and defaults to the value of the principalRoots property. For example: 

roleSearchRoots = [ "ou=groups,dc=example,dc=com" ]
roleSearchFilter

String. A filter applied to each of the role search roots to help narrow the search, if necessary. The string is an LDAP filter expression that permits two substitution variables, {0} for the username, and {1} for the user's DN. The default value is roleOccupant={1}.

For example: 

roleSearchFilter = "membership={1}"
roleNameAttribute

String. The name of an LDAP role DN attribute that contains the group or role identifier used to map to local privileges associated with that role. The default value is CN. For example: 

roleAttribute = "roleID"

Examples, LDAP Authentication Realm

The following is an example of the LDAP realm security configuration subtype. 

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

Open ID Connect Authentication Realm

OpenID Connect (OIDC) is an identity layer on top of the OAuth 2.0 protocol, which allows single sign-on for clients to verify your identity based on the authentication performed by an authorization server. This configuration file also obtains basic profile information about the users in an interoperable and REST-like manner.

The following identity providers are currently supported:

  • Google Identity Platform

  • Auth0

  • Microsoft Azure Active Directory

OIDCAuthenticationRealm

Defines an OIDC authentication realm, which contains settings that configure authentication using OIDC.

name

String. The name of this realm, unique across all authentication realms. This property is required.

For example: 

name = "my-realm"
identityProviders

A map indexed by provider names. Provider names must be URL safe and non-empty. This object is required.

The following properties apply to multiple identity providers except where noted. The provider names below reflect the currently supported ones — Google Identity, Auth0, and Microsoft Azure Active Directory. Note that while each provider uses similar properties, if using Auth0 pay particular attention to the subjectProviderMappings property shown in that example.

Google

Name of the identity provider.

documentDiscoveryURL

String. The identity Provider's Document Discovery URL for obtaining Discovery information. This property is required.

For example: 

documentDiscoveryUrl = "https://accounts.google.com/.well-known/openid-configuration"
clientId

String. The client's authentication ID. This property is required.

For example: 

clientId = "place your client id here"
clientSecret

String. The client's authentication secret key. This required property is encryptable as part of the node-level secrecy system described in Encrypting Sensitive Configuration Data.

For example: 

clientSecret = "place your client secret here"
identityAttributeName

String. The attribute in a given principal's ID Token to be used as the identity for this principal. This property is required.

For example: 

identityAttributeName = "subject email firstName or other claims"
Auth0

Name of the identity provider.

documentDiscoveryURL

String. The identity Provider's Document Discovery URL for obtaining Discovery information. This property is required.

For example: 

https://tibco.auth0.com/.well-known/openid-configuration
clientId

String. The client's authentication ID. This property is required.

For example: 

clientId = "place your client id here"
clientSecret

String. The client's authentication secret key. Any parameter value beginning with #! is enciphered with epadmin encrypt secret command. This property is required.

For example: 

clientSecret = "place your client secret here"
identityAttributeName

String. The attribute in a given principal's ID Token to be used as the identity for this principal. This property is required.

For example: 

identityAttributeName = "subject email firstName or other claims"
subjectProviderMappings

Mappings from Auth0-specific identity provider prefixes to internal identity provider names. Not required for Google or Microsoft identity providers.

Auth0 identity information contains sub claims in the form of sub: google-oauth2|105569619522230371597.

Using | as the delimiter as shown above, google-oauth2 is the prefix that identifies the provider providing the identity information. 105569619522230371597 is the actual subject for the principal from the identity provider represented by google-oauth2.

Note that google-oauth2 is specified below to be interpreted as the Auth0 identifier for the identity provider Google configured above. Also note that, the same principal authenticated directly against Google would have a piece of identity information with sub field being sub: 105569619522230371597.

For example: 

subjectProviderMappings = {
  "google-oauth2" = "Google"
}
Microsoft

Name of the identity provider.

documentDiscoveryURL

String. The identity Provider's Document Discovery URL for obtaining Discovery information. This property is required.

Microsoft Azure Active Directory requires a tenant name in the URL. To determine your tenant name, log into https://login.microsoftonline.com/ and look for Domain on the web page after toggling your account name there.

For example: 

https://login.microsoftonline.com/tenant/.well-known/openid-configuration
clientId

String. The client's authentication ID. This property is required.

For example: 

clientId = "place your client id here"
clientSecret

String. The client's authentication secret key. Any parameter value beginning with #! is enciphered with epadmin encrypt secret command. This property is required.

For example: 

clientSecret = "place your client secret here"
identityAttributeName

String. The attribute in a given principal's ID Token to be used as the identity for this principal. This property is required.

For example: 

identityAttributeName = "subject email firstName or other claims"
pendingAuthenticationTimeoutSeconds

Int. The amount of time that the OIDC client will wait for a provider's response before timing out. This property is optional and its default value is 300 seconds.

For example: 

pendingAuthenticationTimeoutSeconds = 600
fallbackAuthenticationRealmName

String. A reference to a realm for handling non-REST and non-web authentications and all authorizations. This property is required.

For example: 

fallbackAuthenticationRealmName = "my-local-or-ldap-realm"
requireTrustedHostMembership

Bool. If set to true, all incoming requests authenticated by this realm are rejected unless they come from a trusted host. This property is optional and its default value is false.

For example: 

requireTrustedHostMembership = false
defaultRedirectURL

The address to redirect a user to after authentication, if no redirect URL was provided with the authentication request. This property is optional and its default value is null.

For example: 

defaultRedirectUrl = "www.example.com"

Example, OIDC Authentication Realm

The following OIDC Authentication Realm configuration file contains configurations for Google, Auth0, and Microsoft. 

name = "oidc-realm1"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  OIDCAuthenticationRealm = {
    name = "my-realm"
    identityProviders = {
      "Google" = {
        documentDiscoveryURL = "https://accounts.google.com/.well-known/openid-configuration"
        clientId = "place your client id here"
        clientSecret = "place your client secret here"
        identityAttributeName = "subject email firstName or other claims"
      }
      "Auth0" = {        
        documentDiscoveryURL = "https://tibco.auth0.com/.well-known/openid-configuration"
        clientId = "place your client id here"
        clientSecret = "place your client secret here"
        identityAttributeName = "subject email firstName or other claims"
        subjectProviderMappings = {
          "google-oauth2" = "Google"
          }
      }
      "Microsoft" = {        
        documentDiscoveryURL = "https://login.microsoftonline.com/tenant.well-known/
          openid-configuration"
        clientId = "place your client id here"
        clientSecret = "place your client secret here"
        identityAttributeName = "subject email firstName or other claims"
      }
    pendingAuthenticationTimeoutSeconds = 600
    fallbackAuthenticationRealmName = "my-local-or-ldap-realm"
    requireTrustedHostMembership = false
    defaultRedirectURL = "http://url1.tibco.com"
  }
}

Kerberos Authentication Realm

Kerberos is a network authentication protocol for client-server applications, and SPNEGO provides a mechanism for extending Kerberos to web applications through the HTTP protocol. LiveView can be enabled for Kerberos to verify the identity of clients (authentication) and ensure that authenticated clients have permission to access the requested resources on the LiveView server side (authorization). See LiveView Authentication and Authorization for Kerberos.

KerberosAuthenticationRealm

A Kerberos authentication realm contains the configuration required for a LiveView node and its engines to authenticate users with Kerberos.

name

String. Realm name, which must be unique across all authentication realms. This property is required.

For example: 

name = "my-realm"
requireTrustedHostMembership

Bool. If set to true, all incoming requests authenticated by this realm are rejected unless they come from a trusted host. This property is optional and its default value is false.

For example:

fallbackAuthenticationRealmName

String. Kerberos realms perform SPNEGO authentication only. This property specifies the name of the (must be LDAP or local authentication) realm used for non-SPNEGO authentication and for all authorization. This property is required and must match the name defined in the corresponding realm.

For example: 

fallbackAuthenticationRealmName = "sample-fallback-realm-name"
kerberosConfigurationFile

String. The location of the Kerberos system configuration file, specifying among other things the location of the KDC. This property is required and must contain an absolute file path.

Examples: 

linux_x86_64 = "/a/kerberos/config/file"
osx_x86_64 = "/a/kerberos/config/file"
windows_x86_64 = "c:\\a\\kerberos\\config\\file"
serverKeytabFile

String. The server Kerberos keytab file name, used for principal login without kinit. This property is required and must contain an absolute file path.

Examples: 

linux_x86_64 = "/a/keytab/file"
osx_x86_64 = "/a/keytab/file"
windows_x86_64 = "c:\\a\\keytab/file"
serverPrincipalName

String. The server Kerberos principal name, as it is known to the KDC specified in the Kerberos system configuration file. This property is required.

For example: 

serverPrincipalName = "HTTP/my.host.com@example.com"
ticketCacheFile

String. The location of a Kerberos ticket cache file. This property is optional and has no default value. If not specified, then the value of the system environment variable KRB5CCNAME is used. If that is not specified, then a system default location is used. If used, it must contain an absolute file path.

For example: 

ticketCacheFileName = "/a/ticket/cache/file"
jaasDebug

Bool. The JAAS debugging status. Set to true to enable JAAS debug logging, false to disable. This property is optional and its default value is false.

For example: 

jaasDebug = false
internalClientKeytabFile

String. The internal client Kerberos keytab file name, used for internal client login without kinit. This property is optional and has no default value. If no file is specified, the server keytab file is used. If specified, it must contain an absolute file path.

For example: 

internalClientKeytabFile = "/another/keytab/file"
internalClientPrincipalName

String. The internal client Kerberos principal name, as it is known to the KDC specified in the Kerberos system configuration file. This property is optional and has no default value. If not specified, then an internal client JAAS login configuration file containing a principal name must be specified.

For example: 

internalClientPrincipalName = "myprincipal@example.com"
internalClientPrincipalName

String. The internal client Kerberos principal name, as it is known to the KDC specified in the Kerberos system configuration file. This property is optional and has no default value. If not specified, then an internal client JAAS login configuration file containing a principal name must be specified.

internalClientLoginConfigurationFile

String. The JAAS login configuration file that configures internal client use of Kerberos. This property is optional and has no default value. If no file is specified, then an internal client principal name must be specified, and the realm will generate a login file using that principal and either the client keytab file, or the server keytab file if no client keytab file is specified. If specified, it must contain an absolute file path.

Examples, Kerberos Authentication Realm

The following is an example of the Kerberos authentication realm security configuration subtype. 

name = "kerbrealm1"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  KerberosAuthenticationRealm = {
    name = "my-realm"
    requireTrustedHostMembership = false
    fallbackAuthenticationRealmName = "my-ldap-realm"
    kerberosConfigurationFileName = "/a/kerberos/config/file"
    serverKeytabFileName = "/a/keytab/file"
    serverPrincipalName = "HTTP/my.host.com@example.COM"
    ticketCacheFileName = "/a/ticket/cache/file"
    jaasDebug = false
    internalClientKeytabFileName = "/another/keytab/file"
    internalClientPrincipalName = "myprincipal@example.COM"
  }
}

PrivilegeSettingsGroup

PrivilegeSettingsGroup

A privilege settings group is an associative array of privilege settings objects, indexed by name. Privilege settings groups allow a security role to include any number of named privilege settings. Privilege settings can include other settings, allowing greater flexibility and reuse in role-to-privilege mappings.

privilegeSettings

An associative array of privilege settings objects, indexed by name. Privilege settings object names containing dots must be surrounded with double quotes. This object is required.

For example: 

privilegeSettings = {
streambase-privileges

Example name. A security privilege settings object contains a set of privileges as well as inclusions of other privileges by settings name.

For example: 

sample-privilege-streambase = {
includes

A list of zero or more privilege settings objects included by this privilege settings object. All privileges in the included setting(s) (and their included settings, and so on) become part of this privilege settings object. Multiple and nested inclusions are processed depth-first. This object is optional and has no default value.

For example: 

includes = [ "my-referenced-privilege-settings" ]
privileges

A list of this settings object's privilege types and their optional associated resources. Each privilege describes what you can do, and what you can do it to. This object is optional and has no default value.

For example: 

privileges = [
privilege

Name of a privilege. Some privileges are EventFlow-specific, some are LiveView- or LiveView Web client-specific, and some are StreamBase Runtime administrator-specific. This property is required. See this section for a complete list of available privileges.

resource

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

For example: 

resource = "default.InputStream1"

PrivilegeSettingsGroup Example

The following is a general sample PrivilegeSettingsGroup configuration file. Each privilege has an associated resource; a privilege defines what you can do, and its associated resource defines what you can do it to. 

name = "PrivilegeSettingsGroup"
type = "com.tibco.ep.dtm.configuration.security"
version = "1.0.0"
configuration = {
PrivilegeSettingsGroup = {
  privilegeSettings = {
    streambase-privileges = {
      includes = [ "liveview-privileges" ]
      privileges = [ 
        {
          privilege = "APIConnect"
          resource = "sample-resource-name"
        }
      ]
     }
   }
  }
}

Role to Privilege Mappings

RoleToPrivilegeMappings

A description of privileges associated with roles, in the form of list of privilege-resource pairs for each defined role. Each privilege can have an associated resource; a privilege defines what you can do, and its associated resource defines what you can do it to.

As of 10.6.0, a role-to-privilege mapping can include a privilege settings defined in a PrivilegeSettingsGroup root object, allowing greater flexibility and reuse.

A privilege without a matching resource setting applies to all resources of the appropriate type. For example, a privilege setting that pertains to LiveView tables applies to all LiveView tables on the LiveView server unless individual tables are listed as resources.

A RoleToPrivilegeMappings configuration must accompany an LDAP authentication realm configuration, when an LDAP realm is specified. In that case, the defined roles must exactly match the LDAP group names in your LDAP database in spelling and case, except that spaces in LDAP group names (such as Engineering Support) must be escaped with a backslash (Engineering\ Support).

includes

A list of zero or more privilege settings groups included by this privilege settings object. All privileges in the included setting(s) (and their included settings, and so on) become part of this privilege settings object. Multiple and nested inclusions are processed depth-first. This object is optional and has no default value.

For example: 

includes = [ "streambase-privileges", "liveview-privileges" ]
privileges

An associative array of role-to-privilege mappings for EventFlow and LiveView engines. This property is optional and has no default value.

LVUser

String. Role name example.

privilege

Name of a privilege. Some privileges are EventFlow-specific, some are LiveView- or LiveView Web client-specific, and some are StreamBase Runtime administrator-specific. This property is required.

In the example below, the description column maps HOCON-configured privileges to their StreamBase 7 equivalents, where applicable.

Privileges can be one or more of the following:

Privilege Description
StreamBase Runtime privileges
AdminRunCommand StreamBase Runtime epadmin command privileges
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 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
LiveViewAlertActionOSCommand Maps to the LiveView alertaction:oscmd privilege
LiveViewAlertActionLVPublish Maps to the LiveView alertaction:publish privilege
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 named __CronAlertsOnly filters cron-based alert rules. For example, for a role named 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. See Setting Row Level Security for LiveView Tables for configuration details.
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; take care in assigning them to appropriate users. It is a best practice assigning these privileges only to an administrator. Users with LiveViewMetadataExport privileges can view all alert, workspace, and other 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.

resource

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

For example: 

resource = "default.InputStream1"
LVUser

String. LiveView engine example role name.

privilege

The privilege type that maps to the role. This property is required.

The example below shows a LiveView user role, LVAdmin, with all LiveView privileges. 

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 LiveView 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 LiveView user role, LVUser, assigned LiveView engine- and LiveView Web client-specific 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 LiveView user role, LVGuest, assigned LiveView engine-specific 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"
  }
 ]

Example, Role to Privileges Mappings

The following is a general sample RoleToPrivilegeMappings configuration file. Each privilege has an associated resource; a privilege defines what you can do, and its associated resource defines what you can do it to. 

name = "my-role-mappings"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  RoleToPrivilegeMappings = {
    roles = {
        admin = {
    privileges = [
        {
          privilege = "AdminRunCommand"
        }
  ]
  }
        streamBaseSuperuser = {
    privileges = [
        { 
          privilege = "StreamEnqueue"
          resource = "default.InputStream1"
        }
    ]
    }
        basicUser = {
    privileges = [
        {
          privilege = "StreamEnqueue"
          resource = "default.InputStream1"
        },
        {
          privilege = "StreamDequeue"
          resource = "default.OutputStream1"
        }
        ]
   }      
   }
    }
  }

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

name = "my-RoleToPrivilegeMappings"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  RoleToPrivilegeMappings = {
    roles = {
      AdministratorSpecificCommands = {
    privileges = [
    
        {
          privilege = "AdminRunCommand"
          resource = "breakpointplugin::Plugin::continueCommand"
        },
        {
          privilege = "AdminRunCommand"
          resource = "security::SecurityPlugin::display"
        }
      ]
    }
      StreamBaseSuperuser = {
     privileges = [
        { 
          privilege = "StreamEnqueue"
          resource = "default.InputStream1"
        }
      ]
    }
      StreamBaseBasicUser = {
     privileges = [
        {
          privilege = "StreamEnqueue"
          resource = "default.InputStream1"
        },
        {
          privilege = "StreamDequeue"
          resource = "default.OutputStream1"
        }
      ]
    }
      AnotherAdminUser = {
    privileges = [
        {
          privilege = "StreamEnqueue"
          resource = "default.InputStream1"
        },
        {
          privilege = "APIConnect"
        }
      ] }
    
      LDMUserAll = {
    privileges = [
        {
          privilege = "LiveViewAlertAll"
          resource = "alertName1"
        },
        {
          privilege = "LiveViewTupleAll"
          resource = "mySchema1"
        },
        {
          privilege = "LiveViewTableAll"
          resource = "myTable1"
        },
        {
          privilege = "LiveViewAlertActionAll"
          resource = "alertName2"
        },
        {
          privilege = "LiveViewWorkspaceAll"
          resource = "wsName1"
        }
      ]
    }
    
      LDMUserAll2 = {
    privileges = [
        {
          privilege = "LiveViewAll"
        }
      ]
    }
    
      LDMUserEach = {
    privileges = [
        {
          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 LiveView and LiveView Web configuration. 

name = "my-role-mappings"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  RoleToPrivilegeMappings = {
    roles = {
      LVAdmin = {
    privileges = [
        {
          privilege = "LiveViewAll"
        }
      ]
    }
      LVInternal = {
    privileges = [
        {
          privilege = "APIConnect"
        },
        {
          privilege = "LiveViewShutdown"
        },
        {
          privilege = "LiveViewTableQuery"
        },
        {
          privilege = "LiveViewTablePublish"
          resource = "LVAlerts"
        },
        {
          privilege = "LiveViewTableDelete"
          resource = "ItemsSales"
        },
        {
          privilege = "LiveViewTableManage"
        },
        {
          privilege = "LiveViewWorkspaceAll"
        }
      ]
    }
      LVUser = {
    privileges = [
        {
          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 = {
    privileges = [
        {
          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 is a role to privileges mapping that includes two parameter settings groups, streambase-privilege-settings and liveview-privilege-settings: 

name = "my-RoleToPrivilegeMappings"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  RoleToPrivilegeMappings = {
    roles = {
      AdministratorSpecificCommands = {
        privileges = [
          {
            privilege = "AdminRunCommand"
            resource = "breakpointplugin::Plugin::continueCommand"
          },
          {
            privilege = "AdminRunCommand"
            resource = "security::SecurityPlugin::display"
          }
        ]
        includes = [ "streambase-privilege-settings" ]
      }
      StreamBaseSuperuser = {
        privileges = [
          { 
            privilege = "StreamEnqueue"
            resource = "default.InputStream1"
          }
        ]
        includes = [ "liveview-privilege-settings" ]
      }
    }
  }
}

Secure Communication Client Profile

Each profile has a unique name across all server and client profile types. The name serves as a reference target from other configurations wishing to enable secure communication.

The client profile is for INTERNAL client connections, that is from the server to the server. If you enable SSL on a LiveView server, or for an EventFlow application using the Diameter Client and Server input adapters, you need both SecureCommunicationClientProfile and the SecureCommunicationServerProfiles configured. This is due to the server and client certificates having different attributes, and certificate authorities do not issue a single certificate appropriate for both client and server use.

SecureCommunicationClientProfile

A secure communication profile configuration object contains settings used to secure client-side transport connections, for example to external services such as LDAP. Profiles are named, and then referenced as needed by other configurations needing secure communication.

name

The name of this profile, unique across all secure communication profiles. This property is required. For example: 

name = "TLSclient"
keyStore

Absolute, full path to the keystore that contains key materials as well as optional trust store information, depending on keystore format. This property must point to a file. If the keystore contains multiple private key entries (or aliases in JKS parlance), the first is used. The path is required to be absolute, therefore the file must exist on the target node's file system. This property is optional. If present, engines acting as clients can establish secure connections to services and perform client (mutual) authentication.

Examples: 

linux_x86_64 = "/a/keyStore.jks"
osx_x86_64 = "/a/keyStore.jks"
windows_x86_64 = "c:\\a\\keyStore.jks"
keyStorePassword

String. Keystore password, used to access the keystore contents. This required property is encryptable as part of the node-level secrecy system described in Encrypting Sensitive Configuration Data.

For example: 

keyStorePassword = "sample-key-store-password"
keyPassword

String. The password to access the key within the keystore. This optional property is encryptable as part of the node-level secrecy system described in Encrypting Sensitive Configuration Data. If absent, the keystore password is used to access the property.

For example: 

keyPassword = "anothersecret"
keyStoreType

Keystore type. This property is optional and its default value is jks. For example: 

keyStoreType = "jks"
trustStore

Trust store containing CAs by which client certificates must be signed to be trusted. If specified, this must be a file. The path is required to be absolute, therefore the file must exist on the target node's file system. This property is optional. If you do not specify a trust store, the default JRE default CA cert store is used instead (for example, in $STREAMBASE_HOME/jdk/jre/).

Examples: 

linux_x86_64 = "/a/trustStore.jks"
osx_x86_64 = "/a/trustStore.jks"
windows_x86_64 = "c:\\a\\trustStore.jks"
trustStorePassword

The password to access the trust store. This optional property is encryptable as part of the node-level secrecy system described in Encrypting Sensitive Configuration Data.

For example: 

trustStorePassword = "sample-trust-store-password"
trustStoreType

Trust store type. This property is optional and its default value is jks.

For example: 

trustStoreType = "jks"
requireClientAuthentication

Bool. Enable or disable required client authentication. Enabling requires presence of a keystore to sign the client side of the secure communication handshake. This property is optional, and its default value is false. If its value is true, both a keystore and keystore password are required.

For example: 

requireClientAuthentication = true
includedCipherSuites

A list of cipher suites specifically allowed by this configuration. This array is optional and if not present defaults to the JRE's full set of supported cipher suites. Exclusive with excludedCipherSuitePatterns.

For example: 

includedCipherSuites = "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
excludedCipherSuitePatterns

String. A list of Java regular expression patterns for cipher suites specifically excluded by this configuration. This array is optional and has no default value. A missing or empty array allows all cipher suites either explicitly included by this configuration or provided by the JRE. Exclusive with includedCipherSuites. If no excluded patterns are provided, and no included cipher suites are provided either, then a default set of excluded patterns is used that prevents cipher suites with known security flaws from being considered during negotiation.

For example: 

excludedCipherSuitePatterns = [ "^.*_(MD5|SHA|SHA1)$" ]

Default: 

excludedCipherSuitePatterns = [ "^SSL_.*$","^.*DH_.*$","^.*KRB5.*$","^.
  *NULL.*$","^.*anon.*$","^.*DES.*$","^.*MD5$","^.*DSS.*$","^TLS_RSA(?:
  (?!_WITH_AES_128_CBC_SHA).)*$"]
includedProtocols

A list of handshake protocols specifically allowed by this configuration. This array is optional and if not present defaults to the list shown in the example below. It is a best practice using TLS 1.1 or above. Exclusive with excludedProtocolPatterns.

For example: 

includedProtocols = [ "TLSv1.1", "TLSv1.2" ]
excludedProtocolPatterns

This property is deprecated.

A list of Java regular expression patterns for handshake protocols specifically excluded by this configuration. This array is optional and has no default value. A missing or empty array allows all protocols either explicitly included by this configuration or provided by the JRE. Exclusive with includedProtocols.

Examples, Secure Communication Client Profile

The following is a sample that configures a secure communication profile for a client endpoint. A secure communication profile configuration object contains settings used to secure client-side transport connections (for example, to external services such as LDAP). Profiles are named and then referenced as needed by other configurations needing secure communication. 

name = "mycommunicationsettings"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  SecureCommunicationClientProfile = {
    name = "TLSclient"
    keyStore = "/absolute/path/myKeyStore.jks"
    keyStorePassword = "secret"
    keyPassword = "anothersecret"
    keyStoreType = "JKS"
    trustStore = "/absolute/path/myTrustStore.jks"
    trustStorePassword = "athirdsecret"
    trustStoreType = "JKS"
    requireClientAuthentication = true
  }
}

Secure Communication Server Profile

Each profile has a unique name across all server and client profile types. The name serves as a reference target from other configurations wishing to enable secure communication.

This profile is for the LiveView API listener. For SSL with client certificate authentication, the profile contains a trust store used to validate incoming server certificates. Also, if you enable SSL on a LiveView server, you need both the Secure Communication Client Profile and the Secure Communication Server Profiles configured. This is due to the server and client certificates having different attributes, and certificate authorities do not issue a single certificate appropriate for both client and server use.

This profile is also used to configure secure communications for the node's administration, distribution, node-to-node connections, and REST API listeners.

SecureCommunicationServerProfile

A secure communication profile configuration object contains settings used to secure server-side transport connections, for example from EventFlow and LiveView API clients. Profiles are named, and then referenced as needed by other configurations needing secure communication.

name

String. The name of this profile, unique across all secure communication profiles. This property is required. For example: 

name = "TLSserver"
keyStore

String. File path to a keystore that contains the server's certificate as well as optional trust store information, depending on keystore format. If the keystore contains multiple private key entries (aliases in JKS parlance), the first is used. The path is required to be absolute; therefore, the file must exist on the target node's file system. This property is required.

These store encoding types are supported on nodes and can be specified in secure communication profiles:

  • all Java key and trust store types, for example Java Key Store (JKS) and Java Cryptography Extension Key Store (JCEKS). Actual supported types are dependent on the installed JRE being used by a node.

  • Public-Key Cryptography Standards #12 (PKCS12).

For example: 

keyStore = {
  linux_x86_64 = "/a/keyStore.jks"
  osx_x86_64 = "/a/keyStore.jks"
  windows_x86_64 = "c:\\a\\keyStore.jks"
  }
keyStorePassword

String. Keystore password, used to access the keystore contents. This required property is encryptable as part of the node-level secrecy system described in Encrypting Sensitive Configuration Data.

For example: 

keyStorePassword = "sample-key-store-password"
keyPassword

String. The password to access the key within the keystore. This optional property is encryptable as part of the node-level secrecy system described in Encrypting Sensitive Configuration Data. If absent, the keystore password is used to access the property.

For example: 

keyPassword = "anothersecret"
keyStoreType

Keystore type. This property is optional and its default value is jks. For example: 

keyStoreType = "jks"
trustStore

Trust store containing CAs by which client certificates must be signed to be trusted. If specified, this must be a file. The path must be absolute, therefore the file must exist on the target node's file system. This property is optional. If you do not specify a trust store, the default JRE default CA cert store is used instead (for example, in $STREAMBASE_HOME/jdk/jre/).

These store encoding types are supported on nodes and can be specified in secure communication profiles:

  • all Java key and trust store types, for example Java Key Store (JKS) and Java Cryptography Extension Key Store (JCEKS). Actual supported types are dependent on the installed JRE being used by a node.

  • Public-Key Cryptography Standards #12 (PKCS12).

For example: 

trustStore = {
  linux_x86_64 = "/a/trustStore.jks"
  osx_x86_64 = "/a/trustStore.jks"
  windows_x86_64 = "c:\\a\\trustStore.jks"
  }
trustStorePassword

String. The password to access the trust store. This optional property is encryptable as part of the node-level secrecy system described in Encrypting Sensitive Configuration Data.

For example: 

trustStorePassword = "sample-trust-store-password"
trustStoreType

String. Trust store type. This property is optional and its default value is jks.

For example: 

trustStoreType = "jks"
requireClientAuthentication

Bool. Enable or disable required client authentication. Enabling requires presence of a trust store to verify client trust. This property is optional, and its default value is false. If its value is true, both a keystore and keystore password are required.

For example: 

requireClientAuthentication = true
includedCipherSuites

A list of cipher suites specifically allowed by this configuration. This array is optional and if not present defaults to the JRE's full set of supported cipher suites. Exclusive with excludedCipherSuitePatterns.

For example: 

includedCipherSuites = ["TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"]
excludedCipherSuitePatterns

String. A list of Java regular expression patterns for cipher suites specifically excluded by this configuration. This array is optional and has no default value. A missing or empty array allows all cipher suites either explicitly included by this configuration or provided by the JRE. Exclusive with includedCipherSuites. If no excluded patterns are provided, and no included cipher suites are provided either, then a default set of excluded patterns is used that prevents cipher suites with known security flaws from being considered during negotiation.

For example: 

excludedCipherSuitePatterns = [ "^.*_(MD5|SHA|SHA1)$" ]

Default: 

excludedCipherSuitePatterns = [ "^SSL_.*$","^.*DH_.*$","^.*KRB5.*$","^.
  *NULL.*$","^.*anon.*$","^.*DES.*$","^.*MD5$","^.*DSS.*$","^TLS_RSA(?:
  (?!_WITH_AES_128_CBC_SHA).)*$"]

If you installed the Elliptic Curve Cryptography suites (ECC), you can exclude the non-PFS RSA suites as it is a best practice. In the example below, the line wraps to the next for clarity. 

excludedCipherSuitePatterns = [ "^SSL_.*$","^.*DH_.*$","^.*KRB5.*$","^.
*NULL.*$","^.*anon.*$","^.*DES.*$","^.*MD5$","^.*DSS.*$","^TLS_RSA.*$"]
includedProtocols

A list of handshake protocols specifically allowed by this configuration. This array is optional and if not present defaults to the list shown in the example below. It is a best practice using TLS 1.1 or above. Exclusive with excludedProtocolPatterns.

For example: 

includedProtocols = [ "TLSv1.1", "TLSv1.2" ]
excludedProtocolPatterns

This property is deprecated.

A list of Java regular expression patterns for handshake protocols specifically excluded by this configuration. This array is optional and has no default value. A missing or empty array allows all protocols either explicitly included by this configuration or provided by the JRE. Exclusive with includedProtocols.

userNameObjectIdentifierSearchPath

An array of attribute keywords or X.509 object identifiers (OIDs), indicating the order in which the client's X.509 certificate subject Distinguished Name attributes are searched for to find a user name for authorization purposes. This property is only relevant if requireClientAuthentication is enabled. Supported attribute keywords are userID, CN, emailAddress, and DN. This property is optional and its default value is the search order emailAddress, CN, DN.

For example: 

userNameObjectIdentifierSearchPath = [ "userID", "CN", "1.2.3.4", "DN" ]
subjectNameElementToUserNameMappings

An object whose values are certificate-based principal names and whose values are authorization user names. Used in cases where an incoming client certificate is used for authentication, but none of the elements of its subject name are suitable for mapping to roles during authorization. This object is optional; if not present, then no mapping can be performed, and a subject name element extracted with the userNameObjectIdentifierSearchPath must yield a valid user name for authorization purposes.

For example: 

subjectNameElementToUserNameMappings = {
  "subjectNameElementFoo" = "userNameFoo"
  "subjectNameElementBar" = "userNameBar" 
}

Examples, Secure Communication Server Profile

The following sample configures a secure communication profile for a server endpoint. A secure communication profile configuration object contains settings used to secure server-side transport connections (for example, from EventFlow and LiveView API clients). Profiles are named and then referenced as needed by other configurations needing secure communication. 

name = "mycommunicationsettings"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  SecureCommunicationServerProfile = {
    name = "TLSserver"
    keyStore = "/absolute/path/myKeyStore.jks"
    keyStorePassword = "secret"
    keyPassword = "anothersecret"
    keyStoreType = "JKS"
    trustStore = "/absolute/path/myTrustStore.jks"
    trustStorePassword = "athirdsecret"
    trustStoreType = "JKS"
    requireClientAuthentication = true
    userNameObjectIdentifierSearchPath = [ "userID", "CN", "1.2.3.4", "DN" ]
    subjectNameElementToUserNameMappings = {
      "subjectNameElementFoo" = "userNameFoo"
      "subjectNameElementBar" = "userNameBar" 
    } 
  }
}

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 with 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, then the StreamBase Runtime trusts that the host-based authentication mechanism (such as a Linux login) has verified the identity of the principal. See Trusted Hosts for more on the Trusted Hosts feature.

TrustedHosts

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

hosts

String. A comma-separated list of host names and/or IP addresses from which users do not need to authenticate when running administrative commands. The array supports simple host names, fully qualified domain names, partially qualified domain names, IPv4 single addresses, IPv6 single addresses, and CIDR blocks of IPv4 addresses.

Parameter value strings that contain a period must be quoted. This includes domain name and IP address strings.

Example, Trusted Hosts

The following is a sample Trusted Hosts configuration file. 

name = "trustedhosts"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  TrustedHosts = {
    hosts = [
      "able",
      "baker",
      "*.dept.example.com",
      "charlie.example.com",
      "192.0.2.42",
      "198.51.100.0/24",
      "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
    ]
  }
}

The above example configuration defines these trusted hosts:

  • able, baker — simple host names.

  • *.dept.example.com — a partially qualified domain name, which are indicated using the *. prefix. All hosts under the dept.example.com domain are trusted.

  • charlie.example.com — a fully qualified domain name.

  • 192.0.2.42 — an IPv4 address.

  • 198.51.100.0/24 — an IPv4 CIDR block

  • 2001:0db8:85a3:0000:0000:8a2e:0370:7334 — an IPv6 address.

Deprecated Security Features

The following security properties are deprecated but are still supported for backward compatibility:

com.tibco.ep.dtm.configuration.LocalAuthenticationRealm.securityprincipals

The initialPrincipals property replaces the deprecated principals property in the Local Authentication Realm.

Local Admin Authentication Realm

The entire realm configuration is deprecated. Use the local authentication realm instead.

com.tibco.ep.dtm.configuration.security.SecureCommunicationClientProfile.excludedProtocolPatterns

This property is deprecated. Use com.tibco.ep.dtm.configuration.security.SecureCommunicationClientProfile.includedProtocols.

com.tibco.ep.dtm.configuration.security.SecureCommunicationServerProfile.excludedProtocolPatterns

This property is deprecated. Use com.tibco.ep.dtm.configuration.security.SecureCommunicationServerProfile.includedProtocols.

com.tibco.ep.dtm.configuration.security.RoleToPrivilegeMappings.privileges

This property is deprecated. Use com.tibco.ep.dtm.configuration.security.RoleToPrivilegeMappings.roles.

Local Admin Authentication Realm (Deprecated)

This realm is deprecated but still supported for backward compatibility. Instead, use a local authentication realm.

This authentication realm applies to epadmin command users performing such operations as starting and stopping a StreamBase Runtime node. If you do not have admin users in your configuration, the local admin authentication realm is not required.

LocalAdminAuthenticationRealm

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

principals

An array of administrator principals. This property is optional and has no default value.

userName

The principal name. This property is required and cannot be an empty string.

For example: 

userName = "JohnDoe"
hashedPassword

Principal's password, either in clear text or enciphered. This required property is encryptable as part of the node-level secrecy system described in Encrypting Sensitive Configuration Data.

For example: 

Password = "M5DSWylszg5aA9AK29MOiaDLq7SMqmTor+nW3qURTrT9E9eqJfT
  PyyUudCK34nhXHE53PXK6pregp4MW8qrueg"
roles

Roles to which the principal has access, if any. Each role is an arbitrary text string, which can be bound to various privileges in a role-to-privileges mapping object. This key is required, and at least one list member is required.

For example: 

roles = [ "BasicUser"
          "StreamBaseSuperuser"
          "admin" ]
passwordExpirationPeriodDays

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

For example: 

passwordExpirationPeriodDays = 12
passwordAlwaysRequired

Sets 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 property 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

Examples, Local Admin Authentication Realm

The following is a sample local admin authentication realm configuration for epadmin users. 

name = "localadminrealm1"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  LocalAdminAuthenticationRealm = {
    principals = [
      {
        userName = "SBuser"
        hashedPassword = "LKJALISJDOIQUWEOIAJSLKDJALSJDL"
        roles = [
          "BasicUser"
          "StreamBaseSuperuser"
          "admin"
        ]
        passwordExpirationPeriodDays = 12
        passwordAlwaysRequired = true
        trustedHostAccessOnly = false
      }
    ]
  }
}