Administrator's Guide

(1)

Active Directory Module

Administrator's Guide

(2)

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

(5)

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.

(6)

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.

(7)

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.

(8)

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 Description

Name The name of the connection string. Any entity using this connection string will address it by this name.

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

(9)

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 Description

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

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

Profile provider 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:

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

type The full name of the provider class.

connectionStringName The name of the connection string. It is ManagersConnString in our example.

applicationName 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

(10)

minRequiredPasswordLength A minimum number of characters required for the user password. The default value is 1.

minRequiredNonalphanumericCharacters A minimum number of non-alphanumeric characters required for the user password. The default value is 0. requiresQuestionAndAnswer Defines whether the provider requires question and

answer to be set for the user passwords. Default is false.

requiresUniqueEmail Defines whether the provider requires the unique emails to be set for each user. Default is false.

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

connectionPassword The user password.

connectionProtection A system attribute of the provider. Must be set to Secure (default value).

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

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

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

(11)

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:

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

(12)

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.

(13)

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.

(14)

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.

(15)

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.

(16)

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

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.

(17)

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

The table below explains each attribute of this definition:

Name A unique name of the property.

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

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

(18)

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.

(19)

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.

(20)

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: <!-- FULL NAME PROPERTY NAME

Determines the full name property mapping. -->

Note

Remember that Advanced profile feature must be configured as described above to support this mapping.

(21)

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

(22)

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:

(23)

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:

(24)

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:

(25)

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.

(26)

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.

(27)

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

(28)

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.

(29)

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:

(30)

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

(31)

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.

(32)

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

(33)

5.7 Directory Notification

The module uses the DirectoryNotificationControl

(http://msdn.microsoft.com/en-us/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"

useNotification=”false” />

<add name="ad" type="LightLDAP.SitecoreADRoleProvider" connectionStringName="ManagersConnString"

applicationName="sitecore" username="[put the username here]" password="[put the password here]" useNotification=”false”/>

(34)

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.

(35)

Chapter 6 Questions and Answers

(36)

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.

(37)

Chapter 7 Other Information

(38)

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

(39)

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): list contents

read all properties

Important:

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

(40)

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

(41)

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.

(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"

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

Administrator's Guide

Active Directory Module