How to: Create high-trust apps for SharePoint 2013 using the server-to-server protocol (advanced topic)

To follow the steps in this article, be sure you have the following:

• An on-premises SharePoint 2013 development environment. See How to: Set up an on-premises development environment for apps for SharePoint for the setup instructions.

  Note
  If you aren’t sure what kind of app you want to create or whether your development environment will work for the kind of app that you want to create, see Start building apps for Office and SharePoint.

• Experience creating a provider-hosted app for SharePoint. See How to: Create a basic provider-hosted app for SharePoint.

• Visual Studio 2012 installed either remotely or on the computer where you have installed SharePoint 2013.

• Microsoft Office Developer Tools for Visual Studio 2012.

• Familiarity with digital certificates—what they are and how to use them.

Read the following articles to get a better understanding of high-trust apps for SharePoint and how to create them.

A high-trust app is a provider-hosted app for SharePoint for use on-premises, which uses the server-to-server protocol. "High-trust" is not the same as "full trust", and high-trust does not mean the app has full trust. A high-trust app must still request app permissions. The app is considered "high-trust" because it is trusted to use any user identity that the app needs, because the app is responsible for creating the user portion of the access token.

A high-trust app is built for use in an on-premises environment; it's not intended for use in a cloud-hosted environment. Apps that use the server-to-server protocol would typically be installed behind the firewall in instances that are specific to each individual company.

A provider-hosted app that's built for the cloud needs to be rebuilt to work on-premises. You'll have to run certain configuration steps. A high-trust app uses a certificate instead of a context token to establish trust. For more information, see Configure for server-to-server app use and configure trust for your app in this article.

Note
For more information about app permissions, see App permissions in SharePoint 2013.

In SharePoint 2013, the server-to-server security token service (STS) provides access tokens for server-to-server authentication. The server-to-server STS enables temporary access tokens to access other application services such as Exchange 2013, Lync 2013, and apps for SharePoint 2013. You establish a trust relationship between the application services (for example, establishing trust between SharePoint and a remote app) by using Windows PowerShell cmdlets and a certificate.

Note
The server-to-server STS isn't intended for user authentication. Therefore, you won't see the server-to-server STS listed on the user sign-in page, in the Authentication Provider section in Central Administration, or in the People Picker in SharePoint 2013.

This article walks you through the HighTrustSampleApp sample to show you how to create a high-trust app and provides setup instructions for running it. You'll learn to:

• Configure an app for use as a high-trust app.

• Configure SharePoint 2013 to use high-trust apps.

• Create a basic high-trust app.

This example creates and exports a test certificate by using the Create Self Signed Certificate option in IIS. You’ll need a commercial certificate issued by a Certificate Authority when you publish your app.

Alternatively, you can also use the MakeCert test program to generate a test X.509 certificate. For more information about how to use MakeCert, see Signing and checking code with Authenticode.

You’ll create a test .pfx certificate file first, and then a corresponding test .cer file.

Note
For more information about .pfx and .cer files, see Software Publisher Certificate.

To create a test .pfx certificate file

To create a corresponding test .cer file

Note

The .pfx file must be accessible to the computer where Visual Studio is running. The .pfx file must be deployed to the web server that is hosting your web application, in the same file path as the computer running Visual Studio. Alternatively, the path can be adjusted in the web.config file, as shown the Modify Web.config procedure in Creating a provider-hosted app. The .cer file must be accessible to the server running SharePoint.

Next, you generate an issuer ID, which is a GUID. There are many GUID generators online that you can use, or you can use the built-in GUID generator in Microsoft Visual Studio 2012. The issuer ID and the certificate together identify the issuer of the app. The issuer ID must have a one-to-one correspondence with the certificate, so whenever you create a new certificate for a high-trust app, you must create a new issuer ID to associate with it, and if you use the same certificate for more than one app, you must associate the same issuer ID with it. You can also use the following Windows PowerShell command to create a GUID.

[System.Guid]::NewGuid().ToString()

1. Open the SharePoint 15 Management Shell as an administrator.

   Note
   If you haven’t configured app isolation (which is listed as a prerequisite for this article), you must configure it now, before you proceed.

2. On the computer where you installed SharePoint 2013, run the following Windows PowerShell cmdlets to configure trust for your app:

   Note
   You can run these steps once for each development server and share the issuer ID and the certificate that you create for each app that you have in development.

   1. Get the .cer file that you want to use with your app.

      PowerShell

      Copy

      $publicCertPath = "common folder:\HighTrustSampleCert.cer"
      

   2. Get the issuer ID of your app. Currently, all the letters in the issuer ID GUID must be lowercase.

      PowerShell

      Copy

      $issuerId = [System.Guid]::NewGuid().ToString()
      

   3. Get the SharePoint 2013 URL where you will be installing your app.

      PowerShell

      Copy

      $spurl ="http://ContosoSharePoint.com"
      

   4. Get the website where you are installing your app.

      Note
      If you're doing remote development where Visual Studio 2012 and SharePoint 2013 are not installed on the same computer, the root site collection must be created from a Developer Site template. It's required. If Visual Studio 2012 and SharePoint 2013 are installed on the same computer, it isn’t required.

      PowerShell

      Copy

      $spweb = Get-SPWeb $spurl
      

   5. Get the current authentication realm for your SharePoint site.

      PowerShell

      Copy

      $realm = Get-SPAuthenticationRealm -ServiceContext $spweb.Site
      

   6. Get the file that corresponds to the .cer file you’re using for the app.

      PowerShell

      Copy

      $certificate = Get-PfxCertificate $publicCertPath
      

   7. Add the certificate to SharePoint’s list of trusted root certificate authorities.

      PowerShell

      Copy

      New-SPTrustedRootAuthority -Name "unique name for the certificate" -Certificate $certificate
      

   8. Get the issuer ID together with the realm value.

      PowerShell

      Copy

      $fullIssuerIdentifier = $issuerId + '@' + $realm
      

   9. Create a trusted security token service. This fetches metadata from your app (for example, the certificate) and establishes trust with it, so that SharePoint 2013 can accept tokens that are issued by your app.

      PowerShell

      Copy

      New-SPTrustedSecurityTokenIssuer -Name $issuerId -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier –IsTrustBroker
      

      Note
      The –Name parameter must be unique. You cannot reuse a previously used value. If you do, errors will be thrown.

   10. Run the iisreset command to make your new issuer ID valid. The issuer ID will become valid after 24 hours if you do not run iisreset.

Note
The following step is optional. However, we recommend that you develop and test with HTTPS turned on. Turning off HTTPS might cause you as a developer to miss certain issues when building an app that would occur during a production deployment where HTTPS is required.

OAuth now requires SharePoint to run HTTPS, not only for your service but also for SharePoint 2013. You’ll get a 403 (forbidden) message when attempting to make a call to SharePoint by using a test certificate.

On the computer where you have SharePoint 2013 installed, you can turn off the HTTPS requirement during development by using the following Windows PowerShell cmdlets.

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

Remember to turn the HTTPS requirement back on later by using the following Windows PowerShell cmdlets.

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

In this step, you create a provider-hosted app using Microsoft Visual Studio 2012.

Note
As stated in the Prerequisites for creating high-trust apps section, this article assumes you know how to create a provider-hosted app for SharePoint. For more information, , see How to: Create a basic provider-hosted app for SharePoint.

Create an App for SharePoint 2013 project

Run the app

When you are done developing your high-trust app, check How to: Package and publish high-trust apps for SharePoint 2013 for instructions on how to package and publish this kind of app for SharePoint.

The token helper code in TokenHelper.cs does the following:

• Configures .NET to trust certificates when making network calls.

• Retrieves a server-to-server access token that is signed by the application's private certificate on behalf of the specified WindowsIdentity object and that the SharePoint 2013 uses to establish trust.

• Gets the SharePoint security token service (STS) certificate.

• Handles OAuth tokens for the scenario described in OAuth authentication and authorization flow for cloud-hosted apps in SharePoint 2013. That scenario is outside the scope of this article.

For more details, see the comments in the TokenHelper.cs file.

Note

In a high-trust app, there is no context token, even if you use the appredirect.aspx file. The context token is specific to configurations that use Windows Azure Access Control Service (ACS). However, an access token is still required. If you’re using a high-trust configuration, your web application has to authenticate the user in the same way that SharePoint 2013 does (that is, the app is responsible for creating the user portion of the access token).

• How to: Package and publish high-trust apps for SharePoint 2013

• Troubleshooting Tips for High Trust Apps on SharePoint 2013

• Guidelines for registering apps for SharePoint 2013

• OAuth authentication and authorization flow for apps that ask for access permissions on the fly in SharePoint 2013 (advanced topic)

• Authorization and authentication for apps in SharePoint 2013

• App permissions in SharePoint 2013

• Tips and FAQs: OAuth and remote apps for SharePoint 2013

• How to: Create a basic provider-hosted app for SharePoint