This documentation is archived and is not being maintained.
Inside SharePoint SharePoint Directory Integration
Code download available at: SharePoint2008_09.exe (2,775 KB)
Microsoft Windows SharePoint Services (WSS) 3.0 and Microsoft Office SharePoint Server (MOSS) 2007 include directory synchronization capabilities in the form of a Directory Management Service that can provision mail-enabled contacts and group objects for SharePoint resources in Active Directory. Provisioning these types of
recipient objects for SharePoint® resources enables users to select SharePoint libraries, lists, and groups directly from the Microsoft® Outlook® address book when sending documents and other information.
SharePoint recipient objects also provide a way to control message transfer and format conversions in an Exchange Server organization. Among other things, you can prevent unauthenticated senders, such as spammers, from submitting messages to SharePoint libraries by setting message delivery restrictions in Active Directory®.
The SharePoint directory management capabilities are limited, however, and at the time of this writing, assume Exchange Server 2003 as the underlying messaging system. For now, if you use Exchange Server 2007 or a third-party messaging system, you need to extend or replace the built-in directory management features with a custom solution in order to achieve the desired level of interoperability.
In this column I briefly review the SharePoint directory management features and then discuss an approach to overcoming existing limitations. My premise is that the built-in Directory Management Service meets only the most basic user requirements. Environments with a variety of messaging systems and directory platforms need greater flexibility and functionality. By replacing the built-in component with a custom solution, you can synchronize SharePoint recipient information with any directory solution that provides an API or import capabilities.
To prove this point, I show you how to synchronize SharePoint recipient information in way that is compatible with Exchange Server 2007. Similarly, you can use a custom solution to synchronize recipient information with IBM Lotus Notes or other systems.
You also gain the ability to centralize directory provisioning processes based on a metadirectory service, such as Identity Information Server, which is included in Microsoft Identity Lifecycle Manager (ILM) 2007 Feature Pack 1 (FP1). Specifically, I show you how to integrate SharePoint with ILM 2007 to coordinate the provisioning of directory objects for SharePoint document libraries. You can find the tools, source code, and step-by-step instructions to build this solution in the companion material for this column, available in the Code Downloads section of .com.
SharePoint Directory Management Service
Unlike Exchange Server, which uses Active Directory for almost all configuration and recipient information, SharePoint relies on configuration and content databases. SharePoint must therefore propagate recipient information for mail-enabled libraries, lists, and groups from its databases to a directory. After all, messaging clients expect to find recipient information in an address book, which is typically generated from directory objects.
Out of the box, SharePoint includes a Directory Management Service for this purpose, which is part of the E-mail Integration Web service (SharepointEmailWS.asmx) that you can configure in SharePoint 3.0 Central Administration, on the Operations page, under Incoming e-mail settings. Figure 1 illustrates how the built-in Directory Management Service works.
Figure 1 SharePoint Directory Management Service architecture (Click the image for a larger view)
When you enable a Web farm for directory management and then assign a library, list, or group an e-mail address to receive messages, such as by using EmailSettings.aspx, you implicitly call the E-mail Integration Web service to provision corresponding recipient objects in Active Directory. First, SharePoint stores the e-mail address information in the content database. Next, SharePoint sends the provisioning request on your behalf to the E-mail Integration Web service using the identity of the Web application pool account. If the provisioning request fails, you end up with e-mail address information in the content database but without corresponding recipient objects in Active Directory.
Provisioning requests can fail for a number of reasons. The most common reason is missing IIS metabase access permissions. Because SharepointEmailWS.asmx is designed to be a Web service for application pool accounts, this Web service checks the IIS metabase to see if the caller is an application pool account and denies access if that's not the case, regardless of your SharePoint site and Active Directory permission levels.
SharepointEmailWS.asmx performs this access check under the identity of the caller, however, so the calling application pool account needs access to the metabase to verify its own access permissions. This forces you to grant your application pool accounts elevated permissions in order to succeed.
Of course, elevated permissions on a Web server are a source of security concerns. There are better ways to control access to an ASP.NET Web service. Moreover, SharePoint expects to find the Directory Management Service in the Central Administration site, yet this site is not permanently available in a Web farm locked down to reduce the attack surface. So if you want to use the built-in Directory Management Service in your SharePoint production environment, you must accept a weakened security configuration.
Further limitations that exist stem from the fact that the built-in Directory Management Service is based on a tightly coupled client/server architecture. Microsoft.SharePoint.dll uses System.DirectoryServices.dll directly, so you cannot implement your own logic to customize the provisioning process. For example, the built-in Directory Management Service implementation does not write all recipient attributes to support Exchange Server 2007, and there is no option to customize the attribute generation rules.
The inability to implement your own logic also implies that you cannot customize the provisioning process, for example, to implement custom approvals. SharePoint supports approval processes for groups, but this feature is based on the Central Administration site. Only SharePoint Farm Administrators can approve pending requests, yet SharePoint administrators are not necessarily in charge of approving Active Directory provisioning processes.
Perhaps even more importantly, there are no approval processes for mail-enabled document libraries and lists. If you enable directory management, you essentially grant all site administrators in your Web farm the right to create mail-enabled contacts and groups in Active Directory. Nor is it possible to structure recipient management based on organizational units (OUs), because all recipient objects per Web farm are placed in the same OU.
You cannot move the recipient objects to another OU because the Directory Management Service expects to find the recipient objects in the SharePoint OU, and you must grant the SharePoint Central Administration application pool account administrative permissions in Active Directory. Also, there is no way to implement two-way synchronization between SharePoint and Active Directory. Changing object attributes in Active Directory does not propagate the changes back into the SharePoint environment.
Custom Directory Management Service
Now that I've established that the built-in Directory Management Service leaves some room for building additional flexibility, let's discuss some alternatives. The good news is that SharePoint lets you implement your own directory management service. You need only register your Web service as a remote Directory Management Service in SharePoint 3.0 Central Administration, on the Operations page, under Incoming e-mail settings.
For detailed step-by-step instructions to deploy and register a custom Web service, see the worksheet "Directory Integration Based on a Custom Directory Management Service.xps" in the companion material. Also, my custom Web service shows how to provision Exchange Server 2007-compatible recipient objects in Active Directory without cmdlets or Exchange management tools. The corresponding source code is in the EmailIntegrationService folder. Figure 2 illustrates the solution architecture.
Figure 2 Custom Directory Management Service architecture (Click the image for a larger view)
The interface of the custom Web service must adhere to the Directory Management Service interface, as documented in the SharePoint SDK. If you search the MSDN® Web site (msdn.microsoft.com) for "SharepointEmailWS," you can find all the required details. You can also check out the Service.cs file in the EmailIntegrationService\App_Code folder in the companion material. This file implements the required Web service interface, while the actual code to provision Active Directory objects resides in SPRecipient.cs. For example, the UpdateRecipientAttributes function in SPRecipient.cs generates the required Exchange Server 2007 attributes. SPRecipient.cs is the code file that you must replace if you want to develop your own custom directory management service.
A custom directory management service is a good tool for overcoming elevated permission requirements and integrating SharePoint with third-party directory or messaging systems. You do not have to check the IIS metabase to limit Web service access to application pool accounts. Instead, you can add an <authorization> section to your Web service's web.config file (see the companion material for an example).
Several issues remain, however, because you can't control if and when SharePoint calls your directory management service. Among other things, SharePoint does not call the Directory Management Service when you are deleting a mail-enabled document library or list, and so an invalid recipient object remains in Active Directory. Whether you use the built-in Directory Management Service or a custom solution, you cannot guarantee that the recipient information in Active Directory is consistent with the SharePoint resources.
SharePoint and ILM
To achieve reliable directory integration, you should consider deploying a professional directory management package, such as ILM. This system relies on a pull-based directory synchronization model. Management agents pull information from their connected sources, import it into a common metadirectory, and export information from the metadirectory into their connected systems. Source systems do not generally push their information into the metadirectory. By pulling information, you can ensure consistency with each synchronization cycle.
Another benefit is that ILM includes several management agents to support Active Directory, Lotus Notes, and a variety of other systems out of the box. You only need to implement a custom management agent for SharePoint in order to synchronize SharePoint information with another supported directory platform in your environment.
You must implement the logic to retrieve the desired information from SharePoint, save the information in an import file, and transfer the imported information into the metadirectory. But you don't need to implement the logic to export that information from the metadirectory into Active Directory or another directory platform. Figure 3 illustrates how to implement synchronization from SharePoint to Active Directory using ILM. It is also possible to achieve synchronization in the other direction to provision SharePoint resources for directory objects, though this might be considered unnecessary or optional.
Figure 3 Identity Lifecycle Manager-based directory integration (Click the image for a larger view)
A good starting point for developing a SharePoint management agent is Alex Tcherniakhovski's article "Connecting ILM 2007 with SharePoint Services Lists" at blogs.msdn.com/alextch/archive/2007/09/02/wsslistsandilm.aspx. Alex shows how to build an ILM-based directory management solution that relies on InfoPath®-based provisioning requests submitted to a document library. Alex's management agent retrieves all approved requests from the document library and creates corresponding metadirectory objects that can then be exported into connected directories.
But by default, SharePoint does not generate InfoPath-based provisioning requests when you mail-enable a list or group. You can achieve this through a custom directory management service, but then you'll encounter the consistency issues mentioned earlier because SharePoint does not call the directory management service under all circumstances. For this reason, I recommend that your management agent retrieves the desired SharePoint recipient information directly from the lists and groups in your site collection. If you need approval processes, you can then generate InfoPath-based provisioning requests for new resources in the management agent and subsequently process all approved requests.
You have several options to retrieve SharePoint information. You can read the information directly from the content databases, use the SharePoint object model, or take advantage of SharePoint Web services.
Accessing content databases directly is not recommended because the database structures might change in future versions, which would break your directory management solution.
Using the SharePoint object model directly in your management agent is similarly tricky because the object model requires you to run the code locally, yet installing ILM on a Web server in every SharePoint farm in your environment can complicate the directory management infrastructure.
You might think to use SharePoint Web services, but that creates another difficulty because the desired information is not easily accessible through SharePoint Web services, such as e-mail address information for SharePoint groups or the Incoming E-Mail Server Display Address.
In the end, it seems best to implement a custom SharePoint Web service that uses the SharePoint object model to retrieve the desired information, returning it to the caller in the form of an XML document. Now you can centralize the ILM deployment and integrate any number of farms and site collections through individual instances of the custom SharePoint Web service, as illustrated in Figure 3.
There is one remaining aspect worth mentioning, which is that ILM-based directory integration does not eliminate the need for a custom directory management service. This custom service does not need to perform any work because ILM provisions the directory objects, yet you must provide a custom service so that you can enable directory management in SharePoint 3.0 Central Administration. Otherwise, for example, you will not be able to assign e-mail addresses to groups in the first place. Figure 4 shows the resulting solution architecture.
Figure 4 Web Service-based SharePoint directory integration (Click the image for a larger view)
You can turn the custom directory management service included in the companion material into a dummy service by setting the OpMode parameter in the web.config file (<add key="OpMode" value="dummy"/>). In this configuration, the custom service always returns SUCCESS in response to provisioning calls without performing any work.
In addition, the custom service exposes a ResolveUsers method that the SharePoint management agent can call to resolve NetBIOS-based user account names into distinguished names, which is a required step when provisioning groups. (SharePoint returns group membership information as a list of NetBIOS-based user account names, but Active Directory expects distinguished names.) And that's it! For details on how to deploy the resulting solution, see "Configuring Directory Integration based on ILM 2007.xps" in the companion material.
WSS 3.0 and MOSS 2007 include a Directory Management Service to integrate SharePoint with Exchange Server 2003 for messaging-based cross-platform collaboration.
There are several limitations, however. Users must replace the built-in Directory Management Service with a custom solution. You could also use a professional directory management solution, such as ILM, to integrate SharePoint into a directory management infrastructure. This provides the greatest level of flexibility and helps to ensure information consistency through a pull-based synchronization model.
Pav Cherny is an IT expert and author specializing in Microsoft technologies for collaboration and unified communication. His publications include white papers, product manuals, and books with a focus on IT operations and system administration. Pav is president of Biblioso Corporation, a company that specializes in managed documentation and localization services.