Configure server-based authentication with SharePoint on-premises

Server-based SharePoint integration for document management can be used to connect customer engagement apps (Dynamics 365 Sales, Dynamics 365 Customer Service, Dynamics 365 Field Service, Dynamics 365 Marketing, and Dynamics 365 Project Service Automation), with SharePoint on-premises. When using server-based authentication, Microsoft Entra Domain Services is used as the trust broker and users do not need to sign in to SharePoint.

Permissions required

The following memberships and privileges are required to enable SharePoint document management.

• Microsoft 365 Global admin membership - this is required for:

  • Administrative-level access to the Microsoft 365 subscription.
  • Running Enable Server-based Authentication wizard.
  • Running the AzurePowerShell cmdlets.

• Power Apps Run SharePoint Integration Wizard privilege. This is required to run the Enable Server-based Authentication wizard.

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

• For SharePoint on-premises integration, SharePoint 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 SharePoint on-premises

Follow the steps in the order provided to set up customer engagement apps with SharePoint 2013 on-premises.

Important

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.

Verify prerequisites

Before you configure customer engagement apps and SharePoint on-premises for server-based authentication, the following prerequisites must be met:

SharePoint prerequisites

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

  Important

  SharePoint Foundation 2013 versions aren't supported for use with customer engagement apps document management.

• Install the April 2019 Cumulative Update (CU) for the SharePoint 2013 product family. This April 2019 CU includes all SharePoint 2013 fixes (including all SharePoint 2013 security fixes) released since SP1. The April 2019 CU does not include SP1. You need to install SP1 before installing the April 2019 CU. More information: KB4464514 SharePoint Server 2013 April 2019 CU

• SharePoint configuration

  • If you use SharePoint 2013, for each SharePoint farm, only one customer engagement app can be configured for server-based integration.

  • 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) on TCP port 443 (no custom ports are supported) 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 customer engagement apps. More information: Selecting a claims mapping type

  • For document sharing, the SharePoint search service must be enabled. More information: Create and configure a Search service application in SharePoint Server

  • For document management functionality when using the Dynamics 365 mobile apps, the on-premises SharePoint server must be available through the Internet.

Other prerequisites

• SharePoint Online license. Customer engagement apps to SharePoint on-premises server-based authentication must have the SharePoint service principal name (SPN) registered in Microsoft Entra ID. 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 Microsoft 365 subscription that includes SharePoint Online. For example, if you have Microsoft 365 E3, you have the appropriate licensing even if the license isn't assigned to a user.

    For more information about these plans, see Find the right solution for you 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

  • MSOnlineExt

  • To install the MSOnlineExt module, enter the following command from an administrator PowerShell session. PS> Install-Module -Name "MSOnlineExt"

  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 Microsoft Entra Module for Windows PowerShell. MOSSIA is not installed.

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

Update the SharePoint Server SPN in Microsoft Entra Domain Services

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 Microsoft 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 Microsoft 365.

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

   For detailed information about each of the Microsoft Entra IDPowerShell commands listed here, see Manage Microsoft Entra 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 Microsoft 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 Microsoft Entra ID.

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

Caution

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  

Create a trusted security token issuer for Microsoft Entra ID 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 Microsoft Entra ID.

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

   Note

   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 Microsoft Entra ID.

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

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

   Note

   In the following example, the customer engagement app 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 customer engagement apps permission to the specified SharePoint website only. It doesn't grant permission to any subsites under the named site.
     • sitecollection. Grants the customer engagement apps permission to all websites and subsites within the specified SharePoint site collection.
     • sitesubscription. Grants the customer engagement apps 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 "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "EmailAddress" -SameAsIncoming  
   

Run the Enable server-based SharePoint integration wizard

Follow these steps:

1. Verify that you have the appropriate permission to run the wizard. More information: Permissions required

2. Go to Settings > Document Management.

3. In the Document Management area, click Enable server-based SharePoint integration.

4. Review the information and then click Next.

5. For the SharePoint sites, click On-premises, and then Next.

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

7. Click Next.

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

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

Add OneDrive for Business integration

After you complete customer engagement apps and SharePoint on-premises server-based authentication configuration, you can also integrate OneDrive for Business. With customer engagement apps and OneDrive for Business integration, users can create and manage private documents using OneDrive for Business. Those documents can be accessed in once the system administrator has enabled OneDrive for Business.

Enable 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()  
  

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. Note that whatever claims-based authentication type you use, the values, such as email addresses, must match between customer engagement apps and SharePoint. Microsoft 365 directory synchronization can help with this. More information: Deploy Microsoft 365 Directory Synchronization in Microsoft Azure. To use a different type of claims-based authentication mapping, see Define custom claim mapping for SharePoint server-based integration.

Important

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.

See also

Troubleshooting server-based authentication
Set up SharePoint integration with customer engagement apps