共用方式為

Creating High Trust SharePoint Apps with Microsoft Office Developer Tools for Visual Studio 2012 - Preview 2

  • 發行項

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.

Configuring the Environment for High Trust Apps

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. 

Don’t Run as the Farm Account

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.

  

High Trust Requires the User Profile Service Application

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.

  1. Go to Services on Server and make sure the User Profile Service is started.
  2. In Application Management, choose Manage Service Applications and create a new User Profile Service Application.
  3. On the Manage Profile Service: User Profile Service Application page, under People, select Manage User Profiles.
  4. On the Manage User Profiles page, select New Profiles.
  5. On the Add User Profile page, type your account name and save.

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. 

Create and Export a Certificate

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.

clip_image002

Double-click it to open the tool and choose Create Self Signed Certificate.

clip_image004

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.

image

When you click OK, you will now see your certificate.

image

Double-click on the certificate, choose the Details tab, and choose Copy to File.

image

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:

image

Click Finish and the .CER file is generated.

Next, back in IIS, right-click the certificate and choose Export.

image

Provide a file name and a password.  I chose c:\MyHighTrustCert.pfx.

image

Register the App Principal

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 "https://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
$serviceConfig.Update()

 

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.

image

Create a Provider-Hosted App in Visual Studio 2012

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.

image

Provide a name and a path to the site collection you are using for development, and change the hosting type to Provider Hosted.

image

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.

image

SO MUCH EASIER than it used to be!  Click finish, and you now have created your first high trust app for SharePoint 2013. 

Test the App

Now, it’s as easy as hitting F5 and running the app.  You might first see a dialog:

clip_image001

This is asking you if you want to trust the localhost certificate for debugging purposes.  Choose Yes, and you see a second challenge window:

clip_image001[4]

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.

image

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.

image

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.

image

Troubleshooting Tips

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.

For More Information

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

Comments

  • Anonymous
    December 24, 2012
    How to publish this in on-premise app stores (Organization app store)?

  • Anonymous
    December 24, 2012
    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.

  • Anonymous
    May 05, 2014
    I get a 401 unathuorized exception.

  • Anonymous
    July 02, 2014
    Hi Kirk 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.

  • Anonymous
    July 02, 2014
    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.

  • Anonymous
    August 10, 2014
    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?

  • Anonymous
    October 27, 2014
    The comment has been removed