Kirk Evans is a Microsoft Architect for the Azure Center of Excellence.
Introduction to SharePoint and Azure IaaS
Building SharePoint Apps with Windows Azure Platform as a Service
SharePoint Solutions and Architectures on Windows Azure Infrastructure Services
Understanding Authentication and Permissions with Apps for SharePoint and Office
This post shows how to create a High Trust app using Microsoft Office Developer Tools for Visual Studio 2012 - Preview 2 tools.
During SharePoint Conference 2012, Scott Guthrie announced the release of Microsoft Office Developer Tools for Visual Studio 2012 - Preview 2. These are the tools to add to Visual Studio 2012 to support app development for the RTM version of SharePoint 2013. There are a number of enhancements to this version of the tools over the previous preview version, and the one that I am most excited about is the enhanced tooling to support High Trust Apps for SharePoint 2013. To demonstrate this, I’ll walk through the simplest way to get up and running with high trust apps.
I assume that you are performing these steps in your on-premise SharePoint 2013 environment. Further, I assume that you already have a development environment configured. If not, you need to go read How to: Set up an on-premises development environment for apps for SharePoint and then come back here.
There is existing documentation in MSDN that shows How to: Create high-trust apps for SharePoint 2013 using the server-to-server protocol (advanced topic). That page includes a step that no longer is required for the RTM version of SharePoint 2013, namely the step to modify the registry to disable the app principal access token check. Rather than rehash that entire page, I’ll just point to that doc and tell you to skip the step for modifying the registry, it’s not needed for RTM. You need to configure app isolation and configure the User Profile Service Application.
In many developer environments, I see the environment configured where everything runs as a single account and the developer is logged in as that same account. This means that you are logged in as the farm account. Simply put, this won’t work. The farm account (also called the SHAREPOINT\SYSTEM account) cannot be used because you cannot install apps as that account. When I configure my environments, I use an account that is a local administrator on the dev machine, and a second account that is the farm account. The account you use to set up SharePoint becomes a farm administrator, and you can safely use that account for all of your development. The farm account should be a separate account from the one you are actually logged in as.
Creating a high trust app requires setting up the User Profile Service Application. The docs suggest using the farm wizard, but as good SharePoint professionals we know that the farm wizard is evil. If you haven’t configured the User Profile Service Application before, the easiest way to do this is to go into Central Administration.
Note that there is a LOT more that you can do here, such as synchronizing with existing accounts in Active Directory. I am not going to go into the details of configuring synchronization in this post, especially since Spence Harbar has already done a fantastic job of doing this in his post, Rational Guide to implementing SharePoint Server 2010 User Profile Synchronization. Note that you aren’t required to set up user profile synchronization for this to work, but you might find it helpful in your dev environment to actually configure user profile synchronization for testing purposes.
The first step to building a high trust app is to create a certificate. Let’s start with a self-signed certificate.
The first step is to create and export a certificate. I am working with Windows Server 2012, so this might look slightly different if you are using an older version of Windows. Open up IIS Manager and click on Server Certificates.
Double-click it to open the tool and choose Create Self Signed Certificate.
In that wizard, provide a name for your certificate. In Windows Server 2012, you are also asked where to store the certificate, leave the default of Personal.
When you click OK, you will now see your certificate.
Double-click on the certificate, choose the Details tab, and choose Copy to File.
In the next screen, leave the default No, do not export the private key and choose Next.
In the next screen, leave the default DER encoded binary X.509 (.CER) and choose Next.
In the next screen, provide a file name. I chose c:\MyHighTrustCert.cer. The summary page then shows our decisions:
Click Finish and the .CER file is generated.
Next, back in IIS, right-click the certificate and choose Export.
Provide a file name and a password. I chose c:\MyHighTrustCert.pfx.
The next step is to register the app principal. This differs only slightly from the MSDN documentation. Instead of using the variable name “$clientid”, I use the variable name “$issuerID”. This is to highlight that we are going to use this value in a subsequent step. The issuer ID is just a GUID, you can generate it in PowerShell using [guid]::NewGuid(). Make sure the GUID that you use is ALL LOWERCASE, you cannot use uppercase values in the GUID. Remember this value because we’ll use it in Visual Studio 2012 in just a moment.
$issuerID = "04c20e15-a964-40e1-8317-3a474b9c2b54"
$publicCertPath = "C:\MyHighTrustCert.cer"
$certificate = Get-PfxCertificate $publicCertPath
$web = Get-SPWeb "http://intranet.contosodev.com/sites/dev"
$realm = Get-SPAuthenticationRealm -ServiceContext $web.Site
$fullAppIdentifier = $issuerId + '@' + $realm
New-SPTrustedSecurityTokenIssuer -Name "My High Trust Sample App"
-Certificate $certificate -RegisteredIssuerName $fullAppIdentifier
Register-SPAppPrincipal -NameIdentifier $fullAppIdentifier -Site $web
-DisplayName "My High Trust Sample App"
$serviceConfig = Get-SPSecurityTokenServiceConfig
$serviceConfig.AllowOAuthOverHttp = $true
If you’re like me and forgot to write down that issuer ID, no problem, you can go back and find it using PowerShell with the Get-SPTrustedSecurityTokenIssuer cmdlet.
The next step is to create a provider-hosted app in Visual Studio 2012 using the new Preview 2 tools. Create a new app for SharePoint.
Provide a name and a path to the site collection you are using for development, and change the hosting type to Provider Hosted.
Don’t click Finish just yet! Click Next and you’ll see the new addition to the development tools. Here, change the option to Use a certificate. Point to the .PFX that we exported earlier, and provide the same password you used when you exported the certificate. The Issuer ID is the same GUID that you used when configuring the app principal above.
SO MUCH EASIER than it used to be! Click finish, and you now have created your first high trust app for SharePoint 2013.
Now, it’s as easy as hitting F5 and running the app. You might first see a dialog:
This is asking you if you want to trust the localhost certificate for debugging purposes. Choose Yes, and you see a second challenge window:
This is making sure that you really trust it. Trust me, just say Yes here. What it is actually doing behind the scenes is adding the certificate to the Trusted Root Certification Authorities store for the current user so that you don’t get the red bar across the URL in Internet Explorer, and makes it so your certificate can be trusted by SharePoint, allowing your app to make calls back into SharePoint.
This is a timesaver, otherwise you would have had to do this step manually. Now that the certificates have all been trusted, we continue debugging and are prompted to trust the app.
Of course, I trust it, I wrote it! Once you trust it, SharePoint redirects to your new app where you see the title of the host web.
In my environment, I kept getting an error page in IE. After spending a bunch of time trying to troubleshoot, I finally tried uninstalling and reinstalling IIS Express 8.0 using the Web Platform Installer. I haven’t yet determined if this is an error while setting up Visual Studio 2012 (which installs and configures IIS Express 8.0) or if it was isolated to my environment, but I am including this note for completeness. If you run into a problem where your provider-hosted app doesn’t even load, try creating a new ASP.NET Web Forms Application and see if you can hit its SSL endpoint. If you cannot, then try uninstalling IIS Express 8.0 and then installing it using WebPI, this worked for me.
Other troubleshooting tips are to make sure that you have the right URL for your web, and that your issuer ID is all lowercase. If you are still having problems beyond this, Steve Peschka wrote a great blog post, More TroubleShooting Tips for High Trust Apps on SharePoint 2013.
Microsoft Office Developer Tools for Visual Studio 2012 - Preview 2
Web Platform Installer
How to: Set up an on-premises development environment for apps for SharePoint
How to: Create high-trust apps for SharePoint 2013 using the server-to-server protocol (advanced topic)
Rational Guide to implementing SharePoint Server 2010 User Profile Synchronization
More TroubleShooting Tips for High Trust Apps on SharePoint 2013
How to publish this in on-premise app stores (Organization app store)?
To publish to an app catalog for your web application, register the app using the same PowerShell script in your production farm, update the app manifest, and upload the .app package to the app catalog. Your production web application will need to be configured as well with your production certificate and settings. You will also likely want to encrypt the appsettings section of your web.config because it contains the password from your certificate.
I get a 401 unathuorized exception.
I was trying to create provider hosted app for BPOS D. Do we have run Register-SPAppPrincipal for each site collection to use this app on that site collection?
And I get a 401 unauthorized exception.
Apologies, I have no experience with SharePoint Online Dedicated, although I do know that there are differences with configuring the environment for apps. Suggest you contact the service desk for more information about your environment.
Hi Kirk, Sean w/ ThreeWill here. We're working on some proof of concepts to encourage clients to begin *On-Prem* adoption of SharePoint 2013, with PHAs as the recommended architecture for customization.
I was able to get one-way authentication allowing the PHAs to call into SharePoint using the self-signed certificate method you detail here (thanks, btw!). I was not, however, able to make SharePoint happy about calling into the PHA for lifecycle events, workflow service calls, etc. For that I've had to set up a local AD-based Cert Authority. Any guesses as to why the self-signed certs weren't playing nice when SharePoint needs to call into the PHA?