Edge Documentation

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 modern LDAPv3 directory service should work. Please let support know if you have a working configuration or issues with a directory service not listed above.

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

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.

LDAP Role Adapters

LDAP Role Adapters are used to map users to roles within enPortal. 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.

Configuring LDAP Managed Domains

In order to define an enPortal Domain that is mapped to LDAP, you must create a Domain adapter. This defines the name of the Domain and details how it is mapped to the specific LDAP directory structure of your organization. Perform the following steps to configure an LDAP managed Domain in enPortal:

Create an LDAP Repository.
Right-click on the repository name and select New Domain Adapter.
In the panel on the right, enter the following values for the Domain adapter:
- General tab
  - Default Portal Domain - The enPortal Domain name to assign to this Domain.
  - Default Portal Role - The enPortal Role to assign to this Domain. All users in this Domain will inherit this Role assignment.
  - Session Lease - The time in seconds until the current session will expire from lack of use. This is in the context of enPortal sessions for users in this Domain.
  - Session Extension - The number of seconds relative to the current time for which to extend the enPortal session for users in this Domain as they use the enPortal system.
  - Pluggable Authenticator - The pluggable authentication that will be used by enPortal to authenticate any user within this domain. Note: This is the fully qualified Java class that must implement the com.edgetech.eportal.session.SessionAuthenticator interface. Portal is delivered with following authenticators:
    - com.edgetech.eportal.session.impl.LDAPSessionAuthenticatorWithLazyLoad - use this class when accessing non-Microsoft LDAP.
    - com.edgetech.eportal.session.impl.LDAPSessionAuthenticatorExtendedWithLazyLoad - use this class when accessing non-Microsoft LDAP. Password change is possible with this authenticator if the LDAP is OpenDS based.
    - com.edgetech.eportal.session.impl.ActiveDirectoryAuthenticatorWithLazyLoad - use this class when accessing Microsoft Active Directory. Password change is possible with this authenticator.
  - Authentication Type - Type of authentication that is used by the LDAP Server. Example: "simple"
- Search tab
  - Search Base - Identifies a unique node in an LDAP Directory resource to perform the search for Users. This does not include the host, port, and baseURL identified by LDAPDefinition element. Example: "ou=Customer,ou=Users,dc=private,dc=abc"
  - Search Scope - Defines whether to search only within the location identified by the base or if the search should look deeply into the location identified by the base. Example: Recursive
  - Search Filter - Defines a filter for retrieving users from the LDAP repository. Example: "mail=*company.com"
  - User ID Attribute Key - The LDAP attribute of the user object that identifies the user name. Example: "mail"
  - User Class - Allows a filter to be placed on the type of LDAP objects that are interpreted as enPortal Users. Example: "inetOrgPerson"
  - Max Number of Users to Import - The largest number of Users to import from the LDAP Repository into enPortal. This can be used when testing against a Repository with a large number of User accounts. This attribute has a default of 0, which indicates that all entries should be returned. Note the LDAP Server also has configuration settings that may limit the number of entries returned, which, if exceeded, throws a Naming exception.
  - Max Search Time - How long to wait for the search to be performed (in milliseconds). This attribute has a default of 0, which means to wait indefinitely. Note: the LDAP Server also has configuration settings that may limit how long it will try to run a request before throwing a Naming exception.
- Post tab
  - Remove UID Prefix - For cases where LDAP uids include prefix characters that should be removed before creating the enportal userIDs. This attribute should seldom need to be used.
  - Remove UID Suffix - For cases where LDAP uids include domain info such as an email address. This enables the enPortal userid to only be the username portion of the email address. Example: jadams@company.com and uidSuffix="company.com" then the enPortal user name would be jadams.
Click Save. The new Domain adapter will be displayed under the Repository, with a special icon to indicate that it is an LDAP managed Domain.

Synching enPortal and LDAP

Once you have created enPortal Domain and Role adapters that are mapped to LDAP, you may want to execute a command to load Users from LDAP into enPortal.

There are two approaches for creating Users in enPortal from an external LDAP repository:

Lazy Load - This is an on-demand approach. When a User logs in to enPortal, enPortal queries LDAP for the User's information and then loads it into enPortal.
LDAP Sync - The LDAP Sync command is run by the enPortal administrator. It copies some or all of the Users and/or Roles from LDAP into enPortal as a batch process. It can be run one time on a new system, and can also be run at regular intervals, if desired.
- Advantages of using LDAP Sync
  - The enPortal administrator can see all of the Users in the enPortal user interface.
  - The enPortal administrator can provision content to Users in the enPortal user interface.

Perform the following steps to run LDAP Sync:

Log in to enPortal as an administrator
Under the Advanced tab, select Explore System
Click on the /Explorer/Directory/system/LDAPSync channel
Select the appropriate parameters for the sync
- Roles - Check the Roles box to only sync Roles but not Users. This can be useful in the case where you are using the Lazy Load method for loading Users, but you want to configure the Roles to have the appropriate assignments of Content, Look and Feel, etc.
- Update / Create / Delete - Check one of these boxes to identify what type of sync to run:
  - Update - run the creation and deletion syncronization scripts
  - Create - run only the creation synchronization scripts; will create in enPortal any new objects that are found in LDAP but not in enPortal
  - Delete - run only the deletion synchronization scripts; will delete from enPortal any objects that are found in enPortal but not in LDAP
Enter the name of the Repository which you want to sync. It must match the name of a Repository under the LDAP Repositories section.
Click “Start” to run the sync

Avoiding Sync Count Overload Issues

Of the options outlined above, it is generally recommended to sync the Roles and then use an on-demand sync to load users as they log in to the system. However, in some cases you may want to do a full sync of all users from LDAP into enPortal or AppBoard. In this case, care needs to be taken as it is not uncommon for LDAP to have settings that will timeout a large sync or disallow the synching of a large number of users at one time.

Perform the following steps to sync all users in a controlled manner:

Edit the file [INSTALL_HOME]\config\custom.properties. Create the file if it does not already exist for another purpose.
Add the following line:
ldap.pagingSupported=true
Save the file
Re-start enPortal/AppBoard
Re-run the LDAP Sync

Any sync commands will now use the count limits on the domain adapter and role adapter to run a set of queries that will retrieve a limited set of items on each query. This will avoid trying to sync all of the users at one time, which can cause the issues noted above.

Active Directory

Active Directory is a specific type of LDAP that is used by Microsoft Windows. As it is used in many customer environments, it is a fairly common type of LDAP directory that will need to be integrated. Please note the following special considerations when configuring LDAP for Active Directory:

Domain Adapter
- On the Domain Adapter settings (from the Explorer view, right click the domain and select Edit Adapter), in the Search tab, make sure the User Class and the User ID Attribute key are set to values matching your AD environment. Typically these might be "Person" and "sAMAccountName" respectively.
- Use the "ADSI Edit" utility on an Active Directory Server to view user attributes by right clicking an entry and selecting properties:
  - User ID Attribute key: in the list of attributes, find the attribute that contains the username. Note: there may be several options here depending on how your users log-in (e.g. "cn","sAMAccountName","userPrincipalName" -- match this to your specific environment).
  - User Class: in the list of attributes, find the attribute "objectCategory". The first CN listed in the value for "objectCategory" should be used for the User Class (e.g. if objectCategory value = "CN=Person,CN=Schema,CN=Configuration,DC=testlab,DC=it-status,DC=net" the first CN value listed is "Person"). This should be your value for User Class.
- You may also want to update your login form for your domain to prompt users for the right username format.
Role Adapter
- Change Role Class to "group"
- Change Domain/User assignment attribute key to "member"

LDAP With SSL

In some cases, an LDAP server will require a SSL connection. enPortal supports using LDAP with SSL. To incorporate SSL into the LDAP solution, perform the following two additional steps:

Specify ldaps:// and secured port in the connection details defined in the LDAPRepository that is registered.
Add the cert to the cacerts file in JAVA_HOME/lib/security (where JAVA_HOME is the Java runtime that enPortal is configured to run with). Some details on how to do this can be found at http://docs.oracle.com/javaee/1.4/tutorial/doc/Security6.html.

LDAP Configuration Case Study Example

Using the LazyLoad Process

In enPortal, you can use the "LazyLoad" process to create Portal users "On-Demand" so that when a user tries to log in to enPortal, the portal will contact LDAP and create this user and authenticate it.

You have a local ldap server running on ldap://laptop:10565
In dc=example-corp,dc=com you have created three users: jadams, jsmith, jtaylor within ou=people.
Create an ldapRepository pointing to the ldap server and give it credentials to login.
Create a domainAdapter "testOne". Since you do not have a RoleAdapter you need a way of associating roles to the users defined in this domain. So create a /HelpDesk role; and assign it as the defaultRole using the General tab; change the pluggable authenticator to "com.edgetech.eportal.session.impl.LDAPSessionAuthenticatorExtendedWithLazyLoad". Then switching to the Search tab you fill in Search Base ="ou=people,dc=example-corp,dc=com".
Save the changes.
Open a new browser (or log out of the existing portal session) and attempt to log in to the portal using: domain = "testOne", user = "jadams", password = "pw".
The portal then:
1. receives the request.
2. accesses LDAP to see if the user can authenticate. If there is a failure, it returns to the login page.
3. on auth success; checks to see if user is defined. If the user exists, skip the next step.
4. creates the user account in the testOne domain, if the user does not exist.
5. checks to see if the domain dn or user dn is has any ldap group assignments (this will only occur if RoleAdapters were defined for the LDAPRepository definition). Reset the role assignments.
6. checks to see if the user has a role assignment. If so, it looks up provisioned content and renders the page.

Making LDAP Groups Map to enPortal Roles

If the decision is made to use LDAP, you should also define Groups in LDAP that can be used to create roles in the portal. The following is a scenario:

Inside of ou=groups,dc=example-corp,dc=com
Create three Groups named: HelpDesk, Operator, and Manager.
Inside of these Groups edit the membership to assign Users to Groups.
Logging back into the portal, navigate to the LDAPRepository that was created and define a new RoleAdapter named "/MSP" (The fully qualified portal role). On the Search Base In enter "ou=groups,dc=example-corp,dc=com".
Then for each Group add the following memberships:
1. Manager assigned jadams as members.
2. Operator assigned jadams, jsmith as members.
3. HelpDesk assigned jadams, jsmith, jtaylor as members
Run portal ldapsync command and the roles /MSP/Manager, /MSP/Operator, and /MSP/HelpDesk are defined.
Provision some content (views / channels) to these roles.
Log out and then log in using: domain = "testOne", user = "jsmith", password = "pw".
The user will be logged in and they will have /portalAdministration, Operator and HelpDesk roles available. Note: it is recommended to remove /portalAdministration as the default role for the DomainAdapter.

Importing a User Without a Role Adapter Defined

It is possible to import a user without a Role adapter defined. However, a Role must be assigned to the user for the user to be able to log in to the system. The best way for the Role assignment to be made is for the Role assignment to be imported with the user.

Passing Single Sign-on Credentials to Applications

Sometimes you will want to set the Single Sign-on (SSO) configuration for products integrated into AppBoard/enPortal that are also using LDAP. The goal is to have AppBoard/enPortal pass the login credentials from LDAP to the back-end application, when the same credentials are used to access enPortal and the back-end application.

You can use the following expression when configuring the SSO token. It will pass the same credentials entered by the user logging in to AppBoard, to the backend application:

username: ${shim:session.credentials.username}
password: ${shim:session.credentials.password}

User Context 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.

Edit [INSTALL_HOME]/webapps/enportal/WEB-INF/custom.properties
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}