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

TCP Connection States

Dear Reader,

The information below is about TCP and it’s connection states, this piece of information is based on research and other document found online, by no means it’s a complete document and by no means I am a TCP expert. So read it and verify before you use.

TCP Protocol operations may be divided in to three phases. Connections must be properly established in a multi-step handshake process (connection establishment) before entering the data transfer phase. After data transmission is completed, the connection termination closes established virtual circuit and releases all allocated resources.

A TCP connection is managed by an operating system through a programming interface that represents that local end point for communications, the internet socket. During the life time of a TCP connection the local end point undergoes a series of state changes.

LISTEN:
Server represents waiting for a connection request from any remote TCP and port.

SYN_SENT:
Client represents waiting for a matching connection request after having sent a connection request.

SYN_RECEIVED:
Server represents waiting for a confirming connection request acknowledgment after having both received and sent a connection request.

That is, client sent a SYN packet, server in return responded with SYN-ACK and is now waiting for a ACK.

 ESTABLISHED:
Both server and client represents an open connection, data received can be delivered to the user. The normal state for the data transfer phase of the connection.

FIN-WAIT STATES:
In the normal case, each side terminates its end of the connection by sending message with FIN (finish) bit set. This message, sometimes called as FIN, serves as a connection termination request to the other device, while also possibly carrying data like a regular segment. The device receiving the FIN responds with an acknowledgement to the FIN to indicate that it was received. The connection as a whole is not considered terminated until both sides have finished the shut down procedure by sending a FIN and receiving an ACK.

FIN-WAIT has got two sub states as below.

FIN_WAIT-1:
Both server and client represents waiting for a connection termination request from the remote TCP, or an acknowledgement of the connection termination request previously sent.

The FIN_WAIT_1 state is waiting for the peer to ACK the FIN that this end has just sent. That outgoing FIN is subject to all the normal TCP retry and timeout processing, so if the other end has completely disappeared and never responds, TCP should time out the connection and reset.

FIN_WAIT-2:
Both server and client represents waiting for a connection termination request from the remote TCP.

FIN_WAIT_2 seems to occur when the server has an active connection with a client and wants to shut down the TCP connection.

The server sends the client a packet with a “FIN” bit set. At this point, the server in is FIN_WAIT_1 state. The client gets the FIN packet and goes in to CLOSE_WAIT state, and sends an acknowledgement packet back to the server. When the server gets that packet, it goes in to FIN_WAIT_2 state.

From the server perspective, the connection is now closed, and the server can’t send any more data. However, under the TCP protocol, the client needs to shut down also by sending a FIN packet which the TCP implementation should ACK. The server should close about two milliseconds later.

CLOSE_WAIT:
Both server and client represents waiting for a connection termination request from the local user

CLOSE_WAIT means that the local end of the connection has received a FIN from the other end, but the OS is waiting for the program at the local end to actually close it connection.

The problem is  your program running on the local machine is not closing the socket. It is not a TCP tuning issue. A connection can and quite correctly stay in CLOSE_WAIT forever while the program holds the connection open.

Once the local program closes the socket, the OS can send the FIN to the remote end which transitions you to LAST_ACK while you wait for the ACK of the FIN. Once that is received, the connection is finished and drops from the connection table.

CLOSING:
Both server and client represents waiting for a connection termination request acknowledgement from the remote TCP.

Closing should be a relatively rare state. The most obvious way for it to occur is that both ends call close at the same time. However, both ends should then acknowledge the other’s FIN, and then they should move to TIME_WAIT.

LAST_ACK:
Both server and client represents waiting for an acknowledgment of the connection termination request previously sent to the remote TCP, which includes an acknowledgement of its connection termination request.

The LAST_ACK state is the state when you have received your FIN message to close the connection from  your neighbor, but you still need to flush and shutdown your connection. You send the final FIN yourself and wait for an ACK.

TIME_WAIT:
Either server or client represents waiting for enough time to pass to be sure the remote TCP received the acknowledgement of its connection termination request.

According to RFC 793 a connection can stay in TIME-WAIT for a maximum of four minutes known as a MSL (maximum segement lifetime).

TCP uses a special handshake to close completed sessions. The TIME_WAIT state is used to handle possible problems that may occur in the network relating to unreliable or delayed delivery. Accordingly, TCP holds connection for a temporary waiting period (TIME_WAIT) to ensure that any delayed packets are caught and not treated as new connection requests.

Reduced TIME_WAIT in windows:
use regedit and create a REG_DWORD named TcpTimedWaitDelay under

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TcpIp\Parameters
Set it to a decimal value of 30 which is for 30 seconds - the miminum

Reduced TIME_WAIT in Linux:
Set the timeout_timewait paramater using the following command:
/sbin/sysctl -w net.ipv4.vs.timeout_timewait=30
This will set TME_WAIT for 30 seconds.

Connection Establishment
To establish a connection, TCP uses a three-way handshake. Before a client attempts to connect with a server, the server must first bind  to and listen at a port open it up for connections, this is called a passive open. Once the passive open is established, a client may initiate an active open, to establish a connection, three way handshake occurs:

  1. SYN: The active open is performed by the client sending a SYN to the server. The client set the segments sequence number to a random value A
  2. SYN-ACK: In response, the server replies with a SYN-ACK. The acknowledgment number is set to one more than the received number (A+1), and the sequence number that the server chooses for the packet is another random number, B.
  3. ACK: Finally, the client sends an ACK back to the server. The sequence number is set to the received acknowledgement value ie. A+1, and the acknowledgement number is set to one more than the received sequence number i.e B+1.

Happy TCP .. ing

Thanks

Hardeep