SharePoint Services Connector for FIM 2010 R2 Technical Reference

The objective of this document is to provide you with the reference information that is required to deploy the SharePoint User Profile Store connector for Microsoft® Forefront® Identity Manager (FIM) 2010 R2.

Overview of the SharePoint User Profile Store Connector

The SharePoint User Profile Store connector enables you manage SharePoint resources using FIM 2010 R2 SP1. The connector is available as a download from the Microsoft Download Center. From a high level perspective, the following features are supported by the current release of the connector:

Requirement	Support
Connect to data source	Server: SharePoint server 2013 with User Profile service application (UPA)
Scenario	Object Lifecycle Management User Management
Operations	Full import Delta import for updates Export
Schema	User Group Contact

In SharePoint 2013, a user profile is a collection of properties that describes a single user, and also the policies and other settings associated with each property. The user who is described by a profile is represented by a unique identifier in the profile, and the remaining properties provide information about that user, such as the user's phone numbers, manager, office number, job title, and so on. The set of user profiles for a SharePoint Server 2013 farm are stored in the profiles database associated with a User Profile service application.

As shown in the following illustration, user profiles can be composed of properties that are imported from a directory service, imported from business systems, and supplied by users.

Deploying a SharePoint User Profile Store connector in your FIM environment provides the following benefits:

Support for heterogeneous directory environments – The SharePoint User Profile Store connector enables you to synchronize data from any directory that you manage using FIM into the SharePoint user profile store. Since data from other sources is now consumable by SharePoint applications, you can make additional application functionality available to your SharePoint users.

Support for multiple ADDS forests - The SharePoint User Profile Store connector enables you to synchronize data that has been contributed by various ADDS forests into the SharePoint user profile store. For users that are distributed amongst various forests, you can simplify the ability to access data in a SharePoint.

Connected Data Source Requirements

In order to manage objects using a FIM 2010 R2 connector, you need to make sure that all requirements of the connected data source are fulfilled. This includes tasks such as opening the required network ports and granting the necessary permissions. The objective of this section is to provide an overview of the requirements of a connected data source to perform the desired operations.

Connected Data Source Permissions

When you configure the management agent for SharePoint 2013, you need to specify an account that is used by the management agent to connect to the SharePoint 2013 central administration web site. The account must have administrative rights on SharePoint 2013 and on the computer where SharePoint 2013 is installed.

If the account doesn’t have full access to SharePoint 2013 and the local folders on the SharePoint computer, you might run into issues during, for example, an attempt to export the picture attribute.

If possible, you should use the account that was used to install SharePoint 2013.

Ports and Protocols

During the installation of Microsoft SharePoint Foundation 2013, the Central Administration Web site is established on a randomly-assigned TCP port, or on a port that you select when you create the farm. You need to determine the number of the port that is used by the computer running the Central Administration Web site because you need to specify this port when configuring your management agent. In addition to this, you also need to make sure that this port is not blocked by a firewall when configuring your management agent.

Connector Deployment

Before you can start with the installation of a connector, you need to make sure that the deployment prerequisites are satisfied. The objective of this section is to give you an overview of what these prerequisites are and to provide you with the required information to install and configure your SharePoint User Profile Store connector.

Deployment Prerequisites

The management agent for SharePoint 2013 expects a specific FIM build to be installed on your FIM synchronization server. The connector can only be deployed on the version of the FIM synchronization service that is included in this package. In addition this this, the management agent requires the .Net 4.5 framework to be installed.

User Profile Synchronization Service Configuration

Before you can install the management agent for SharePoint 2013, you need to make sure that user profile synchronization service is installed but not running on your SharePoint server.

Configuring the User Profile Synchronization Service

1. To install the user profile synchronization service, on your SharePoint server, go to Administration > System Setting > Manage Services on Server:

   

2. If the user profile synchronization service is not started, click Start.

   

   Note

   It can take 15 – 30 minutes to install the service.

3. When the user profile synchronization service is installed, you need to disable the user profile incremental synchronization. The related configuration page is under “Central Administration > Monitoring > Job Definitions”.

   

4. As a last step, you need to disable the internal Forefront Identity Manager synchronization service.

   

Connector Installation and Configuration

This section provides an overview of the SharePoint User Profile Store connector installation and configuration.

Connector Installation

The SharePoint User Profile Store connector is a standalone setup package available from the Microsoft Download Center.

The connector is installed at the following location:

%Program Files%\Microsoft Forefront Identity Manager\2010\Synchronization Service\Extensions

Connector Configuration

You configure your SharePoint User Profile Store connector by using the Management Agent Designer.
For the management agent for SharePoint, only the “Connectivity” has configuration settings that are specific to this management agent.

In the following section, you will find configuration details for this page.

Connectivity

On the Connectivity page, you specify the SharePoint server configuration, the account used to connect to SharePoint and the user picture settings.

The following screenshot shows an example for the related configuration page:

Object Lifecycle Management

This section provides an overview of the supported object types and the required attributes for each object type.

Group Objects

The group object on SharePoint has a fixed schema. Additionally, all attributes of a group object are “export only”. This means, they cannot be changed on the SharePoint side. Therefore, schema discovery is not required for this object type.

Attribute Name	ProfileIdentifier
Data Type	String
Multi-Valued	No
Flow Direction	Export only
Notes	There is no specific source attribute value you are required to populate this attribute with. The best practice recommendation is to populate this attribute with the DN of the originating object.

Attribute Name	SID
Required	Yes
Data Type	String
Multi-Valued	No
Flow Direction	Export only
Notes	The SID attribute is only required if the originating object is located in ADDS to enable SharePoint authentication for this object type. In this case, you should populate this attribute with the value the originating object’s SID..

Contact Objects

The contact object on SharePoint has a fixed schema. Additionally, all attributes of a group object are “export only”. This means, they cannot be changed on the SharePoint side. Therefore, schema discovery is not required for this object type.

The following section lists the required attributes of a contact object:

Attribute Name	ProfileIdentifier
Data Type	String
Multi-Valued	No
Flow Direction	Export only
Notes	There is no specific source attribute value you are required to populate this attribute with. The best practice recommendation is to populate this attribute with the DN of the originating object.

User Objects

In SharePoint, the user object schema is customizable. As a consequence of this, a schema discovery is required to show the full list of attributes that are available for the user object.
Because the attributes of the group and contact objects are export only, the user object attributes with the same name as contact of group attributes must be export only, too.
By default, the attributes of a user object can be part of import and export attribute flow rules. However, some attributes require special considerations. In SharePoint, attributes can be configured to be auto-changed by an administrator. The affected attributes can be identified by a meta-data field of an attribute called “TermSet”. If the “TermSet” for an attribute is set to anything but NULL, the attribute should be treated as export only to avoid an infinite loop of updates.

The following section lists the required attributes of a user object:

Attribute Name	ProfileIdentifier
Data Type	String
Multi-Valued	No
Flow Direction	Export only
Notes	For ADDS originated users, the format of this attribute should be “domain\username”. For all other sources, the format should be “domain:username”.

Determining the domain attribute value of an object is a bit challenging because domain is not an attribute of a user in ADDS. For example, when this attribute is required in AD DS, the directory service has to look up the value from the configuration container. The following screenshot shows an example for this:

You can find a solution for populating the domain attribute for a user in How Do I Synchronize Users from AD DS to FIM.

Attribute Name	SID
Required	Yes
Data Type	String
Multi-Valued	No
Flow Direction	Export only
Notes	The SID attribute is only required if the originating object is located in ADDS to enable SharePoint authentication for this object type. In this case, you should populate this attribute with the value the originating object’s SID.

Provisioning Objects

The management agent for SharePoint supports declarative provisioning based on a synchronization rule and provisioning based on a metaverse rules extension.

Declarative Provisioning

When you configure a synchronization rule, you need to configure an initial flow for the DN attribute. In the case of the management for SharePoint, you can use any value that is unique to the management agent’s connector space.

For example, you could populate the DN using the originating objects GUID in the case of an ADDS source object. This value is later replaced by SharePoint with the actual SharePoint anchor generated by SharePoint.

Provisioning Using a Metaverse Rules Extension

If your provisioning implementation is based on a metaverse rules extension, there is no need to specify a DN attribute value when you create a new connector. The following code snippet shows a simplified example for this.

Best Practice Recommendations and Known Issues

The objective of this section is to provide you with best practice recommendations for deploying the SharePoint Services connector and information about known issues.

Import of existing users

Due to specifics of the current SharePoint implementation, when you run a full import or a delta import, users that have been created using the SharePoint user interface won’t be staged in the connector space of the SharePoint management agent. Only users that have been populated to SharePoint by the legacy user profile synchronization service or using the SharePoint management agent are visible during import operations.

Confirming imports

In FIM, export operations need to be completed by a following import operation that is also known as confirming import.
The SharePoint management agent is an exception to this rule. Due to the specifics of the SharePoint implementation, some export operations are auto-confirmed during an export. This is, for example, true for export operations of new objects including all attributes that are not reference attributes. The FIM user interface shows for the affected objects and attributes a status of pending import” instead of “awaiting import confirmation”.

Updates to already existing objects as well as all operations related to reference attributes are not affected by this exception. For these operations, the status will be still indicated as “awaiting export confirmation” when an export has finished.

Mismatch between exported and imported changes

As mentioned in the previous section, the SharePoint management agent does not require a confirming import for all export operations. As a consequence of this, during an import operation, you should not expect parity between the number of reported export changes and the number of reported import changes.

Population of reference attributes

In SharePoint, values of reference attributes are not immediately calculated. The calculation of reference attribute is subject of a job called "User Profile Service Application - System Job to Manage User Profile Synchronization", which runs on regular intervals. If an export run has with the exception of reference attributes completed as expected, you should verify that you have implemented configured the steps listed under User Profile Synchronization Service Configuration.

Picture attributes

On SharePoint, the picture attribute is handled in a special way. Once exported by the connector, pictures will not be automatically updated in SharePoint. In order to populate the changes, you need to run a PowerShell command on your SharePoint server to make sure that the pictures will appear on the SharePoint side.

The structure of the PowerShell command is:

Update-SPProfilePhotoStore -MySiteHostLocation https://my-server-name/my 
                                -CreateThumbnailsForImportedPhotos $true

To make sure that this task is performed on a regular basis, you should create a job that runs the PowerShell command on a regular basis. You can find a screenshot that shows the related configuration setting for the picture attribute in the Connectivity section,

Even if you ensure that the PowerShell command runs on a regular basis, it is possible that you run into an issue with a full import that is run after an export. This is because SharePoint updates the binary representation of the attribute after an export, which introduces a delta between the exported value and the data available during a following full import. To address this issue, you should perform another export, delta import, delta synchronization cycle.

Attribute considerations

SharePoint performs a normalization on a variety of exported values. As part of this process, a number of special symbols are removed from attribute values. As a side effect of this process, you will see export-not-reimported errors reported by the synchronization engine.

Affected symbols that are:

• ASCII #9 (TAB), #10 (LF), #13 (CR)

• “

• ;

• <

• >

• &

• Leading and trailing spaces

• Multiple spaces that are converted into a single space

The recommended workaround to this issue is to preprocess the affected attributes in advanced export attribute flow rules from the metaverse to the SharePoint connector space to ensure that attribute values staged for an export don’t have these special symbols.

Attribute Population Considerations

SharePoint performs an attribute validation on some attribute values and removes the values if they don’t pass the validation. This is, for example, true for attributes that are expected to contain an email address.

The affected attributes will result in exported-not-reimported errors during an import.

You should verify whether SharePoint attribute value validation is reason for it if this error is reported in your environment.

Troubleshooting

For information on how to enable logging to troubleshoot the connector, see the How to Enable ETW Tracing for FIM 2010 R2 Connectors

See Also

Concepts

Management Agents in FIM 2010 R2
Understanding Data Synchronization with External Systems
Introduction to Inbound Synchronization
Introduction to Synchronization Policy Based Outbound Synchronization

Other Resources

FIM User Forum
FIM 2010 Management Agents from Partners
How to Enable ETW Tracing for FIM 2010 R2 Connectors