pGina Documentation

LDAP Plugin Documentation

How the LDAP Plugin Works

The LDAP plugin provides pGina services using an LDAP server as the primary data source. It provides support for SSL encryption and failover to one or more alternate servers.


In the authentication stages, this plugin maps the user name to a LDAP Distinguished Name (DN) and attempts to bind to the LDAP server using the DN. If the bind is successful, it provides a positive result to the pGina service.

The user name can be mapped to a DN by one of two means: simple pattern substitution, or via a search of the LDAP database. When a search is used, the plugin connects to the LDAP server anonymously (or via supplied credentials) and attempts to find an entry for the user. If the entry is found, the plugin closes the connection and attempts to bind again using the DN of the entry, and the password provided by the user. If this bind is successful, the plugin registers success.


In the authorization stage the LDAP plugin can authorize users based on membership in LDAP groups. The plugin searches the LDAP tree for group membership and allows or denies based on a set of rules that can be configured via the configuration interface (see below).

If the LDAP server cannot be contacted, it can be configured to allow or deny access. It can also be configured to deny if the LDAP plugin fails in the authentication stage.


In the gateway stage, this plugin can add the user to local groups based on membership in LDAP groups. The plugin will search the LDAP tree for group membership then add the user to local groups based on a set of rules (see below). A common use for this is to add the user to the local Administrators group when the user is a member of a given LDAP admin group.

Typical Setup

A typical (minimal) setup for LDAP authentication is to enable the Local Machine plugin in the authentication and gateway stages, and enable LDAP in the authentication stage. Within the authentication stage, order the LDAP plugin before Local Machine.


The configuration interface for the LDAP plugin is shown below.

LDAP configuration

The configuration options are described below:

Authentication Options

Authorization Options

LDAP configuration

The authorization tab provides an interface for creating, removing, and deleting authorization rules. The rules are tested by the plugin in order and the first matching rule is applied. If none of the rules match, the default rule is applied. The default is configured using the radio buttons at the top of the tab interface.

The other configuration options are described below:

Gateway Options

LDAP configuration

The gateway tab provides options for creating and removing rules for adding local groups based on LDAP group membership. The rules are all applied in order from top to bottom. All rules are applied regardless of how many are a match for the user logging in.

When users are removed from LDAP groups, they may not be removed from the local groups without careful configuration of the LocalMachine plugin. For this to work properly, you should make sure to configure the LocalMachine plugin to scramble passwords and/or to remove accounts and profiles after logout. This will make sure that the LocalMachine plugin does not retain group information on consecutive logins. For more information, see the documentation for the LocalMachine plugin.

Note that it is important to make sure that this plugin executes prior to the LocalMachine plugin in the gateway stage. This is because the LocalMachine plugin is responsible for actually adding the local account to the local groups. If it executes prior to the LDAP plugin, it will not apply the groups that have been added by this plugin.