When you install a Streaming node, a default node administration realm is created. The default realm name is 'default-realm'. The OS-level user who installed the node is automatically granted administrative access.

However, this can present a security risk, as node administration commands can be run on that machine without the need to supply any credentials (so long as the currently logged-in user is the same user who installed the node).

To increase node security, you may replace the default node administration realm with an LDAP authentication realm. This allows you to grant node administration privileges to existing LDAP users in your company.

First, identify the LDAP group to be used for the node administration role. The default node administration role is named 'administrator', but groups in your company LDAP system need to be manually mapped to node administration privileges. This is done by adding a role-mappings HOCON configuration to your project under src/main/configurations/. For example:
 

name = "roleMappings"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  RoleToPrivilegeMappings = {
    privileges = {
      readers = [
        {
          privilege = "AdminRunCommand"
        } 
        {
          privilege = "APIConnect"
        }
      ]
    }
  }
}

In the above example, the LDAP group named 'readers' is mapped to the 'AdminRunCommand' and 'APIConnect' node administration privileges. This means that any LDAP users who are a member of the 'readers' group will become node administrators.

Next, create an LDAP authentication HOCON configuration (again, under src/main/configurations/) to define your company LDAP parameters. For example:
 

name = "LDAPAuthRealm"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration = {
  LDAPAuthenticationRealm = {
    name = "LDAPAuthRealm"
    servers = [             
      {
        host = "localhost"
        portNumber = 1389
        principalSearchFilter = "cn={0}"
        principalSearchRoots = [ "dc=example,dc=org" ]                
        roleSearchRoots = [ "dc=example,dc=org" ]
        roleSearchFilter = "member={1}"                
        systemPassword = "adminpassword"
        systemPrincipal = "cn=admin,dc=example,dc=org"
      }
    ]
  }
}

Note: The configuration examples shown above are known to work with the Bitnami openldap image from Docker Hub. TIBCO takes no position about the suitability of the Bitnami openldap image for use in any application or infrastructure; it is used here solely as an example of an LDAP server that is convenient for the purposes of this article. It may be run on your local machine with command:
 

$ docker run -p 1389:1389 --name openldap --detach bitnami/openldap:latest

To determine the correct settings for your company LDAP HOCON configuration, refer to our Knowledge article entitled "Configuring a TIBCO Streaming LDAPAuthenticationRealm".

Next, install and start the Streaming node. At this time, you may replace the default-realm with the LDAP authentication realm you defined earlier. This is done using the epadmin setadmin realm command. For example:
 

$ epadmin --servicename nodeA.clusterA setadmin realm --name LDAPAuthRealm --newrealmusername user01 --newrealmpassword bitnami1

..where 'user01' is an existing LDAP user who is a member of the 'readers' LDAP group, as noted above.

Finally, confirm that the realm replacement was successful by running the epadmin getadmin realm command.

First, try the command without providing a username and password:
 

$ epadmin --servicename nodeA.clusterA getadmin realm
[nodeA.clusterA] Failed to open a connection to the node YourMachineName:56961. Reason: Authentication of user [YourOSUsername] failed: authentication failed

This confirms that the default node administration realm is no longer active, since the OS-level user ('YourOSUsername') does not have admin privileges now (and the command fails).

Now try running the same command, but specify your LDAP user credentials:
 

$ epadmin --username user01 --password bitnami1 --servicename nodeA.clusterA getadmin realm
[nodeA.clusterA] Realm Name = LDAPAuthRealm

In this case, the command is executed successfully because 'user01' is now a node administrator.

For increased security, you can optionally remove the --password and --newrealmpassword parameters to prevent the password from being written to the console in plain text. For example:
 

$ epadmin --username user01 --servicename nodeA.clusterA getadmin realm
Node Administrator Password: (enter 'bitnami1' here)
[nodeA.clusterA] Realm Name = LDAPAuthRealm

This article outlines the steps needed to replace the default node administration realm with a custom LDAP authentication realm. This allows users to perform node administration tasks using their company LDAP credentials, which prevents the need to manage an additional set of usernames and passwords.