Edit

Share via

Configure server-based authentication with SharePoint on-premises

Note

The new and improved Power Platform admin center is now generally available. We're currently updating the documentation to reflect these changes, so check back to ensure that you're getting the latest updates.

Server-based SharePoint integration for document management is 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 don't 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 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 allows 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 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 2016 on-premises.

Important

The steps described here must be completed in the order provided. If a task isn't 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

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 access, 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, go to Find the right solution for you and Compare SharePoint options.

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

    Microsoft.Graph

    To install the Microsoft.Graph module, enter the following command from an administrator PowerShell session.

    $currentMaxFunctionCount =
    $ExecutionContext.SessionState.PSVariable.Get("MaximumFunctionCount").Value

# Set execution policy to RemoteSigned for this session
if ((Get-ExecutionPolicy -Scope Process) -ne "RemoteSigned") {
    Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned -Force
}

# Update MaximumFunctionCount if needed
if ($currentMaxFunctionCount -lt 32768) {
    $ExecutionContext.SessionState.PSVariable.Set("MaximumFunctionCount", 32768)
}

# Install and import required modules
if (-not (Get-Module -ListAvailable -Name "Microsoft.Graph")) {
    $Params = @{
        Name = "Microsoft.Graph"
        Scope = CurrentUser
    }
    Install-Module @Params -Force
}

$Params = @{
    Name = "Microsoft.Graph"
    Function = @("Connect-MgGraph", "Get-MgOrganization")
}
Import-Module @Params

if (-not (Get-Module -ListAvailable -Name "Microsoft.Graph.Identity.DirectoryManagement")) {
    $Params = @{
        Name = "Microsoft.Graph.Identity.DirectoryManagement"
        Scope = CurrentUser
    }
    Install-Module @Params -Force
}

$Params = @{
    Name = "Microsoft.Graph.Identity.DirectoryManagement"
    Function = @("Get-MgServicePrincipal", "Update-MgServicePrincipal")
}
Import-Module @Params

  • 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. Learn more in 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 2016 Management Shell, run these PowerShell commands in the order given.

  1. Connect to Microsoft 365.

    When you run the Connect-MgGraph command, you must provide a valid Microsoft account that has global admin membership for the SharePoint Online license that's required.

    For detailed information about each of the Microsoft Entra IDPowerShell commands listed here, go to Manage Microsoft Entra using Windows PowerShell.

    Connect-MgGraph -Scopes "Directory.ReadWrite.All", "Application.ReadWrite.All"

  2. Set the SharePoint host URL.

    The value that you set for the variable HostNameUrl must be the complete host name URL 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 URL is https://SharePoint.contoso.com.

    Important

    If there are multiple sites, run the following command for each site.

    # Generate Service Principal Name
# Note: If there are multiple sites, and the host is the same, no action is needed.
#       If the host is different, each site needs to be configured to add the 
#       host to the service principal.
$uri = [System.Uri]"https://SharePoint.constoso.com/sites/salesteam"
$hostName = $uri.Host
$baseUrl = "$($uri.Scheme)://$hostName"
$servicePrincipalName = $baseUrl

  3. Get the Microsoft 365 object (tenant) ID and SharePoint Server Service Principal Name (SPN).

    # SharePoint Online App ID
$SPOAppId = "00000003-0000-0ff1-ce00-000000000000"

# Retrieve SharePoint Online Service Principal
$SharePoint = Get-MgServicePrincipal -Filter "AppId eq '$SPOAppId'"

$UpdatedServicePrincipalNames = $SharePoint.ServicePrincipalNames |
    Where-Object { $_ -ne $servicePrincipalName }
$UpdatedServicePrincipalNames += $servicePrincipalName

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

    $maxRetries = 5
$retryDelay = 5 # seconds 

for ($retry = 1; $retry -le $maxRetries; $retry++) {
    try {
        $Params = @{
 	         ServicePrincipalId = $SharePoint.Id
 			     ServicePrincipalNames = $UpdatedServicePrincipalNames
 		   }
 		   Update-MgServicePrincipal @Params
 		   Write-Host "Service Principal Names updated successfully."
 		   break
 	 }
 	 catch {
 		   if ($_.Exception.Message -match "Directory_ConcurrencyViolation" -and
            $retry -lt $maxRetries) {
 			     Write-Host "Concurrency violation detected. (Attempt $retry of $maxRetries)"
 			     Start-Sleep -Seconds $retryDelay
   		 }
   		 else {
     			 Write-Host "Failed to update Service Principal Names. Error: $_"
 		    	 exit 1
        }
    }
}

After these commands complete, don't close the SharePoint 2016 Management Shell. Continue to the next step.

Update the SharePoint realm to match that of SharePoint Online

On the SharePoint on-premises server, in the SharePoint 2016 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 command may cause unexpected behavior with other applications that use access tokens. Learn more in Set-SPAuthenticationRealm.

# SPOContextId is the tenant ID for the dynamics 365 tenant. It is used to identify the tenant in Azure AD and SharePoint Online.
$SPOContextId = "<tenantId>"
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 2016 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, go to Use Windows PowerShell cmdlets to administer security in SharePoint 2016.

  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://login.microsoftonline.com/common/.well-known/openid-configuration"  
$oboissuer = "https://sts.windows.net/*/" 
$issuer = "00000007-0000-0000-c000-000000000000@" + $SPOContextId

  3. Create the new token control service application proxy in Microsoft Entra ID.

    $existingIssuer = Get-SPTrustedSecurityTokenIssuer "D365Obo"
if ($existingIssuer) {
    $Params = @{
        Identity = $existingIssuer
        IsTrustBroker = $true
        MetadataEndpoint = $metadataEndpoint
        RegisteredIssuerName = $oboissuer
    }
    Set-SPTrustedSecurityTokenIssuer @Params
} else {
    $Params = @{
        Name = "D365Obo"
        IsTrustBroker = $true
        MetadataEndpoint = $metadataEndpoint
        RegisteredIssuerName = $oboissuer
    }
    $obo = New-SPTrustedSecurityTokenIssuer @Params
}

Grant customer engagement apps permission to access SharePoint and configure the claims-based authentication mapping

On the SharePoint on-premises server, in the SharePoint 2016 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.

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

  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.

    Important

    If there are multiple sites, run the script for each site.

    $Params = @{
    NameIdentifier = $issuer
    Site = "https://sharepoint.contoso.com/sites/crm/"
}
$app = Get-SPAppPrincipal @Params

$Params = @{
    AppPrincipal = $app
    Site = $site.Rootweb
    Scope = "sitecollection"
    Right = "FullControl"
}
Set-SPAppPrincipalPermission @Params

  3. Set the claims-based authentication mapping type.

    Important

    By default, the claims-based authentication mapping uses the user's Microsoft account email address and the user's SharePoint on-premises work email address for mapping. When you use claims-based authentication mapping, the user's email addresses must match between the two systems. Learn more in Selecting a claims-based authentication mapping type.

    $Params = @{
    IncomingClaimType = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
    IncomingClaimTypeDisplayName = "EmailAddress"
}
$map1 = New-SPClaimTypeMapping @Params -SameAsIncoming

Run the Enable server-based SharePoint integration wizard

Follow these steps:

  1. Verify that you have the appropriate permission to run the wizard. Learn more in 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, go to 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 used for document management with SharePoint in Document Management Settings. Go to Settings > Document Management. Learn more in 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 after the system administrator enables 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 uses the user's Microsoft account email address and the user's SharePoint on-premises work email address for mapping. 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 helps email addresses match. Learn more in Deploy Microsoft 365 Directory Synchronization in Microsoft Azure. To use a different type of claims-based authentication mapping, go to 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, go to Create, edit, or delete User Profile service applications in SharePoint Server 2016. To make changes to a user property, such as Work email, go to Edit a user profile property. For more information about the User Profile Service Application, go to Overview of the User Profile service application in SharePoint Server 2016.

Related content