Enportal/5.5/admin/user administration/ldap configuration: Difference between revisions

imported>Jason.nicholls
imported>Jason.nicholls
 
(41 intermediate revisions by 2 users not shown)
Line 11: Line 11:
== Supported LDAP Servers ==
== Supported LDAP Servers ==


{{Note|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.}}
{{Note|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.}}


{|class="wikitable"
{|class="wikitable"
Line 19: Line 19:
!Notes
!Notes
|-
|-
| Microsoft Active Directory (AD)
| [[enportal/5.5/admin/user_administration/ldap_configuration/active_directory|Microsoft Active Directory (AD)]]
| yes
| yes <tt>*</tt>
| -
| -
|
|
|-
|-
| OpenLDAP
| OpenLDAP
| yes
| yes <tt>*</tt>
| -
|
|-
| OpenDS
| yes <tt>*</tt>
| -
| -
|
|
|-
|-
| Sun ONE Directory Server
| Sun ONE Directory Server
| yes
| yes <tt>*</tt>
| yes
| yes
| replaced by Sun Java System Directory Server
| replaced by Sun Java System Directory Server
|}
|}
<tt>*</tt> For enPortal to support password changes the appropriate ''pluggable authenticator'' needs to be configured on the LDAP Domain Adapter.


== Accessing LDAP Configuration in enPortal ==
== 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.


Perform the following steps to access the LDAP Configuration screens in enPortal:
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:


# Log in to enPortal as an administrator.
[[File:enportal-5.5-ldap-repositories.png|frame|center|Managing LDAP configuration]]
# Mouse over the <b>Advanced</b> tab and click <b>Explore System</b>. The <b>Explorer</b> panel is displayed.
# Expand the main <b>Explorer</b> folder, and click on the <b>LDAP Repositories</b> folder.


=== LDAP Repositories ===


== Configuring 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.


Perform the following steps to configure an LDAP Repository in enPortal:
{|class="wikitable"
!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 <tt>ldap://''directory_server'':389</tt> or <tt>ldaps://''directory_server'':636</tt> 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: <tt>cn=Manager,dc=edgeti,dc=com</tt>
|-
|'''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) ====


# Right click on <b>LDAP Repositories</b> and select <b>New Repository</b>.
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 [[enportal/5.5/admin/enPortal_installation/installation/runtime_options|Runtime Options]].
# In the panel on the right, fill in the following values under the <b>General</b> tab:
#* <b>Repository Name</b> - Enter the Repository Name. It is a unique name used to identify an LDAP Server that will be mapped into enPortal.
#* <b>Repository URL</b> - 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.
#* <b>Factory</b> - The Java class used by JNDI to talk to the LDAP server. This is set by default to "com.sun.jndi.ldap.LdapCtxFactory".
#* <b>Connection Timeout</b> - 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.
#* <b>LDAP Authentication User</b> - 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"
#* <b>Password</b> - Enter the Password of the user with permission to log in and query the LDAP server
#* <b>Admin Access</b> - 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.
#* <b>Authentication Type</b> - Type of authentication that is used by the LDAP Server. This is set by default to "simple" and should not be modified.
# Click <b>Save</b>. The new LDAP repository will be displayed under <b>LDAP Repositories</b>.


== Configuring LDAP Managed Roles ==
=== 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.


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:
{|class="wikitable"
!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: <tt>/myLDAProles</tt>. 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: <tt>ou=Groups,dc=edgeti,dc=com</tt>
|-
|'''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: <tt>cn</tt>.
|-
|'''Role Class'''
|Only objects of this class are used, for example <tt>posixGroup</tt> or <tt>groupOfUniqueNames</tt>.
|-
|'''Domain/User assignment attribute key'''
|This LDAP attribute is what's used to assign users into the role - i.e. the usernames. For example: <tt>memberUid</tt> or <tt>uniqueMember</tt>.
|-
|'''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.
|}


# Create an LDAP Repository.
=== LDAP Domain Adapters ===
# Right-click on the repository name and select <b>New Role Adapter</b>.
# In the panel on the right, enter the following values for the Role adapter:
#* <b>Fully qualified portal role</b> - Identifies the name of the Role in which LDAP-managed Roles are to be created in enPortal. Example: /myLdapRoles
#* <b>Search Base</b> - 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"
#* <b>Search Scope</b> - 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"
#* <b>Search Filter</b> - Defines a filter for retrieving users from the LDAP repository. Example: "ou=company.com"
#* <b>Role ID Attribute Key</b> - The LDAP attribute of the LDAP Group that identifies the enPortal Role name. Example: "cn"
#* <b>Role Class</b> - Allows a filter to be placed on the type of LDAP objects (Groups) that are to be interpreted as intended enPortal Roles. Example: "groupOfUniqueNames"
#* <b>Domain/User Assignment Attribute Key</b> - The LDAP attribute that assigns the LDAP-managed Roles to Users and/or Domains. Example: "uniquemember"
#* <b>Max Number of Roles to Import</b> - 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.
#* <b>Max Search Time</b> - 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.
# Click <b>Save</b>. 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 ==
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:


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:
==== General ====


# Create an LDAP Repository.
{|class="wikitable"
# Right-click on the repository name and select <b>New Domain Adapter</b>.
!Field
# In the panel on the right, enter the following values for the Domain adapter:
!Description
#* <b>General</b> tab
|-
#** <b>Default Portal Domain</b> - The enPortal Domain name to assign to this Domain.
|'''Name'''
#** <b>Default Portal Role</b> - The enPortal Role to assign to this Domain. All users in this Domain will inherit this Role assignment.
|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.
#** <b>Session Lease</b> - 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.
|-
#** <b>Session Extension</b> - 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.
|'''Default Role'''
#** <b>Pluggable Authenticator</b> -  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:
|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.
#*** <tt>com.edgetech.eportal.session.impl.LDAPSessionAuthenticatorWithLazyLoad</tt> - use this class when accessing non-Microsoft LDAP.
|-
#*** <tt>com.edgetech.eportal.session.impl.LDAPSessionAuthenticatorExtendedWithLazyLoad</tt> - use this class when accessing non-Microsoft LDAP. Password change is possible with this authenticator if the LDAP is OpenDS based.
|'''Session Expiry'''
#*** <tt>com.edgetech.eportal.session.impl.ActiveDirectoryAuthenticatorWithLazyLoad</tt> - use this class when accessing Microsoft Active Directory. Password change is possible with this authenticator.
|This can be used to override the system default inactivity timeout for users within this domain.
#** <b>Authentication Type</b> - Type of authentication that is used by the LDAP Server. Example: "simple"
|-
#* <b>Search</b> tab
|'''Session Extension'''
#** <b>Search Base</b> - 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"
|Used in conjunction with above to extend a session when a user is active in the system.
#** <b>Search Scope</b> - 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
|-
#** <b>Search Filter</b> - Defines a filter for retrieving users from the LDAP repository. Example: "mail=*company.com"
|'''Pluggable Authenticator'''
#** <b>User ID Attribute Key</b> - The LDAP attribute of the user object that identifies the user name. Example: "mail"
|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:
#** <b>User Class</b> - Allows a filter to be placed on the type of LDAP objects that are interpreted as enPortal Users. Example: "inetOrgPerson"
* <tt>com.edgetech.eportal.session.impl.LDAPSessionAuthenticator</tt>: Default generic authenticator. This does ''not'' support password changes or lazy loading.
#** <b>Max Number of Users to Import</b> - 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.
* <tt>com.edgetech.eportal.session.impl.LDAPSessionAuthenticatorWithLazyLoad</tt>: As above with lazy load support.
#** <b>Max Search Time</b> - 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.
* <tt>com.edgetech.eportal.session.impl.LDAPSessionAuthenticatorExtendedWithLazyLoad</tt>: 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.
#* <b>Post</b> tab
* <tt>com.edgetech.eportal.session.impl.ActiveDirectoryAuthenticatorWithLazyLoad</tt>: Specific authenticator for Microsoft Active Directory which supports both password changes and lazy load.
#** <b>Remove UID Prefix</b> - 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.
|-
#** <b>Remove UID Suffix</b> - 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.
|'''Authentication Type'''
# Click <b>Save</b>. The new Domain adapter will be displayed under the Repository, with a special icon to indicate that it is an LDAP managed Domain.
|Do not change this unless instructed by support.
|}


== Synching enPortal and LDAP ==
==== Search ====


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.
{|class="wikitable"
!Field
!Description
|-
|'''Search Base'''
|Identifies a unique node in the directory server to perform the search for LDAP users. For example: <tt>ou=People,dc=edgeti,dc=com</tt>
|-
|'''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: <tt>uid</tt>.
|-
|'''User Class'''
|Only objects of this class are used, for example <tt>inetOrgPerson</tt>.
|-
|'''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 ====


There are two approaches for creating Users in enPortal from an external LDAP repository:
{|class='wikitable'
# 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.
!Field
# 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.
!Description
#* Advantages of using LDAP Sync
|-
#** The enPortal administrator can see all of the Users in the enPortal user interface.
|'''Remove UID Prefix'''
#** The enPortal administrator can provision content to Users in the enPortal user interface.
|For cases where LDAP usernames include prefix characters that should be removed before creating enPortal User Names.
 
|-
 
|'''Remove UID Suffix'''
Perform the following steps to run LDAP Sync:
|For cases where LDAP usernames include suffix characters that should be removed before creating enPortal User Names. For example: the LDAP username may be <tt>jadams@company.com</tt> and setting this field to <tt>@company.com</tt> would result in an enPortal User Name of <tt>jadams</tt>.
 
|}
# 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
#* <b>Roles</b> - Check the <b>Roles</b> 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.
#* <b>Update / Create / Delete</b> - Check one of these boxes to identify what type of sync to run:
#** <b>Update</b> - run the creation and deletion syncronization scripts
#** <b>Create</b> -  run only the creation synchronization scripts; will create in enPortal any new objects that are found in LDAP but not in enPortal
#** <b>Delete</b> -  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 <b>LDAP Repositories</b> section.
# Click “Start” to run the sync


==== Note on Case Sensitivity ====


=== Avoiding Sync Count Overload Issues ===
enPortal accounts are case sensitive, however most LDAP searches for usernames are case '''in-sensitive''' depending on the LDAP schema. As a result it may be possible for a user to end up with multiple enPortal accounts if they log in using different case. Having duplicate enPortal accounts may also result in some issues with LDAP Role Adapters.


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.
Therefore it is recommended to normalize the account names used by enPortal to ensure consistency. This can be accomplished using a custom login page to convert usernames entered to all lowercase or uppercase. Refer to the [[enportal/5.5/admin/system_administration/System_Settings#System_Login_Page|System Login Page]] documentation for more information.


==== Note on Legacy LDAP Servers ====


Perform the following steps to sync all users in a controlled manner:
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:


# Edit the file [INSTALL_HOME]\config\custom.properties.  Create the file if it does not already exist for another purpose.
# edit <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/custom.properties</tt> and add the line <tt>ldap.policyControlSupported=false</tt>
# Add the following line:
# Restart enPortal.
#: <tt>ldap.pagingSupported=true</tt>
# Save the file
# Re-start enPortal/AppBoard
# Re-run the LDAP Sync


=== Synching enPortal and LDAP ===


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


== Active Directory ==
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.


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:
To perform an LDAP sync:


* '''Domain Adapter'''<br><br>
# Right-click on ''LDAP Repositories'' in the ''Explorer'' tree
** 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.<br><br>
# Select ''Sync LDAP''
** Use the "ADSI Edit" utility on an Active Directory Server to view user attributes by right clicking an entry and selecting ''properties'':<br><br>
# By default only roles are synchronized. Un-check the ''Roles Only'' checkbox to also sync users.
***''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).<br><br>
# Select the appropriate ''Option'' to determine the sync behaviour.
***''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''.<br><br>
# The ''Repositories'' field can be used to limit the sync to a specific repository, enter the repository name in this field.
** You may also want to update your login form for your domain to prompt users for the right username format.<br><br>
# Click the ''Start'' button.
* '''Role Adapter'''<br><br>
** Change ''Role Class'' to "group"<br><br>
** Change ''Domain/User assignment attribute key'' to "member"<br><br>


== LDAP With SSL ==
==== Automated Syncing ====


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:
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 <tt>cron</tt> on Linux/UNIX systems). Please note for this to work a valid session must be established with enPortal first. Refer to the [[enportal/5.5/admin/accessing_enportal#Login_Credentials|Accessing enPortal]] documentation for the information on authenticating via GET or POST.


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


# Specify ldaps:// and secured port in the connection details defined in the LDAPRepository that is registered.
Examples:
# 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 ==
# Perform a role-only sync for all repositories:<br><tt>/enportal/servlet/pd/vdir/system/LDAPSync?Submit=true&roles=on&syncAction=u&repositories=</tt>
# Perform role and user sync for only the "myLDAP" repository:<br><tt>/enportal/servlet/pd/vdir/system/LDAPSync?Submit=true&syncAction=u&repositories=myLDAP</tt>
# End-to-end example with authentication and role-only sync using <tt>curl</tt>:<br><tt>$ curl -c cookies.txt -o out.txt <nowiki>"http://localhost:8080/enportal/servlet/pd/?login=yes&userid=administrator&password=administrator&domainSelect=System"</nowiki><br>$ curl -b cookies.txt -o out.txt <nowiki>"http://localhost:8080/enportal/servlet/pd/vdir/system/LDAPSync?Submit=true&roles=on&syncAction=u&repositories="</nowiki></tt>


=== Using the LazyLoad Process ===
==== Directory Server Limits ====


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.
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):


# You have a local ldap server running on ldap://laptop:10565
# Edit <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/custom.properties</tt> and add the line <tt>ldap.pagingSupported=true</tt>.
# In dc=example-corp,dc=com you have created three users: jadams, jsmith, jtaylor within ou=people.
# Edit the domain and/or role adapters and enable ''Maximum Users/Roles''. Set a value which represents the maximum number of results per query.
# Create an ldapRepository pointing to the ldap server and give it credentials to login.
# Restart enPortal.
# 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:
## receives the request.
## accesses LDAP to see if the user can authenticate.  If there is a failure, it returns to the login page.
## on auth success; checks to see if user is defined.  If the user exists, skip the next step.
## creates the user account in the testOne domain, if the user does not exist.
## 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.
## checks to see if the user has a role assignment.  If so, it looks up provisioned content and renders the page.


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.


=== Making LDAP Groups Map to enPortal Roles ===
== Session Variables from LDAP ==
 
 
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:
## Manager assigned jadams as members.
## Operator assigned jadams, jsmith as members.
## 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:
 
* <b>username</b>: ${shim:session.credentials.username}
* <b>password</b>: ${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.
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.
Line 259: Line 274:
The following syntax shows how these variables can be accessed via SHIM expressions:
The following syntax shows how these variables can be accessed via SHIM expressions:


* <b>email</b>: ${shim:session.var.userInfo.key.email}
* <b>email</b>: <tt>${shim:session.var.userInfo.key.email}</tt>
* <b>phone</b>: ${shim:session.var.userInfo.key.phone}
* <b>phone</b>: <tt>${shim:session.var.userInfo.key.phone}</tt>
* <b>branch</b>: ${shim:session.var.userInfo.key.branch}
* <b>branch</b>: <tt>${shim:session.var.userInfo.key.branch}</tt>
 
== Additional Information ==
 
* [[enportal/5.5/admin/user_administration/ldap_configuration/tutorial|LDAP Tutorial]]

Latest revision as of 07:13, 23 April 2015


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

Template-note.png
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. As a result it may be possible for a user to end up with multiple enPortal accounts if they log in using different case. Having duplicate enPortal accounts may also result in some issues with LDAP Role Adapters.

Therefore it is recommended to normalize the account names used by enPortal to ensure consistency. This can be accomplished using a custom login page to convert usernames entered to all lowercase or uppercase. Refer to the System Login Page documentation for more information.

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 [INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/custom.properties and add the line ldap.policyControlSupported=false
  2. 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
Template-note.png
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