Define custom claim mapping for SharePoint server-based integration

Article
11/28/2016

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

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

By default, Dynamics 365 uses the following claims to integrate with SharePoint:

Scenario	Claims
Dynamics 365 (online) and SharePoint Online	NameId (PUID) Both Dynamics 365 and SharePoint share Microsoft Azure Active Directory for user identity.
Dynamics 365 (online) 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 and mapped to work email address from SharePoint.
Dynamics 365 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 and mapped to work email address from SharePoint.
Dynamics 365 on-premises and SharePoint on-premises	Security Identifier (SID) Both Dynamics 365 and SharePoint share Microsoft Windows Server Active Directory for user identity.

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

To define a custom claim mapping in Dynamics 365, 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 Dynamics 365. 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, Dynamics 365 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 Dynamics 365.

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

Define custom claim mapping for SharePoint server-based integration

See Also

Additional resources