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.
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.
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.comidentifies 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 withou=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.
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 thatusername. -
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
usernameis matched against the Role to Privileges configuration file to determine the StreamBase and LiveView access rights for theusernamewe started with.
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 isCN={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.
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
principalRootsproperty. 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 isroleOccupant={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.