Configure server-based authentication with Customer Engagement (on-premises) and SharePoint Online

Article
08/02/2022

This topic describes how to configure server-based authentication between Dynamics 365 Customer Engagement (on-premises) and Microsoft SharePoint Online.

Permissions required

Customer Engagement (on-premises)

System Administrator security role. This is required to run the Enable Server-Based SharePoint Integration wizard in Customer Engagement (on-premises).
If you are using a self-signed certificate for evaluation purposes, you must have local Administrators group membership on the computer where Microsoft Dynamics 365 Server is running.

SharePoint Online

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

Set up server-based authentication with Customer Engagement (on-premises) and SharePoint Online

Follow the steps in the order provided to set up Customer Engagement (on-premises) with SharePoint Online.

Important

The steps described here must be completed in the order provided. If a task is not completed, such as a Windows PowerShell command that returns an error message, the issue must be resolved before you continue to the next command, task, or step.
After you enable server-based SharePoint integration, you can’t revert to the previous client-based authentication method. This means you can’t use the Microsoft Dynamics CRM List Component after you have configured your Customer Engagement (on-premises) organization for server-based SharePoint integration.
To connect multiple Customer Engagement (on-premises) organizations in the same Customer Engagement (on-premises) deployment to more than one SharePoint Online site, the SharePoint Online sites must be in the same Microsoft Office 365 tenant.

Verify prerequisites

Before you configure Customer Engagement (on-premises) and SharePoint Online for server-based authentication, the following prerequisites must be met:

The Customer Engagement (on-premises) deployment must already be configured and available through the Internet. More information: Configure IFD for Dynamics 365 for Customer Engagement (on-premises)
Microsoft Dynamics 365 Hybrid Connector. The Microsoft Dynamics 365 Hybrid Connector is a free connector that lets you use server-based authentication with Dynamics 365 (on-premises) and SharePoint Online. More information: Microsoft Dynamics CRM Hybrid Connector
An x509 digital certificate issued by a trusted certificate authority that will be used to authenticate between Customer Engagement (on-premises) and SharePoint Online. If you are evaluating server-based authentication, you can use a self-signed certificate.

The following software feature is required to run the Windows PowerShell cmdlets described in this topic.

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.

Set up server-based authentication

On the Dynamics 365 Server where the deployment tools server role is running, start the Azure Active Directory Module for Windows PowerShell.

Important

The computer where you run the following PowerShell commands must have the prerequisite software features described earlier in Verify prerequisites.

Prepare the certificate.

$CertificateScriptWithCommand = “.\CertificateReconfiguration.ps1 -certificateFile c:\Personalcertfile.pfx -password personal_certfile_password -updateCrm -certificateType S2STokenIssuer -serviceAccount contoso\CRMWebApplicationService -storeFindType FindBySubjectDistinguishedName”

 Invoke-Expression -command $CertificateScriptWithCommand

Prepare the PowerShell session.

The following cmdlets enable the computer to receive remote commands and add Office 365 modules to the PowerShell session.
```
Enable-PSRemoting -force
New-PSSession
Import-Module MSOnline -force
Import-Module MSOnlineExt -force
```
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 MSOnline module for Azure Active Directory PowerShell commands listed here, see MSOnline.
```
$msolcred = get-credential
connect-msolservice -credential $msolcred
```

Set the certificate.

$Certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
$Certificate.Import(“c:\Personalcertfile.cer”)
$CERCertificateBin = $Certificate.GetRawCertData()
$CredentialValue = [System.Convert]::ToBase64String($CERCertificateBin)

Set the Azure Active Directory Service Principal Name (SPN) in SharePoint.

Replace *.contoso.com with the domain name where Microsoft Dynamics 365 Server is located.

$RootDomain = “*.contoso.com”
$CRMAppId = "00000007-0000-0000-c000-000000000000" 
New-MsolServicePrincipalCredential -AppPrincipalId $CRMAppId -Type asymmetric -Usage Verify -Value $CredentialValue
$CRM = Get-MsolServicePrincipal -AppPrincipalId $CRMAppId
$ServicePrincipalName = $CRM.ServicePrincipalNames
$ServicePrincipalName.Remove("$CRMAppId/$RootDomain")
$ServicePrincipalName.Add("$CRMAppId/$RootDomain")
Set-MsolServicePrincipal -AppPrincipalId $CRMAppId -ServicePrincipalNames $ServicePrincipalName

Configure the Microsoft Dynamics 365 Server for server-based authentication with SharePoint.

Add-PSSnapin Microsoft.Crm.PowerShell 
$setting = New-Object "Microsoft.Xrm.Sdk.Deployment.ConfigurationEntity"
$setting.LogicalName = "ServerSettings"
$setting.Attributes = New-Object "Microsoft.Xrm.Sdk.Deployment.AttributeCollection"
$attribute1 = New-Object "System.Collections.Generic.KeyValuePair[String, Object]" ("S2SDefaultAuthorizationServerPrincipalId", "00000001-0000-0000-c000-000000000000")
$setting.Attributes.Add($attribute1)
$attribute2 = New-Object "System.Collections.Generic.KeyValuePair[String, Object]" ("S2SDefaultAuthorizationServerMetadataUrl", "https://accounts.accesscontrol.windows.net/metadata/json/1")
$setting.Attributes.Add($attribute2)
Set-CrmAdvancedSetting -Entity $setting

Run the Enable Server-Based SharePoint Integration Wizard

In the Customer Engagement (on-premises), go to Document Management.
In the Document Management area, choose Enable server-based SharePoint integration.
Review the information and then select Next.
For the SharePoint sites, select Online, and then select Next.
On the Prepare Sites stage, enter the following information.
- Enter the SharePoint Online site collection URL, such as https://contoso.sharepoint.com/sites/salesteam.
- Enter the tenant ID. More information: Get the SharePoint online tenant ID
Select Next.
The validate sites section appears. If all sites are determined to be valid, select Enable. If one or more sites are determined to be invalid, see Troubleshooting server-based authentication.

Get the SharePoint online tenant ID

Use PowerShell

In the Azure Active Directory module for Windows PowerShell shell, run the following commands.
```
$CRMContextId = (Get-MsolCompanyInformation).ObjectID
$CRMContextId
```
Copy the GUID that is displayed to the clipboard.

Use site settings

Sign in to the SharePoint site collection that you will use for document management with Customer Engagement (on-premises).
Go to Site settings > Site app permissions.

The tenant ID is displayed under App Identifier, to the right of the @ sign. Copy and paste in only the GUID. Do not paste in any part of the identifier to the left of @.

Troubleshoot enable server-based authentication wizard validation issues

Failed Authentication. This error can be returned when the certificate used for server-to-server authentication is missing or invalid.