Configure server-based authentication with Dynamics CRM Online and SharePoint on-premises

Applies To: Dynamics CRM 2015

Introduced with Microsoft Dynamics CRM Online 2015 Update 1, server-based Microsoft SharePoint integration for document management can now be used to connect Microsoft Dynamics CRM Online with SharePoint on-premises. When you use server-based authentication, Azure Active Directory Access Control Services (ACS) is used as the trust broker and users do not need to sign-in to SharePoint. Additionally, the list control, which requires the deprecated SharePoint sandboxing feature, is not required to display SharePoint documents in Microsoft Dynamics CRM views.

Permissions required

Office 365

• Office 365 Global Administrators membership. This is required for administrative-level access to the Microsoft Office 365 subscription and to run the Microsoft Azure PowerShell cmdlets.

Microsoft Dynamics CRM Online

• Run SharePoint Integration Wizard privilege. This is required to run the Enable Server-based Authentication wizard in Microsoft Dynamics CRM.

  By default, the System Administrator security role has this permission.

SharePoint on-premises

• Farm Administrators group membership. This is required to run most of the PowerShell commands on the SharePoint server.

Set up server-to-server authentication with CRM Online and SharePoint on-premises

Follow the steps in the order provided to set up CRM Online with SharePoint 2013 on-premises.

Verify prerequisites

Before you configure Microsoft Dynamics CRM Online and SharePoint on-premises for server-based authentication, the following prerequisites must be met.

SharePoint prerequisites

• Microsoft SharePoint 2013 (on-premises) with Service Pack 1 (SP1) or later version

  Important

  Microsoft SharePoint Foundation 2013 versions aren’t supported for use with Microsoft Dynamics CRM document management.

• Hotfix KB2883081 for SharePoint Foundation 2013 August 12, 2014 (Sts-x-none.msp) 

  Important

  The following updates are prerequisites to KB2883081 and may also be required.

  • https://support2.microsoft.com/kb/2768000

  • https://support.microsoft.com/kb/2767999

  • https://support.microsoft.com/kb/2880963

• SharePoint configuration

  • SharePoint must be configured for a single farm deployment only.

  • SharePoint website must be accessible via the Internet. A reverse proxy may also be required for SharePoint authentication. More information: Configure a reverse proxy device for SharePoint Server 2013 hybrid

  • SharePoint website must be configured to use SSL (HTTPS) and the certificate must be issued by a public root Certificate Authority. More information: SharePoint: About Secure Channel SSL certificates

  • A reliable user property to use for claims-based authentication mapping between SharePoint and Microsoft Dynamics CRM. More information: Selecting a claims-based authentication mapping type

Other prerequisites

• SharePoint Online license. Microsoft Dynamics CRM Online to SharePoint on-premises server-based authentication must have the SharePoint service principal name (SPN) registered in Azure Active Directory. To achieve this, at least one SharePoint Online user license is required. The SharePoint Online license can derive from a single user license and typically comes from one of the following:

  • A SharePoint Online subscription. Any SharePoint Online plan is sufficient even if the license isn’t assigned to a user.

  • An Office 365 subscription that includes SharePoint Online. For example, if you have Office 365 E3, you have the appropriate licensing even if the license isn’t assigned to a user.

  For more information about these plans, see Office 365: Select a plan and Compare SharePoint options

• The following software features are required to run the PowerShell cmdlets described in this topic.

  • Microsoft Online Services Sign-In Assistant for IT Professionals Beta

  • Azure Active Directory Module for Windows PowerShell (64-bit version)  

  Important

  At the time of this writing, there is an issue with the RTW version of Microsoft Online Services Sign-In Assistant for IT Professionals. Until the issue is resolved, we recommend that you use the Beta version. More information: Microsoft Azure Forums: Cannot install Azure Active Directory Module for Windows PowerShell. MOSSIA is not installed.

• A suitable claims-based authentication mapping type to use for mapping identities between Microsoft Dynamics CRM Online and SharePoint on-premises. By default, email address is used. More information: Grant Microsoft Dynamics CRM permission to access SharePoint and configure the claims-based authentication mapping

Update the SharePoint Server SPN in ACS

On the SharePoint on-premises server, in the SharePoint 2013 Management Shell, run these PowerShell commands in the order given.

1. Prepare the PowerShell session.

   The following cmdlets enable the computer to receive remote commands and add Office 365 modules to the PowerShell session. For more information about these cmdlets see Windows PowerShell Core Cmdlets.

   Enable-PSRemoting -force
   New-PSSession
   Import-Module MSOnline -force
   Import-Module MSOnlineExtended -force
   

2. Connect to Office 365.

   When you run the Connect-MsolService command, you must provide a valid Microsoft account that has Office 365 Global Administrator membership for the SharePoint Online license that is required.

   For detailed information about each of the Azure Active Directory PowerShell commands listed here, see MSDN: Manage Azure AD using Windows PowerShell.

   $msolcred = get-credential
   connect-msolservice -credential $msolcred
   

3. Set the SharePoint host name.

   The value that you set for the variable HostName must be the complete host name of the SharePoint site collection. The hostname must be derived from the site collection url and is case sensitive. In this example, the site collection url is https://SharePoint.constoso.com/sites/salesteam, so the hostname is SharePoint.contoso.com.

   $HostName = "SharePoint.contoso.com"
   

4. Get the Office 365 object (tenant) id and SharePoint Server Service Principal Name (SPN).

   $SPOAppId = "00000003-0000-0ff1-ce00-000000000000"
   $SPOContextId = (Get-MsolCompanyInformation).ObjectID
   $SharePoint = Get-MsolServicePrincipal -AppPrincipalId $SPOAppId
   $ServicePrincipalName = $SharePoint.ServicePrincipalNames
   

5. Set the SharePoint Server Service Principal Name (SPN) in ACS.

   $ServicePrincipalName.Add("$SPOAppId/$HostName") 
   Set-MsolServicePrincipal -AppPrincipalId $SPOAppId -ServicePrincipalNames $ServicePrincipalName 
   

After these commands complete do not close the SharePoint 2013 Management Shell, and continue to the next step.

Update the SharePoint realm to match that of SharePoint Online

On the SharePoint on-premises server, in the SharePoint 2013 Management Shell, run this Windows PowerShell command.

The following command requires SharePoint farm administrator membership and sets the authentication realm of the SharePoint on-premises farm.

Set-SPAuthenticationRealm -Realm $SPOContextId

Create a trusted security token issuer for ACS on SharePoint

On the SharePoint on-premises server, in the SharePoint 2013 Management Shell, run these PowerShell commands in the order given.

The following commands require SharePoint farm administrator membership.

For detailed information about these PowerShell commands, see Use Windows PowerShell cmdlets to administer security in SharePoint 2013.

1. Enable the PowerShell session to make changes to the security token service for the SharePoint farm.

   $c = Get-SPSecurityTokenServiceConfig
   $c.AllowMetadataOverHttp = $true
   $c.AllowOAuthOverHttp= $true
   $c.Update()
   

2. Set the metadata endpoint.

   $metadataEndpoint = "https://accounts.accesscontrol.windows.net/" + $SPOContextId + "/metadata/json/1"
   $acsissuer = "00000001-0000-0000-c000-000000000000@" + $SPOContextId
   $issuer = "00000007-0000-0000-c000-000000000000@" + $SPOContextId
   

3. Create the new token control service application proxy in ACS.

   New-SPAzureAccessControlServiceApplicationProxy -Name "ACSInternal" -MetadataServiceEndpointUri $metadataEndpoint -DefaultProxyGroup
   

   Note

   The New- SPAzureAccessControlServiceApplicationProxy command may return an error message indicating that an ACS application proxy with the same name already exists. If the named ACS application proxy already exists, you can ignore the error.

4. Create the new token control service issuer in SharePoint on-premises for ACS

   $acs = New-SPTrustedSecurityTokenIssuer –Name "ACSInternal" –IsTrustBroker:$true –MetadataEndpoint $metadataEndpoint -RegisteredIssuerName $acsissuer 
   

Grant Microsoft Dynamics CRM permission to access SharePoint and configure the claims-based authentication mapping

On the SharePoint on-premises server, in the SharePoint 2013 Management Shell, run these PowerShell commands in the order given.

The following commands require SharePoint site collection administration membership.

1. Register Microsoft Dynamics CRM with the SharePoint site collection.

   Enter the SharePoint on-premises site collection URL. In this example, https://sharepoint.contoso.com/sites/crm/ is used.

   Important

   To complete this command, the SharePoint App Management Service Application Proxy must exist and be running. For more information about how to start and configure the service, see the Configure the Subscription Settings and App Management service applications subtopic in Configure an environment for apps for SharePoint (SharePoint 2013).

   $site = Get-SPSite "https://sharepoint.contoso.com/sites/crm/"
   Register-SPAppPrincipal -site $site.RootWeb -NameIdentifier $issuer -DisplayName "crm"
   

2. Grant Microsoft Dynamics CRM application access to the SharePoint site. Replace https://sharepoint.contoso.com/sites/crm/ with your SharePoint site URL.

   Note

   In the following example, the CRM application is granted permission to the specified SharePoint site collection by using the –Scope site collection parameter. The Scope parameter accepts the following options. Choose the scope that is most appropriate for your SharePoint configuration.

   • site. Grants the CRM application permission to the specified SharePoint website only. It doesn’t grant permission to any subsites under the named site.

   • sitecollection. Grants the CRM application permission to all websites and subsites within the specified SharePoint site collection.

   • sitesubscription. Grants the CRM application permission to all websites in the SharePoint farm, including all site collections, websites, and subsites.

   $app = Get-SPAppPrincipal -NameIdentifier $issuer -Site "https://sharepoint.contoso.com/sites/crm/"
   Set-SPAppPrincipalPermission -AppPrincipal $app -Site $site.Rootweb -Scope "sitecollection" -Right "FullControl"
   

3. Set the claims-based authentication mapping type.

   Important

   By default, the claims-based authentication mapping will use the user’s Microsoft account email address and the user’s SharePoint on-premises Work email address for mapping. When you use this, the user’s email addresses must match between the two systems. For more information, see Selecting a claims-based authentication mapping type.

   $map1 = New-SPClaimTypeMapping -IncomingClaimType "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "EmailAddress" -SameAsIncoming
   

Run the Enable server-based SharePoint Integration wizard

In the Microsoft Dynamics CRM app, follow these steps.

1. Go to Settings > Document Management.

2. In the Document Management area, choose Enable server-based SharePoint integration.

3. Review the information and then choose Next.

4. For the SharePoint sites, choose On-Premises, and then choose Next.

5. Enter the SharePoint on-premises site collection URL, such as https://sharepoint.contoso.com/sites/crm. The site must be configured for SSL.

6. Choose Next.

7. The validate sites section appears. If all sites are determined valid, choose Enable. If one or more sites are determined invalid, see Troubleshooting server-based authentication.

Select the entities that you want to include in document management

By default, Account, Article, Lead, Product, Quote, and Sales Literature entities are included. You can add or remove the entities that will be used for document management with SharePoint in Document Management Settings in Microsoft Dynamics CRM. Go to Settings > Document Management. More information: Customer Center: Enable document management on entities

Selecting a claims-based authentication mapping type

By default, the claims-based authentication mapping will use the user’s Microsoft account email address and the user’s SharePoint on-premises work email address for mapping. Notice that, whatever claims-based authentication type you use, the values, such as email addresses, must match between the Microsoft Dynamics CRM Online and SharePoint. Office 365 directory synchronization can help with this. More information: Deploy Office 365 Directory Synchronization (DirSync) in Microsoft Azure To use a different type of claims-based authentication mapping, see MSDN: Define custom claim mapping for SharePoint server-based integration.

See Also

Troubleshooting server-based authentication
Set up SharePoint integration with Microsoft Dynamics CRM

© 2016 Microsoft Corporation. All rights reserved. Copyright