The purpose of this blog series is to consolidate and provide a simple flow on how to setup Provider Hosted App Infrastructure and understand the basics around Packaging and Deploying provider hosted apps. I assume you have setup the infrastructure for Provider Hosted Apps. If not, start Part 1 of my blog series here before continuing this blog. Part 2 covers how to create a simple provider hosted app in Visual Studio 2013 and how to package and deploy the solution to both the remote server (hosting the remote web application) and SharePoint 2013 (drop the app in the app catalog). This blog will not cover how to deploy your app to a developer site in order to debug within Visual Studio 2013. This is fairly basic and plenty of documentation exists which guides one through this. This blog is is for a 100% on premise SharePoint 2013 provider hosted app environment. Also, some of the steps below I grabbed from various spots on MSDN and I’ll provide references to MSDN links which provide useful details.
Before going through the steps, I’ll provide a quick intro into my basic setup:
Domain: Contoso.local (all boxes are Windows 2012 member servers joined to the domain)
Remote Web (will host provider hosted apps) – Windows 2012 running IIS 8.0
- Default Web Site responds to http://remoteweb (used host header and set up SSL)
- Each app will reside under the default web site as a Virtual Directory
- Default Web Site set to Windows Authentication
SharePoint: SharePoint 2013 running latest cumulative update (Single Server Farm)
Create a simple app in Visual Studio 2013
The first step is to create a simple provider hosted app. I’m not going to do anything fancy with app development and simply going to leverage the OOB default.aspx page that’s produced and add a paragraph. The app will not call back into SharePoint in this case and instead will redirect a user that clicks on the app to the default.aspx page on the remote web server. To reiterate, the purpose of this blog as mentioned in part 1 of this blog series isn’t to show you how to do x and y with apps but rather show you the basics for setup, packaging, and deploying Provider Hosted Apps.
1. Start Visual Studio 2013 and 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 whatever you want. In my case: RemoteSampleApp.
5. Ensure you point the URL to the developer site you created in SharePoint 2013
6. Save the project in a location you choose, and then choose OK.
7. Select the Provider-hosted option, and then choose the Next button.
Note: The site inputted above should point to the developer site
8. If 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
9. For the Configure authentication settings page perform the following steps:
a. 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\remotewebapps.pfx. (Note: this is my cert created from part 1 (previous blog) here)
b. Type the password for this certificate in the Password box. In this case, it is "password".
c. Type the issuer ID (8cb8c3db-5bfd-4a7a-8b18-189000065ad0) in the Issuer ID box. (Note this is the issuer id (random guid) associated to the sptrustedsecuritytokenissuer I created from part 1 (previous blog) here)
Note: It should look like the following:
d. Click finish and the default.aspx page automatically opens so added a paragraph to the page and saved it.
11. This step is just for observation purposes) Click on the AppManifest.xml for the app looks like the following:
Note: the Start page contains the virtual directory, path, and page name that will be deployed on the remote web.
12. Save Project and Build the Solution
Register App in SharePoint Farm
The next step is the app must be registered in the SharePoint farm where it will be deployed. We also require the App ID generated for Visual Studio 2013 when we build the app package.
1. Access any site and append /_layouts/15/appregnew.aspx
2. Click Generate buttons for both App Id and App Secret fields.
3. The App Domain is the domain name set on the remote web application server’s IIS Site that will be hosting this app.
4. The redirect URI isn’t required in my case so click create button which produces the following:
5. Copy the output as it’s needed during the packaging phase.
Publish the App Web (remote Web)
Publishing the App Web builds a package that includes files and a script. These files are copied to the remote web server and deployed. First, in Visual Studio 2013 you’ll have two different projects created. One is for the app which produces an app file and that file is uploaded to the app catalog and made available to SharePoint Sites. The second project is for the remote web and is a simple asp.net web application. In my case, RussMaxSecProvHostedApp is the app project and RussMaxSecProvHostedAppWeb is the remote web project. These steps apply to the remoteweb.
1. Right click the "RussMaxSecProvHostedAppWeb" and hit publish.
2. Created a New Profile and set the connection like the following:
Note: In my case, I want all of my provided hosted apps living under the default web site as a virtual directory. So I specified the site name as “Default Web Site/RussMaxSecProvHostedApp”
3. Click next and choose Release
4. Choose Next
5. Click Publish and Success!
6. Checking the directory I have the package
7. Copy this directory + output to the IIS Server hosting this remote web.
Deploy and Test Remote Web
At this point, the app/remote web package has been copied to the remote web server.
1. Start Command Prompt and navigate to the directory containing the package files
2. Run the following command: yourproviderhostedappwebname.deploy.cmd /y
Note: In my case it’s: russmaxsecprovhostedappweb.deploy.cmd
Note 2: It finished successfully and refreshing IIS gives me the new site:
3. Test by manually attempted to browse to the site.
And Page renders:
Note: I had to remove the inherits element from default.aspx page because of a server side error. In my case, I removed: Inherits="RussMaxSecProvHostedAppWeb.Default"
Publish the App
At this point, the remotewebapp project has been packaged and deployed to the remoteweb. The final step includes publishing the app, deploying to the desired SharePoint 2013 app catalog, and finally installing the app to a team site and test.
1. Within Visual Studio 2013, right click the "RussMaxSecProvHostedApp" and hit publish.
2. Click Edit and fill out the fields.
Note: The client ID is the App ID which came from the appregnew page. The Issuer ID is assigned to the associated SPTrustedSecurityTokenIssuer object. I assume you know what this ID is and please leverage Part 1 of the blog series for more details.
3. Hit OK and then click Package the App
Important: You must point at your site + virtual directory. In my case, the RussMaxSecProvHostedApp will be created under the Default Web Site.
4. Click Finish and it builds the app package automatically:
Note: It automatically opens windows explorer to the app.
5. Copy this file over to a server that can access the app catalog.
Add App to App Catalog
For an app to be consumed, it must be added to an app catalog.
1. Navigate to the app catalog and select Apps for SharePoint
2. Select New App and upload the .app file produced from the last set of steps
In my case, it looks like the following after upload:
Note: I added RussMaxSecProvHostedApp so I have two apps available now.
Install App to a site
1. Access a team site and selected site contents and clicked Add App.
Note: I see it here
2. Click on it and click Trust It
Note: If it errors on this step and you’re logged in as the system account, try again using a non-system account.
3. After install, test by clicking on the app.
For Example: Clicked on the following (Before):
And the redirect works!
Russ Maxwell, MSFT