Using LDAP for User Authentication Product version: 4.60 Document version: 1.0 Document creation date: 31-03-2006 Purpose This technical note describes how to configure and set up EPiServer to use an LDAP server for user authentication. This is an advanced operation and good knowledge of your LDAP environment is required. TECHNICAL NOTE
2 Using LDAP for User Authentication Table of Contents REQUIREMENTS 2 INITIAL SETUP TO USE ACTIVE DIRECTORY 2 INITIAL SETUP TO USE EDIRECTORY 3 IMPORT GROUPS FROM LDAP SERVER 3 USING LDAP ACCOUNTS FOR EDITORS AND ADMINISTRATORS 4 ADVANCED CONFIGURATION OPTIONS 4 SYNCHRONIZING VALUES FROM AN LDAP SOURCE 5 ADDING SYNCHRONIZATION SETTINGS... 5 ACTIVE DIRECTORY AUTHENTICATION 6 Requirements EPiServer 4.0.0.20 or later running on Windows 2000 Server or later. EPiServer uses the native Windows LDAP APIs introduced in Windows 2000 and does not run on earlier versions of Windows. A Windows Active Directory (AD) server and an account with read/browse rights to the Active Directory. - or - A Novell edirectory version 8.5 or later and an account with read/browse rights to the entire edirectory. Initial Setup to Use Active Directory Open web.config, which is in the root folder of your EPiServer installation, and modify the following settings under configuration/appsettings. See Advanced Configuration Options for more information. Key EPsLdapServer EPsLdapDomain EPsLdapUser EPsLdapPassword EPsLdapRootContext Value The DNS name or IP address of the AD domain, for example company.com. The domain of the account that you want to use to access information from your AD, for example MyDomain. If you are using simple authentication, this should be left blank. The username of the account that you want to use to access information from your AD, for instance MyUser (If you are using simple authentication this should be MyDomain\MyUser). This account should have read/browse access to the entire tree. Note The role Account Operators should have sufficient access rights in the AD. The password for the account that you want to use to access information from your AD. The root of the AD domain. Using the same example as before (company.com) it should be dc=company,dc=com.
Initial Setup to Use edirectory 3 EPnLdapAuthenticationType 1158 EPfLdapAuthenticateWithBind True EPsLdapServerType Set this parameter to AD if you use AuthenticationMode = Windows. This will enable check of LDAP group membership event for Windows accounts. Note This does not work in EPiServer 4.21 and previous versions. Initial Setup to Use edirectory Open web.config, which is in the root folder of your EPiServer installation, and modify the following settings under configuration/appsettings. See Advanced Configuration Options for more information. Key EPsLdapServer EPsLdapDomain EPsLdapUser EPsLdapPassword EPsLdapRootContext Value The DNS name or IP address of the AD domain, for example company.com. Empty An account that has read/browse rights to the edirectory, for instance cn=ldapbrowser,o=company. Note You must enter the account name as a fully qualified LDAP name. The more common "dotted notation" usually used with NDS/eDirectory will not work. The password for the account that you want to use to access information from your edirectory. Empty EPnLdapAuthenticationType 128 EPfLdapAuthenticateWithBind False Import Groups from LDAP Server To be able to fully utilize the LDAP server for authentication, you need to import the groups / organizational units (OU) that you want to use for controlling access to EPiServer. If you skip this step, you will still be able to use accounts from the LDAP server, but they will only belong to the group "Everyone" from EPiServer s point-of-view. Note In AD, a group that is used in EPiServer and is defined as Primary Group for a user cannot be retrieved when EPiServer queries LDAP for group membership. Normally this means that you can import a primary group (such as Domain Users) to EPiServer, but an LDAP user that has this group as primary group will not act as a member of this group in EPiServer. How to import groups: 1. Log on and go to Admin mode. 2. Select Administer groups under Access rights. 3. In the text area above the Import from LDAP server button, enter a search expression to retrieve a list of groups/ous from the LDAP server. The search expression should usually be in the form prefix*, where prefix will match the beginning of a group name or OU. If the search expression is left blank, all groups
4 Using LDAP for User Authentication will be returned. Note that this can take a long time and may fail if excessive amounts of data are returned. 4. Click Import from LDAP server to retrieve a group list. 5. Select the groups that you want to import and click Save. You can now use the imported groups to set access rights for pages in EPiServer. Note Previously selected groups should be selected as default when you make a new search. Using LDAP Accounts for Editors and Administrators If you want to use LDAP accounts for Editors and Administrators, you need to perform additional configuration changes in web.config. In the following example we assume that the following groups have been imported: "EPiServerAdmins-Users-company-com" (actual LDAP name is CN=EPiServerAdmins,CN=Users,DC=company,DC=com) "EPiServerEditors-Users-company-com" (actual LDAP name is CN=EPiServerEditors,CN=Users,DC=company,DC=com) All LDAP accounts that belong to the EPiServerAdmins group should have access to Admin mode, and accounts belonging to EPiServerEditors should have access to the Edit mode. In web.config, locate the section <location path="admin"> and the contained tag that reads <allow roles="webadmins, Administrators" />. Change this tag to <allow roles="webadmins, Administrators, EPiServerAdmins-Users-company-com" />. Note To access the system settings, you must use a Windows account that has local Administrator privileges on the Web server. In web.config, locate the section <location path="edit"> and the contained tag that reads <allow roles=" WebAdmins, WebEditors, Administrators" />. Change this tag to <allow roles=" WebAdmins, WebEditors, Administrators, EPiServerEditors-Users-company-com " />. This change is enough to give users access to the Edit mode, but to be allowed to edit pages you must set the correct access rights for the pages that they should be allowed to edit. Advanced Configuration Options This is a description of the LDAP configuration settings in web.config. EPsLdapServer EPsLdapDomain EPsLdapUser EPsLdapPassword EPsLdapRootContext Host name of LDAP server or the name of the Active Directory domain. If you are using an AD domain, it is highly recommended to use the domain name to take advantage of failover functions, etc. For example "ldap.microsoft.com" or "192.168.12.23". Should be set to the domain of the user if you are using Negotiate authentication. If you are using simple authentication, this should be left blank. A user that has read/browse rights to the entire tree where you want to authenticate. Password for EPsLdapUser If you want to limit the scope of group searches, set this parameter to the desired starting point. For ActiveDirectory sites, you must set this
Synchronizing Values From an LDAP Source 5 parameter to the root (or somewhere below the root). Otherwise searches will be performed against schema data. For the ActiveDirectory domain company.com, the root context should be "dc=company,dc=com". EPnLdapAuthenticationType A numeric value to select the authentication type. Possible values are: 128 = Simple authentication, i e clear text. 1158 = Negotiate authentication. Add 131072 to force communication over SSL. EPfLdapAuthenticateWithBind If your LDAP server does not support the ldap_compare command to check passwords, set to True to use a second Bind to provide the authentication service. The ldap_compare is a much faster operation than performing a bind so you should set this parameter to False if possible. EPsLdapServerType For AD, set this parameter to AD if you use AuthenticationMode = Windows. This will enable check of LDAP group membership event for Windows accounts. Note This does not work in EPiServer 4.21 and previous versions. Synchronizing Values From an LDAP Source From EPiServer 4.51 it is possible to synchronize values from an LDAP source. This functionality is included in the standard built-in provider for LDAP in EPiServer. When a user is logged in with the LDAP provider, the values are synchronized with the LDAP source according to the synchronization settings in web.config. When the user has been logged in, the cache provider handles the login and no calls are made to the LDAP server. The user settings will then be synchronized every time the LDAP provider logs in the user; this can occur if the process is restarted, the cache times out or the user logs out and in again. Adding Synchronization Settings To activate synchronization via LDAP, add the following to web.config, under the configuration section. <configuration> <configsections> <sectiongroup name="episerver"> <section name="ldapsync" type="system.configuration.namevaluesectionhandler, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" /> </sectiongroup> </configsections> <episerver> <ldapsync> <add key="givenname" value="personalfirstname" /> <add key="sn" value="personallastname" /> <add key="mail" value="personalemail" /> <add key="company" value="personalcompany" /> </ldapsync> </episerver>... </configuration>
6 Using LDAP for User Authentication The ldapsync section allows you to map the values from LDAP that should be mapped to a property for the user in EPiServer. It is possible to map to any appropriate values in EPiServer. The built-in metadata for the user has Personal as prefix, e.g. PersonalLanguage. The following metadata is available: (PersonalUserName)* PersonalFirstName PersonalLastName PersonalTitle PersonalDescription PersonalEmail PersonalCompany PersonalAddress PersonalPostalAddress PersonalPostalNumber PersonalTelephone PersonalMobile PersonalLanguage PersonalCountry Note The above values apply to EPiServer. Refer to the documentation for your LDAP provider for those values. Active Directory Authentication Using the LDAP support in EPiServer for connecting to Active Directory (AD) is no longer the recommended way to do Active Directory integration. The primary reason for this is performance using Windows Authentication against AD is much faster than doing LDAP authentication. You should use the LDAP authentication support only if you need to set access rights based on OUs (i.e. structural information in AD). For further information on this, see the appendix in the technical note "Security in EPiServer". Copyright ElektroPost Stockholm AB. ElektroPost and EPiServer are registered trademarks of ElektroPost Stockholm AB. Other product and company names mentioned in this document may be the trademarks of their respective owners. The document may be freely distributed in its entirety, either digitally or in printed format, to all EPiServer users. Changes to the content or partial copying of the content may not be carried out without permission from ElektroPost Stockholm AB: ElektroPost Stockholm AB Finlandsgatan 38 SE-164 74 Kista Sweden Changes are periodically made to the document and these will be published in new editions of the document. ElektroPost reserves the right to improve or change the products or programs included in this document at any time.