Adding an External User Directory

Introduction

This article will document the steps necessary to add or edit a connection to an external Lightweight Directory Access Protocol (LDAP) server within PSIfusion.  For an overview of user directories and their role within the application, please refer to the User Directories article.  

Adding or Editing a Directory

  1. Login to PSIfusion using an account with the Administrator role grant
  2. Open the Administration module by clicking the gear icon on the top right area of the screen.
  3. Select the Users tab
  4. If editing an existing directory:
    1. Select the appropriate directory from the list
    2. Click the edit button
  5. To add a new directory, click the Add button

The following sections of the article will explain the various options available on the user directory dialog.

General Tab

The settings on the general tab define the connection to the external directory server as well as options that control how PSIfusion should integrate users from this directory into the application.

Predefined Configurations

PSIfusion provides a number of predefined configuration templates to help you quickly configure a new directory. Selecting one of these templates will populate the fields on the dialog with typical values for the selected provider. After selecting a predefined configuration you are free to edit any of the settings to suit your environment. In addition to populating settings on the general tab, selecting one of these configurations will also add the appropriate attribute mapping entries on the attribute mapping tab.

OptionDescription
Microsoft Active DirectoryConfigure the directory to make a clear text connection (no encryption) to Active Directory using port 389
Microsoft Active Directory (SSL1)Configure the directory to make an encrypted connection to Active Directory using SSL on port 636
Microsoft Active Directory (TLS2)Configure the directory to make an encrypted connection to Active Directory using TLS on port 389
Novell eDirectoryConfigure the directory to make a clear text connection (no encryption) to eDirectory using port 389
Novell eDirectory (SSL)Configure the directory to make an encrypted connection to eDirectory using SSL on port 636
Novell eDirectory (TLS)Configure the directory to make an encrypted connection to eDirectory using TLS on port 389

(1): Secure Sockets Layer
(2): Transport Layer Security 

Connection Options

The settings on the left side of the dialog control how PSIfusion will connect to the LDAP server.

Directory Name

Enter a unique name to identify this user directory. This name is used to locate the directory in the list of user directories, and has no bearing on the connection to the external LDAP directory.

Server

Enter the LDAP server host name or address. When using canonical names, the host name entered must be a valid host that is resolvable by the Domain Name System (DNS) configured on the server hosting the PSIfusion application.

Port

Enter the LDAP server port. The default ports for each LDAP connection type are:

TypePort
Default (no encryption) / TLS389
SSL636
Search Root

Enter the distinguished name of the container you wish to use as the search root for all PSIfusion LDAP queries. Alternatively, if you complete the binding type and authentication options first, you can click the select button to browse for the search root to use.

The search root is used to limit the results of any query performed by PSIfusion. This includes queries for users, user authentication and groups. A query for a user or other entity that does not fall under the specified search root will automatically return no results.

Binding Security Type

Select the type of encryption to employ when making connections to the LDAP server. The setting used here must correspond to the binding configurations applied to the LDAP server. Attempting to make an encrypted connection to an LDAP server that has not been configured to respond to or process encrypted connections will always fail.

TypeDescription
NoneUse a clear text (no encryption) connection
TLSConnect using Transport Layer Security
SSLConnect using Secure Socket Layers
Binding Type

Select the type of authentication to perform when connecting to the LDAP server.  

TypeDescription
AnonymousThe LDAP server does not require authentication before issuing queries.
ExplicitSpecify a user and password to use for all queries made to the LDAP server.
User Name & Password

Enter the user name and password for a user that has permission to execute queries against the LDAP server.

The user name and password fields will not be accessible unless the Explicit binding type is selected.

Ignore certificate errors

When connecting to the server using an encrypted binding type (SSL or TLS), the connection will fail if the server does not use an SSL certificate that has been signed by a trusted root certification authority (CA). Enabling this option will ignore connection failures due to certificates that are not trusted.

Authentication Domain

Enter the domain name to use when authenticating users, including the binding user. This option will typically only be set for Microsoft Active Directory servers. If the binding user includes a domain specification already, the setting here will not be used for binding, and will only be applied to user authentication when accessing the client application.

Query Format Options

The options on the right side of the dialog control how PSIfusion will format LDAP queries.  

Selecting a predefined configuration will populate these values with acceptable defaults.

User Class Name

Enter the name of the LDAP class applied to user objects.  

User Name Attribute

Enter the name of the LDAP attribute that contains the user name that should be used for authentication.  

Group Membership Attribute

Enter the name of the LDAP attribute that contains the group membership values for each user object.

Group Class Name

Enter the name of the LDAP class applied to group objects.

Options

The options section contains settings which modify the default behavior of PSIfusion with respect to how the user directory interacts with the external LDAP directory as well as how the user directory should be used by the application itself.

OptionDescription
Authenticate users by distinguished nameSelect this option if authentication queries against the LDAP server should be made by distinguished name instead of user name.
Create Fusion User on Successful AuthenticationThis option enables users who authenticate against the LDAP directory successfully to automatically be added as a new PSIfusion user, if they do not already have a user account in the application. When this option is disabled, LDAP users that do not have a corresponding PSIfusion user account will not be able to access the system.
Deny login for users without a User Group MappingWhen this option is enabled users that have not been assigned to one or more User Groups will not be allowed access to the application. This option can be used to limit access to PSIfusion to those users in your LDAP directory that belong to a specific LDAP group. Refer to the Group Mapping Tab section below for more information.
Search Group Membership RecursivelyThis option causes PSIfusion to resolve LDAP group membership using recursive group searches. There are performance implications to enabling this option, and it's use should be carefully considered. For a full explanation LDAP group mapping in PSIfusion please refer to the LDAP Group Mapping article.
Query Cache TimeoutPSIfusion caches LDAP query results to improve performance and reduce the load on your external directory servers. The minimum acceptable cache time is one minute, however a longer cache time can be chosen if desired.

Attribute Mapping Tab

Attribute mapping enables PSIfusion to query user details from the external LDAP directory and use those details to populate the user's PSIfusion profile. Attribute mappings will be populated with reasonable default values if you use a predefined configuration. The following user profile attributes can be mapped from the LDAP directory:

AttributeDescription
FirstNameThe user's given name
LastNameThe user's surname
Display NameThe display name to use for the user. This may be the user's full name, name with middle initial, a nickname, etc.
EmailAddressThe user's email address

Group Mapping Tab

Group mapping enables user's who authenticate through the external LDAP directory to be automatically mapped to User Groups and system roles within PSIfusion based on their group membership within the LDAP organization.

Adding a Group Mapping

Before adding a group mapping, any required User Groups must already be created.

To add a new group mapping select the Add button and you will be presented with the following dialog:

External Group

The external group is the distinguished name (DN) of the LDAP group to which this mapping should apply. Use the select button to browse for a group. The resulting dialog will be filtered to only display group objects.

Mapping Type

There are three types of group mapping supported by PSIfusion:

TypeDescription
Role GrantsGrant a PSIfusion role to all users that belong to a particular LDAP group. Current roles include: Administrator and Supervisor. 
Group MappingMaps all users within the given LDAP group to the selected User Group.
Team MappingMaps all users within the given LDAP group to the selected Team.

Editing a Group Mapping

To edit a group mapping, select the mapping you wish to edit and click the Edit button. The dialog and options displayed are the same as those documented above in the add mapping section.

On this page:


Related Items: