Configure an environment to run your provider-hosted high trust apps in SharePoint 2013.

This blog posts describes the steps necessary to configure an environment to run your provider-hosted high trust apps in SharePoint 2013. Provider-hosted apps are apps that are hosted outside SharePoint. They run for example on an IIS server. Anything is possible. A provider-hosted app is considered as a high trust app when any user identity can be used for creating the access token. The app creates the user portion of the access token that is passed to SharePoint. A high trust uses a digital certificate to establish a trust between the provider-hosted app and SharePoint. Be aware that a high trust is not the same as a full trust. A high trust app must still request app permissions.

There are a lot of great resources out there in articles, blog posts, comments on questions and of course on TechNet. To my honest opinion none of them explains it from beginning to end. To understand the process, you need to understand the necessary steps taken. In principal these steps are valid from development to production. Some of the steps are only needed when you are using a development environment and should not be performed on a production environment because there are not needed there and could create an unsecure configuration. It will be explained per step if that’s the case.

My current configuration

To have a start point it is important to understand which configuration I’m using to demonstrate this. Some functionality depends on certain versions of SharePoint and Windows Server. My current configuration is as follows.

• Windows Server 2012 Standard (latest updates installed)
• SharePoint Server 2013 (version 15.0.4693.1000)
• SQL Server 2012 (version 11.00.3128)
• Visual Studio Premium 2013 (12.0.31101.00 Update 4)

Define your domains

Before we start configuring an environment we need to define some domains for our solution.

You need to use SSL to run apps in your SharePoint web applications. There are many reasons to have a secured connection. Think of the validation process and getting the access token. So both domains need an SSL certificate. I will be using a wildcard certificate to allow me to deploy more than one provider-hosted app under the same high trust.

DNS

When you start working with host names you need to resolve them to the correct IP address. Most people use the host file found under c:windowssystem32driversetc. I recommend to start using DNS to resolve them. Your environment will then be the same as your “real” world production environments.

Open Server Manager Dashboard and select “Tools” at the right top. Select the application “DNS”. We need to specify so called “Forward Lookup Zones” for the domains. The configuration differs per environment. Other IP addresses and DNS configurations may apply to your case. The first one will be for contosoweb.com.

Right mouse click on “Forward Lookup Zones” and select New Zone. Use the following settings:

• Primary Zone
• To All DNS servers running on domain controllers in this domain
• Zone name: contosoweb.com
• Do not allow dynamic updates

Create a new host A record in the created zone with the following settings:

• Name is empty
• IP Address = 127.0.0.1

When all configurations are done it will look like below.

The second forward lookup zone is created for the domain apphost-contosoweb.com.

Right mouse click on “Forward Lookup Zones” and select New Zone. Use the following settings:

• Primary Zone
• To All DNS servers running on domain controllers in this domain
• Zone name: apphost-contosoweb.com
• Do not allow dynamic updates

Create a new host A record in the created zone with the following settings:

• Name is empty
• IP Address = 127.0.0.1

Create a new alias CName record in the created zone with the following settings:

• Alias name = *
• Fully Qualified domain name = apphost-contosoweb.com

When all configurations are done it will look like below.

The next step is only necessary when you are creating a demo or development environment. We need to use the DNS on our machine instead of the DNS given to the environment. Go to your network adapter and open the properties. Open the “Internet Protocol Version 4” and specify the local DNS server. In our case this is 127.0.0.1.

Because all traffic is now routed to our DNS we will lose internet availability. To correct that we specify the Google Public DNS server in our DNS. Go to DNS. Right mouse click on the server and select properties. Open tab “Forwarders” and add the IP Address 8.8.8.8 to the list.

Create your SharePoint website

First we need to create the contosoweb.com website in SharePoint. Go to Central Administration à Application Management à Manage Web Applications. As we already mentioned every website is running under SSL. So we create a new web application with the port set to 443 and SSL turned on. Don’t forget to set the host header to contosoweb.com.

Choose any site template you wish. In my case I used a standard team site. When you are creating a development environment and you want to deploy your apps to your SharePoint website from Visual Studio you will need to use a Developer site template or another template which has side loading of apps enabled. Only use side loading of apps for development purposes. So don’t use it on any production environment. To enable side loading of apps for a specific SharePoint website use the following PowerShell script.

Add-PSSnapin Microsoft.SharePoint.PowerShell

Enable-SPFeature e374875e-06b6-11e0-b0fa-57f5dfd72085 –url https://contosoweb.com

Certificates

As mentioned earlier I will be using a wildcard certificate for the provider-hosted apps. But be aware! Wildcard certificates are very expensive. Use if possible self-signed certificates and only use an official wildcard certificate for your production environment. Using self-signed certificates can cause a little pain, since trusting these certificates requires additional tasks in the browser. Something you don’t want to have on your production environment, while on your development or test environment it shouldn’t be a problem.

If you are going to use self-signed certificates there are a lot of tools available to generate them. Some of these tools cause problems when using multiple self-signed certificates on the same user. My recommendation to you is using the tool MAKECERT. This tool is automatically installed with Visual Studio. If you are on a production environment you can temporarily download the Windows SDK kit to get the tool. It works great!

Run the following commands in a command line or Windows PowerShell.

 

 

This will generate a root certificate with the name “ContosoWeb Root”. The actual certificates which will be used for the websites are generated below this root certificate. You will need to give a number of parameters with the commands. These options are explained here https://msdn.microsoft.com/en-us/library/bfsktky3%28v=vs.110%29.aspx

The number given to option Eku describes the object identifier. This identifier specifies: iso(1), identified-organization(3), dod(6), internet(1), security(5), mechanisms(5), pkix(7), kp(3) and serverAuth(1). It indicates that the certificate can be used as a SSL server certificate. For more information http://www.oid-info.com/get/1.3.6.1.5.5.7.3.1

Now open a console to certificates. If you don’t know how just follow my lead.

Run the command MMC. File à Add/remove snap-in…Select “Certificates in the left column and add this one to the right. During adding select the option “Computer account” and “Local Computer”. Press the “OK” button. You will find yourself now in the screen for certificates.

You will find both certificates under Certificates (Local Computer) à Personal à Certificates. The next step will be exporting both certificates.

Click right mouse button on the certificate. Select All tasks à Export. Leave all the default settings as is and export the certificates to the following corresponding file names “apps-contosoweb-com.cer” and “contosoweb-com.cer”.

The next step is to import them again. But this time into the folder Certificates (Local Computer) à Trusted Root Certification Authorities à Certificates and Certificates (Local Computer) à SharePoint à Certificates. Importing the certificate can be done by right mouse click the folder and select All tasks à Import. The result will be as follow.

You need to place the certificates under Trusted Root Certification Authorities to prevent SSL warnings in your browser when using self-signed certificates.

Both the certificate files are needed later on when we enable SSL on the web applications.

Creating a high trust

A trust is necessary due to the fact that the provider-hosted app is hosted outside SharePoint in a separate web application. To create a high trust we need the token issuer ID from the certificate. Get the token issuer ID by double mouse click on the provider-hosted app certificate and select the second tab “Details”.

Next look for the field called “Authority Key Identifier” and click it. In the box below the properties the KeyID is shown. This is the token issuer ID we need to use for our high trust. We need to convert this value to a GUID.

KeyID = a4 88 24 4b 10 3e ae ca 2f 58 6d 30 6c d3 a0 8a becomes A488244B-103E-AECA-2F586D306CD3A08A

It is very important that the GUID is convert to upper case. If not the script we are going to use to create the high trust will fail. Run the following script to create a high trust between the provider-hosted app(s) and SharePoint.

 

 

We need to check if there is a trust relationship enabled between the domain for the provider-hosted apps and SharePoint. Open Central Administration à Security à Manage trusts to get the list of trust relationships with your SharePoint farm.

As you can see there is a trust relationship named apphost-contosoweb-com.cer and it contains the certificate issuer and to whom it is issued. In this case it is issued to the certificate which will be used for the provider-hosted app.

Create your provider-hosted app website

The next step is creating a web application for the provider-hosted app. This is done in Internet Information Services Manager. Open IIS and select the folder sites under the server name. Right mouse click and select Add Website. This dialog allows you to create an ASP.NET web application.

Give it a site name and select a folder on disk where the web application files are stored. For the binding you need to select https and port 443. Next you need to specify the host name. Our provided-hosted app is called “myapp”. So the host name becomes myapp.apphost-contosoweb.com. Since IIS 8.0 we have something called “Server Name Indication”. It is an extension of the TLS protocol and it allows you to run multiple SSL certificates on a single IP address for websites. Due to this option there is no need for additional IP addresses anymore. Our setup, especially when it runs on the same machine, needs to have this enabled. Finally we select the correct SSL certificate. This is the wildcard certificate for the domain under which our provider-hosted app is hosted.

By default Windows Authentication is not enabled for the web application. Therefore select the web application and select the option “Authentication”. Enable Windows Authentication. You are now set and ready to publish your provider-hosted app to this location.

Set the certificate for the SharePoint website

Our SharePoint website which was generated earlier does not yet have a SSL certificate binding. Select the web application in IIS and select the option “Bindings” on the right. This opens a dialog with all the bindings defined for the SharePoint website.

Select the one which has the type https. Some of the settings are already set by SharePoint during the creation of the web application through Central Administration. We only need to enable “Server Name Indication” and select the right SSL certificate. Now the SharePoint website is available through https.

Get the private key

Before we can start creating our provider-hosted app we need one more thing from certificates. We need the private key. So open again certificates and select the certificate created for the domain app-host-contosweb.com. Right mouse click à All Tasks à Export.

Select the option “Yes, export the private key”. In the second screen leave the default settings.

In the third screen you need to specify a password for the private key. Both the private key and password are necessary during provider-hosted app creation in Visual Studio. Finish the wizard and store the private key at a known location on disk.

Create your provider-hosted app

Finally we can start creating our provider-hosted app using Visual Studio. Open Visual studio and create a new project. Go to File à New à Project. Select “App for SharePoint” under the category Office/SharePoint à Apps.

Select the SharePoint site as the site which you want to use for debugging. Secondly select the type of app. In our case this is the Provider-hosted option.

In the next step select the type of web application. In our case I have chosen to create an ASP.NET Web Forms Application. It really doesn’t matter for the app.

In the last step you need to specify a certificate. We are going to run the provider-hosted app using high trust in our on-premise environment. Browse for your private key file and enter the password you entered when you exported the private key from the certificate. Finally we need to specify the issuer ID. This is the same ID we used to create the high trust. But watch out! Specify the issuer ID as a GUID in lowercase. Otherwise your app will not run. Click the Finish button to create the project.

Before we can actually publish and use the provider-hosted app some additional steps are needed. The first is opening the web.config file. In this configuration file all settings specified during the creation process of the provider-hosted app are stored. You are allowed to change these afterwards. When publishing the app to another server you need to be certain that the private key is also published there and that the reference is still valid.

The next step we need to do is changing the way how the client context is retrieved. There is no context token with high trust apps. The context token is specifically for the Windows Azure Access Control Service (ACS). We will get the client context based on the windows identity by calling the method TokenHelper.GetS2SClientContextWithWindowsIdentity.

The final step is changing the start page of the app. The app is going to be published under myapp.apphost-contosoweb.com. Therefore we change the start page as shown below.

Everything is now set to get your provider-hosted app up and running. Define a publish profile which publishes the app to the web application we have created earlier.

Deploy your app (the part with the manifest) to the SharePoint site. Run a browser and go to https://contosoweb.com. Click on the app and it will start your provider-hosted app. If everything went well your app is now running!

Conclusion

Creating provider-hosted apps is a great way of creating additional functionality for or remote provision your SharePoint environment without installing custom solutions. There are a lot of steps to be taken to accomplish using SSL certificates and the high trust between the app and SharePoint. Leaving out a step can result in not running the app correctly or even not running at all. Still I think it is not that difficult to setup an environment using provider-hosted apps in a high trust in on-premise environments. As long as you understand what you are doing you will make the right choices.

References

Some references to additional information for this article.

How to: Create high –trust apps for SharePoint 2013
https://msdn.microsoft.com/en-us/library/office/fp179901.aspx

What is Server Name Indication (SNI)?
http://www.networking4all.com/en/ssl+certificates/faq/server+name+indication/

IIS 8.0 Server Name Indication (SNI): SSL Scalability
http://www.iis.net/learn/get-started/whats-new-in-iis-8/iis-80-server-name-indication-sni-ssl-scalability

Using Google Public DNS
https://developers.google.com/speed/public-dns/docs/using