Enportal/5.4/admin/user administration/enPortal LDAP configuration

enPortal provides provisioning tools for managing Domains, Users, and Roles inside of enPortal. However, some organizations already have an LDAP server in place to manage Users and Roles. In this case, enPortal can map to the existing LDAP configuration and rely on LDAP for externally managing this information. This page provides instructions on configuring LDAP with enPortal.

Introduction to LDAP

Many modern applications make use of the same concepts of Users, Roles, and Domains that are used in AppBoard/enPortal. It is not efficient to replicate the same lists of Users, Domains, and Roles in each application. Also, such lists would be difficult to maintain and keep in sync with one another.

LDAP is Lightweight Directory Access Protocol. It provides a service for storing and managing directories of items such as Users and Roles. It also provides simple interfaces for applications to access this information. This enables an organization to store all of this information in one centralized location.

The LDAP Repository Explorer is a tool in enPortal for setting up Domains or Roles to be managed externally by an LDAP server.

Accessing LDAP Configuration in enPortal

Perform the following steps to access the LDAP Configuration screens in enPortal:

1. Log in to enPortal as an administrator.
2. Mouse over the Advanced tab and click Explore System. The Explorer panel is displayed.
3. Expand the main Explorer folder, and click on the LDAP Repositories folder.

Configuring LDAP Repositories

Perform the following steps to configure an LDAP Repository in enPortal:

1. Right click on LDAP Repositories and select New Repository.
2. In the panel on the right, fill in the following values under the General tab:
   • Repository Name - Enter the Repository Name. It is a unique name used to identify an LDAP Server that will be mapped into enPortal.
   • Repository URL - The URL where the LADP Repository can be accessed by enPortal. This URL will typically begin with "ldap://". Example: "ldap://192.168.155.165:389" or "ldaps://192.168.155.165:636" for ssl access
     • Note: Failover of repositories is also supported. Instead of entering one URL, you can enter multiple URLs separated by a space.
       • Example: ldap://192.168.155.165:389 ldap://192.168.155.276:389 ldap://192.168.155.387:389
       • Each time a user attempts to log in to enPortal in an LDAP-backed domain, enPortal will try the first Repository URL in the list. If it fails to connect to the LDAP Repository, it will try the second URL in the list, and so on.
   • Factory - The Java class used by JNDI to talk to the LDAP server. This is set by default to "com.sun.jndi.ldap.LdapCtxFactory".
   • Connection Timeout - Defines a fixed period of time to attempt to connect with the LDAP Server. This is typically only used in a redundant LDAP Server configuration. Enter the number of milliseconds to wait before aborting the connection attempt. The default value is 10,000.
   • LDAP Authentication User - Enter the Distinguished Name of the user with permission to log in and query the LDAP server. If unspecified, the anonymous account will be used. This account should have read-only access to the repository information needed for synchronization. Example: "uid=LimitedAdmin,ou=System,ou=Users,dc=private,dc=abc"
   • Password - Enter the Password of the user with permission to log in and query the LDAP server
   • Admin Access - If this box is unchecked, the Domains or Roles managed by the adapters in this Repository are set to ReadOnly via the admin user interface. Leaving this box unchecked prevents the following actions: Domain deletion, User creation, User deletion, Role creation, and Role deletion.
   • Authentication Type - Type of authentication that is used by the LDAP Server. This is set by default to "simple" and should not be modified.
3. Click Save. The new LDAP repository will be displayed under LDAP Repositories.

Configuring LDAP Managed Roles

In order to define the enPortal Roles that are mapped from LDAP, you must create a Role adapter. This defines the name of the root enPortal Role in which LDAP-managed Roles are created. Perform the following steps to configure LDAP-managed Roles in enPortal:

1. Create an LDAP Repository.
2. Right-click on the repository name and select New Role Adapter.
3. In the panel on the right, enter the following values for the Role adapter:
   • Fully qualified portal role - Identifies the name of the Role in which LDAP-managed Roles are to be created in enPortal. Example: /myLdapRoles
   • Search Base - Identifies a unique node in an LDAP Directory resource to perform the search for LDAP Groups that will map to enPortal Roles. This does not include the host, port, and baseURL identified by LDAPDefinition element. Example: "ou=Solutions,ou=Applications,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: "One Level"
   • Search Filter - Defines a filter for retrieving users from the LDAP repository. Example: "ou=company.com"
   • Role ID Attribute Key - The LDAP attribute of the LDAP Group that identifies the enPortal Role name. Example: "cn"
   • Role Class - Allows a filter to be placed on the type of LDAP objects (Groups) that are to be interpreted as intended enPortal Roles. Example: "groupOfUniqueNames"
   • Domain/User Assignment Attribute Key - The LDAP attribute that assigns the LDAP-managed Roles to Users and/or Domains. Example: "uniquemember"
   • Max Number of Roles to Import - The largest number of Roles to import from the LDAP Repository into enPortal. This can be used when testing against a Repository with a large number of Roles. 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.
4. Click Save. The new Role adapter will be displayed under the Repository, with a special icon to indicate that it is an LDAP managed Role.

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:

1. Create an LDAP Repository.
2. Right-click on the repository name and select New Domain Adapter.
3. 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.
4. 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:

1. 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.
2. 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:

1. Log in to enPortal as an administrator
2. Under the Advanced tab, select Explore System
3. Click on the /Explorer/Directory/system/LDAPSync channel
4. 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
5. Enter the name of the Repository which you want to sync. It must match the name of a Repository under the LDAP Repositories section.
6. 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:

1. Edit the file [INSTALL_HOME]\config\custom.properties. Create the file if it does not already exist for another purpose.
2. Add the following line:

   ldap.pagingSupported=true

3. Save the file
4. Re-start enPortal/AppBoard
5. 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:

1. Specify ldaps:// and secured port in the connection details defined in the LDAPRepository that is registered.
2. 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.

1. You have a local ldap server running on ldap://laptop:10565
2. In dc=example-corp,dc=com you have created three users: jadams, jsmith, jtaylor within ou=people.
3. Create an ldapRepository pointing to the ldap server and give it credentials to login.
4. 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".
5. Save the changes.
6. 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".
7. 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:

1. Inside of ou=groups,dc=example-corp,dc=com
2. Create three Groups named: HelpDesk, Operator, and Manager.
3. Inside of these Groups edit the membership to assign Users to Groups.
4. 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".
5. 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
6. Run portal ldapsync command and the roles /MSP/Manager, /MSP/Operator, and /MSP/HelpDesk are defined.
7. Provision some content (views / channels) to these roles.
8. Log out and then log in using: domain = "testOne", user = "jsmith", password = "pw".
9. 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.

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}