In this post, we will discuss how we can create a Provider-Hosted App using Visual Studio 2012 in SharePoint 2013. Follow below steps to do that:
1. Launch VS2012 and create new solution:
2. Make sure that Provider-hosted option is selected:
3. Visual Studio will generate two projects: DemoApp and DemoAppWeb
Note that TokenHelper.cs file was generated which implements authentication-related logic.
The problem with this sample is that VS generates it assuming that the app is going to be deployed to Office 365 environment and will be using ACS as trusted cloud authentication provider. This code needs to change to the following in order to work in high trust on-premises scenario.
Uri hostWeb = new Uri(Request.QueryString[“SPHostUrl”]);
using (varclientContext = TokenHelper.GetS2SClientContextWithWindowsIdentity(hostWeb, Request.LogonUserIdentity))
clientContext.Load(clientContext.Web, web => web.Title);
Let’s get this solution to the stage when it’s ready to be deployed to IIS and SharePoint.
Note:It’s also possible to use IIS Express for development and testing. In this case appropriate changes have to be made to ensure that site is running using https protocol. In general, IIS Express is not recommended approach because every time its URL changes, the app stops working until corrections are made in relevant parts of the configuration.
In order to deploy a solution to IIS and SharePoint respectively, we have to take some extra steps and update information in the solution before it can be packaged. Next sections describe how to do this.
Preparing the Certificates:
Before deploying DemoAppWeb website, you have to prepare certificates (.pfx and .cer files). This builds trust communication between SharePoint sites and DemoAppWeb website.
1. Log in to the server where you want to install DemoAppWeb website and launch IIS manager
2. Double-click ‘Sever Certificates’ and select ‘Create Self-Signed Certificate’ on the right:
3. Give it a name and click OK.
4. Right-click this certificate and select Export.. . Export Certificate pop-up windows appears:
5. Specify location and password. For this demo we generate file DemoApp.pfxand password is set to Password
6. Double-click certificate in IIS and navigate to Details tab:
7. Click Copy to File… to export .cer file.
8. Click Next -> select ‘No, do not export the private key’, leave ‘DER encoded binary X.509 (.Cer)’ selected.
9. On the final screen, specify the name and location of .cer file. Click Next and Finish
10. Now you should have both .cer and .pfx files ready
11. Jump back to VS and open web.config
12. Add the following settings to appSettings section:
<add key=”ClientSigningCertificatePath”value=”d:\TFS14\SharePoint2013\Scripts\Provider-Hosted Apps\DemoApp.pfx” />
<add key=”ClientSigningCertificatePassword” value=”Password123″ />
Creating SharePoint Developer site:
1. Launch SharePoint Central Administration site, click Application Management -> Create Site Collections
2. Create new site collection based on ‘Developer Site’ template:
Registering the App Principal:
The app principal ensures that DemoApp can access SharePoint sites.
RegisterAppPrincipal.ps1 file accompanying this guide takes care of registering the app principal. However, some changes are required.
Open the script in text editor and modify the following value:
$publicCertPath – should be pointing at .cer file exported above
Note: Same certificate can be used by more than one App Principal
$web – Url parameter in Get-SPWeb cmdlet should be the url of the developer site created above.
Note: It can be URL of any site collection that already exists as long as it belongs to same authentication realm (farm) which apps infrastructure was configured for.
DisplayName – display name of the SharePoint Trusted Security Token Issues. This is normally displayed name of SharePoint provider-hosted application.
Run the script from SharePoint 2013 Management shell using farm admin account. Output should be similar to the screenshot below:
In the below command, replace the “-Name” attribute with DisplayName as provided above.
New-SPTrustedRootAuthority -Name “Demo App” -Certificate $root
Make note of generated Issuer ID, jump back to VS and open web.config file. Add the following settings to appSettings section and set generated issuer Id:
If SharePoint sites don’t use https (in our case they don’t), the following script needs to be executed: SetHttpsMode.ps1
This will enable OAuth authentication over http.
Registering the App:
Any application that’s not distributed by Microsoft Marketplace or uploaded automatically by Visual Studio has to be manually registered.
Add /_layouts/appregner.aspxto URL of any site to access app registration page.
For App Id and App Secret fields click’Generate’ button
Title – Demo App
App Domain – apps.dev.echonet
Redirect URL – https://demoapp.apps.dev.echonet/Pages/default.aspx (this URL will be configured in IIS later)
Make note of App Id and App Secretvalues.
1. Jump back to VS and open AppManifest.xml file. Replace RemoteWebApplicationClientId attribute’s value with generated AppId.
2. Navigate to Web.config file and update ClientId with generated AppId and ClientSecret with generated App Secret:
Creating and configuring a DemoAppWeb Web Site:
3. Return to IIS manager and configure Add Web Site page:
4. Click Application Pools in the left pane. Then, right-click the newly-created application pool and select Advanced Settings.
5. Change .Net Framework Version to 4.0
Change Application Pool Identity to SharePoint farm admin account: Click Ok to save changes. Apply created SSL certificate to newly created site:
Execute the following command to configure hostname for new binding:
SSL_bindings.bat demoapp demoapp.apps.dev.echonet
Host Name should now appear in the list of bindings:
Modify authentication of a newly created site: disable Anonymous Authentication and enable Windows Authentication:
6. Publish DemoAppWeb web site to file system.
7. Make sure that the path you specify is a path that was configured for new site in IIS.
Important: Once the site has been published, check its web.config file to make sure it’s still the same as in VS. You’ll probably find that ClientId and ClientSecret values are blank. If that’s the case, re-apply them.
To verify that the site works, add the following entry to hosts file and restart IE:
Note: Ideally *.apps.dev.echonet wildcard domain is needed
8. Create file called index.html with some text in folder:
10. Save changes and navigate to URL https://demoapp.apps.dev.echonet/
Packaging and deploying SharePoint App:
Some changes are needed before SharePoint App can be packaged and deployed to SharePoint developer site.
Open AppManifest.xmlfile. Make sure that:
1. The title is set to ‘Demo App’. It should be the same title as specified on appregnew.aspx page
2. Add support for at least one locale. In this example regional settings of target dev site are set to US (http://lons00110834:24174/sites/AppDevelopmentSite/_layouts/15/start.aspx#/_layouts/15/regionalsetng.aspx). Therefore app has to support at least ‘en-US’ locale. Add the following section after StartPage section:
<SupportedLocale CultureName=”en-US” />
3. Specify what kind of permissions SharePoint app should have by adding new section after <AppPrincipal>:
<AppPermissionRequest Scope=”http://sharepoint/content/sitecollection/web” Right=”Manage”/>
In this case, the app will be able to read and modify data.
4. Use app publishing wizard to create an app package. Right-click DemoApp project and provide settings as below:
DemoApp.app package should be generated successfully.
5. Navigate to the home page of the SharePoint developer site and click ‘new app to deploy’. In the modal dialog window click Upload and browse to DemoApp.app. Click Ok and then Deploy.