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

 

Updated: November 28, 2016

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

Introduced with Microsoft Dynamics CRM Online 2015 Update 1, server-based Microsoft SharePoint integration for document management can be used to connect Microsoft Dynamics 365 (online) with SharePoint on-premises. When using server-based authentication, Azure AD Domain Services is used as the trust broker and users do not need to sign in to SharePoint.

Dynamics 365 (online) and SharePoint on-premises

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 AzurePowerShell cmdlets.

Microsoft Dynamics 365 (online)

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

    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.

Follow the steps in the order provided to set up Dynamics 365 (online) with SharePoint 2013 on-premises.

System_CAPS_importantImportant
  • The steps described here must be completed in the order provided. If a task is not completed, such as a PowerShell command that 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 Microsoft Dynamics 365 (online) and SharePoint on-premises for server-based authentication, the following prerequisites must be met:

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 DirectoryPowerShell 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 Azure Active Directory.

    
    $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.

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.

System_CAPS_cautionCaution

Running this command changes the authentication realm of the SharePoint on-premises farm. For applications that use an existing security token service (STS), this may cause unexpected behavior with other applications that use access tokens. More information: Set-SPAuthenticationRealm.


Set-SPAuthenticationRealm -Realm $SPOContextId

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 Azure Active Directory.

    New-SPAzureAccessControlServiceApplicationProxy -Name "Internal" -MetadataServiceEndpointUri $metadataEndpoint -DefaultProxyGroup
    
    
    System_CAPS_noteNote

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

  4. Create the new token control service issuer in SharePoint on-premises for Azure Active Directory.

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

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 365 with the SharePoint site collection.

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

    System_CAPS_importantImportant

    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 365 application access to the SharePoint site. Replace https://sharepoint.contoso.com/sites/crm/ with your SharePoint site URL.

    System_CAPS_noteNote

    In the following example, the Dynamics 365 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 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 $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.

    System_CAPS_importantImportant

    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 "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "EmailAddress" -SameAsIncoming
    
    

In the Microsoft Dynamics 365 app, follow these steps:

  1. 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 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. Click Next.

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

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 authentication configuration, you can also integrate OneDrive for Business. With Microsoft Dynamics 365 and OneDrive for Business integration, Dynamics 365 users can create and manage private documents using OneDrive for Business. Those documents can be accessed in 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()

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. Note that whatever claims-based authentication type you use, the values, such as email addresses, must match between  Microsoft Dynamics 365 (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 Define custom claim mapping for SharePoint server-based integration.

System_CAPS_importantImportant

To enable the Work email property, SharePoint on-premises must have a User Profile Service Application configured and started. To enable a User Profile Service Application in SharePoint, see Create, edit, or delete User Profile service applications in SharePoint Server 2013. To make changes to a user property, such as Work email, see Edit a user profile property. For more information about the User Profile Service Application, see Overview of the User Profile service application in SharePoint Server 2013.

© 2017 Microsoft. All rights reserved. Copyright

Community Additions

ADD
Show: