Enportal/5.6/admin/user administration/ldap configuration

Overview

For organizations with an existing directory service it's possible to configure enPortal to use this service for user authentication, role assignment, and retrieval of additional user data.

Lightweight Directory Access Protocol (LDAP) is a common protocol used by many directory services and enPortal provides out-of-the-box support for these. Refer to the Supported LDAP Servers section below for more details.

For more information in general about authentication domains, users, and roles refer to the Provisioning documentation. Understanding how the default provisioning model works before trying to configure LDAP will make things easier.

Supported LDAP Servers

This table represents known working information, however any LDAP directory service should work. Please let support know if you have a working configuration or issues with a directory service not listed.

Product	Support Pass Change	Legacy	Notes
Microsoft Active Directory (AD)	yes *	-
OpenLDAP	yes *	-
OpenDS	yes *	-
Sun ONE Directory Server	yes *	yes	replaced by Sun Java System Directory Server

* For enPortal to support password changes the appropriate pluggable authenticator needs to be configured on the LDAP Domain Adapter.

Managing LDAP

This section covers actually managing the LDAP repository, that is setting up connection information, managing LDAP authentication domains, and managing LDAP role assignment.

With LDAP configured managing and assigning content is performed on LDAP domains, users, and roles as per normal through the enPortal user interface.

To access the LDAP configuration you must be logged in as an administrator and navigate to Advanced -> Explore System -> LDAP Repositories as shown in the screenshot below:

Managing LDAP configuration

LDAP Repositories

LDAP Repositories encapsulate the connection and authentication information to talk to the directory service. enPortal supports multiple repositories although typically there is just one.

To create a new repository click the top-level LDAP Repository entry in the Explorer tree. You can also right-click and select New Repository. Fill out the fields as described in the table below and click the Save button to save the repository.

Field	Description
LDAP Repository Name	Unique name for this repository, it is used internally and must be unique. After creating the repository this name cannot be changed.
LDAP Repository URL	The connection URL for the directory server, typically of the form ldap://directory_server:389 or ldaps://directory_server:636 for secure LDAP. enPortal also supports failover and multiple connection URLs can be entered here separated by spaces.
Factory	Do not change this unless instructed by support.
Connection Timeout	Optional and only applicable in the case where failover (multiple connection URLs) is configured. This represents the timeout waiting on a directory server response before failing over to the next configured. The value is in milliseconds and if not set defaults to 10,000 (10 seconds).
LDAP Authentication User	The distinguished name (DN) of a user with permission to query the LDAP server. If unspecified the anonymous account will be used. This account should have read-only access to the information needed for synchronization of users and roles. For example: cn=Manager,dc=edgeti,dc=com
Password	The password for the LDAP Authentication User
Admin Access	This should be left un-checked. By default the UI provides protection against modifying LDAP managed authentication domains and roles as changes from the UI would only be temporary until the next LDAP synchronization. Enabling admin access removes this UI restriction.
Authentication Type	Do not change this unless instructed by support.

Secure LDAP (TLS/SSL)

As noted above enPortal supports secure LDAP which is identified via the connection URL. In addition the LDAP server certificate must be added to the Java Trust Store. This can be via the system trust store or via a trust store defined in the enPortal Runtime Options.

LDAP Role Adapters

LDAP Role Adapters are used to map LDAP groups to enPortal roles and LDAP user group memberships to enPortal role assignments. To create a new LDAP Role Adapter right-click on the ldap repository to be used and select New Role Adapter. To edit an existing adapter, right-click on the adapter and select Edit Adapter. Make sure to click the Save button when complete.

Field	Description
Fully qualified portal role	Unique enPortal role name which is used as a base for the roles read in by the adapter. For example: /myLDAProles. This cannot be changed after creating the adapter.
Search Base	Identifies a unique node in the directory server to perform the search for LDAP groups. For example: ou=Groups,dc=edgeti,dc=com
Search Scope	Determines the scope of the search - just search within the search base (One Level) or recursively search children objects (Recursive).
Search Filter	The search may contain results that should be mapped to enPortal and the search filter can be used to exclude search results. See below the Role Class' already filters the results for only matching classes.
Role ID attribute key	This represents the LDAP attribute which is the name for the role, for example: cn.
Role Class	Only objects of this class are used, for example posixGroup or groupOfUniqueNames.
Domain/User assignment attribute key	This LDAP attribute is what's used to assign users into the role - i.e. the usernames. For example: memberUid or uniqueMember.
Maximum roles	By default 0 indicates no limit. When first configuring LDAP it may be useful to place a specific limit on large directory services to avoid issues when performing synchronisation until the base, scope, and filtering is fine tuned to only return the desired results.
Search Timeout	By default 0 indicates no limit. Similar to above.

LDAP Domain Adapters

LDAP Domain Adapters are used to map users within a directory service to users in enPortal. To create a new LDAP Domain Adapter right-click on the ldap repository to be used and select New Domain Adapter. To edit an existing adapter, right-click on the adapter and select Edit Adapter. Make sure to click the Save button when complete.

The configuration for domain adapters is split into the following 3 sections:

General

Field	Description
Name	This is a unique name for this domain adapter. Users who are a member of this authentication domain are required to enter this on the login page along with their username and password. In other words, the name is visible to end-users. It is not possible to change this name after creating the domain adapter.
Default Role	Optional field to automatically assign a role to users in this domain. Can be left blank. Alternatively a Role Adapter can be configured to map users to roles, or both.
Session Expiry	This can be used to override the system default inactivity timeout for users within this domain.
Session Extension	Used in conjunction with above to extend a session when a user is active in the system.
Pluggable Authenticator	enPortal ships with a number of authenticators depending on the directory server features. Please note that in order to support password changes the appropriate authenticator must be used in conjunction with secure LDAP. The available authenticators are: com.edgetech.eportal.session.impl.LDAPSessionAuthenticator: Default generic authenticator. This does not support password changes or lazy loading. com.edgetech.eportal.session.impl.LDAPSessionAuthenticatorWithLazyLoad: As above with lazy load support. com.edgetech.eportal.session.impl.LDAPSessionAuthenticatorExtendedWithLazyLoad: This supports password changes for LDAP servers that support policy controls, and certain legacy LDAP servers (see Legacy LDAP Servers section). This also supports lazy load. com.edgetech.eportal.session.impl.ActiveDirectoryAuthenticatorWithLazyLoad: Specific authenticator for Microsoft Active Directory which supports both password changes and lazy load.
Authentication Type	Do not change this unless instructed by support.

Search

Field	Description
Search Base	Identifies a unique node in the directory server to perform the search for LDAP users. For example: ou=People,dc=edgeti,dc=com
Search Scope	Determines the scope of the search - just search within the search base (One Level) or recursively search children objects (Recursive).
Search Filter	The search may contain results that should be mapped to enPortal and the search filter can be used to exclude search results. See below the User Class already filters the results for only matching classes.
User ID Attribute key	This represents the LDAP attribute which is the name for the user, for example: uid.
User Class	Only objects of this class are used, for example inetOrgPerson.
Maximum Users	By default 0 indicates no limit. When first configuring LDAP it may be useful to place a specific limit on large directory services to avoid issues when performing synchronisation until the base, scope, and filtering is fine tuned to only return the desired results.
Search Timeout	By default 0 indicates no limit. Similar to above.

Post

Field	Description
Remove UID Prefix	For cases where LDAP usernames include prefix characters that should be removed before creating enPortal User Names.
Remove UID Suffix	For cases where LDAP usernames include suffix characters that should be removed before creating enPortal User Names. For example: the LDAP username may be jadams@company.com and setting this field to @company.com would result in an enPortal User Name of jadams.

Note on Case Sensitivity

enPortal accounts are case sensitive, however most LDAP searches for usernames are case in-sensitive depending on the LDAP schema. To prevent duplicate accounts being created in enPortal if a user happens to log in multiple times with different case the LDAP adapters behave in this way:

• Regardless of the case entered by the user on the login form, enPortal will use the case as returned from LDAP. For example, if a user logs in as "Joe.Bloggs" but the user is actually "joe.bloggs" in LDAP, then authentication will still succeed assuming the password is correct, and enPortal will use the returned case of "joe.bloggs" as the User Name.
• If using a Lazy Load LDAP authenticator it will also use the returned case from LDAP when creating new enPortal accounts.

This behaviour is new as of enPortal 5.6 and existing deployments on older versions may be using some kind of workaround such as normalizing the case using a custom login page with javascript. If upgrading to enPortal 5.6 it is recommended to use the supported features and remove any customizations if possible. However, it is possible to disable the new behaviour and act as enPortal 5.5 or earlier by setting the following configuration option:

1. Edit or create: [INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/custom.properties
2. Add a new line with the following: users.ldap.userNameCaseSetbyLDAP=false
3. Restart the enPortal server process.

Note on Legacy LDAP Servers

Some older LDAP servers do not support the password policy controls. These are marked as Legacy in the table of supported LDAP servers above. For these directory servers it's necessary to disable policy control for them to work correctly:

1. Edit or create: [INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/custom.properties
2. Add a new line with the following: ldap.policyControlSupported=false
3. Restart enPortal.

Synching enPortal and LDAP

LDAP synchronization is the process where enPortal will read in users from the domain adapters and roles / role mappings from the role adapters.

Generally it's recommended to perform a sync of roles only and allow users to be created on-demand by using authenticators that support lazy loading (see the pluggable authenticators in the LDAP Domain Adapters section). For configuration and testing purposes it is still useful to sync users, but this can be done in conjunction with limits to avoid syncing the entire set of users unless that is the intention.

If content is to be provisioned directly to users versus roles, then it is necessary to sync users to enPortal or the users will not be available in the provisioning interface.

To perform an LDAP sync:

1. Right-click on LDAP Repositories in the Explorer tree
2. Select Sync LDAP
3. By default only roles are synchronized. Un-check the Roles Only checkbox to also sync users.
4. Select the appropriate Option to determine the sync behaviour.
5. The Repositories field can be used to limit the sync to a specific repository, enter the repository name in this field.
6. Click the Start button.

Automated Syncing

With lazy loading users are synchronized on-demand. However if using LDAP Role Adapters it's necessary to run LDAP Sync regularly to ensure enPortal matches the directory service. This process can be automated by triggering syncs through the web API using a scheduled job (for example cron on Linux/UNIX systems). Please note for this to work a valid session must be established with enPortal first. Refer to the Accessing enPortal documentation for the information on authenticating via GET or POST.

• base URL: /enportal/servlet/pd/vdir/system/LDAPSync?Submit=true
• roles=on: include this parameter to sync only roles.
• syncAction=: set this to u for update, c for create, and d for delete.
• repositories=: set this to the LDAP Repository name to limit the sync to a specific repository.

Examples:

1. Perform a role-only sync for all repositories:
   /enportal/servlet/pd/vdir/system/LDAPSync?Submit=true&roles=on&syncAction=u&repositories=
2. Perform role and user sync for only the "myLDAP" repository:
   /enportal/servlet/pd/vdir/system/LDAPSync?Submit=true&syncAction=u&repositories=myLDAP
3. End-to-end example with authentication and role-only sync using curl:
   $ curl -c cookies.txt -o out.txt "http://localhost:8080/enportal/servlet/pd/?login=yes&userid=administrator&password=administrator&domainSelect=System"
   $ curl -b cookies.txt -o out.txt "http://localhost:8080/enportal/servlet/pd/vdir/system/LDAPSync?Submit=true&roles=on&syncAction=u&repositories="

Directory Server Limits

In some cases a full sync is desired but the directory server itself has restrictions around the total query time or size of results. enPortal can be configured to synchronize in pages (blocks):

1. Edit [INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/custom.properties and add the line ldap.pagingSupported=true.
2. Edit the domain and/or role adapters and enable Maximum Users/Roles. Set a value which represents the maximum number of results per query.
3. Restart enPortal.

With the above configured, when enPortal is requested to perform a synchronization it will limit queries results to the maximum value set and perform multiple queries until the full result set is obtained.

Session Variables from LDAP

Sometimes you will want to pull in user information that was provisioned in LDAP. The goal is to have AppBoard/enPortal pass these settings from LDAP to the back-end application or data source filters.

You can define any number of variables to pull in from the user's LDAP context. Here's how you can pull in the: 'email', 'phone', and 'branch' values.

1. Edit [INSTALL_HOME]/webapps/enportal/WEB-INF/custom.properties
2. Add a line for each variable to pull from the user's LDAP context prefixed with ldap.userInfo., in this example:

   ldap.userInfo.email

   ldap.userInfo.phone

   ldap.userInfo.branch

The user's LDAP context variables are retrieved on successful authentication and stored in the enPortal database for the life of the session. A new login is required to re-read the values from LDAP.

The following syntax shows how these variables can be accessed via SHIM expressions:

• email: ${shim:session.var.userInfo.key.email}
• phone: ${shim:session.var.userInfo.key.phone}
• branch: ${shim:session.var.userInfo.key.branch}

Additional Information

• LDAP Tutorial