Active Directory Module AD Module Administrator's Guide Rev. 090923 Active Directory Module Administrator's Guide Installation, configuration and usage of the AD module
Table of Contents Chapter 1 Introduction... 4 Chapter 2 Installation and Configuration... 5 2.1 Installing Sitecore package... 6 2.2 Web.config Modifications... 7 2.3 Firewall modification... 8 2.3.1 Adding a Connection String to the Active Directory domain... 8 2.3.2 Configuring the ASP.NET security providers... 9 Chapter 3 Basic Scenarios... 13 3.1 Managing Roles and Users... 14 3.1.1 Creating users/roles... 14 3.1.2 User Specific Operations... 14 Chapter 4 Advanced Profile Configuration... 15 4.1 Configuring the profile provider... 16 4.2 Configuring the Custom Properties... 17 4.3 Extending the Sitecore Template... 18 4.4 Mapping Active Directory Display Name attribute to the Full Name property in Sitecore.. 20 Chapter 5 Features... 21 5.1 Single Sign-on... 22 5.1.1 Prerequisites... 22 5.1.2 Feature Usage... 24 5.2 Status Page... 27 5.3 Debug Mode... 29 5.4 Connecting to multiple domains... 30 5.5 Cache settings... 31 5.6 Additional LDAP.config settings... 32 5.7 Directory Notification... 33 5.8 Nested Groups (Indirect Membership)... 34 Chapter 6 Questions and Answers... 35 6.1 Module Behavior Questions... 36 Chapter 7 Other Information... 37 7.1 Necessary user permissions... 38 7.1.1 Read-only... 38 7.1.2 Limited read-write... 38 7.1.3 Change Password... 39 7.1.4 Full Read-write... 39 7.2 Installed entities... 40 Page 2 of 42
7.3 FAQs... 41 7.4 Developers Notes... 42 7.4.1 The timeout alert may occur in AD containing 1000000 users... 42 7.4.2 Sorting in Windows 2008... 42 Page 3 of 42
Chapter 1 Introduction Sitecore CMS 6 provides solid and self-sufficient security model, based on the ASP.NET 2.0 provider model, but the enterprise solutions may require complex security infrastructure. Many organizations have already set up a domain in some directory services, for instance, Active Directory. The Sitecore CMS Active Directory module provides the integration of Active Directory domain with the Sitecore CMS solution. You can integrate the domain users and groups available into Sitecore CMS as Sitecore users and Sitecore roles immediately after the module installation and configuration. Moreover, user profiles can be easily extended with the custom properties from the Active Directory. The present document describes the installation, configuration and usage of the Active Directory module. It also includes the architectural background of the technology used. It is highly recommended to get acquainted with the Low-level Sitecore Security and Custom Providers article before reading this document. Page 4 of 42
Chapter 2 Installation and Configuration This chapter covers the installation and configuration procedure of the module. Unlike other Sitecore CMS 6 modules, Active Directory module requires the manual modification of the web.config file. This chapter contains the following sections: Sitecore CMS package installation. Manual web.config modification. Page 5 of 42
2.1 Installing Sitecore package The Active Directory module is distributed as a usual Sitecore package. You can install it using the Installation Wizard available via the Sitecore desktop link Sitecore» Development Tools» Installation Wizard. Page 6 of 42
2.2 Web.config Modifications Once the package is installed, it is necessary to make several manual modifications to the web.config file in order to complete the module installation. The area of the manual configuration modifications is limited to: The /App_Config/connectionStrings.config file. The /App_Config/Security/domains.config file. The system.web and sitecore/switchingproviders sections of the web.config file. Page 7 of 42
2.3 Firewall modification Active Directory requires ports 389 and 445 to be opened by default: 389 for client communications 445 Microsoft SMB/CIFS port 2.3.1 Adding a Connection String to the Active Directory domain If you have decided to use the Active Directory module, you should probably have the appropriate Active Directory domain to connect to. In most cases this is a company domain which stores the entire security infrastructure of the company. Add a connection string to the <connectionstrings> section of the main /App_Config/connectionstrings.config. If you re using SQLite installation, the same changes are required in the /App_Config/connectionstringssqlite.config file. It may look as outlined below: <connectionstrings> <add name="managersconnstring" connectionstring="ldap://testsrv/ou=managers,dc=testdomain,dc=sitecore,dc=net" /> </connectionstrings> Note The Managers is just a sample organization unit. Replace it with the real OU from your environment. Let s examine the given of configuration code. The <connectionstrings> element can have a number of connection strings defined. Each one is defined by the <add> tag. This element has a number of attributes, but here we use only two of them: Attribute Name connectionstring Description The name of the connection string. Any entity using this connection string will address it by this name. The connection string itself. The Active Directory module supports the LDAP format of the connection strings: Each string starts with the prefix LDAP:// The prefix is followed by the server name, which the component is to connect to. The slash (/) must follow the domain name. The last part of the connection string should contain the full path to the Active Directory container, where the users and groups will be taken from. Say, you have the Organization Unit called Managers in your organization infrastructure and you wish to make the members of this unit available in Sitecore CMS. Assume also that the Active Directory server name is ADServer and it is located in the ADDomain.company.com domain. In such case the connection string will look like this: LDAP://ADServer/OU=Managers,DC=ADDomain,DC=company,DC=com If a sub unit should be used, let s say, Support Managers, the connection string will transform to: LDAP://ADServer/OU=Support Managers,OU=Managers,DC=ADDomain,DC=company,DC=com And vice versa, if the entire domain should be used, specify the following connection string: LDAP://ADServer/DC=ADDomain,DC=company,DC=com Page 8 of 42
For more information about the LDAP connection string format, see this article on MSDN. 2.3.2 Configuring the ASP.NET security providers The Active Directory module is based on the ASP.NET security model architecture. This means that the module provides a set of basic providers that are used to manage users, roles and profile properties. The table below describes each of them briefly: Service Membership provider Role provider Profile provider Description Provides a set of operations to get the user(s), create, update, delete them, and also to perform some other operations, like validating the user (by the username and password) and changing the user password. For more information about the membership service, visit MSDN library. Provides a set of operations to get the roles, create, delete them, add users to and remove the users from roles. For more information about the roles service, visit MSDN library. Provides a set of operations to get/set the properties of the user profile, as well as different actions for the profile objects (delete/find profiles, etc.) For more information about the profile service, visit MSDN library. Configuring the Membership Provider Open web.config file, search for the <membership> element in the <system.web> section and paste the following code inside (the order is not important): <add name="ad" type="lightldap.sitecoreadmembershipprovider" connectionstringname="managersconnstring" applicationname="sitecore" minrequiredpasswordlength="1" minrequirednonalphanumericcharacters="0" requiresquestionandanswer="false" requiresuniqueemail="false" connectionusername="[put the username here]" connectionpassword="[put the password here]" connectionprotection="secure" attributemapusername="samaccountname" enablesearchmethods="true" /> The table below explains every attribute of this provider definition: Attribute name type connectionstringname applicationname Description The provider name. In general, this can be any string value, unique within the set of membership providers. But due to the fact that a part of the configuration is done automatically, this particular element requires the name ad in order to leave everything unchanged. The full name of the provider class. The name of the connection string. It is ManagersConnString in our example. A standard attribute of any provider; defines the area of visibility of the provider data. It should be sitecore in our example. See the MSDN documentation for details Page 9 of 42
Attribute minrequiredpasswordlength minrequirednonalphanumericcharacters requiresquestionandanswer requiresuniqueemail connectionusername connectionpassword connectionprotection attributemapusername enablesearchmethods Description A minimum number of characters required for the user password. The default value is 1. A minimum number of non-alphanumeric characters required for the user password. The default value is 0. Defines whether the provider requires question and answer to be set for the user passwords. Default is false. Defines whether the provider requires the unique emails to be set for each user. Default is false. In order to connect to the Active Directory domain, you should specify the user which has enough rights to perform necessary operations. These credentials are to be used by the provider when connecting to the AD domain. Define the username here. The user password. A system attribute of the provider. Must be set to Secure (default value). This attribute defines which Active Directory attribute is to be used as the username. This attribute must be set to samaccountname, which is the default value. Enables the search functionality of the provider when set to true (default value). Important Notes If a user can t be locked after exceeding the number of bad password attempts, verify that the Account Lockout policy is set correctly in the AD domain you use. In order to enable the functionality to reset password, you must specify the enablepasswordreset attribute and set its value to true in the configuration above. Besides, the provider requires the mapping of several attributes to the Active Directory properties. For more information, take a look at the MSDN article on this topic. Also, verify that the new password meets the requirements of the domain security policy for passwords in your AD domain. The connectionprotection attribute set to Secure requires one more element to be added to the <system.web> section (can be placed anywhere inside this section): <!-- Machine key attributes --> <machinekey validationkey="bddfe367cd36aaa81e195761befb073839549ff7b8e34e42c0dea4600851b0065856b211719adef C76F3F3A556BC61A5FC8C9F28F958CB1D3BD8EF9518143DB6" decryptionkey="0dac68d020b8193df0fcee1baf7a07b4b0d40dcd3e5ba90d" validation="sha1" /> This key is used to encrypt/decrypt the data transferred between the client and the Active Directory server. You can either paste this key to your web.config, or generate another unique key here or here. If you were logged in to the Sitecore CMS shell before performing the.config modifications described earlier, you may receive an error like Padding is not valid. This is a consequence of adding a system key and changing the connection protection level. To get rid of this error, clean your browser cookies. If this doesn t help, restart the browser. Page 10 of 42
Configuring the Role Provider Open the web.config file, search for the <rolemanager> element in the <system.web> section and paste the following definition inside it (the order is not important): <add name="ad" type="lightldap.sitecoreadroleprovider" connectionstringname="managersconnstring" applicationname="sitecore" username="[put the username here]" password="[put the password here]" /> The attributes of this element are described in the table earlier and have the same meaning for the role provider. Configuring the Profile Provider (Optional) The Active Directory module provides an option to store additional properties in the Active Directory domain. The configuration has extra steps apart from the configuring the provider in web.config. This approach is covered in detail in the Advanced Profile Configuration section later in this document. Note If you do not intend to extend the user profile with custom attributes from the Active Directory, you can skip the Advanced Profile Configuration chapter. Activating Switching providers In order to make the system aware about the presence of extra source of users and roles, the Switching mechanism must be activated. Follow the steps below to accomplish this: In web.config file, browse for <membership> element in <system.web> section, find the provider named sitecore and set its realprovidername attribute to switcher. In web.config file, browse for <rolemanager> element in <system.web> section, find the provider inside named sitecore and set its realprovidername attribute to switcher. The result of this action is the same as modifying the defaultprovider attribute for the root element of the service (membership or rolemanager). But the providers named sitecore are necessary for the CMS system needs. For more details on this, see the Low-Level Sitecore CMS Security and Custom Providers article. Adding a new domain Open the App_Config/Security/Domains.config.xml file and add the following line into the root element: <domain name="ad" ensureanonymoususer="false"/> Adding the domain-provider mappings Open web.config file, and browse to the <switchingproviders> element in of <sitecore> section. It has three groups inside: <membership>, <rolemanager> and <profile>: Add the following line to the <membership> group (the order is not important): <provider providername="ad" storefullnames="false" wildcard="*" domains="ad" /> Add the following line to the <rolemanager> group (the order is not important): <provider providername="ad" storefullnames="false" wildcard="*" domains="ad" /> [Optional] Add the following line to the <profile> group (it must be the first definition in this group, for more details about this feature, see the Advanced Profile Configuration section of this document): Page 11 of 42
<provider providername="ad" storefullnames="false" wildcard="*" domains="ad" /> The phrase the order is not important means that the definition will work in any case. The only difference the order makes is the order of the users/roles in Sitecore CMS 6 security tools. For instance, if you put the ad membership mapping before the sql one, then you ll see the Active Directory users in User Manager before the default Sitecore CMS ones. Page 12 of 42
Chapter 3 Basic Scenarios WARNING Any changes made in Sitecore CMS to the active directory users are done in the LIVE mode. The changes are applied immediately to the real Active Directory objects. The only exception is a user lock-out, in this case the users are locked out locally for Sitecore CMS and remain active in the Active Directory domain. After the configuration steps are done, start Sitecore CMS and login to the Desktop interface with the administrator account. Start the Role Manager application (Sitecore» Security Tools» Role Manager). You can see the roles from the Active Directory along with the Sitecore CMS roles. See the ad\ prefix - it means that the roles belong to the Sitecore domain called ad. Each Sitecore CMS domain can be served via a single provider. For more details on this, see the Low-Level Sitecore CMS Security and Custom Providers article. Start the User Manager and you will see the Active Directory users as well. Note You may experience a delay before the Role/User Manager application starts compared to the earlier cases when the Active Directory module wasn t installed. The delay may vary depending on the number of entities in the plugged Active Directory domain. The more users and roles, the longer the delay. Page 13 of 42
3.1 Managing Roles and Users You can make any changes to users which are fetched from the Active Directory domain, just like to regular Sitecore CMS users. And the standard Role or User Manager applications is used for this. For instance, say you wish a user ad\john to be able to login to Sitecore CMS desktop. All you should do is add this user to the sitecore\sitecore Client Users role. After you do this, you can log in as the ad\john user and use the Sitecore desktop. Note You must specify the full username (with the domain name) when logging in. In order to allow any user of a certain Active Directory role to login to Sitecore shell, you should add this role to the sitecore\sitecore Client Users role. In this case, the Roles-In-Roles functionality will do the job. There is a certain limitation in this area. In order to add a user to the Active Directory role, the user must exist in the same Active Directory domain. As a result, a user from Sitecore CMS cannot be added to the role from the Active Directory. But this limitation can be easily worked around by the Roles-In-Roles functionality: add the necessary Sitecore CMS users to the Sitecore CMS role, and then add this role to the Active Directory role. The Roles-In-Roles service works on top of the ASP.NET providers, thus this scenario is possible. 3.1.1 Creating users/roles In order to create a user/role in the Active Directory, you should select the appropriate domain (ad in our case) in the New User/New Role dialog. 3.1.2 User Specific Operations Such operations as Change Password, Enable, Lock are applied to the Active Directory users in the same way as to the regular Sitecore CMS users. Page 14 of 42
Chapter 4 Advanced Profile Configuration The Active Directory module allows to store custom properties of a user profile in the attributes of a corresponding domain user object. For example, you have a telephone number set for each user in the Active Directory and you want this property to be visible for each user in Sitecore CMS. This section offers a step-by-step scenario on how to enable such functionality. Page 15 of 42
4.1 Configuring the profile provider First you need to add a profile provider definition. Open the web.config file, browse for the <profile> element in the <system.web> section. Paste the following provider definition inside the profile/providers element (the order is not important): <add name="ad" type="lightldap.sitecoreadprofileprovider" connectionstringname="managersconnstring" applicationname="sitecore" username="[put the username here]" password="[put the password here]" /> Then, change the defaultprovider attribute of the <profile> element to switcher. In the general configuration procedure, you should also provide a mapping correspondence for the profile provider as for any other service. If you skipped this step before, it is time to get back to it now. So, in your main web.config file, browse for the switchingproviders/profile element and put the following line there: Technical note <provider providername="ad" storefullnames="false" wildcard="*" domains="ad" /> This element must go first in this section. The reason is rather trivial. The SQL server provider, which is default for the profile service, is very universal. If it can t find the appropriate profile property, it considers this property a custom one and just stores it in the custom table. As a result, if the SQL server goes first in this section, it will always handle all the properties. In order to allow the AD provider to handle its properties and provide the information from AD domain, its definition must be the first in this section. Page 16 of 42
4.2 Configuring the Custom Properties Any custom property, which you wish to extend the profile with, should be defined in the <properties> group of the <profile> element. In our example, we should place the telephonenumber property there. So, browse to the <profile> element in the <system.web> section of web.config file, locate the <properties> group inside this element and add the following line there (the order is not important): <add type="system.string" name="telephone" customproviderdata="ad unicode string telephonenumber" /> The table below explains each attribute of this definition: Attribute Name Type customproviderdata Description A unique name of the property. The.NET type of the property. This is the type the property will have in the ASP.NET environment. This parameter must always be System.String for ad profile properties. Sitecore works with all properties as with the string type. Any data required for the provider serving this property. In our example, ad means that this property is to be handled by the ad provider. The unicode string defines the native type of the property in Active Directory. And the telephonenumber specifies the name of the corresponding Active Directory attribute. In general, this attribute can be of any form. The ad provider expects the pipe separator ( ) between the attribute parts. The Active Directory module expects the customproviderdata in the following format: ad [native type name] [ad native name]. The native type name is the type of the property in Active Directory. The following basic types are supported: unicode string, boolean and integer. If anything else is specified, the unicode string type is taken as a fallback. The last optional ad native name part is a real name of the corresponding property in Active Directory. If it is omitted, the value falls back to the name attribute. Note The Active Directory module does not support reflecting the custom Active Directory attributes to the Sitecore CMS roles. Sitecore CMS security is based on the.net security model, and this underlying engine does not provide an option to have a kind of profiles for the roles. Such reflection is not supported in the Active Directory module, as well as in the Sitecore CMS. Page 17 of 42
4.3 Extending the Sitecore Template After the custom properties are defined in the web.config file, you should extend the Sitecore template in order to make those properties accessible from the Sitecore CMS security applications. The following steps describe the procedure: Start Sitecore CMS and login with the administrator credentials and switch to the core database. Open the Content Editor, and browse for the /sitecore/templates/system/security/user template in the content tree Add the new field to this template called Telephone (exactly the same as the appropriate property name in web.config) of Single-Line Text type and mark it as Shared. Save changes and switch to the master database. Open the User Manager and edit any user from the Active Directory domain, for instance, ad\john. Switch to the Profile tab Click the Change button and choose a user template. Close this window. Page 18 of 42
If you edit ad\john user again and switch to the Profile tab, you ll see that its profile is extended with the telephonenumber property: The property is filled with the telephonenumber attribute value from the Active Directory user. Refer to the Low-Level Sitecore CMS Security and Custom Providers article for more details about this feature and what conditions the provider should satisfy to support the profile extension. Assigning the non-default profile to AD users automatically The guidance above of how to extend Sitecore profile template includes the step to assign the profile item to the user. It is obvious that such a manual operation is not a way to go for hundreds of users. For this purpose, Sitecore allows to set a common profile item on the domain level. Open the /App_Config/Security/Domains.config.xml file and add the following line to the domains element: <domain name="ad" ensureanonymoususer="false" defaultprofileitemid="{ddeda46f-169b- 4A70-8732-DBD3F407AF2E}"/>. The defaultprofileitemid attribute defines the profile item that will be used for users from the domain if the profile is not set for the user explicitly. Page 19 of 42
4.4 Mapping Active Directory Display Name attribute to the Full Name property in Sitecore The value from the DisplayName property of the AD user will automatically be passed to the default Full Name field. Note also that it is not required to extend the user s profile template with a new field for this property the value will be displayed in the Full Name edit field of the Edit User dialog, General tab: If you want to map another AD property to the Full Name field you can do it in the App_config/Include/ldap.config file. Set the appropriate value for the LDAP.FullName setting: Note <!-- FULL NAME PROPERTY NAME Determines the full name property mapping. --> <setting name="ldap.fullname" value="ad unicode string displayname" /> Remember that Advanced profile feature must be configured as described above to support this mapping. Page 20 of 42
Chapter 5 Features The Active Directory module provides extra features in order to make the security resolution easier and more convenient. The main features are listed below: Single Sign-on Status page Debug mode Multiple domain connections Indirect Membership Page 21 of 42
5.1 Single Sign-on In most cases, if an organization has the domain controller set up, the workstations are usually included into this domain. Imagine that you have established a connection between the Managers organization unit and your Sitecore CMS installation. This means that the members of this organization unit are now able to work in Sitecore CMS according to their roles. Naturally, these users wish to be logged in to Sitecore CMS automatically. When users start Sitecore CMS, they are definitely logged in to their organization domain. This feature is called Single Sign-on and the Active Directory module offers such an option. 5.1.1 Prerequisites There are some prerequisites for using this functionality: The workstation must be a member of the appropriate domain. The anonymous access must be disabled to the /sitecore/admin/ldaplogin.aspx page and the Integrated Windows security mode must be turned on. In order to disable the anonymous access in IIS, follow the steps below: Start IIS. Expand the target website. Navigate to the /sitecore/admin folder and select the LDAPLogin.aspx page. Right-click the LDAPLogin.aspx page and select Properties. Switch to the File Security tab, uncheck the anonymous access checkmark. As a result, the IIS configuration should look similar to this: IIS 7 configuration Page 22 of 42
The configuration of IIS 7 differs a bit. The steps below help to pass this procedure for this version of IIS. To begin with, IIS 7 does not support mixed authentication mode. Hence you cannot have several authentication types enabled for you site. To use Windows Authentication you have to disable Forms authentication (which is default for Sitecore installation) and enable Windows Authentication for your site, as shown below: Page 23 of 42
Next step is pretty straightforward. You have to go to the AD login page and disable anonymous access for that page, as shown below: 5.1.2 Feature Usage Now, when the prerequisites are satisfied, you can login to Sitecore CMS with your system account without providing the user credentials manually. So, run the following URL in your browser: http://[yoursite]/sitecore/admin/ldaplogin.aspx Note You can still login in the usual way by addressing the default Sitecore shell login page (http://[yoursite]/sitecore) If you did forget to verify the prerequisites and your machine appeared not to be in a domain or the anonymous access has not been removed from the login page, the system will not log you in, displaying the reason of the refuse: Some errors may occur when the system begins to analyze user credentials. For instance, if the domain name is correct, and you re a member of the Active Directory domain, but you re not a Page 24 of 42
member of the Managers organization unit which is plugged into Sitecore, you ll get the following warning: It may happen that the real domain name differs from the domain name entered in Sitecore CMS. For instance, you may be a user of the Active Directory domain called Company.com, but this very domain is plugged into Sitecore CMS as ad (which is done by default). In such case, the system won t reject your attempt to login, but will iterate the existent Sitecore CMS domains trying to find the appropriate user. If the user is still not found, the following warning will be displayed: In case when the user is found in Active Directory domain, but it doesn t have enough permissions to login to Sitecore CMS shell interface (the user is not included in the sitecore\sitecore Client Users role), the system will reject the login attempt and display the following message: And finally if everything is fine and the user is allowed to login, you ll be logged in automatically and redirected to the Sitecore CMS desktop. Page 25 of 42
Note If the debug mode is used, you ll first see the entire list of roles you are a member of in Sitecore CMS. Also, the button will be enabled allowing you to login then. Read more about the debug mode later in this article. Page 26 of 42
5.2 Status Page As an additional option for the troubleshooting of the potential problems with security, the module offers a special status page. This page can be opened by following the next URL: http://[yoursite]/sitecore/admin/providerstatus.aspx You will see something like this: This page reflects the basic information about the domains and security providers. You can see each domain listed here and the providers which handle these domains. There is also high level status information about each provider: If the status is ON, this means that the provider is functioning and can serve the requests. If the status is OFF, this means that the provider refused a simple request and the system marked it as broken. It is not always possible to display this page depending on the problem which occurred. Sometimes the entire application will fail to start if there is an error in the provider configuration. But this is the first Page 27 of 42
step to take when troubleshooting the Active Directory module configuration or the security providers definition in general. Once any provider is shown as off, this indicates that it is not functioning and its configuration needs to be adjusted. The next troubleshooting step is examining the log file. Developer s note The status page performs a simple call to any method of the appropriate provider, which doesn t require valid input parameters, to make a decision if the provider works. For instance, the method GetAllUsers() is called for the membership provider. If the method throws an exception, the status is automatically set to OFF. Page 28 of 42
5.3 Debug Mode The Active Directory module offers a so-called debug mode a special mode when more detailed information is written to the log file and is displayed on a login page. This method is also called verbose logging in some systems. Using the debug mode, the administrator can try to locate a potential problem himself, examining the detailed log files. It is also quite helpful for the technical support the detailed logs contain enough information to identify the type and place of the error. To enable the debug mode, you should open the /App_Config/Include/ldap.config file, locate the LDAP.Debug setting and set it to true. This setting is false by default. Due to the fact that the changes to the pluggable.config file are applied immediately, the next request to the module will dump much more information to the Sitecore CMS log file. The LDAP.Debug setting applies to the entire module. But there s also an option to enable this mode for the Single Sign-on feature only. To do so, append the following query string parameter to the login page URL:?debug=true. When you try to login in the debug mode, you will first be presented the membership information about your account. This information includes the direct and indirect roles the user is a member of. You can login by pressing the Log me in button, which is also there if you have enough permissions to login: Page 29 of 42
5.4 Connecting to multiple domains The Active Directory module and Sitecore security model allow you to have the connections to as many AD domains as you wish. You may want to have the Managers from your company headquarters and the Developers from the regional office in one Sitecore CMS installation. In order to achieve this you need to configure one more set of providers in the web.config file: Add a connection string to the new AD domain. Add a membership provider definition. Add a role provider definition. Add a profile provider definition (if you wish to share the user profile). Add a new Sitecore CMS domain and point it to the new set of providers. For more information about configuring extra security providers, see the Low-Level Sitecore CMS Security and Custom Providers article. Page 30 of 42
5.5 Cache settings The module caches some information to improve the performance. Cache settings are defined in the App_Config/include/ldap.config file: LDAP.Caching.UserCache - determines the cache size for the user information; LDAP.Caching.MemberOfCache - determines the cache size for the memberof information; LDAP.Caching.MembersCache- determines the cache size for the members information. Page 31 of 42
5.6 Additional LDAP.config settings Additional settings in the /App_Config/Include/ldap.config file: LDAP.EnableSorting defines whether sorting is enabled. Default value is false. Warn: Sorting doesn t work on Windows Server 2008. LDAP.SortKey defines the name of the AD attribute that is used for sorting AD users. The setting influences the AD performance. The more different values for this field are in the AD the more time it takes the AD server to sort requested users. Default value is the codepage. LDAP.SizeLimit the max number of users that AD returns for the * search pattern. It means that the User Manager shows not more than LDAP.SizeLimit users for each AD domain. The setting was added to improve the performance. Default value is 1000. Narrowing down the search criteria will do the job of finding the necessary user. LDAP.FindSizeLimit the max number of users that AD returns for other search patterns. It means that the User Manager shows not more than LDAP.FindSizeLimit users for each AD domain when user is using the search operation. The setting was added to improve the performance. Default value is 100. LDAP.SettingsPropertyValueFactory by default the module allows working with boolean, unicode string and integer types of AD properties from the user profile. You can implement your class that allows you using more AD property types if need be. LDAP.ReconnectPeriod defines the period when the module restores a notification connection if it is broken (to keep the actual cache data the module is notified by the AD server about changes). LDAP.NotificationTimeOut defines the timeout of notification connections. LDAP.DeleteScope defines whether the module is allowed to delete AD objects from the whole AD tree or just under defined in the connection string Organization Unit (one level). Page 32 of 42
5.7 Directory Notification The module uses the DirectoryNotificationControl (http://msdn.microsoft.com/enus/library/system.directoryservices.protocols.directorynotificationcontrol.aspx) to be notified when changes are made to an object in the Active Directory Domain Services. You can disable this feature if all the changes in the AD are made by the only Sitecore application. Set the usenotification= false attribute for all AD Role and Membership providers in the web.config file: <add name="ad" type="lightldap.sitecoreadmembershipprovider" connectionstringname="managersconnstring" applicationname="sitecore" minrequiredpasswordlength="1" minrequirednonalphanumericcharacters="0" requiresquestionandanswer="false" requiresuniqueemail="false" connectionusername="[put the username here]" connectionpassword="[put the password here]" connectionprotection="secure" attributemapusername="samaccountname" enablesearchmethods="true" usenotification= false /> <add name="ad" type="lightldap.sitecoreadroleprovider" connectionstringname="managersconnstring" applicationname="sitecore" username="[put the username here]" password="[put the password here]" usenotification= false /> Page 33 of 42
5.8 Nested Groups (Indirect Membership) Sitecore Active Directory module supports the indirect membership by applying to the inner membership of the Active Directory domain. For instance, assume that we have a user called John, which is a member of the Professional Service group, which in turn is a member of a parent group called Solution Department. Thus, in order to allow John to login to Sitecore, you need to add the Solution Department group to the sitecore\sitecore Client Users default role. But, along with this, you should enable the indirect membership feature by opening the /App_Config/Include/ldap.config file and setting the value of the LDAP.IndirectMembership setting to true. Note The indirect membership option is applicable to the login procedure, but Sitecore CMS security tools will not show the complete membership for users with such membership and the entire set of users for roles which implement the indirect membership. Speaking the technical language, the method IsUserInRole of the role provider knows about the indirect membership, while other methods do not. Extending the module in this area would lead to the full Active Directory manager application in Sitecore CMS, which is out of the scope of the Active Directory module. Page 34 of 42
Chapter 6 Questions and Answers This chapter contains some frequently asked questions and their answers. Page 35 of 42
6.1 Module Behavior Questions This section includes questions about the expected module behavior. Q: I m trying to create a user in the Active Directory domain from Sitecore CMS, but the CMS says that the user can t be created. I m filling in all the required fields, but still no luck. What can be the reason? A: One of the possible reasons is that the user already exists. You may argue saying that User Manager does not display such a user. In such case you are probably plugging in only a single organization unit to Sitecore CMS, not the entire Active Directory domain. In this case, the user probably exists in another organization unit. Note, that when creating a user the module verifies the uniqueness of the username in the entire domain. Q: When I create a user in the Active Directory domain from Sitecore CMS, I don t specify the value for the comment field, but when the user is created, I can see the string please enter a comment here there. Why is it filled automatically? Can I prevent this? A: You may also face with this when updating the user and leaving the comment field blank. The Sitecore CMS active directory provider is based on the Microsoft default Active Directory provider, which requires the comment not to be blank when updating the user information. That is why it is populated with the default value if you leave it blank. You can put your value there at any time. Q: I have created a user and I can see that their title and department values are set to undefined. Why? A: That is because you have set the attribute requiresquestionandanswer of the provider definition element to true. You should have also put additional attributes there for mapping password question and answer to the AD attributes. For instance, you have mapped them to the title and department attributes accordingly. When the user is created and the configuration requires password question and answer, these fields can t be left empty or null. Hence, they are set to undefined in this case. To avoid this behavior, switch the attribute requiresquestionandanswer to false. Page 36 of 42
Chapter 7 Other Information This chapter contains additional useful information. Page 37 of 42
7.1 Necessary user permissions The module uses credentials to communicate with the AD server. It is not always required the write access right. Call the Properties dialog of the organization unit to set necessary permissions. You can use one of the following access levels to make your configuration better: Read-only Limited read-write Change Password Full Read-write 7.1.1 Read-only This access level allows: reading users/roles reading profile properties Minimum required permissions: list contents read all properties 7.1.2 Limited read-write This access level includes read-only operations and allows: modifying profile properties Page 38 of 42
password operations modifying an email adding an AD user to an AD role Minimum required permissions: list contents read all properties write all properties 7.1.3 Change Password This access level requires additional permissions: read all properties change password reset password (for reset password operation) Also you have to add some permission to an AD container ( Authenticated Users role): Important: list contents read all properties If any of those permissions is not set, you will see the following exception: Exception Details: System.DirectoryServices.DirectoryServicesCOMException: There is no such object on the server. 7.1.4 Full Read-write This access level includes limited read-write and change password operations and allows: creating users/roles deleting users/roles Minimum required permissions: list contents read all properties write all property create group objects delete group objects create user objects delete user objects all extended rights Page 39 of 42
7.2 Installed entities The module package contains only the files. No items or security entities are included. The entire list is: /bin/lightldap.dll (the main assembly of the module). /bin/lightldapclient.dll (the client assembly of the module). /App_Config/Include/ldap.config (the pluggable configuration file of the module). /sitecore/admin/ldaplogin.aspx (the login page for the single Sign-On feature). /sitecore/admin/providerstatus.aspx (the statistics page of the provider status). Page 40 of 42
7.3 FAQs This section contains the frequently asked questions. 1. Question: I have renamed a user and it lost its security assignments immediately.but when I rename it back, it obtains its old assignments back. Where the trick is? Answer: This behavior reflects the way.net security treats the username. The fully-qualified username plays the role of a unique identifier. Due to the fact that this name is used to store security settings for items in Sitecore CMS, renaming a user is similar to creating a new user. The general recommendation is not to rename users which have got any security assignments. 2. Question: How can I access the profile properties which come from the Active Directory? Answer: As other profile properties, these properties can be addressed in the following way: user.profile[ property_name ] = property_value ; The line above assumes that the user is an object of class Sitecore.Security.Accounts.User. 3. Question: I would like to reflect some group attributes of Active Directory to the role in Sitecore. Is this possible? Answer: This scenario is not supported in the Active Directory module, as well as in Sitecore CMS, because Sitecore security is based on the.net security model, and this underlying engine doesn t provide an option to have a kind of profiles for the roles. Page 41 of 42
7.4 Developers Notes 7.4.1 The timeout alert may occur in AD containing 1000000 users You can get the timeout alert while searching a user in AD containing more than 1000000 users. Workaround: add the serverpagetimelimit attribute to a membership definition: <add name="ad" type="lightldap.sitecoreadmembershipprovider" connectionstringname="managersconnstring" applicationname="sitecore" minrequiredpasswordlength="1" minrequirednonalphanumericcharacters="0" requiresquestionandanswer="false" requiresuniqueemail="false" connectionusername="[put the username here]" connectionpassword="[put the password here]" connectionprotection="secure" attributemapusername="samaccountname" enablesearchmethods="true" serverpagetimelimit = 5 /> The attribute indicates the time limit for searching an individual page of results by the server. The default value is -1 second, it means that the AD is searching for users till all the users are analyzed. 7.4.2 Sorting in Windows 2008 If the LDAP.EnableSorting is set to true, the User Manager shows the following error: The server does not support the requested critical extension. Sorting must be disabled on Windows 2008. Page 42 of 42