Active Directory Module and Sitecore

This post describes how to configure and integrate sitecore active directory module. Shortening it and would refer to as ADM in the rest of the post. It also explains some of the common errors and their resolutions to get it working in the “Errors & Resolutions” section of the post.

Some information in this post like configuration steps, attribute definitions etc. are taken from “Active Directory Module 1.1 for CMS 6.6-7.0 Administrator’s Guide”.

What it does not explains?

This post only covers integration of ADM with Sitecore. Other open ended topics like installation of Active Directory, LDAP installation and Sitecore installations are not covered here.

Sitecore and AD module version

The post considers integration of Sitecore 6.6 (rev 130529) and 7.0 (rev 130424) and ADM v1.1 (rev. 130705)

Compatibility
Below table gives an insight for various ADM versions compatibility with various Sitecore versions.

CMS 6.0

CMS 6.1

CMS 6.2

CMS 6.3

CMS 6.4

CMS 6.5

CMS 6.6

CMS 7.0

Active Directory module v1.0.0

Active Directory module v1.0.2

Active Directory module v1.0.3

Active Directory module v1.0.4

Active Directory module v1.1

Installation and documentation sources

In order to download the package for ADM you need to be a Sitecore certified developer and registered with Sitecore Developer Network.

Download links

ADM
Download Active Directory Module Administrator’s Guide

Installation Steps

Install the ADM module using Package installer. The installation package adds few files to the website, hence make sure to include them in your visual studio project once ADM package is installed on your Sitecore solution.

– App_Config\Include\ldap.config
– Bin\lightldap.dll
– Bin\lightldapclient.dll
– Sitecore\admin\ldaplogin.aspx
– Sitecore\admin\providerstatus.aspx

To my surprise the installation does not add any Sitecore items.

Configuration Steps

Enough of the details! Now let’s dive deep and start working with actuals. Once the installation is successful the next step is to proceed with ADM configuration hence tweaking it to work for our environments.
After you install the package, you must modify some configuration files to complete the installation namely,

  • The /App_Config/connectionStrings.config file.
  • The domains.config.xml file.
  • The system.web and sitecore/switchingProviders sections of the web.config file.

Adding a Connectionstring

In connnectionstrings.config file add a connection string to <connectionStrings> section. The section may look like this,

<connectionStrings>

<add name=”LDAPConnString”

connectionString=”LDAP://ADServer.domain.name:389/DC=domain,DC=name”/>

</connectionStrings>

Key Points

  • Each string starts with the prefix LDAP://
  • The prefix is followed by the server name, which the component should connect to. The slash / must follow the domain name.
  • The last part of the connection string must contain the full path to the Active Directory container that the users and groups should be extracted from.
  • To avoid some exceptions and for greater stability, specify the Active Directory server name as a Fully Qualified Domain Name (FQDN) with the port number.

Examples of Connectionstrings

  • LDAP://ADServer.domain.name:389/OU=ITOperations,DC=ADDomain,DC=company.
  • This allows to connect to Organization Unit “ITOperations”. The active directory is located at ADServer and the domain is ADDomain.company.
  • LDAP://ADServer.domain.name:389/ OU=ITSupport,OU=ITOperations,DC=ADDomain,DC=company. Use above connectionstring when you want to use a sub unit call ITSupport.

Next we will look at configuring the ASP.Net membership providers. The Active Directory module is based on the ASP.NET security model architecture. The module therefore contains a set of basic providers that you can use to manage users, roles, and profiles

Adding a New Domain

Open the App_Config/Security/Domains.config.xml file and add the following line to the root element:

<domain name=”ad” ensureAnonymousUser=”false”/>

Adding Domain-Provider Mappings

In web.config file browse to <sitecore >/<switchingProviders>/ element.

This section contains three groups for the three membership providers i.e. <membership>, <roleManager> and <profile>.

Add following line to <membership> group

<provider providerName=”mydomain” storeFullNames=”false” wildcard=”*” domains=”mydomain” />

Add following line to <role> group

<provider providerName=”mydomain” storeFullNames=”false” wildcard=”*” domains=”mydomain” />

Note: If you want your AD Roles and Users to appear before Sitecore roles and users the definition should precede the SQL provider mapping. Hence the order of the mapping decides in which order roles and users will be seen in the Role Manager and User Manager in Sitecore.

Add following line to <profile> group

<provider providerName=”mydomain” storeFullNames=”false” wildcard=”*” domains=”mydomain” />

Note: Make sure it must be the first definition in the <profile> group. You might be thinking as to why this should be first in the list here the reason for it.

The SQL server provider, which is the default for the profile service, has been designed to be very flexible. As such, if it can’t find the appropriate profile property, it considers this property to be a custom property and stores it in the Custom table.

As a result, if the SQL Server is listed first in this section, it will always handle all the properties. The definition of the AD provider must therefore be listed first in this section to allow the AD provider to handle its properties and supply the information from the AD domain.

Once you have configured all the three membership provider your <switchingProviders> section might look like

switching providers

Configuring Membership Provider

Open web.config file and browse to /, create a new entry as follows,


Below table explains the attributes in detail,

name The provider name. In general, this can be any string value that is unique within the set of membership providers.The value in my case is “mydomain” but that can be changed to desirable value as long as it remains unique.
Type The full name of the provider class.
connectionStringName The name of the connection string. In our example, it is ManagersConnString.
applicatioName A standard attribute of any provider that defines the area of visibility of the provider data. It should be sitecore in our example.
minRequiredPasswordLength The minimum number of characters required in a user password. The default value is 1.
minRequiredNonalphanumericCharacters The minimum number of non-alphanumeric characters required in a user password. The default value is 0.
requiresQuestionAndAnswer Defines whether the provider requires question and answer to be set for the user passwords. The default value is false.
requiresUniqueEmail Defines whether the provider requires each user to have a unique email address. The default value is false.
connectionUsername The user name.To connect to the Active Directory domain, you should specify a user who has sufficient rights to perform the necessary operations. The provider uses these credentials when it connects to the AD domain.
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 user name.The user has to explicitly set the “attributeMapUsername” property to “userPrincipalName if you use “userPrincipalName” as the user names.The user has to explicitly set the “attributeMapUsername” property to “sAMAccountName” if you use “sAMAccountName” as the user names.
enableSearchMethods Enables the search functionality of the provider when set to true (default value).

Table 1.1

However I ignored some of the above listed attributes and my actual setting looked like,

Configuring Role Provider

Open web.config file and browse to <system.web>/<roleManager>, create a new entry as follows,

All the attributes mentioned in Table 1.1 holds true for Role provider with an addition of an extra attribute cacheSize which is explained below,

cacheSize Defines the size of the role cache. The default value is 2 MB.

Table 1.2

Configuring Profile Provider

1) Open web.config file and browse to /< profile>, create a new entry as follows,


sitecoreMapDomainName Specifies the Sitecore security domain handled by the current profile provider. By default, it is equal to the provider name.

2) Change the defaultProvider attribute of the element to “switcher”.

Now with all the configurations in place you should be happy running the ADM.

The status page

ADM creators are smart guys and they have provided us a way to check whether ADM is configured correctly with Sitecore. I am talking about Provider Status page. This page provides information about various domains and membership providers configured for those domains. It’s also a tool to troubleshoot potential security problems.

To open this page use http://[yoursite]/sitecore/admin/ProviderStatus.aspx

Below image depicts how the page looks like

Status page

Errors & Resolutions

This section will describe few of the errors and misconfigurations that were faced by me. After all, we are humans and do make errors!

1) Roles appearing in Role Manager but Users not appearing in User Manager.

In such case check your web.config file and assure that attributes mentioned in Table 1.1 are properly named as XML is case sensitive and hence “connectionStringName” and “connectionstringname” are interpreted differently.

Also ensure that correct values are provided for “connectionUsername” and “connectionPassword” attributes.

Note: The attribute names differ for Membership and Role provider configuration

2) User appearing in User manager but Roles not appearing in Role Manager.

In my case attributes value of “username” and “password” were incorrect hence the roles were not loading in Role Manager. I was able to figure it out from the logs files with below error.

Log

3) Provider name cannot be null or empty.

The yellow screen of death appears in case you have not mentioned Full Qualified Domain Name (FQDN) in the connectionstrings.config file for your LDAP location. Ensure that LDAP connectionstring contains FQDN with port as well.

You might face same error in case if you are not using correct username and password to access your domain. So check the username and password supplied in the provider setting are correct, not locked out or not expired.

Provider name cannot be null or empty

My next plan is to write How to configure Single Sign on with Sitecore so keep watching this space

More blogs on Active Directory & Sitecore

Using Sitecore with Microsoft Active Directory Lightweight Directory Services (AD LDS) by Adam Weber

Authentication Options with the Sitecore ASP.NET CMS by John West

Making my way through Active Directory forests by Alex Shyba

3 thoughts on “Active Directory Module and Sitecore

  1. Congratulations for the great post! The official documentation is not exactly straight-forward and you made a good job summarizing everything we need to change to make the Active Directory module works.

    In the other hand I’ve never been a big fan of changing the Web.config: you can easily lose track of your changes and a Sitecore upgrade would become harder. Also, turning the module off is also harder, so I decided to take another approach of isolating the configs on include files.

    Please check my solution and let me know what you think:
    http://blog.peplau.com.br/en_US/best-way-to-setup-active-directory-module-in-a-sitecore-solution/

  2. Hi Brijesh,
    Great post. only question about web.config file.

    Is the correct config file is located in WebsiteApp_COnfigSitecore.config?

    or WebsiteWeb.config?

    I am asking this this because all the section you have mentioned(Membership, RoleManager etc) are in both config files.

    And the SwitchingProvidor section is in Sitecore.config along with Membership, Rolemanager etc?
    Please could you help in clarifying my doubt.

    Neeraj

Leave a Reply

Your email address will not be published. Required fields are marked *