Configure server-based authentication with Microsoft Dynamics 365 (on-premises) and SharePoint on-premises

 

Updated: November 28, 2016

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

This topic describes how to configure server-based integration between Dynamics 365 (on-premises) and Microsoft SharePoint On-Premises.

Follow the steps, in the order provided, to set up Dynamics 365 (on-premises) with Microsoft SharePoint Server On-Premises.

System_CAPS_importantImportant
  • If a task isn’t completed, for example, if a PowerShell command returns an error message, the issue must be resolved before you continue to the next command, task, or step.

  • Once you enable server-based SharePoint integration, you won't be able to revert to the previous client-based authentication method. Therefore, you can’t use the Microsoft Dynamics CRM List Component after you have configured your Dynamics 365 organization for server-based SharePoint integration.

Before you configure Dynamics 365 (on-premises) and SharePoint On-Premises for server-based integration, the following permissions and prerequisites are required.

Microsoft Dynamics 365

  • System Administrator security role - this is required to run the Enable Server-Based SharePoint Integration wizard in Microsoft Dynamics 365.

  • 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 On-Premises

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

  • X509 digital certificate to be used for server-based authentication between Microsoft Dynamics 365 Server and the SharePoint server. The certificate keys must have a minimum of 2048-bit encryption. In most cases this certificate must be issued by a trusted certificate authority, but for evaluation purposes you can use a self-signed certificate.

  • The identity for the CRMAppPool application pool must have read access to the x509 certificate that will be used for server-based authentication with Microsoft Dynamics 365 Server and the SharePoint server. You can use the Certificates MMC snap-in to grant this access.

  • If you use Microsoft SharePoint 2013, for each SharePoint farm, only one Microsoft Dynamics 365 organization can be configured for server-based integration.

The CertificateReconfiguration.ps1 is a Windows PowerShell script that installs a certificate to the local certificate store, grants the specified Microsoft Dynamics 365 Asynchronous Processing Service identity access to the certificate, and updates Microsoft Dynamics 365 Server to use the certificate.

Add the server-to-server certificate to the local certificate store and Microsoft Dynamics 365 configuration database

  1. Open a PowerShell command prompt on the server where Microsoft Dynamics 365 Server is installed. For server role deployments, this is the server where the Deployment Tools server role is running.

  2. Change your location to the <drive>:\Program Files\Microsoft Dynamics CRM\Tools folder.

  3. Run the CertificateReconfiguration.ps1 Windows PowerShell script where:

    • certificateFile path\Personalcertfile.pfx . Required parameter that specifies the full path to the personal information exchange file (.pfx). More information: Working with digital certificates

    • password personal_certfile_password. Required parameter that specifies the private certificate password.

    • certificateType S2STokenIssuer. Required parameter that specifies the type of certificate. For Microsoft Dynamics 365 and SharePoint server-based integration, only S2STokenIssuer is supported.

    • serviceAccount 'contoso\CRMAsyncService' or ‘Network Service’. Required parameter that specifies the identity for the Microsoft Dynamics 365 Asynchronous Processing Service. The identity is either a domain user account or Network Service. The identity will be granted permission to the certificate.

    • updateCrm. Adds the certificate information to the Microsoft Dynamics 365 configuration database.

    • storeFindType FindBySubjectDistinguishedName. Specifies the type of certificate store. By default, this value is FindBySubjectDistinguishedName and is recommended when you run the script.

    System_CAPS_importantImportant

    Although the updateCrm and StoreFindType parameters are optional to run the command, these parameters are required for server-based SharePoint integration so that certificate information is added to the certification database.

    Example

    .\CertificateReconfiguration.ps1 -certificateFile c:\Personalcertfile.pfx -password personal_certfile_password -updateCrm -certificateType S2STokenIssuer -serviceAccount contoso\CRMAsyncService -storeFindType FindBySubjectDistinguishedName
    

Get the Dynamics 365 Realm ID

  1. Start the Enable Server-Based SharePoint Integration wizard. Go to Settings > Document Management.

  2. Click Next, click On-Premises, and then Next.

  3. The ID is displayed next to Dynamics 365 Realm Id on the page.

    System_CAPS_tipTip

    Save the Dynamics 365 Realm ID in a text file on a secure network share or cloud-based storage. Then you can easily retrieve it from the location where you run the Enable Server-Based SharePoint Integration wizard.

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

Prepare the SharePoint server for Dynamics 365 Server authentication

  1. If you are using a PowerShell management shell that is not the SharePoint Management Shell, you must register the SharePoint module using the following command.

    Add-PSSnapin Microsoft.SharePoint.PowerShell
    

    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. Create the trusted security token service object, where OrganizationName is the unique name of the Microsoft Dynamics 365 organization and CrmServer is the name of the IIS web server where the Microsoft Dynamics 365 web application server role is installed, and -Name “crm” is used to name the security token server (STS).

    System_CAPS_importantImportant
    • Connecting more than one Microsoft Dynamics 365 organization to a single SharePoint server is not supported.

    • When you run the New-SPTrustedSecurityTokenIssuer PowerShell command you must specify HTTPS for the Microsoft Dynamics 365 metadata endpoint when the Microsoft Dynamics 365 application web site has only HTTPS or both HTTPS and HTTP bindings, like the following example.

    New-SPTrustedSecurityTokenIssuer –Name "crm" –IsTrustBroker:$false –MetadataEndpoint https://CrmServer/XrmServices/2015/metadataendpoint.svc/json?orgName=OrganizationName
    
  3. Register Microsoft Dynamics 365 with the SharePoint site collection.

    To run the following commands, you must specify two parameters:

    • The SharePoint On-Premises site collection URL. In the example here, https://sharepoint.contoso.com/sites/crm/ is used for the site collection URL.

    • The CrmRealmId is the ID of the Microsoft Dynamics 365 organization you want to use for document management with SharePoint. More information: Get the Dynamics 365 Realm ID

    System_CAPS_importantImportant

    To complete these commands, 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 topic in Configure an environment for apps for SharePoint (SharePoint 2013).

    $CrmRealmId = "CRMRealmId"
    
    $Identifier  = "00000007-0000-0000-c000-000000000000@" + $CrmRealmId
    
    $site = Get-SPSite "https://sharepoint.contoso.com/sites/crm/"
    
    Register-SPAppPrincipal -site $site.RootWeb -NameIdentifier $Identifier -DisplayName "crm"
    
  4. Grant the Microsoft Dynamics 365 application access to the SharePoint site.

    System_CAPS_noteNote

    In the example below, the Microsoft Dynamics 365 application is granted permission to the specified SharePoint site collection by using the –Scope sitecollection parameter. The Scope parameter accepts the following options. Use the scope that is most appropriate for your SharePoint configuration:

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

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

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

    $app = Get-SPAppPrincipal -NameIdentifier $Identifier -Site $site.Rootweb
    Set-SPAppPrincipalPermission -AppPrincipal $app -Site $site.Rootweb -Scope "sitecollection" -Right "FullControl" -EnableAppOnlyPolicy
    #"Set up claims-based authentication mapping"
    New-SPClaimTypeMapping -IncomingClaimType "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "EmailAddress" -SameAsIncoming
    
    
    

  1. In the Microsoft Dynamics 365 app, go to Settings > Document Management.

  2. In the Document Management area, click Enable Server-Based SharePoint Integration.

  3. Review the information and then click Next.

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

  5. On the Prepare Sites stage, enter the following information:

    •  SharePoint On-Premises site collection URL, such as https://sharepoint.contoso.com/sites/crm. The site must be configured for TLS/SSL.

    • SharePoint Realm ID. Get the SharePoint realm ID

  6. Click Next.

  7. The validate sites section appears. If all sites are valid, click Enable. If one or more sites are invalid, see Troubleshooting Dynamics 365 Server (on-premises) to SharePoint Server On-Premises server-based integration.

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 365. Go to Settings > Document Management. More information: Customer Center: Enable document management on entities

After you complete Microsoft Dynamics 365 and SharePoint On-Premises server-based integration configuration, you can also integrate OneDrive for Business. With Microsoft Dynamics 365 OneDrive for Business integration, Microsoft Dynamics 365 users can create and manage private documents using OneDrive for Business. Those documents can be accessed within Dynamics 365 once the system administrator has enabled OneDrive for Business.

On the Windows Server where SharePoint Server On-Premises is running, open the SharePoint Management Shell and run the following commands.

Add-Pssnapin *
# Access WellKnown App principal
[Microsoft.SharePoint.Administration.SPWebService]::ContentService.WellKnownAppPrincipals

# Create WellKnown App principal
$ClientId = "00000007-0000-0000-c000-000000000000"
$PermissionXml = "<AppPermissionRequests AllowAppOnlyPolicy=""true""><AppPermissionRequest Scope=""http://sharepoint/content/tenant"" Right=""FullControl"" /><AppPermissionRequest Scope=""http://sharepoint/social/tenant"" Right=""Read"" /><AppPermissionRequest Scope=""http://sharepoint/search"" Right=""QueryAsUserIgnoreAppPrincipal"" /></AppPermissionRequests>"

$wellKnownApp= New-Object -TypeName "Microsoft.SharePoint.Administration.SPWellKnownAppPrincipal" -ArgumentList ($ClientId, $PermissionXml)

$wellKnownApp.Update()

For information about how to troubleshoot the Enable Server-Based SharePoint Integration wizard and view SharePoint monitoring logs, see Troubleshooting server-based authentication.

For documentation management with SharePoint troubleshooting and known issues, see Troubleshooting server-based authentication.

By default, server-based authentication between Dynamics 365 (on-premises) and SharePoint on-premises uses the user’s security identifier (SID) to authenticate each user. If Microsoft Dynamics 365 Server and SharePoint are located in different Active Directory domains that do not have a trust, you must use a custom claims-based authentication mapping, such as the user’s email address. More information: Define custom claim mapping for SharePoint server-based integration

The following procedure creates a personal information exchange file (.pfx).

  1. On a computer that has access to the certificate you want to use for server-to-server authentication, Click Start, click Run, type MMC, and then press Enter.

  2. Click File, then click Add/Remove Snap-in.

  3. In the Available snap-ins list, click Certificates, click Add, click Computer account, click Next, click Finish to select the local computer, and then click OK.

  4. Expand Certificates, expand Personal, and then click Certificates.

  5. Right-click the certificate that you want to use to create a personal certificate file, point to All Tasks, and then click Export.

  6. Click Next, click Yes to export the private key, make sure the following options are checked, and then click Next.

    • Include all certificates in the certification path if possible

    • Export all extended properties

  7. Click Browse and enter a location and file name for the .pfx file, and then click Save.

  8. Click Next and then click Finish.

Run the following PowerShell command in the SharePoint Management Shell, where https://sharepoint.contoso.com/sites/crm/ is the URL for the SharePoint site collection.

Get-SPAuthenticationRealm -ServiceContext https://sharepoint.contoso.com/sites/crm/

Alternatively, you can find the SharePoint realm ID in the site app permissions setting of the SharePoint site collection.

  1. Sign in to the SharePoint site collection that you will use for document management with Microsoft Dynamics 365.

  2. Go to Site settings > Site app permissions.

  3. The realm ID is displayed under App Identifier to the right of the @ sign. Copy it to the clipboard. In the Enable Server-Based SharePoint Integration wizard, paste in only the GUID. Do not paste in any part of the identifier to the left of @.

© 2017 Microsoft. All rights reserved. Copyright

Community Additions

ADD
Show: