Managing Sync Connections with *-SPProfileSyncConnection cmdlets in Service Pack 1

Print | posted on Tuesday, July 12, 2011 9:20 PM

One of the most common conversations I have with customers, partners and random SharePoint consultants is around the creation of SharePoint Server 2010 User Profile Synchronization Connections. These guys are the key link, or connection string if you will between the User Profile Service Application (UPA) and the connected directory services. A very common complaint is the inability to automate their creation using Windows PowerShell. The good news is that Service Pack 1 (SP1) introduces a couple of new cmdlets which help in this regard. This post looks at these cmdlets and also details why they might not be all you had hoped for…

[UPDATE 25/08/2011]

Please note that these cmdlets are only intended for use within SharePoint Online environments by SharePoint Online engineers. Their use in on premises deployments is NOT supported. You have been warned!

What is a Synchronization Connection?

A Sync Connection is the link between the User Profile Synchronization service instance (UPS) and the connected directory services. When they are created a Forefront Identity Manager (FIM) Management Agent is created behind the scenes and it’s these bad boys which do the work of getting data to and from the connected sources to SharePoint. Sync Connections can be created easily using the UPA’s Configure Synchronization Connections page. However this page suffers from numerous flaws, especially when working with enterprise directory services implementations.

Why do people want to automate them?

There are a number of reasons, but there are usually one of two key drivers. Firstly a lot of people promise customers a 100% automated SharePoint deployment. This of course is a nirvana that cannot be achieved with SharePoint 2010. Of course automation is a good thing, but it’s just a silly promise that cannot be met. It’s a bad driver on it’s own. Any SharePoint practitioner with any credibility would never make such a promise.

Secondly, and more importantly one of the key limitations of the Configure Synchronization Connections page is that it can’t really handle the directory services design of many large enterprise AD implementations. There are some timeouts that can be configured, but often these will not suffice and it becomes impossible using this page to create the connections in the manner desired. The page doesn’t scale basically. This leaves us with but one other approach, to use the Synchronization Services Manager (miisclient.exe) after creating the connection in UPA management to change the selected containers. Unfortunately such an approach is NOT supported.

Thus being able to create the connections using Windows PowerShell would avoid this problem.

The new Windows PowerShell cmdlets.

Service Pack 1 therefore introduces two new cmdlets for working with Sync Connections, Add-SPProfileSyncConnection and Remove-SPProfileSyncConnection. Luckily for us they decided not to spell out Synchronization in full :). These cmdlets do make it easier to manage Sync Connections, however there are some considerable limitations. Furthermore note that there is no Get-SPProfileSyncConnection or Update-SPProfileSyncConnection. Also rather annoyingly, like all of the new cmdlets in SP1 whilst of course get-help is implemented there are no examples.

Without further ado here is how to use Add-SPProfileSyncConnection:

$upa = Get-SPServiceApplication 972fe314-7eb9-47b7-a265-20ffbc94680b
$syncAccountPassword = convertto-securestring "Password1" -asplaintext -force

Add-SPProfileSyncConnection -ProfileServiceApplication $upa `
			-ConnectionForestName "contoso.com" `
			-ConnectionDomain "Contoso" `
			-ConnectionUserName "spups" `
			-ConnectionPassword $syncAccountPassword `
			-ConnectionSynchronizationOU "OU=SharePoint Users,DC=contoso,DC=com"

Looks pretty straightforward right? Almost! But not quite!

There are some additional optional parameters. For reference the full params are:

Now that’s all very nice. However there are some key limitations with the cmdlet which will impact how much you can use it in a real deployment.

1. The account running the PowerShell host must be added as an administrator for the UPA
   This isn’t really a limitation but it upsets purists. Instead of using the Proxy, we need the UPA itself, and this means we must have at least the Manage User Profiles administration rights on the UPA. If you don’t have this and attempt to run the cmdlet, you will receive the generic error from FIM, “MOSS MA Not Found”.
2. There is no DisplayName parameter
   The name of the connection will be the NETBIOS name of the domain, i.e. the ConnectionDomain parameter. This will also be used for the Description. This also means that you can add only one connection per domain. Now this is strong recommended practice, but it prevents some scenarios from being possible with this cmdlet and is a major oversight.
3. There's no option to create more than one connection per forest
   Since you have to specify the ConnectionDomain parameter. Again more than one connection per forest is strongly discouraged but there are numerous scenarios where this is needed. Again this cmdlet is no use to you if you are in that boat.
4. If you specify the same ConnectionDomain parameter, the system will overwrite the ConnectionSynchronizationOU, ConnectionUserName and ConnectionPassword parameters.
5. If the connection cannot be created due to a FIM error, the command completes
   No errors are reported at all! We still need to use miisclient.exe to verify things have worked!
6. Remove-SPProfileSyncConnection does not delete sync connections!
   The Remove-SPProfileSyncConnection cmdlet only removes the ConnectionSynchronizationOU specified, will not delete the connection itself. There is no way to use these cmdlets to delete sync connections.
7. These cmdlets only work for Active Directory Sync Connections

A couple of other things to understand about the cmdlets:

When creating the connection you may receive permission related errors, if so you need to use user@domain as the format for the ConnectionUserName parameter.

If you have an existing Sync Connection for the domain and omit the ConnectionSynchronizationOU parameter, it will update the credentials for the connection.

Conclusion

We have a couple of new cmdlets which do help the automation of sync connections. However they have significant limitations which restrict their value, and they could have been so much better. Ensure you are familiar with the limitations before diving in and attempting scripted UPA nirvana! :) We still have no cmdlets for working with connection filters.

[UPDATE 25/08/2011]

Please note that these cmdlets are only intended for use within SharePoint Online environments by SharePoint Online engineers. Their use in on premises deployments is NOT supported. You have been warned!

.