Reference for LDAP Authentication Realm Configuration

Overview

This article provides a reference for writing an ldapauthrealm HOCON configuration file.

The LDAP realm configuration defines a redundant set of LDAP servers used to authenticate StreamBase or Live Datamart users and check the roles to which those users belong. It is separate from the base engine configuration and can therefore be managed separately without having to recreate an application archive and redeploy the application.

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 = "ldaprealm1"
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.streambase.configuration.ldapauthrealm"

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.

LDAPAuthenticationRealm

A class describing a set of LDAP servers used to authenticate principals.

connectorFactoryClassName

String. An LDAP connector factory class name used to talk to servers in this realm. This class overrides the default connector factory class and is for advanced users only. This name-value pair is optional and has no default value.

For example:

connectorFactoryClassName = "com.mycompany.mylocation"
transformPrincipal

A descriptor containing information used to transform principals in this realm's LDAP servers into StreamBase authentication principals. This name-value pair is optional and has no default value.

searchRegexp

String. A search expression that matches on a pattern in a name-value pair in an LDAP database. This name-value pair is required.

For example:

searchRegexp = "xyz"
replaceRegexp

String. A replacement pattern for matches found by the search pattern. This name-value pair is required.

For example:

replaceRegexp = "abc"
serverConnectAlgorithm

When multiple LDAP servers are specified in this realm, this name-value pair defines the order in which the servers are connected for authentication. To authenticate in a round robin (the default) fashion specify round-robin. To authenticate against LDAP servers until the first successfully authentication request specify first-hit.

This name-value pair is optional and its default value is first-hit.

For example:

serverConnectAlgorithm = "round-robin"
servers

An array of one or more LDAP servers that authenticate principals in this LDAP realm. This name-value pair is required, and must contain at least one element.

The authentication code needs to log in to the LDAP server to enumerate user roles and to authenticate users. The login credentials can be specified one of two ways. If this name-value pair is present, its user and password are used to log in. If it is not present, the authentication system uses SSL and a private key to log in. The latter requires that secure communication be configured and client authentication enabled.

authenticationCredentials

The authentication system needs to log in to the LDAP server to enumerate user roles and to authenticate users. The login credentials can be specified one of two ways. If this name-value pair is present, its user and password are used to log in. If it is not present, the authentication system uses SSL and a private key to log in. The latter requires that secure communication be configured.

userName

String. The user name used by the authentication system to log in to the LDAP server. Maps to the java.naming.security.principal naming context property. This name-value pair is required.

For example:

userName = "cn=SBLDAPUser,cn=Users,dc=ldap,dc=example,dc=com"
password

String. The password used by the authentication system to log in to the LDAP server. 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 = "secret"
host

String. The LDAP server's host name. This name-value pair is optional and its default value is localhost.

For example:

host = "ldap.example.com"
portNumber

Int. The LDAP server's portNumber number. This name-value pair is optional and its default value is 389.

For example:

portNumber = 390
secure

Bool. A secure-transport indicator. If true, use TLS to secure communication to the LDAP server, if false do not. Enabling secure communication requires that the engine have a secure communication configuration, or this indicator value is ignored. This name-value pair is optional and its default value is false.

For example:

secure= true
principalRoot

String. The Distinguished Name pattern that describes the directory information tree on the LDAP server, from the required entry to the directory root. Principal names will be applied to the pattern during authentication. This name-value pair is required.

For example:

principalRoot = "o=yourcompany/ou=yourdepartment"
principalSearch

String. The key name and index within the LDAP to use when looking up principals. This name-value pair is required.

For example:

principalSearch = "cn={0}"
roleRoot

String. The Distinguished Name pattern that describes the directory information tree on the LDAP server, for role search. This name-value pair is required.

For example:

roleRoot = "o=yourcompany/ou=yourdepartment"
roleSearch

String. Search criteria for role membership given a principal substituted into the '{0}' token. This name-value pair is required.

For example:

roleSearch = "cn={0}"
roleAttribute

String. Attribute for a user showing the roles of which they are a member. This name-value pair is required.

For example:

roleAttribute = "memberOf"

HOCON Configuration File Sample

The following is an example of the com.tibco.ep.streambase.configuration.ldapauthrealm type.

name = "ldaprealm1"
version = "1.0.0"
type = "com.tibco.ep.streambase.configuration.ldapauthrealm"
configuration = {
  LDAPAuthenticationRealm = {
    connectorFactoryClassName = "com.mycompany.mylocation"
    transformPrincipal = {
      searchRegexp = "xyz"
      replaceRegexp = "abc"
    }
    serverConnectAlgorithm = "round-robin"

    servers = [
      {
        authenticationCredentials = {
          userName = "cn=SBLDAPUser,cn=Users,dc=ldap,dc=example,dc=com"
          password = "secret"
        }
        host = "ldap.example.com"
        portNumber = 390
        secure= true
        principalRoot = "o=yourcompany/ou=yourdepartment"
        principalSearch = "cn={0}"
        roleRoot = "o=yourcompany/ou=yourdepartment"
        roleSearch = "cn={0}"
        roleAttribute = "memberOf"
      }
    ]
  }
}