In my previous blog about provider-hosted app on premises, we briefly touched upon the how and why of provider-hosted apps on a SharePoint on premises farm. In this installment, we'll go through the process of installing a provider-hosted app.
Prerequisites
Installing apps in general and high trust apps specifically introduces a few requirements for your farm. For example, you need an app catalog and you'll probably want to consider setting a wildcard dns entry to accommodate the apps. Since preparing your farm for apps would result in a blogpost on its own and this has been described expertly by many already, I'll simply assume the farm is ready for SharePoint-hosted apps. With this set up, you'll need one additional step: setting up a trusted security token issuer. We'll create first using a short PowerShell snippet.
# change this path to match your farm
$publicCertPath = "C:\Certificates\MyCertificate.cer"
$certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($publicCertPath)
New-SPTrustedRootAuthority -Name make.maven.dev -Certificate $certificate
$realm = Get-SPAuthenticationRealm
# generate a new guid and use it here, you'll need it later
$issuerid = [System.Guid]::Parse("120aec12-c05c-4244-8fa0-ad19d53b2fb5")
$fullIssuerId = $issuerid.ToString() + '@' + $realm
New-SPTrustedSecurityTokenIssuer -Name "ProviderHostedIssuer" -Certificate $certificate -RegisteredIssuerName $fullIssuerId -IsTrustBroker
This snippet assumes you already have access to a certificate. The token issuer requires the public version of the certificate (a .cer file), the AppWeb requires a version which includes the private key (a .pfx file). On my development machine, I've simply generated these myself using IIS. You can either buy a certificate form a certificate authority (ca) or run a ca in your network to generate them. Adjust the path to the certificate and the issuer id and run the script. Be sure to write the issuer id down somewhere, you'' need it later on.
You can suffice with using a single token issuer and use it for multiple apps in your farm. This does mean that all the apps will use the same certificate. You can also set up multiple token issuers if you require them and configure the each app accordingly.
Now that we have our farm set up for provider-hosted apps, let's get into the process of installing one!
Six simple steps to installing a provider-hosted app
Installing a provider-hosted should be a simple task once you know how and the six steps below illustrate this:
- Add the app to the app catalog
- Register the app in your site collection(s)
- Add the app to your site(s)
- Install the AppWeb on your app server
- Don't forget about authentication
- Update the web.config on the AppWeb
Add app to the app catalog
Your developer or supplier should have provided you with an .app file and a folder or zip containing the code for the AppWeb. Adding the app to the catalog is probably the easiest step in the process. Open your app catalog, go to Apps for SharePoint drag the .app file to the page, click Ok and you're done.
Note that an app catalog is connected to web application and you might have several if you have more than one web application. Make sure you add the app to the app catalog(s) linked to the web application(s) which contains your site collection(s).
Register the app in your site collection(s)
Next we'll need to register the app in the site collections you'll want to use it in. This step will need to be repeated for every site collection that will use the app!
Open the following url in your browser: [SiteCollectionUrl]/_layouts/15/appregnew.aspx. On my development environment this would be https://demo.mavention.local/_layouts/15/appregnew.aspx and fill out the form on the page.
ClientSecret is a required field, but since it's only used for low trust apps, we can just generate a random key and leave it at that. The same goes for app domain and app redirect uri. These fields are not used in this scenario, so you can just use dummy values for these fields.
Your supplier or developer should have provided you with the ClientId. In case they didn't or you just aren't sure if it the ClientId is correct, there is a simple trick to learn your app's ClientId. We can extract the ClientId from the .app file by renaming the .app file to a .zip file and opening it in windows explorer. The file you're looking for is called AppManifest.xml. Simply open this file in notepad or whatever text editor you're comfortable with and note the ClientId.
The appregnew form creates an app principal. It can also be set up using PowerShell. I've chosen the web approach since most people are familiar with this screen already and it's also supported in an online scenario.
Add the app to your site(s)
Open the site contents page on the site where you want to use the app and click on "Add an app". The app you've just added should be one of the first apps in the list. Alternatively you can use the search box to find it. Click on the app to install it. The popup will inform you of the permissions the app will have on your farm. Click "Trust it" to install the app. If the permissions do not match what you expected, click "Cancel" and contact your developer or supplier!
If you want to use the app in subsequent sites, this step will need to be repeated for all of them.
We now have the SharePoint part of the app installed. Let's move on to installing the AppWeb.
Install the AppWeb on your app server
The idea behind provider-hosted apps is making sure managed code does not run on SharePoint. Therefore, I do not recommend hosting the managed code of your provider-hosted app (the AppWeb) on a SharePoint server. This might be ok for a development environment but in a production scenario, I would recommend introducing an app server for this purpose.
On your app server, go to your web server instance (most likely IIS, but note that provider-hosted apps are not limited to the Microsoft stack when it comes to the AppWeb) and create a new website and copy the contents of the AppWeb folder or zip to the root of the website. You'll probably need to make a few changes in the web.config to get the site up and running, but we'll handle that later.
Don't forget about authentication
One could argue that this step is a bit redundant and should have be mentioned while setting up the AppWeb. However, experience has taught me that setting the authentication on the AppWeb is often overlooked and might cause problems later. The AppWeb requires that user is authenticated. Allowing anonymous access will not force authentication and cause an error in the app. We need to disable anonymous access and set up the appropriate authentication.
In this example I'll use IIS since it's the most common web server in SharePoint farms.
Open the site in IIS and open Authentication. Here you should disable anonymous access and enable Windows authentication. Alternatively, you could configure this in the AppWeb's web.config as well.
Update the web.config on the AppWeb
The final step in installing your provider-hosted app is configuring the AppWeb to match your farm. Go to the rootfolder of your AppWeb on the file system and open the web.config in your favorite text editor. Your web.config should look something like this.
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<system.web>
<compilation targetFramework="4.5" />
<httpRuntime targetFramework="4.5" />
</system.web>
<appSettings>
<add key="ClientId" value="18a0b936-fc3b-4284-b06b-2911510bb3e9" />
<add key="ClientSigningCertificatePath" value="C:\Certificates\MyCertificate.pfx" />
<add key="ClientSigningCertificatePassword" value="mavention123" />
<add key="IssuerId" value="120aec12-c05c-4244-8fa0-ad19d53b2fb5" />
</appSettings>
<system.serviceModel>
<bindings>
<basicHttpBinding>
<binding name="secureBinding">
<security mode="Transport" />
</binding>
</basicHttpBinding>
</bindings>
<protocolMapping>
<add binding="basicHttpBinding" scheme="https" bindingConfiguration="secureBinding" />
</protocolMapping>
</system.serviceModel>
</configuration>ClientId should match the ClientId of your app. The two keys for the certificate should contain the full path to your certificate and the password for the certificate. The IssuerId should match the guid you used to create your token issuer. Note that this is not the Id property of the token issuer. If you use Get-SPTrustedSecurityTokenIssuer to look up the id, you need to copy the RegisterIssuerName property of the token issuer. This property is formatted as follows: <issuer id>@<farm id>, so you only need the first part.
And that's it. You've now installed your provider-hosted app for SharePoint. While this process may seem simple enough, a lot can actually go wrong and the error logging is not always informative. In my next blog, I'll go over some of the things that can go wrong with your installation and how to fix them.