Enportal/5.6/admin/user administration/ldap configuration - Revision history

imported>Jason.nicholls: /* Note on Legacy LDAP Servers */

2015-06-16T15:14:39Z

Note on Legacy LDAP Servers

← Older revision		Revision as of 15:14, 16 June 2015
Line 220:		Line 220:

	# Edit or create: <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/custom.properties</tt>		# Edit or create: <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/custom.properties</tt>
	# Add ~~the following on~~ a new line: <tt>ldap.policyControlSupported=false</tt>		# Add a new line with the following: <tt>ldap.policyControlSupported=false</tt>
	# Restart enPortal.		# Restart enPortal.

imported>Jason.nicholls: /* Note on Legacy LDAP Servers */

2015-06-16T15:14:19Z

Note on Legacy LDAP Servers

← Older revision		Revision as of 15:14, 16 June 2015
Line 219:		Line 219:
	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:		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~~ <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/custom.properties</tt> ~~and add~~ the line <tt>ldap.policyControlSupported=false</tt>		# Edit or create: <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/custom.properties</tt>
			# Add the following on a new line: <tt>ldap.policyControlSupported=false</tt>
	# Restart enPortal.		# Restart enPortal.

imported>Jason.nicholls: /* Note on Case Sensitivity */

2015-06-16T15:13:23Z

Note on Case Sensitivity

← Older revision		Revision as of 15:13, 16 June 2015
Line 206:		Line 206:
	enPortal accounts are case sensitive, however most LDAP ''searches'' for usernames are case '''in-sensitive''' depending on the LDAP schema. To prevent duplicate accounts being created in enPortal if a user happens to log in multiple times with different case the LDAP adapters behave in this way:		enPortal accounts are case sensitive, however most LDAP ''searches'' for usernames are case '''in-sensitive''' depending on the LDAP schema. To prevent duplicate accounts being created in enPortal if a user happens to log in multiple times with different case the LDAP adapters behave in this way:

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

imported>Jason.nicholls: /* Note on Case Sensitivity */

2015-06-16T14:55:28Z

Note on Case Sensitivity

← Older revision		Revision as of 14:55, 16 June 2015
Line 209:		Line 209:
	* If using a Lazy Load LDAP authenticator it will also use the returned case from LDAP when creating new enPortal accounts.		* If using a Lazy Load LDAP authenticator it will also use the returned case from LDAP when creating new enPortal accounts.

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

	# Edit or create: <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/custom.properties</tt>		# Edit or create: <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/custom.properties</tt>

imported>Jason.nicholls: /* Note on Case Sensitivity */

2015-06-16T14:53:53Z

Note on Case Sensitivity

← Older revision		Revision as of 14:53, 16 June 2015
Line 204:		Line 204:
	==== Note on Case Sensitivity ====		==== 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.~~		enPortal accounts are case sensitive, however most LDAP ''searches'' for usernames are case '''in-sensitive''' depending on the LDAP schema. To prevent duplicate accounts being created in enPortal if a user happens to log in multiple times with different case the LDAP adapters behave in this way:

	~~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.6/~~admin~~/~~system_administration/System_Settings~~#~~System_Login_Page\|System Login Page]] documentation for more information~~.		* Regardless of the case entered by the user on the login form, enPortal will use the case as returned from LDAP. For example, if a user logs in as "Joe.Bloggs" but the user is actually "joe.bloggs" in LDAP, then authentication will still succeed (assuming the password is correct) and enPortal will use the returned case of "joe.bloggs" as the User Name.
			* If using a Lazy Load LDAP authenticator it will also use the returned case from LDAP when creating new enPortal accounts.

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

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

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

imported>Jason.nicholls: 1 revision

2015-04-30T11:18:24Z

1 revision

← Older revision	Revision as of 11:18, 30 April 2015
(No difference)

imported>Jason.nicholls: /* Legacy LDAP Servers */

2015-04-23T07:13:08Z

Legacy LDAP Servers

New page

[[Category:enPortal 5.6]]
{{DISPLAYTITLE:LDAP Configuration}}
== Overview ==

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

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

For more information in general about authentication domains, users, and roles refer to the [[enportal/5.6/admin/user_administration/enPortal_provisioning|Provisioning]] documentation. Understanding how the default provisioning model works before trying to configure LDAP will make things easier.

== Supported LDAP Servers ==

{{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"
!Product
!Support Pass Change
!Legacy
!Notes
|-
| [[enportal/5.6/admin/user_administration/ldap_configuration/active_directory|Microsoft Active Directory (AD)]]
| yes <tt>*</tt>
| -
|
|-
| OpenLDAP
| yes <tt>*</tt>
| -
|
|-
| OpenDS
| yes <tt>*</tt>
| -
|
|-
| Sun ONE Directory Server
| yes <tt>*</tt>
| yes
| 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.

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

[[File:enportal-5.5-ldap-repositories.png|frame|center|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.

{|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) ====

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.6/admin/enPortal_installation/installation/runtime_options|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.

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

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

{|class="wikitable"
!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:
* <tt>com.edgetech.eportal.session.impl.LDAPSessionAuthenticator</tt>: Default generic authenticator. This does ''not'' support password changes or lazy loading.
* <tt>com.edgetech.eportal.session.impl.LDAPSessionAuthenticatorWithLazyLoad</tt>: As above with lazy load support.
* <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.
* <tt>com.edgetech.eportal.session.impl.ActiveDirectoryAuthenticatorWithLazyLoad</tt>: 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 ====

{|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 ====

{|class='wikitable'
!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 <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>.
|}

==== 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 [[enportal/5.6/admin/system_administration/System_Settings#System_Login_Page|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:

# edit <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/custom.properties</tt> and add the line <tt>ldap.policyControlSupported=false</tt>
# 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:

# Right-click on ''LDAP Repositories'' in the ''Explorer'' tree
# Select ''Sync LDAP''
# By default only roles are synchronized. Un-check the ''Roles Only'' checkbox to also sync users.
# Select the appropriate ''Option'' to determine the sync behaviour.
# The ''Repositories'' field can be used to limit the sync to a specific repository, enter the repository name in this field.
# 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 <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.6/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.

Examples:

# Perform a role-only sync for all repositories: <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: <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>: <tt>$ curl -c cookies.txt -o out.txt <nowiki>"http://localhost:8080/enportal/servlet/pd/?login=yes&userid=administrator&password=administrator&domainSelect=System"</nowiki> $ 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>

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

# Edit <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/config/custom.properties</tt> and add the line <tt>ldap.pagingSupported=true</tt>.
# Edit the domain and/or role adapters and enable ''Maximum Users/Roles''. Set a value which represents the maximum number of results per query.
# 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.

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

{{Note|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: <tt>${shim:session.var.userInfo.key.email}</tt>
* phone: <tt>${shim:session.var.userInfo.key.phone}</tt>
* branch: <tt>${shim:session.var.userInfo.key.branch}</tt>

== Additional Information ==

* [[enportal/5.6/admin/user_administration/ldap_configuration/tutorial|LDAP Tutorial]]