Define custom claim mapping for SharePoint server-based integration

For server-based integration with SharePoint, Dynamics 365 Customer Engagement (on-premises) uses claims to authenticate and authorize Customer Engagement users to access the documents stored in SharePoint. For more information about claims-based authentication, see Claims-based identity in SharePoint 2013.

By default, Customer Engagement uses the following claims to integrate with SharePoint:

Scenario	Claims
Customer Engagement and SharePoint Online	NameId (PUID) Both Dynamics 365 Customer Engagement (on-premises) and SharePoint share Azure Active Directory for user identity.
Customer Engagement and SharePoint on-premises	SMTP (email) No shared active directory infrastructure for user identity; claims sent as SMTP address. The claims is picked from WindowsLiveID field in Dynamics 365 Customer Engagement (on-premises) and mapped to work email address from SharePoint.
Dynamics 365 Customer Engagement (on-premises) and SharePoint Online	SMTP (email) No shared active directory infrastructure for user identity; claims sent as SMTP address. The claims is picked from PrimaryEmailAddess field in Dynamics 365 Customer Engagement (on-premises) and mapped to work email address from SharePoint.
Dynamics 365 Customer Engagement (on-premises) and SharePoint on-premises	SMTP (email) Both Dynamics 365 Customer Engagement (on-premises) and SharePoint share Microsoft Windows Server Active Directory for user identity.

You can use the UserMapping entity to specify custom claim mappings in Customer Engagement to use a value other than the default value used by Customer Engagement to authenticate and authorize Customer Engagement users in SharePoint. For example, you can use the “last name” and “first name” of the user instead of “email” to authenticate Customer Engagement users in SharePoint. Custom claim mappings override the default claim mappings used by Customer Engagement. You can define multiple custom claim mappings in Customer Engagement. By default, only users having the System Administrator role have access to the UserMapping entity.

To define a custom claim mapping in Customer Engagement, create a UserMapping entity record, and specify the attribute values listed in the following table.

Attribute	Value	Description
UserMapping.PartnerApplicationType	- 0: SharePoint - 1: For internal use only.	The partner application type for which this claim mapping is to be used. In the current release, only 0 (SharePoint) is supported.
UserMapping.SystemUserAttributeName	String value	The logical name of the attribute in the SystemUser (user) entity from where the value for the claims will be used. Note: If the attribute used for custom claim mapping doesn’t contain a value, the default claim mapping is used by Customer Engagement. For example, if you want to use the first name of the user as the attribute for custom claim mapping and a user’s first name is missing, Customer Engagement will use the default claim mapping (PUID or email).
UserMapping.ClaimType	String value	Specify the claim type to be sent to SharePoint. For a list of claim types, see ClaimTypes Members. Note: The referred claim type list is just for reference. All the claim types listed there might not be supported by SharePoint, or might not contain all the claim types supported by SharePoint.

The following sample code shows how to define a custom claim mapping using the UserMapping entity.

UserMapping customMapping = new UserMapping  
{  
   PartnerApplicationType = new OptionSetValue(0),  
   SystemUserAttributeName = "personalemailaddress",  
   ClaimType = "smtp"  
};  
_serviceProxy.Create(customMapping);  

Note

Any instance of the UserMapping entity with valid values will override the default claim mappings used by Customer Engagement.

By default, SharePoint supports the following claim types: NameId (PUID), SMTP (email), and UPN (user principal name). If you’re passing a claim of any other type, you must also create corresponding claim type mappings in SharePoint. More information:New-SPClaimTypeMapping

See Also

UserMapping Entity
Integrate Microsoft Dynamics 365 Customer Engagement (on-premises) with SharePoint