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
- Login to PSIfusion using an account with the Administrator role grant
- Open the Administration module by clicking the gear icon on the top right area of the screen.
- Select the Users tab
- If editing an existing directory:
- Select the appropriate directory from the list
- Click the edit button
- 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.
| Option | Description |
|---|---|
| Microsoft Active Directory | Configure 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 eDirectory | Configure 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:
| Type | Port |
|---|---|
| Default (no encryption) / TLS | 389 |
| SSL | 636 |
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.
| Type | Description |
|---|---|
| None | Use a clear text (no encryption) connection |
| TLS | Connect using Transport Layer Security |
| SSL | Connect using Secure Socket Layers |
Binding Type
Select the type of authentication to perform when connecting to the LDAP server.
| Type | Description |
|---|---|
| Anonymous | The LDAP server does not require authentication before issuing queries. |
| Explicit | Specify 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.
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.
| Option | Description |
|---|---|
| Authenticate users by distinguished name | Select this option if authentication queries against the LDAP server should be made by distinguished name instead of user name. |
| Create Fusion User on Successful Authentication | This 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 Mapping | When 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 Recursively | This 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 Timeout | PSIfusion 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:
| Attribute | Description |
|---|---|
| FirstName | The user's given name |
| LastName | The user's surname |
| Display Name | The display name to use for the user. This may be the user's full name, name with middle initial, a nickname, etc. |
| EmailAddress | The 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:
| Type | Description |
|---|---|
| Role Grants | Grant a PSIfusion role to all users that belong to a particular LDAP group. Current roles include: Administrator and Supervisor. |
| Group Mapping | Maps all users within the given LDAP group to the selected User Group. |
| Team Mapping | Maps 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: