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.

  • 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 in How to: Create high-trust apps for SharePoint 2013.

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. 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. Create a folder to which the app pool identity of the remote web application has Read rights. (By default, IIS will assign a user called ApplicationPoolIdentity to its web applications when they are created. This user cannot be given Read access to non-local files. If the certificate is not stored on the same server that is hosting the remote web application, then you need to change the app pool identity to a user who has Read rights to the non-local folder.)

  3. 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. Be sure that Allow this certificate to be exported is enabled and click OK.

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

      Figure 4. Exporting a test certificate

      Exporting a test certificate
    7. Export the file to the folder that you created in the earlier step and enter its password.

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.

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. 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 first procedure in this section is performed on every SharePoint server in the farm. Use the same values on every server; for example, the same folder name.

To distribute the cer file to SharePoint

  1. Create a folder and be sure that the app pool identity for the following IIS app pools have Read rights 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 the .cer file from the remote web server to the folder you just created on the SharePoint server.

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) and can be done on any SharePoint server.

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

Note Note

The registration of the certificate as a token issuer is not effective immediately. 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.

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.

  • ClientSigningCertificatePath: This is the full path and filename of the *.pfx file.

  • ClientSigningCertificatePassword: This is the password that you gave the certificate.

  • 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 a random 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.

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="ClientSigningCertificatePath" value=" C:\MyCerts\MyCert.pfx" />
  <add key="ClientSigningCertificatePassword" value="4Sa7YA#yr" />
  <add key="IssuerId" value="f94591d5-89e3-47cd-972d-f1895cc158c6" />
</appSettings>

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 modification, 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 unmodified, 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:
© 2014 Microsoft