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

apps for SharePoint

Learn how to package and publish a high-trust app for SharePoint for on-premises use.

You need 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.

  • An IIS web server to host the remote web application. IIS Manager should be installed.

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

  • Microsoft Office Developer Tools for Visual Studio

  • Web Deploy installed on the Visual Studio computer, and the same version of Web Deploy installed on the remote web application server.

Table 1 lists some useful articles that can help you to understand the concepts involved in creating apps for SharePoint.

Table 1. Core concepts for publishing 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: Create high-trust apps for SharePoint 2013

Learn how to create a basic high-trust app for SharePoint with the Office Developer Tools for Visual Studio by using a self-signed certificate and an associated issuer ID.

Web Deploy

Web Deploy simplifies deployment of web applications and websites to IIS servers.

Digital Certificates and Working with Certificates

Learn the basic ideas behind digital certificates.

Note Note

High-trust apps for SharePoint 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. This article explains how to publish the app in that scenario. Also, in this article 'customer' refers to the business that installs the app for SharePoint and hosts the remote components of the app.

Before you can publish the app, it has to be registered with the SharePoint farm's app management service. High-trust apps for SharePoint are always registered on the SharePoint farm on which the app is to be installed. (They cannot be sold through the Office Store.) Registration is done on the page http://SharePoint_website/_layouts/15/appregnew.aspx as described in the following procedure.

To register the app

  1. Navigate to the http://SharePoint_website/_layouts/15/appregnew.aspx page. Choose the Generate buttons to generate values for the app ID and secret. (The secret is not actually used in high-trust apps for SharePoint, but the form requires one.) Provide the base URL of the domain where the remote web application of the app will run. Do not include the protocol (HTTPS) in the domain, but you have to include the port that the remote components will use for HTTPS requests if it is not 443 (for example, www.contoso.com:5555 or MyAppServer:4444).

    If you need a redirect URI, enter a value for that also. See Authentication Code OAuth flow for apps in SharePoint 2013 for an explanation of how the redirect URI can be used.

    The form on the page should look similar to Figure 1. In this example, the remote web application server is listening for HTTPS requests on the default port 443, so it's not necessary to specify the port in the app domain.

    Figure 1. Register app on appregnew.aspx

    Register app on appregnew.aspx
  2. Choose Create. The information that you entered for the app will be displayed on the next page, as shown in Figure 2. Be sure to keep this information available because you will need it when you use the Visual Studio publishing tools. Consider taking a quick screenshot of the page.

    Figure 2. App registration complete

    App registration complete

When a developer is using F5 in Visual Studio to develop and debug a high-trust app for SharePoint, the developer can use a self-signed certificate, as described in How to: Create high-trust apps for SharePoint 2013. However, when the app is published, using a self-signed certificate causes the browser to display a warning page before it will open the remote web application's start page. The user has to choose whether to proceed. Figure 3 shows examples of such warnings.

Figure 3. Warnings for self-signed certificates

IE and Chrome warnings for self-signed certificate

This annoyance might be acceptable for a developer, but it would be unacceptable for customers. So before final publication to a production environment, the customer has to get a certificate that is signed by a trusted third party. The third party can be a commercial Certificate Authority (CA) or an on-premises CA. In regard to commercial CAs, note that the industry is phasing out "intranet-only" certificates for web servers. They can still be purchased, but all such certificates will expire in November, 2016, or sooner. It is not necessary to have this kind of certificate for a high-trust app for SharePoint, because certificates that can be used for internet-facing web servers can also be used for intranet web servers, but the latter generally cost more.

The certificate should be in two formats, Personal Information Exchange (pfx) and Security Certificate (cer). If it is not in either of these formats when originally obtained, the customer can convert it using a utility. Also, once a pfx format version has been obtained, the pfx file can be imported into IIS and then the cer version exported as described below.

If the certificate is originally obtained is a cer format, it will contain both the private and public keys. As a general practice, the .cer file that is used by SharePoint should not contain the private key. Consider importing the original certificate to IIS and then exporting a new cer version that does not include the private key as described below. For more information about .pfx and .cer files, see Software Publisher Certificate.

In addition, the customer has to consider whether to use a single certificate for all high-trust apps for SharePoint or separate certificates for each. For more information about this decision, see Deciding between using one certificate or many for high-trust apps for SharePoint.

The following procedures are performed on the remote web server hosting the remote web application.

To configure the remote web server and pfx certificate

  1. Give the .pfx certificate a strong password. For more information, see Guidelines for creating strong passwords and Strong passwords.

  2. Import the certificate into IIS on the remote web server with these steps:

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

    2. Double-click the Server Certificates icon.

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

    4. On the Import Certificate dialog, use the browse button to browse to the .pfx file, and then enter the password of the certificate.

    5. If you are using IIS Manager 8, there is a Select Certificate Store drop down. Choose Personal. (This refers to the "personal" certificate storage of the computer, not the user.)

    6. If you don't already have a cer version, or you do but it includes the private key, enable Allow this certificate to be exported.

    7. Click OK.

To open the Windows Certificate Store

  1. On the same server, open the Microsoft Management Console and as described in Open MMC 3.0.

  2. Add the Certificates snap-in for the computer account as described in Add the Certificates Snap-in to an MMC. Be sure to use the procedure for the computer, not a user or service. Choose the local computer, not "another" computer, when prompted.

Skip the next procedure if you are using ISS Manager 8.

Additional steps for ISS Manager 7 to get the certificate into the Windows Certificate Store

  1. Create a folder on the server file system to be used as a very temporary storage place for the certificate.

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

  3. Double-click the Server Certificates icon.

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

    Figure 4. Exporting a certificate

    Exporting a test certificate
  5. Export the file to the folder that you created and enter its password.

  6. In the Microsoft Management Console import the certificate as described in Import a Certificate. Be sure to specify the Personal store.

  7. Leave the console open for the next procedure.

  8. Delete the folder that you created in the first step and the certificate file in it. The security advantages of keeping the certificate in the certificate store are defeated if it is also on the file system.

The next procedure applies to both IIS Manager 7 and 8.

To get the serial number of the certificate

  1. In the Microsoft Management Console, navigate to the Certificates folder under the Personal folder of the Certificates (Local Computer) snap-in, if it is not already open.

  2. Double-click the certificate for your app for SharePoint to open it, and then open the Details tab.

  3. Select the Serial Number field to make the entire serial number is visible in the box.

  4. Copy the serial number, without the spaces, to a text file and give it to the developer of the app for SharePoint.

    Tip Tip

    Some developer blog posts and forum questions report that copying the serial number directly into the clipboard creates a string with hidden characters that makes the serial number unrecognizable to code in the app for SharePoint. Consider manually typing the number instead of copying it.

Next you create a cer version of the certificate. This contains the public key of the remote web server and is used by SharePoint to unencrypt requests from the remote web application and validate the access tokens in those requests. It is created on the remote web server and then moved to the SharePoint farm.

To create the cer certificate

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

  2. Double-click Server Certificates.

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

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

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

  6. Use the default values on the next page. Choose Next.

  7. Choose Browse and browse to any folder. (The cer file is going to be moved off of this computer anyway.) Give the file the same name as the pfx file, and then choose Save. The certificate is saved as a .cer file.

  8. Choose Next.

  9. Choose Finish.

The procedures in this section can be performed on any SharePoint server on which the SharePoint Management Shell is installed.

To distribute the cer file to SharePoint

  1. Create a folder and be sure that the app pool identities for the following IIS app pools have Read right to it:

    • 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. Move (don't merely copy) the .cer file from the remote web server to the folder you just created on the SharePoint server. The file will be in this folder only temporarily.

The following procedure configures the certificate as a trusted token issuer in SharePoint. It is performed just once (for each high-trust app for SharePoint).

To configure the certificate

  1. If you have not done so already, create the high-trust configuration Windows PowerShell script or scripts that you need, as described in High-trust configuration scripts for SharePoint 2013.

  2. Copy the scripts to the SharePoint server.

  3. Open the SharePoint Management Shell as an administrator and run the appropriate scripts.

  4. One of the scripts is intended for use when the customer is sharing a single certificate among multiple apps for SharePoint. That script outputs a file that contains the GUID for the token issuer. If you use that script, give the file that it outputs to the developer of the high-trust app for SharePoint.

  5. Delete the cer file from the file system of the SharePoint server.

Note Note

The registration of the certificate as a token issuer is not effective immediately and the app will not work until it is. It may take as long as 24 hours before all the SharePoint servers recognize the new token issuer. Running an iisreset on all the SharePoint servers, if you can do that without disturbing SharePoint users, would cause them to immediately recognize the issuer.

Tip Tip

For a code sample that includes a modified web.config, see PnP / Samples / Core.OnPrem.S2S.WindowsCertStore..

Edit the web.config file so that it contains new values for the following keys in the appSettings node:

  • ClientID: This is the web application's client ID (GUID) that was generated on appregnew.aspx.

  • ClientSigningCertificateSerialNumber: (You will need to add this key, if the Microsoft Office Developer Tools for Visual Studio did not add it.) This is the serial number of the certificate. There should be no spaces or hyphens in the value.

  • IssuerId: This is the GUID of token issuer (which must be lower-case). Its value depends on the certificate strategy of the customer:

    • If the high-trust app for SharePoint has its own certificate that it is not sharing with other apps for SharePoint, the IssuerId is the same as the ClientId.

    • If the app for SharePoint is sharing the same certificate that other apps for SharePoint are using, the IssuerId is an arbitrary GUID. The script for this scenario that you can find in High-trust configuration scripts for SharePoint 2013 generates a text file with this GUID in it. The IT staff can pass the outputted file to the app developer for insertion as the IssuerId in the web.config file.

Note Note

The Office Developer Tools for Visual Studio may have added app setting keys for ClientSigningCertificatePath and ClientSigningCertificatePassword. These are not used in a production app and should be deleted.

The following is an example. Note that there is no ClientSecret key for a high-trust app for SharePoint.

<appSettings>
  <add key="ClientID" value="c1c12d4c-4900-43c2-8b89-c05725e0ba30" />
  <add key="ClientSigningCertificateSerialNumber" value="556a1c9c5a5415994941abd0ef2f947b" />
  <add key="IssuerId" value="f94591d5-89e3-47cd-972d-f1895cc158c6" />
</appSettings>

The TokenHelper.cs (or .vb) file generated by Office Developer Tools for Visual Studio needs to be modified to work with the certificate stored in the Windows Certificate Store and to retrieve it by its serial number. The example below shows one way. The example uses C#.

Tip Tip

For a code sample that includes a modified tokenhelper.cs, see PnP / Samples / Core.OnPrem.S2S.WindowsCertStore..

To modify the TokenHelper

  1. Near the bottom of the #region private fields part of the file are declarations for ClientSigningCertificatePath, ClientSigningCertificatePassword, and ClientCertificate. Remove all three.

  2. In their place, add the following line:

    private static readonly string ClientSigningCertificateSerialNumber 
        = WebConfigurationManager.AppSettings.Get("ClientSigningCertificateSerialNumber");
    
  3. Find the line that declares the SigningCredentials field. Replace it with the following line:

    private static readonly X509SigningCredentials SigningCredentials 
        = GetSigningCredentials(GetCertificateFromStore());
    
  4. Go to the #region private methods part of the file and add the following two methods:

    private static X509SigningCredentials GetSigningCredentials(X509Certificate2 cert)
    {
        return (cert == null) ? null 
                              : new X509SigningCredentials(cert, 
                                                           SecurityAlgorithms.RsaSha256Signature, 
                                                           SecurityAlgorithms.Sha256Digest);
    }
    
    private static X509Certificate2 GetCertificateFromStore()
    {
        if (string.IsNullOrEmpty(ClientSigningCertificateSerialNumber))
        {
            return null;
        }  
    
        // Get the machine's personal store
        X509Certificate2 storedCert;
        X509Store store = new X509Store(StoreName.My, StoreLocation.LocalMachine); 
    
        try
        {
            // Open for read-only access                 
            store.Open(OpenFlags.ReadOnly);
    
            // Find the cert
            storedCert = store.Certificates.Find(X509FindType.FindBySerialNumber, 
                                                 ClientSigningCertificateSerialNumber, 
                                                 true)
                           .OfType<X509Certificate2>().SingleOrDefault();
        }
        finally
        {
            store.Close();
        }
    
        return storedCert;
    }
    

Tip Tip

Microsoft updates Visual Studio and Office Developer Tools for Visual Studio on a much more frequent schedule than in the past and documentation cannot always be updated to keep up with the changes. This section was written using the version of Visual Studio released in October, 2013, and the version of Office Developer Tools for Visual Studio that was included in it. If you are working with an earlier or later version of either Visual Studio or the tools, you may need to consult Visual Studio help and blog posts to find the equivalent ways of carrying out the steps in these procedures.

To package the remote web application

  1. In Solution Explorer, right-click the web application project (not the app for SharePoint project), and select Publish.

  2. On the Profile tab, select New Profile on the drop-down list.

  3. When prompted, give the profile an appropriate name. For example, Payroll SP app – Remote Web Application.

  4. On the Connection tab, select Web Deploy Package in the Publish method drop-down list.

  5. For Package location, use any folder. To simplify later procedures, this should be an empty folder. The subfolder of the bin folder of the project is typically used.

  6. For the site name, enter the name of the IIS website that will host the web application. Do not include protocol or port or slashes in the name; for example "PayrollSite." If you want the web application to be a child of the Default Web Site, use Default Web Site/<website name>; for example, "Default Web Site/PayrollSite." (If the IIS website does not already exist, it is created when you execute the Web Deploy package in a later procedure.)

  7. Click Next.

  8. On the Settings tab select either Release or Debug on the Configuration drop down.

  9. Click Next and then Publish. A zip file and various other files that will be used in to install the web application in a later procedure are created in the package location.

To create an app for SharePoint package

  1. Right-click the app for SharePoint project in your solution, and then choose Publish.

  2. In the Current profile drop-down, select the profile that you created in the last procedure.

  3. If a small yellow warning symbol appears next to the Edit button, click the Edit button. A form opens asking for the same information that you included in the web.config file. This information is not required since you are using the Web Deploy Package publishing method, but you cannot leave the form blank. Enter any characters in the four text boxes and click Finish.

  4. Click the Package the app button. (Do not click Deploy your web project. This button simply repeats what you did in the final step of the last procedure.) A Package the app form opens.

  5. In the Where is your website hosted? text box, enter the URL of the domain of the remote web application. You must include the protocol, HTTPS, and if the port that the web application will listen for HTTPS requests is not 443, then you must include the port as well; for example, https://MyServer:4444. (This is the value that Office Developer Tools for Visual Studio uses to replace the ~remoteAppUrl token in the app manifest for the app for SharePoint.)

  6. In the What is the app's Client ID? text box, enter the client ID that was generated on the appregnew.aspx page, and which you also entered in the web.config file.

  7. Click Finish. Your app package is created.

To publish the web application

  1. Navigate to the folder you used as the Package location when you packaged the remote web application, and then copy all the files in it to a folder on the remote server.

  2. In this folder, open the project_name.deploy-readme.txt file (where project_name is the name of the Visual Studio web application project), and follow the instructions in the file to install the web application using the project_name.deploy.cmd file.

To configure protocol binding for the web application

  1. In IIS Manager, highlight the new website in the Connections pane. (If the new web application is a child of the Default Web Site, highlight the Default Web Site and carry out this procedure for the Default Web Site.)

  2. Click Bindings in the Actions pane.

  3. Click Add on the Site Bindings dialog. On the Add Site Binding dialog that opens, take the following steps.

    1. Select HTTPS in the Type drop down list.

    2. Select All Unassigned in the IP address drop down list.

    3. Enter the port in the Port text box. If you specified a port in the app domain when you registered the app for SharePoint on appregnew.aspx (as described in Register the high-trust app), then you have to use the same number here. If you did not specify a port on appregnew, then use 443 here.

    4. In the SSL certificate drop down list, select the certificate that you used to configure the server in Configure the remote web server with the certificate above.

    5. Click OK.

  4. Click Close.

To configure authentication for the web application

  1. When a new web application is installed in IIS, it is initially configured for anonymous access, but almost all high-trust app for SharePoint are designed to require authentication of users, so you need to change it. In IIS Manager, highlight the web application in the Connections pane. It will be either a peer website of the Default Web Site or a child of the Default Web Site.

  2. Double-click the Authentication icon in the center pane to open the Authentication pane.

  3. Highlight Anonymous Authentication and then click Disable in the Actions pane.

  4. Highlight the authentication system that the web application is designed to use and click Enable in the Actions pane.

    If the web application's code uses the generated code in the TokenHelper and SharePointContext files without modifications to the user authentication parts of the files, then the web application is using Windows Authentication, so that is the option you should enable.

  5. If you are using the generated code files without modifications to the user authentication parts of the files, you also need to configure the authentication provider with the following steps:

    1. Highlight Windows Authentication in the Authentication pane.

    2. Click Providers.

    3. In the Providers dialog, ensure that NTLM is listed above Negotiate.

    4. Click OK.

To upload and install the app for SharePoint

  1. Upload the *.app package file of the app for SharePoint to the organization app catalog. (High-trust apps for SharePoint cannot be distributed through the Office Store.) For details, see Add apps to the App Catalog.

  2. Install the app on any website within the same parent SharePoint web application that contains the app catalog. For details about uploading and installing the app for SharePoint, see Add apps for SharePoint to a SharePoint 2013 site.

Show:
© 2015 Microsoft