LDAP Authentication Realm

< Previous		Next >

Overview

A Lightweight Directory Access Protocol (LDAP) authentication realm performs authentication against one or more LDAP servers with potentially disjoint databases. The realm allows any number of LDAP servers, each with different search properties, authentication mechanisms, and secure communication profiles. You can use multiple servers for high availability (replicas of the same server), for unifying disjoint user communities, or both. When multiple LDAP servers are configured in a realm, they are tried in turn, always starting with the first server configured in the realm configuration, until a server responds with a positive authentication, or the request fails on all servers.

An LDAP realm configuration is specified in an LDAPAuthenticationRealm root object of the security configuration type. A RoleToPrivilegeMappings configuration must accompany an LDAP configuration to define StreamBase and LiveView privilege roles that match the LDAP group names in your LDAP directory, as described below.

An LDAP configuration can enable secure communication client authentication. That is, if a request is transported over a secure communication connection such as TLS and that connection uses client (mutual) authentication, then no password is required. The server network listener provides the authenticated user, which is responsible for mapping the client X.509 certificate's subject DN to a user name.

If you require extra security, the configuration can require a password even if the request originates from a trusted host. This behavior effectively disables trusted hosts unless the realm is configured to require that all requests originate from a trusted host. In that case, the configuration becomes a white list with required passwords for maximum security.

StreamBase and LiveView support three different mechanisms for LDAP authentication, configured with the principalAuthenticationAlgorithm property:

Local password verification: The user's password is queried from the LDAP server over a connection authenticated with system credentials, and sent to the realm LDAP client, which compares it with the password provided by the user being authenticated. If the provided password is encrypted, it is decrypted by the master secret manager before comparing with the password returned by the LDAP server. This mechanism is used in cases where the LDAP server does not support remote password verification described next.
Remote password verification: The user's password is sent to the LDAP server over a connection authenticated with system credentials, and the LDAP server compares it with the user's LDAP password. If the password sent to the server for comparison is encrypted, it is decrypted by the master secret manager before sending to the LDAP server. This mechanism is preferred to local verification, even when using a secure LDAP connection, because the user's actual password never leaves the server.
Bind: The realm attempts to connect to the LDAP server using the user's name and password, and authentication succeeds if the connect attempt succeeds.

The default mechanism is Bind, and can be changed in the realm configuration on a per-LDAP-server basis.

If there are multiple LDAP servers in a realm configuration, they are tried in turn, starting with the first server in configuration-defined order, until a server responds with positive authentication.

LDAP Terminology

The LDAP standard defines a simple, fast, query-response mechanism for retrieving authentication information from a defined directory information tree (DIT). However, LDAP is designed to be extremely flexible and therefore does not define a particular structure for DITs. Instead, each LDAP vendor, and each customer site might have different DIT structures.

For this reason, LDAP terminology is necessarily generic, and can appear to be obscure. The following LDAP terms are used in StreamBase documentation.

DIT

Directory information tree, the LDAP database of users, groups, group memberships, and other information as configured. The structure of the DIT is not defined by the LDAP standard, and can therefore be customized for the needs of different organizations or different sites within an organization. One LDAP server has one DIT, but more than one server can have the same structure.

principal

The primary unit searched for when querying a DIT. In practice for StreamBase, the principal is usually a user name, which might be expressed as a simple username string, as an email address with @domain, or another way.

attribute

Attribute is the name portion of an LDAP name-value pair.

FQN

Fully qualified name, the globally unique set of name components that identifies a resource. In Internet Protocol, for example, the URI ldap.example.com identifies exactly one server. In LDAP, a distinguished name is fully qualified identifier containing the comma-separated steps from the principal up to the top of the directory information tree.

DC

Domain component, a prefix for the components of an Internet domain name, as in dc=example,dc=com.

OU

Organization unit, a prefix for a division of an organization. This can refer to an existing subdomain, such as engineering.example.com, which would be specified with ou=engineering. It can also refer to an org chart division without subdomain, such as Engineering or Marketing.

CN

Common name generally refers to a standard name for a person, such as a firstname-lastname pair, or a name for a group, such as Admins or Users.

UID

User ID, a login name.

DN

Distinguished Name, a string that uniquely identifies an entry in the DIT; a fully qualified name for an LDAP resource. The LDAP format for expressing a DN is with a comma-separated list of the steps from the resource up to the top of the DIT, which is always a domain name. Spaces and special characters must be escaped with a backslash. The following are example DNs:

uid=mercutio,ou=Engineering,dc=example,dc=com
cn=Willy\ Shakes,ou=Marketing,dc=example,dc=com

For other LDAP terms, see ldap.com or another Internet reference.

LDAP Authentication and StreamBase

While an LDAP directory information tree can be configured to contain many attributes for each principal, it does not contain any concept of StreamBase or LiveView access privileges. For this reason, a StreamBase LDAP configuration file must always be accompanied by a RoleToPrivilegesMapping configuration file.

Configure the Role file with a set of StreamBase role names that exactly match the LDAP group names in your LDAP directory. You might benefit from the use of LDAP browser software to inspect the actual group or organization unit names in your directory information tree. The StreamBase role names must match in spelling and case, except that any spaces in LDAP group names (such as Engineering Support) must be escaped with a backslash (Engineering\ Support) in the Role file.

With an LDAP authentication realm in place, and with any of the three principalAuthenticationAlgorithm property settings described in the Overview, StreamBase contacts the LDAP server to authenticate the provided username and password. The username might be taken from the currently logged in operating system username, or from a username entered on a login form you provide. It is matched against the LDAP DIT as follows:

The username and password are sent to the LDAP server as a query (or retrieved from the server to match locally).
The username is searched for a match starting at the portion of the DIT that you designate with the principalSearchRoots property. For the example DIT shown above, you would search:
```
principalSearchRoots = [ "ou=People,dc=example,dc=com" ]
```
If you let the search start at the top of the tree, it would waste time searching in branches that have no usernames defined.
Once a match is found with a simple username, the query returns the fully qualified DN for that username.
The query then searches the roleSearchRoots for the LDAP groups that contain that DN. For the example DIT shown above:
```
roleSearchRoots = [ "ou=Groups,dc=example,dc=com" ]
```
Back in the StreamBase client, the returned list of LDAP group names for username is matched against the Role to Privileges configuration file to determine the StreamBase and LiveView access rights for the username we started with.

User Search

Because each LDAP database can have its own schema for organizing users and roles, the LDAP realm has a number of configuration properties used to find users on the LDAP server.

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 the example DIT shown above, you would search:

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

principalSearchFilter

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.

principalPasswordAttribute

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.

Role Search

Use the following role search configuration properties to find the roles associated with a particular user:

roleSearchRoots

An array of search root DNs 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 the example DIT shown above:

roleSearchRoots = [ "ou=Groups,dc=example,dc=com" ]

roleSearchFilter

A filter applied to each of the role 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 roleOccupant={1}.

roleNameAttribute

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.

Configuration of LDAP Authentication Realm

The LDAPAuthenticationRealm root configuration object defines LDAP integration for a node. Figure 1, “LDAPAuthenticationRealm relationships” shows the relationships to other configuration objects.

LDAPAuthenticationRealm relationships

A detailed description of the configuration object properties is in LDAPAuthenticationRealm object properties and a snippet for these properties is in Example 1, “LDAPAuthenticationRealm object snippet”.

LDAPAuthenticationRealm object properties

Name	Type	Description
`allowSecureCommunicationClientAuthentication`	Boolean	Automatically authenticate if user is connecting over a secure communication channel. A value of `true` allows automatic authentication, a value of `false` disables automatic authentication. Optional. Default value is `false`.
`servers`	`LDAPServer` [ ]	LDAP server configuration (see LDAP Server). Multiple LDAP servers can be configured. Authentication is attempted to each server in the order they are defined in this configuration property until authentication is successful, or there are no more servers configured. Required.
`name`	String	Name of the authentication realm. This name must be unique across all authentication realms. Required.
`requirePassword`	Boolean	Require a password if user is connecting from a trusted host unless automatically authenticated because of a secure communication channel. A value of `true` requires a password when connecting from a trusted host, a value of `false` allows connection from a trusted host without a password. Optional. Default value is `true`.
`requireTrustedHostMembership`	Boolean	A value of `true` only allows user to connect from a trusted host, a value of `false` allows user to connect from any host. Optional. Default value is `false`.

Example 1. LDAPAuthenticationRealm object snippet

name = "ldap-authentication-realm"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration =
{
    LDAPAuthenticationRealm =
    {
        name = "my-ldap-authentication-realm"
        requireTrustedHostMembership = true
        allowSecureCommunicationClientAuthentication = true
        requirePassword = false
        servers =
        [
            { ... }
            { ... }
        ]
    }
}

LDAP Server Configuration

The LDAPServer configuration object defines LDAP server configuration. Figure 2, “LDAPServer relationships” shows the relationships to other configuration objects.

LDAPServer relationships

A detailed description of the configuration object properties is in LDAPServer object properties and a snippet for these properties is in Example 2, “LDAPServer object snippet”.

LDAPServer object properties

Name	Type	Description
`host`	String	LDAP server host name. Optional. Default value is `localhost`.
`portNumber`	Short	LDAP server port number. Optional. Default value is `389`.
`principalAuthenticationAlgorithm`	Enumeration with these valid values, `BIND`, `LOCAL_PASSWORD_COMPARE`, and `REMOTE_PASSWORD_COMPARE`.	The type of authentication to perform. `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 password attribute, and comparing the values locally with the principal's credentials. `REMOTE_PASSWORD_COMPARE` is the same as `LOCAL_PASSWORD_COMPARE` except that the comparison is performed by the LDAP server. Optional. Default value is `BIND`.
`principalPasswordAttribute`	String	The password attribute for this LDAP server's principals. Optional. Default value is `userPassword`.
`principalSearchRoots`	String [ ]	A list of Distinguished Names under which principals are searched for during search-based authentication operations or user name to Distinguished Name conversions. Required. Must contain at least on element.
`principalSearchFilter`	String	The LDAP filter expression used when searching for principals. The filter permits Java pattern substitution expressions. `{0}` is bound to the input principal and `{1}` is bound to its corresponding distinguished name. Optional. Default value is `CN={0}`.
`roleSearchRoots`	String [ ]	A list of Distinguished Names under which roles are searched for. Optional. Default value is the `principalSearchRoots` value.
`roleSearchFilter`	String	The LDAP filter expression used when searching for roles of which a principal is a member. The filter permits Java pattern substitution expressions. `{0}` is bound to the input principal and `{1}` is bound to its corresponding Distinguished Name. Optional. Default value is `roleOccupant={1}`.
`roleNameAttribute`	String	Attribute of a role entry that is used to map to privileges. Optional. Default value is `CN`.
`secureCommunicationProfileName`	String	Name of a secure communication client profile to use when configuring secure communications with an LDAP server. Optional. No default value. If not set LDAP server connections are not secure.
`systemPassword`	String	The system principal password to log in to the LDAP server to perform authentication operations. Opaque passwords are generated using the epadmin secret target. See epadmin-secret(1). Required.
`systemPrincipal`	String	The system principal to log in to the LDAP server to perform authentication operations. Required.

Example 2. LDAPServer object snippet

name = "ldap-authentication-realm"
version = "1.0.0"
type = "com.tibco.ep.dtm.configuration.security"
configuration =
{
    LDAPAuthenticationRealm =
    {
        servers =
        [
            {
                host = "ldap.primary.acme.com"
                portNumber = 390
                principalAuthenticationAlgorithm = LOCAL_PASSWORD_COMPARE
                principalPasswordAttribute = "password"
                principalSearchRoots = [ "ou=users,dc=example.dc=com" ]
                principalSearchFilter = "cn={0}"
                roleSearchRoots = [ "ou=roles,dc=example.dc=com" ]
                roleSearchFilter = "membership={1}"
                roleNameAttribute = "roleID"
                secureCommunicationProfileName = "secure-ldap-client-profile"
                systemPassword = "secret"
                systemPrincipal = "cn=SBLDAPUser,cn=Users,dc=ldap,dc=example,dc=com"
            }
            {
                host = "ldap.backup.acme.com"
                portNumber = 390
                principalAuthenticationAlgorithm = LOCAL_PASSWORD_COMPARE
                principalPasswordAttribute = "password"
                principalSearchRoots = [ "ou=users,dc=example.dc=com" ]
                principalSearchFilter = "cn={0}"
                roleSearchRoots = [ "ou=roles,dc=example.dc=com" ]
                roleSearchFilter = "membership={1}"
                roleNameAttribute = "roleID"
                secureCommunicationProfileName = "secure-ldap-client-profile"
                systemPassword = "secret"
                systemPrincipal = "cn=SBLDAPUser,cn=Users,dc=ldap,dc=example,dc=com"
            }
        ]
    }
}