- Index

< Previous |  | Next >

# LDAP Authentication Realm

## Overview

An LDAP realm performs authentication against a set of 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.

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 Live Datamart support three different mechanisms for LDAP authentication:

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, always starting with the first server, until a server responds with positive authentication.

## 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. The Configuration Guide provides detailed information on the entire realm configuration. The following is a brief summary of user search properties:

principalSearchRoots

  An array of search root DNs that are searched for users.

principalSearchFilter

  A filter applied to each of the above search roots. The filter is a string in LDAP search format that permits two substitution variables, {0} for the user name, and {1} for the user's DN. The default value is CN={0}

principalPasswordAttribute

  The name of the LDAP user object attribute containing the user's password. The default value is userPassword.

## 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 roles. If not specified, the user search roots are used instead.

roleSearchFilter

  A filter applied to each of the above search roots. The filter is a string in LDAP search format that permits two substitution variables, {0} for the user name, 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 role identifier used to map to local privileges associated with that role. The default value is CN.