Export (0) Print
Expand All

Configure server-to-server authentication from SharePoint Server 2013 to SharePoint Online

SharePoint 2013
 

Applies to: SharePoint Online, SharePoint Server 2013

Topic Last Modified: 2015-05-12

Summary: Learn how to build a server-to server trust between SharePoint Server 2013 and SharePoint Online.

This article is part of a roadmap of procedures for configuring SharePoint hybrid solutions. Be sure you're following a roadmap when you do the procedures in this article.

This article provides guidance for the SharePoint hybrid environment deployment process, which integrates SharePoint Server 2013 and SharePoint Online.

TipTip:
For the most reliable outcome, complete the procedures in the order they are shown in this article.

In SharePoint hybrid, federated users can send requests to SharePoint Online from any SharePoint Server 2013 web application that’s configured to use Integrated Windows authentication with NTLM.

For example, you have to make sure that the on-premises search center site(s) that you want to use in your solution are configured to use Integrated Windows authentication with NTLM. If they’re not, you have to either reconfigure the web application to use Windows authentication with NTLM or use a search center site on a web application that meets this requirement. You also have to make sure that the users who expect search results to be returned from SharePoint Online are federated users.

To verify that a web application meets the requirement
  1. Confirm that the user account that will do this procedure is a member of the Farm Administrators SharePoint group.

  2. In Central Administration, click Application Management > Manage web applications.

  3. In the Name column, select the web application that you want to verify, and then on the ribbon, click Authentication Providers.

  4. In the Authentication Providers dialog box, in the Zone column, click the zone the search center site is associated with.

  5. In the Edit Authentication dialog box, verify that Integrated Windows authentication and NTLM are selected as shown in the following picture.

    This figure illustrates the authentication type setting for a web application

By default, OAuth in SharePoint Server 2013 requires HTTPS. If you configured your primary web application to use HTTP instead of SSL, you have to enable OAuth over HTTP on every web server in your SharePoint Server 2013 farm.

NoteNote:
If you configured your primary web application to use SSL, this step is not required, and you can skip ahead to Create and configure a target application for the SSL certificate in SharePoint Online.

To enable OAuth over HTTP, run the following commands as a farm administrator account from the SharePoint 2013 Management Shell command prompt on each web server in your SharePoint Server 2013 farm.

$serviceConfig = Get-SPSecurityTokenServiceConfig
$serviceConfig.AllowOAuthOverHttp = $true
$serviceConfig.Update()

If you have enabled OAuth over HTTP for testing but want to reconfigure your environment to use SSL, you can disable OAuth over HTTP by running the following commands as a farm administrator account from the SharePoint 2013 Management Shell command prompt on each web server in your SharePoint Server 2013 farm.

$serviceConfig = Get-SPSecurityTokenServiceConfig
$serviceConfig.AllowOAuthOverHttp = $false
$serviceConfig.Update()

This section will help you set up server-to-server authentication among:

  • SharePoint Server 2013

  • SharePoint Online

  • Azure Active Directory

When you set up server-to-server authentication for hybrid environments, you create a trust relationship between your on-premises SharePoint farm and your SharePoint Online tenant, which uses Azure Active Directory as a trusted token signing service. By adding the required Windows PowerShell modules and snap-ins, this process can occur in a single Windows PowerShell window on an on-premises SharePoint web server.

TipTip:
You’ll want to keep a record of your steps, the Windows PowerShell cmdlets you run, and any errors that you might encounter. You should capture all the contents of the Windows PowerShell buffer when you have finished and before you close the window. This will give you a history of the steps that you took, which will be helpful if you have to troubleshoot or explain the process to others. This can also be useful to refresh your memory if the setup happens in stages.

Here’s a high-level view of the procedures you have to complete in this section:

  1. Configure the Security Token Service (STS) in SharePoint Server 2013:

    • Create a new STS certificate.

    • Replace the default STS certificate on each server in your SharePoint Server 2013 farm.

  2. Install online service management tools on a web server in your SharePoint Server 2013 farm.

  3. Configure server-to-server authentication:

    • Set variables you’ll be using in later steps.

    • Upload the new on-premises STS certificate to SharePoint Online.

    • Add a Service Principal Name (SPN) to Azure.

    • Register the SharePoint Online application principal object ID with on-premises SharePoint Server 2013.

    • Configure a common authentication realm between your on-premises SharePoint Server 2013 farm and SharePoint Online.

    • Configure an Azure Active Directory application proxy on-premises.

To continue, you need to install these tools on an on-premises SharePoint Server 2013 web server:

  • The Microsoft Online Services Sign-In Assistant

  • The Azure Active Directory Module for Windows PowerShell

  • The SharePoint Online Management Shell

This is most easily accomplished on a web server in your SharePoint farm because it’s easier to load the Microsoft.SharePoint.PowerShell snap-in on the web servers than on servers that don’t have SharePoint Server 2013 installed.

Authentication to SharePoint Server 2013, SharePoint Online, and Azure Active Directory requires different user accounts. For information about how to determine which account to use, see Accounts needed for hybrid configuration and testing.

NoteNote:
To make it easier to complete the steps in this section, we'll open a Windows PowerShell Command Prompt window on a SharePoint Server 2013 web server and add the modules and snap-ins that let you connect to SharePoint Server 2013, SharePoint Online, and Azure Active Directory. (We'll give you detailed steps on how to do this later in this article.) We'll then keep this window open to use for all the remaining Windows PowerShell steps in this article.

To install the online service management tools and configure the Windows PowerShell window:

  1. Install the online service management tools:

    1. Install the Microsoft Online Services Sign-In Assistant:

      Microsoft Online Services Sign-In Assistant for IT Professionals BETA (64 bit version) (http://go.microsoft.com/fwlink/?LinkId=391943)

      For additional information, see Microsoft Online Services Sign-In Assistant for IT Professionals RTW (http://go.microsoft.com/fwlink/?LinkId=392322).

    2. Install the Azure Active Directory Module for Windows PowerShell:

      Azure Active Directory Module for Windows PowerShell (64 bit version) (http://go.microsoft.com/fwlink/p/?linkid=236297)

      For additional information about Azure Active Directory Module for Windows PowerShell, see Manage Azure Active Directory by using Windows PowerShell (http://aka.ms/aadposh).

    3. Install the SharePoint Online Management Shell:

      SharePoint Online Management Shell (64 bit version) (http://go.microsoft.com/fwlink/?LinkId=392323)

      For additional information, see Introduction to the SharePoint Online management shell (http://go.microsoft.com/fwlink/?LinkId=392324).

  2. Open a Windows PowerShell window.

  3. To help ensure that you don’t fill the buffer and lose any of your command history, increase the buffer size of the Windows PowerShell window:

    1. Click the upper-left corner of the Windows PowerShell window, and then click Properties.

    2. In the Windows PowerShell Properties window, click the Layout tab.

    3. Under Screen Buffer Size, set the Height field to 9999, and then click OK.

  4. This step loads the modules you downloaded so you can use them in your Windows PowerShell session. Copy the following commands into your Windows PowerShell session, and press Enter.

    Add-PSSnapin Microsoft.SharePoint.PowerShell
    Import-Module Microsoft.PowerShell.Utility
    Import-Module MSOnline -force
    Import-Module MSOnlineExtended -force
    Import-Module Microsoft.Online.SharePoint.PowerShell -force
    

    If you need to run any of the configuration steps again later, remember to run these commands again to load the required modules and snap-ins in Windows PowerShell.

  5. Configure remoting in Windows PowerShell:

    From the Windows PowerShell command prompt, type the following commands.

    enable-psremoting
    new-pssession
    

    For more information, see about_Remote_Requirements (http://go.microsoft.com/fwlink/?LinkId=392326).

  6. To log on to your SharePoint Online tenant, from the Windows PowerShell command prompt, type the following commands.

    $cred=Get-Credential
    Connect-MsolService -Credential $cred
    

    You are prompted to log on. You need to log on using an Office 365 global administrator account.

    Leave the Windows PowerShell window open until you've completed all the steps in this article. You need it for a variety of procedures in the following sections.

You have to replace the STS certificate in the on-premises SharePoint farm. The job of this certificate is to establish trust between the Security Token Service of your on-premises SharePoint site collection and the SharePoint Online tenant. This enables the STS Service and Azure Active Directory to sign security tokens for authenticated users.

For production environments, we recommend your new STS certificate be issued by a public Certificate Authority (CA). This gives you the highest level of certificate security and reduces the chance a self-signed certificate will have integration issues with other applications and services. You can use a self-signed certificate for test or pilot environments.

ImportantImportant:
Certificates usually expire after one year. So plan in advance for certificate renewals to avoid service interruptions. This certificate must have at least 2048 bit encryption.

If you obtained an STS certificate from a CA during planning, go to Replace the STS Certificate. Otherwise, if you want to create a self-signed certificate, continue to Create a self-signed certificate.

In this step, you create a new self-signed SSL certificate to use as your STS certificate. You create a new certificate in two file formats:

  • .pfx, which contains the private key

  • .cer, which does not contain the private key

You use IIS Manager when you do this, as illustrated by the following figure.

This picture shows where to click in IIS Manager to create a self-signed certificate

This figure illustrates IIS Manager

To generate a self-signed certificate as a Personal Information Exchange (.pfx) file and then export it as a .cer file, use the IIS snap-in to complete the following steps.

Create the self-signed certificate as a .pfx file
  1. On a web server in your SharePoint Server farm, click Start > Administrative Tools > Internet Information Services (IIS) Manager.

  2. Click the name of your server.

  3. In the details pane, double-click Server Certificates under IIS.

  4. In the Actions pane, click Create Self-Signed Certificate.

  5. On the Specify Friendly Name page, specify a friendly name for the certificate, and then click OK.

  6. In the details pane, right-click the new certificate, and then click Export.

  7. In Export Certificate, specify a path and name to store the .pfx file for the certificate in Export to, and specify a password for the certificate file in Password and Confirm password. This creates a .pfx file that contains the private key.

  8. Click Finish, and then click OK twice.

Export the self-signed certificate as a .cer file
  1. Right-click the new certificate you created in the last step, and then click View.

  2. On the Details tab, click Copy to File.

  3. Click Next on the wizard.

  4. On the Export Private Key page, click Next.

  5. On the Export File Format page, choose Base-64 encoded X.509 (.CER). Click Next.

  6. For Export Certificate, type a path and file name for the .cer file. Click Next.

  7. Click Finish, and then click OK twice.

To replace the STS certificate on each server in the SharePoint Server 2013 farm, you have to complete the following two procedures in the order shown:

  • Replace the STS certificate in the certificate store.

  • Update the settings of the SharePoint security token service (STS) identity provider.

To replace the STS certificate in the Windows certificate store, follow these steps on each server in the SharePoint Server 2013 farm.

To replace the STS certificate in the certificate store
  1. Verify that the user account running this procedure is a member of the Farm Administrators group.

  2. Click Start > Run.

  3. Type mmc, and then press ENTER. If a User Account Control dialog box is displayed, click Yes.

  4. Go to File > Add/Remove Snap-in > Certificates > Add > Computer account > Next > Finish, and then click OK.

  5. Click the plus sign to expand Certificates, right-click Trusted Root Certification Authorities > All Tasks > Import.

  6. Click Next. The Welcome to the Certificate Import Wizard dialog box is displayed.

  7. Click Browse. Select the *.cer file name you want to import, click Open, and then click Next.

  8. Under Certificate Store, click Place all certificates in the following store, make sure Trusted Root Certification Authorities is chosen (as shown in the following picture) and then click Next.

    Illustrates the name of the certificate store to be chosen
  9. Click Finish.

  10. Repeat steps 1 through 9 on the other front-end web and application servers in the SharePoint Server farm.

In this procedure, you will update the settings of the STS service.

CautionCaution:
Do this procedure during a maintenance window because after replacing the STS certificate on each farm server, you need to restart IIS and the SharePoint timer service. This will interrupt the service of your SharePoint Server 2013 farm.
To replace a STS certificate by using SharePoint 2013 Management Shell
  1. Copy the following values of the following variable declarations that are specific to your organization, and then paste them into a text editor like Notepad.

    • <path to replacement certificate (.pfx file)>
      e.g. c:\certificates\NewSTScert.pfx

    • <certificate password>

  2. At the Windows PowerShell command prompt, paste the following commands:

    $pfxPath = "<path to replacement certificate (.pfx file)>"
    $pfxPass = "<certificate password>"
    $stsCertificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2 $pfxPath, $pfxPass, 20
    Set-SPSecurityTokenServiceConfig -ImportSigningCertificate $stsCertificate
    certutil -addstore -enterprise -f -v root $stsCertificate
    iisreset
    net stop SPTimerV4
    net start SPTimerV4
    
    NoteNote:
    These commands will not display any output if they are successful.
  3. To validate this step, on each server in the farm, at the Windows PowerShell command prompt type:

    $stsCertificate |fl
    

    In the output on the screen, confirm that the certificate has the new friendly name.

  4. Repeat steps 1 through 6 on each remaining front-end web and application server in the SharePoint Server 2013 farm.

Now that you installed the tools to enable you to remotely administer Azure Active Directory and SharePoint Online, you’re ready to set up server-to-server authentication.

This section describes the variables you will set in the procedure that follows. These variables contain important information used in many of the remaining configuration steps.

 

Variable

Comments

$spcn

The root domain name of your public domain. This value should not be in the form of a URL; it should be the domain name only, with no protocol.

An example is adventureworks.com.

$spsite

The internal URL of your on-premises primary web application, such as http://sharepoint or https://sharepoint.adventureworks.com. This value is a full URL using the proper protocol (either http:// or https://).

This is the internal URL of the web application that you are using for hybrid functionality.

An example is http://sharepoint or https://sharepoint.adventureworks.com.

$site

The object of your on-premises primary web application. The command that populates this variable gets the object of the site you specified in the $spsite variable.

This variable is automatically populated.

$spoappid

The SharePoint Online application principal ID is always 00000003-0000-0ff1-ce00-000000000000. This generic value identifies SharePoint Online objects in an Office 365 tenant.

$spocontextID

The context ID (ObjectID) of your SharePoint Online tenant. This value is a unique GUID that identifies your SharePoint Online tenant.

This value is automatically detected when you run the command to set the variable.

$metadataEndpoint

The URL that is used by your Azure Active Directory proxy to connect to your Azure Active Directory tenancy.

You don't need to input a value for this variable.

Now that you identified the variables that you need to set, use these instructions to set them. Pre-populating the most commonly used variables should help you do the remaining steps faster. These variables remain populated as long as you don’t close the Windows PowerShell session. Be careful to provide accurate information wherever you see angle brackets (< >), and always remove the angle brackets before you run the command. Don’t alter the code outside of the angle brackets.

NoteNote:
If you have to do any of these configuration steps again later, you should begin by running the following Windows PowerShell commands in this step to repopulate the important variables.

Copy the following variable declarations and paste them into a text editor like Notepad. Set the input values specific to your organization. From the Windows PowerShell command prompt you configured with the online service management tools, run the commands.

$spcn="*.<public_root_domain_name>.com"
$spsite=Get-Spsite <principal_web_application_URL>
$site=Get-Spsite $spsite
$spoappid="00000003-0000-0ff1-ce00-000000000000"
$spocontextID = (Get-MsolCompanyInformation).ObjectID
$metadataEndpoint = "https://accounts.accesscontrol.windows.net/" + $spocontextID + "/metadata/json/1"

After you populate these variables, you can view their values by entering the variable name in the Windows PowerShell window. For example, entering $metadataEndpoint returns a value similar to the following:

https://accounts.accesscontrol.windows.net/00fceb75-246c-4ac4-a0ad-7124xxxxxxxx/metadata/json/1

In this step, you upload the new STS certificate to your SharePoint Online tenant, which enables SharePoint Server 2013 and SharePoint Online to connect to and consume each other’s service applications.

This figure illustrates the architecture involved when a STS certificate is uploaded to SharePoint Online

The commands in this step add the new on-premises STS certificate and private key to the SharePoint Online principal object of your Office 365 tenancy.

NoteNote:
These steps use the STS certificate files in both the .pfx and the .cer format.

Copy the following variable declarations and paste them into a text editor like Notepad. Set the input values specific to your organization, and from the Windows PowerShell command prompt, type the following commands.

$cerPath = "<path to replacement certificate (.cer file)>"
$cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2 -ArgumentList $pfxPath, $pfxPass
$cer.Import($cerPath)
$binCert = $cer.GetRawCertData()
$credValue = [System.Convert]::ToBase64String($binCert);
New-MsolServicePrincipalCredential -AppPrincipalId $spoappid -Type asymmetric -Usage Verify -Value $credValue

In this step, you add a service principal name (SPN) to your Azure Active Directory tenant. The SPN is comprised of the SharePoint Online principal object and your company’s public DNS namespace.

Just like SPNs function in Active Directory, creating this SPN registers an object in Azure Active Directory that is used to support mutual authentication between SharePoint Server 2013 and your SharePoint Online tenant. The basic syntax for the SPN is:

<service type>/<instance name>

where:

  • <service type> is the SharePoint Online principal object, which is the same for all SharePoint Online tenants.

  • <instance name> is the URL of your company’s public DNS domain namespace, which is always expressed as a wildcard, even if the Secure Channel SSL Certificate is a SAN certificate.

Here’s an example:

00000003-0000-0ff1-ce00-000000000000/*.<public domain name>.com

If the common name in your certificate is sharepoint.adventureworks.com, the syntax of the SPN will look like this:

00000003-0000-0ff1-ce00-000000000000/*.adventureworks.com

Using a wildcard value lets SharePoint Online validate connections with any host in that domain. This is useful if you ever need to change the host name of the external endpoint (if your topology includes one) or if you want to change your SharePoint Server 2013 web application, in the future.

To add the SPN to Azure Active Directory, enter the following commands in the Azure Active Directory Module for Windows PowerShell command prompt.

$msp = Get-MsolServicePrincipal -AppPrincipalId $spoappid
$spns = $msp.ServicePrincipalNames
$spns.Add("$spoappid/$spcn") 
Set-MsolServicePrincipal -AppPrincipalId $spoappid -ServicePrincipalNames $spns

To validate that the SPN was set, enter the following commands in the Azure Active Directory Module for Windows PowerShell command prompt.

$msp = Get-MsolServicePrincipal -AppPrincipalId $spoappid
$spns = $msp.ServicePrincipalNames 
$spns

You should see a current list of SPNs for SharePoint Online in your Office 365 tenancy, and one of the SPNs should include your public root domain name, prefaced by the SharePoint Online application principal ID. This registration is a wildcard registration and should look like the following example:

00000003-0000-0ff1-ce00-000000000000/*.<public domain name>.com

This should be the only SPN in the list that includes your public root domain name.

This step registers the SharePoint Online application principal object ID with the on-premises SharePoint Application Management Service, which allows SharePoint Server 2013 to authenticate to SharePoint Online using OAuth.

From the Windows PowerShell command prompt, type the following commands.

$spoappprincipalID = (Get-MsolServicePrincipal -ServicePrincipalName $spoappid).ObjectID
$sponameidentifier = "$spoappprincipalID@$spocontextID"
$appPrincipal = Register-SPAppPrincipal -site $site.rootweb -nameIdentifier $sponameidentifier -displayName "SharePoint Online"

To validate this step, from the Windows PowerShell command prompt, type the $appPrincipal variable:

$appPrincipal | fl

The expected output is a description of the registered application principal with the name SharePoint Online, which should look something like this.

This figure illustrates the registered application principal for SharePoint Online

This step sets the authentication realm of your SharePoint Server 2013 farm to the context ID of the organization’s Office 365 tenancy.

From the Windows PowerShell command prompt, type the following command.

Set-SPAuthenticationRealm -realm $spocontextID

To validate this step, from the Windows PowerShell command prompt, type the following commands.

$spocontextID
 Get-SPAuthenticationRealm

The output of each of these commands is the GUID that represents the context ID of the SharePoint Online tenancy. These GUIDs should be identical.

ImportantImportant:
If you have configured farm setup scripts that specify the farm authentication realm value, you should update the setup scripts with this new value before you run them again.
For more information about the requirements for realm values in farm setup scripts, see Plan for server-to-server authentication in SharePoint 2013. Because you have now configured this SharePoint farm to participate in the hybrid configuration, the SharePoint farm authentication realm value must always match the tenant context identifier. If you change this value, the farm will no longer participate in hybrid functionality.

In this step, you create an Azure Active Directory proxy service in the SharePoint Server 2013 farm. This enables Azure Active Directory as a trusted token issuer that SharePoint Server 2013 will use to sign and authenticate claims tokens from SharePoint Online.

From the Windows PowerShell command prompt, type the following commands.

New-SPAzureAccessControlServiceApplicationProxy -Name "ACS" -MetadataServiceEndpointUri $metadataEndpoint -DefaultProxyGroup
New-SPTrustedSecurityTokenIssuer -MetadataEndpoint $metadataEndpoint -IsTrustBroker:$true -Name "ACS"

To validate the New-SPAzureAccessControlServiceApplicationProxy command:

  1. Browse the SharePoint 2013 Central Administration website, and click Security > General Security > Manage trust.

  2. Make sure you have an entry with a name that begins with ACS and the type Trusted Service Consumer.

To validate this step, from the Windows PowerShell command prompt, type the following command.

Get-SPTrustedSecurityTokenIssuer

The output that's expected is a description of the farm's trusted token issuer, where the value of the RegisteredIssuerName property is the following:

00000001-0000-0000-c000-000000000000@<context ID>

where <context ID> is the context ID of your SharePoint Online tenancy, which is the value in the $spocontextID variable.

After finishing the tasks in this topic and its validation steps, you should confirm a few final things:

  • Check your SSO and Directory Synchronization setup by using the validation steps in Validate your SSO configuration.

  • Make sure the STS Service in your on-premises SharePoint Server 2013 farm is working. (For example, verify that you can browse your sites and access files and folders without errors.)

    You can manually check the STS certificate on each farm server:

    1. Log on to the server using a farm administrator account.

    2. From the Windows PowerShell command prompt, type the following command:

      Get-ChildItem cert:\LocalMachine\Sharepoint |fl

    3. Make sure you see a certificate that matches the subject and friendly name of your replacement STS certificate.

So that you have a history of the steps you’ve taken, you should capture the entire contents of the Windows PowerShell buffer into a file. This will be crucial if you need to reference your configuration history to troubleshoot, or for any other reasons. This will also help you pick up where you left off if the configuration spans multiple days or involves multiple people.

After you have completed and validated the configuration tasks in this topic, continue with your configuration roadmap.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2015 Microsoft