Export (0) Print
Expand All

How to: Create high-trust apps for SharePoint 2013 (advanced topic)

apps for SharePoint

Learn how to create a high-trust app for SharePoint. A high-trust app uses digital certificates to establish a trust between the remote web application and SharePoint 2013. High-trust apps can only be installed to on premises SharePoint, not to Microsoft SharePoint Online, and they are primarily intended for use with an on premises, rather than cloud-based, web application.

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

Read the following articles to get a better understanding of apps for SharePoint and digital certificates.

Table 1. Core concepts for setting up SharePoint 2013 to run high-trust apps

Article title

Description

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

Learn how to create a basic provider-hosted app for SharePoint with the Office Developer Tools for Visual Studio, how to interact with SharePoint 2013 sites by using the SharePoint CSOM.

Digital Certificates and Working with Certificates

Learn the basic ideas behind digital certificates.

A high-trust app is a provider-hosted app for SharePoint that uses the digital certificates to establish trust between the remote web application and SharePoint. "High-trust" is not the same as "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 that it passes to SharePoint.

A high-trust app for SharePoint is is primarily intended for use in an on-premises environment. The high-trust app cannot be installed to Microsoft SharePoint Online, and the remote components are typically installed on premises, too, within the corporate firewall. Thus, the instances of the app for SharePoint are specific to each individual company.

A high-trust app uses a certificate instead of a context token to establish trust. (A provider-hosted app that's built to use Microsoft Azure Access Control Service (ACS) as its trust broker needs to be modified to work as a high-trust app.) High-trust apps require some configuration on the SharePoint farm and on the server hosting the remote web application. This topic describes the configuration steps that are needed to get Visual Studio debugging (F5) working. Configuring a test, staging, or production environment are somewhat different and are described in the topic How to: Package and publish high-trust apps for 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 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 shows you how to create a high-trust app and provides setup instructions for running it within Visual Studio by pressing F5. 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.

You need an X.509 digital certificate for the remote web application of your high-trust app. To fully test your app for SharePoint, you need a domain-issued certificate or a commercial certificate issued by a Certificate Authority. However, for the initial phase of debugging, you can use a self-signed certificate. The following procedure describes how to create and export a test certificate by using IIS. You'll learn how to replace the self-signed certificate with a domain-issued or commercial certificate in the section Complete debugging with a domain issued or commercial certificate below.

Alternatively, you can also use the MakeCert test program to generate a 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. The .pfx certificate contains the private key that is used by the remote web application to sign its communications to SharePoint. The .cer contains the public key that SharePoint uses to decrypt the messages, verify that they come from the remote web application, and verify that the remote web application has an access token from a token issuer that SharePoint trusts. For more information about .pfx and .cer files, see Software Publisher Certificate

To create a self-signed test .pfx certificate file

  1. When you are debugging a high-trust app for SharePoint in Visual Studio, the remote web application is hosted in IIS Express on the machine where Visual Studio is installed. So the remote web application computer doesn't have an IIS Manager where you can create the certificate. For this reason, you use the IIS on the SharePoint test server to create the certificate. In IIS manager, select the ServerName node in the tree view on the left.

  2. Select the Server Certificates icon, as shown in Figure 1.

    Figure 1. Server Certificates option in IIS

    Server Certificates option in IIS
  3. Select the Create Self-Signed Certificate link from the set of links on the right side, as shown in Figure 2.

    Figure 2. Create Self-Signed Certificate link

    Create Self-Signed Cerificate link
  4. Name the certificate HighTrustSampleCert, and then choose OK.

  5. Right-click the certificate, and then select Export, as shown in Figure 3.

    Figure 3. Exporting a test certificate

    Exporting a test certificate
  6. In Windows, or at a command line, create a folder called C:\Certs.

  7. Back in IIS Manager, export the file to C:\Certs and give it a password. In this example, the password is password.

  8. If your test SharePoint installation is not on the same computer where Visual Studio is running, create a folder C:\Certs on the Visual Studio computer and move the HighTrustSampleCert.pfx file to it. This is the computer where the remote web application runs when you are debugging in Visual Studio.

To create a corresponding .cer file

  1. On the SharePoint server, be sure that the app pool identity for the following IIS app pools have Read rights to the C:\Certs folder:

    • SecurityTokenServiceApplicationPool

    • The app pool that serves the IIS web site that hosts the parent SharePoint web application for your test SharePoint website. For the SharePoint – 80 IIS website, the pool is called OServerPortalAppPool.

  2. In IIS manager, select the ServerName node in the tree view on the left.

  3. Double-click Server Certificates.

  4. In Server Certificates view, double-click HighTrustSampleCert to display the certificate details.

  5. On the Details tab, choose Copy to File to launch the Certificate Export Wizard, and then choose Next.

  6. Use the default value No, do not export the private key, and then choose Next.

  7. Use the default values. Choose Next.

  8. Choose Browse, browse to C:\Certs, name the certificate HighTrustSampleCert, and then choose Save. The certificate is saved as a .cer file.

  9. Choose Next.

  10. Choose Finish.

The Windows PowerShell script that you create in this section is intended to support the use of F5 in Visual Studio. It will not properly configure a staging or production SharePoint installation. For instructions on configuring a production SharePoint to use certificates, see How to: Package and publish high-trust apps for SharePoint 2013.

Note Note

Double-check that you have completed the steps in Configure services in SharePoint 2013 for server-to-server app use (which is listed as a prerequisite for this article). If not, you must configure it now, before you proceed.

To configure SharePoint

  1. In a text editor or Windows PowerShell editor, start a new file and add the following lines to it to create a certificate object:

    $publicCertPath = "C:\Certs\HighTrustSampleCert.cer"
    $certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($publicCertPath)
    
    
  2. Add the following line to ensure that SharePoint treats the certificate as a root authority.

    New-SPTrustedRootAuthority -Name "HighTrustSampleCert" -Certificate $certificate 
    
    
  3. Add the following line to get the ID of the authorization realm.

    $realm = Get-SPAuthenticationRealm
    
    
  4. Your remote web application will use an access token to get access to SharePoint data. The access token must be issued by a token issuer that SharePoint trusts. In a high-trust app for SharePoint, the certificate is the token issuer. Add the following lines to construct an issuer ID in the format that SharePoint requires: specific_issuer_GUID@realm_GUID.

    $specificIssuerId = "11111111-1111-1111-1111-111111111111"
    $fullIssuerIdentifier = $specificIssuerId + '@' + $realm 
    
    
    NoteNote

    The $specificIssuerId value must be a GUID because in a production environment each certificate must have a unique issuer. However, in this context, where you use the same certificate to debug all your high-trust apps, you can hard code the value. If for any reason, you use a different GUID from the one used here, be sure that any letters in the GUID are lower case. The SharePoint infrastructure currently requires lower case for certificate issuer GUIDs.

  5. Add the following lines to register the certificate as a trusted token issuer. The -Name parameter must be unique so in a production configuration, it is common to use a GUID as part (or all) of the name, but in this context, you can use a friendly name. The –IsTrustBroker switch is needed to ensure that you can use the same certificate for all the high-trust apps you develop. The iisreset command is required to make your token issuer registered immediately. Without it, you might have to wait as long as 24 hours for the new issuer to be registered.

    New-SPTrustedSecurityTokenIssuer -Name "High Trust Sample Cert" -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier –IsTrustBroker
    iisreset 
    
    
  6. SharePoint 2013 does not normally accept self-signed certificates. So when you are using a self-signed certificate for debugging, add the following lines to turn off SharePoint's normal requirement that HTTPS be used when remote web applications call into SharePoint. If you don't, then you’ll get a 403 (forbidden) message when the remote web application calls SharePoint using a self-signed certificate. You will reverse this step in a later procedure. Turning off the HTTPS requirement means that requests from the remote web application to SharePoint are not encrypted, but the certificate is still used as a trusted issuer of access tokens which is its main purpose in high-trust apps for SharePoint.

    $serviceConfig = Get-SPSecurityTokenServiceConfig
    $serviceConfig.AllowOAuthOverHttp = $true
    $serviceConfig.Update()
    
    
  7. Save the file with the name HighTrustConfig-ForDebugOnly.ps1.

  8. Open the SharePoint Management Shell as an administrator and run the file with the following line:

    ./HighTrustConfig-ForDebugOnly.ps1
    

In this section, you learn how to create a high-trust app for SharePoint using Visual Studio.

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

To create a high-trust app for SharePoint

  1. In Visual Studio, choose File, New, Project.

  2. In the New Project wizard, expand the Visual C# or Visual Basic node, and then expand the Office/SharePoint node.

  3. Choose Apps, and then choose to create an App for SharePoint 2013 project.

  4. Name the project HighTrustSampleApp.

  5. Save the project in a location you choose, and then choose OK.

  6. Select the Provider-hosted option, and then choose the Next button.

  7. If you are prompted to specify the type of web project, select ASP.NET Web Forms Application for the continuing example in this topic, and then choose the Next button.

  8. The Configure authentication settings page of the wizard opens. The values that you add to this form will be added to the web.config file automatically. Under How do you want your app to authenticate?, choose Use a certificate.

  9. Click the Browse button next to the Certificate location box and navigate to the location of the self-signed certificate (.pfx file) that you created (C:\Certs). The value of this field should be the full path C:\Certs\HighTrustSampleCert.pfx.

  10. Type the password for this certificate in the Password box. In this case, it is "password".

  11. Type the issuer ID (11111111-1111-1111-1111-111111111111) in the Issuer ID box.

  12. Choose Finish. Much of the configuration is done when the solution opens. Two projects are created in the Visual Studio solution, one for the app for SharePoint and the other for the ASP.NET web application.

To run and debug the app

  1. Office Developer Tools for Visual Studio automatically generates a default.aspx and default.aspx.cs file when the ASP.NET project is created. The generated code fetches the title of the SharePoint host web and prints it on the default page of the remote web application. The exact markup and code in these files varies depending on the version of the tools. For this topic, you use the generated default.aspx and default.aspx.cs files without modification.

  2. To test the app for SharePoint and its remote web application, press F5 in Visual Studio. The web application will be deployed to IIS Express at localhost. The app for SharePoint will be installed to the target SharePoint website. You’ll be prompted by SharePoint to grant the permissions that the app for SharePoint requests. Some versions of Office Developer Tools for Visual Studio will launch the app immediately, others will open the Site Contents page of your target SharePoint website and you’ll see the new app listed there.

    Launch the app, if it is not launched automatically. The remote web application opens to the page that is specified as Start Page in the AppManifest.xml file, which is Default.aspx. Your app should look similar to Figure 4.

    Figure 4. Sample app calling SharePoint Server and retrieving the title of the SharePoint host web.

    Sample app retrieving web title

The Windows PowerShell script you created earlier turned off SharePoint's usual requirement that remote web applications use the HTTPS protocol to access SharePoint. Working with HTTPS turned off 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. Accordingly, you should not consider the developing and debugging phases completed until you have replaced the test certificate with a domain-issued or commercial certificate and then retested the app with the HTTPS requirement turned on.

When you have obtained the new certificate, you need to add a password to it, if it doesn't already have one. In a production environment, you would use a strong password, but for debugging an app for SharePoint, you can use anything. You will need the certificate in two formats, pfx and cer. If it is not in pfx format when you obtain it, you may need to convert it to pfx using a utility. When you have a pfx file, you can import it into IIS and export the cer file as described in the following procedure.

To import the new certificate

  1. Put the .pfx file in C:\Certs on the SharePoint server. for purposes of this article, we assume that the file is named MyCert.pfx. You should replace "MyCert" in all of these instructions with the actual name of your certificate.

  2. In IIS Manager, select the ServerName node in the tree view on the left.

  3. Double-click the Server Certificates icon.

  4. Select Import in the Actions pane on the right.

  5. On the Import Certificate dialog, use the browse button to browse to C:\Certs\MyCert.pfx, and then enter the password of the certificate.

  6. Be sure that Allow this certificate to be exported is enabled and click OK.

  7. In the Server Certificates list, right-click the certificate, and then select Export, as shown in Figure 3 above.

  8. Export the file to C:\Certs and specify its password.

  9. If your test SharePoint installation is not on the same computer where Visual Studio is running, move the MyCert.pfx file to the C:\Certs folder on the Visual Studio computer.

  10. In Server Certificates view, double-click MyCert to display the certificate details.

  11. On the Details tab, choose Copy to File to launch the Certificate Export Wizard, and then choose Next.

  12. Use the default value No, do not export the private key, and then choose Next.

  13. Use the default values. Choose Next.

  14. Choose Browse, browse to C:\Certs, name the certificate MyCert, and then choose Save. The certificate is saved as a .cer file.

  15. Choose Next.

  16. Choose Finish.

To configure SharePoint 2013 to use the new certificate

  1. Open the HighTrustConfig-ForDebugOnly.ps1file for editing and make the following changes:

    1. Replace HighTrustSampleCert in both places where it appears with MyCert.

    2. Replace the specific issuer ID, 11111111-1111-1111-1111-111111111111, with 22222222-2222-2222-2222-222222222222.

    3. Replace "High Trust Sample Cert" with "My Cert" or some other appropriate friendly name.

    4. In the line $serviceConfig.AllowOAuthOverHttp = $false, replace the false with true. This will turn back on the requirement that HTTPS be used.

  2. Save the file.

  3. Open the SharePoint Management Shell as an administrator and run the file with the following line:

    ./HighTrustConfig-ForDebugOnly.ps1
    

To reconfigure the remote web application

  1. In Visual Studio, open the web.config file of the web application project and make the following changes:

    1. In the ClientSigningCertificatePath key, replace C:\Certs\HighTrustSampleCert.pfx with C:\Certs\MyCert.pfx.

    2. Replace the ClientSigningCertificatePassword key value with the actual password of the certificate.

    3. Replace the IssuerId key value with 22222222-2222-2222-2222-222222222222.

  2. Press F5 to debug 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.

Office Developer Tools for Visual Studio includes a TokenHelper.cs (or .vb) file in the remote web application. Some versions of the tools also include a SharePointContext.cs (or .vb) file. The code in these files does the following:

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

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

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

  • In apps that use ACS rather than the high-trust authorization system, these files have additional tasks, such as handling 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 about TokenHelper and SharePointContext, see the comments in the files.

Note 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 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). When you are debugging in Visual Studio with F5, Microsoft Office Developer Tools for Visual Studio uses Windows Authentication, and the two generated code files use the Windows identity of the person running the app to create the access token. When your app is published, you need to configure the remote web application in IIS Manager to use Windows Authentication if you want to use it. If your app will not use Windows Authentication on the production environment, you will need to customize the generated code files, TokenHelper and/or SharePointContext, to use a different authentication system. You would also customize these files if your remote web application accesses SharePoint in an identity other than the user who is running the app for SharePoint. For more information, see How to: Package and publish high-trust apps for SharePoint 2013.

Show:
© 2014 Microsoft