How to - Set up High Trust Apps for SharePoint 2013 & Troubleshooting Tips

  • Article

SharePointers, I am back !!

This time with my experiences with the ever engrossing SharePoint 2013. Last week I was setting up High Trust Apps that uses the server-to-server (S2S) protocol. This is a Provider Hosted App deployed in a private network which eliminates the need to involve ACS for creating Authentication tokens. In essence an S2S trust represents a trusted connection between a client app running on a local app server and the web servers in the SharePoint farm.

We need to set up the S2S Security token issuer service (STS) to provide access tokens for authentication. The S2S STS creates temporary access tokens signed with your own certificate.

So, lets go ahead and see the steps needed to set up your High Trust Apps. But at the outset, please ensure that you have the below mentioned steps in place to avoid any issues.

Prerequisite Step:
  1. App Isolation set up : utilize either Configure an environment for apps for SharePoint or Setting up your App domain for SharePoint 2013 via PowerShell to set it up.
  2. Use non Farm Account (SHAREPOINT\SYSTEM) : instead use a separate Developer Account that will used for App development. Ensure this user has right set of privileges (part of local administrators group on the Developer box, right permissions set on the relevant databases etc.).
  3. User Profile Service Application set up :   shouldn’t be difficult for most folks; anyways you can refer to SharePoint 2013 - User Profile Service Application & Create, edit, or delete User Profile service applications in SharePoint Server 2013 for additional info.
Step 1: Create a Certificate

1. In the development environment you can use a self-signed certificate, but you would need a commercial certificate when you publish your Apps to store. So we will create a self signed one. In the IIS manager, click on Server Certificates.image

2. Click on Create Self Signed Certificate

image

3. Enter some meaningful name like HighTrustCert and Click on Ok.

image

4. Now we need to export the personal exchange format (.pfx) file. Right Click on the Certificate in IIS click on Export and provide an accessible location. Also enter the password that you want to use and Click on Ok 

image image

5. Next, double click on the Certificate in IIS. Click on Details tab and click on Copy to File.

image

6. Now you should see the Certificate Export Wizard (remember earlier we exported the .pfx file). The first screen elucidate the significance of what we are doing. Keep Clicking Next across the three screens. Below screenshots demonstrate the same. I keep all the default options. Just one thing to mark that now we are now exporting the .cer file. I choose the same location. Click on Save.

 imageimageimageimage

and finally, click on Finish. You should see you the message “The export was successful”.

image

7. To verify, go to your Trusted Root Certification Authorities Store  and you should see your Certificate there. If you can’t locate it, follow the first 7 steps (only) described at Adding certificates to the Trusted Root Certification Authorities store for a local computer. Remember we just need to confirm our certificate is available or not. If you are here, the battle is half won.

Step 2 : Run Windows PowerShell cmdlets to set up trusted security token service

1. Run SharePoint 2013 Management Shell as administrator. First thing first, you need an Issuer ID. Use the below PowerShell cmdlets to get one. Remember to make note of this, as we will use it later. An important point, it has to be Lowercase only.

[System.Guid]::NewGuid()

2. Run the below PowerShell cmdlets to create trusted security token service.

$issuerID = "29b0ebdd-791b-41c3-b1f7-a4152a1b7a8d"
$publicCertPath = "C:\HighTrustCert.cer"
$certificate = Get-PfxCertificate $publicCertPath
$web = Get-SPWeb "https://sp/sites/DevCenter"
$realm = Get-SPAuthenticationRealm -ServiceContext $web.Site
$fullAppIdentifier = $issuerId + '@' + $realm
New-SPTrustedSecurityTokenIssuer -Name "High Trust App" -Certificate $certificate -RegisteredIssuerName $fullAppIdentifier -IsTrustBroker
iisreset

Significance/additional info of the cmdlets

  1. issuerID : assigning the GUID generated in the previous step
  2. publicCertPath : path where I saved my .cer file.
  3. web : your Developer site URL
  4. realm : should be the same as your farm ID
  5. New-SPTrustedSecurityTokenIssuer : Just a tip, when you use the Name parameter it can be helpful to include a readable name, such as “High Trust App” or “Contoso S2S apps” instead of the issuer ID.
  6. -IsTrustBroker: this flag ensures that you can use the same certificate for other apps as well. If you don’t include this, you might receive “The issuer of the token is not a trusted issuer" error. So we have two possible approaches each having their own pros and cons .i.e. use the same certificate shared by multiple apps Or use a separate certificate for each app. Read additional details at Guidelines for using certificates in high-trust apps for SharePoint 2013
  7. iisreset : to ensure the Issuer becomes valid, else it takes 24 hours.

                   

3. Additionally you can turn off the https requirements using below PowerShell cmdlets. But ensure to turn it on by changing $true to $false in the second cmdlet below.

$serviceConfig = Get-SPSecurityTokenServiceConfig
$serviceConfig.AllowOAuthOverHttp = $true
$serviceConfig.Update()

4. Refer to the screenshot below of for the complete steps:

image

If you are here, you are almost done

Step 3 : Create a Simple “High Trust” Provider Hosted App using Visual Studio 2012

1.  Open Visual Studio 2012, under Office/SharePoint section select App for SharePoint 2013. Enter a name and click OK

image

2. Select Provider-hosted and don’t forget to Click Next (and not Finish)

image

3. Then select Use a Certificate and provide the location of your certificate .pfx file. Provide the same password as provided in sub-step 4 under Step 1.   The Issuer ID should be same as created above, under sub-step 1 of Step 2. Then Click Finish.

image

4. The App Solution should be set up with its two projects.  Since we don’t intend to do anything extravagant, if you go ahead and Hit F5. After a few seconds you should see the below screen asking whether you ‘Trust’ this App. Click Trust it.

image

5. And we are done!! You should see the title of your Developer site displayed as shown below. Yay Smile

image

6. Note that the App is right now hosted on the IIS Express.

 

Important troubleshooting tips & tricks

Each step above should not take more than 5 minutes each, if there are no issues with your environment. In case you face any issues. then follow the important tips & tricks that I have collated below which I learnt along the way. Big thanks to Kirk Evans[MSFT] for helping me with this.

  1. Make sure all the Prerequisite Steps listed at the start of the article are in place.
  2. If you run into 401 unauthorized error when running a high-trust app. Try the steps below:
  • Use the PowerShell cmdlet to get the List of all TrustedSecurityTokenIssuer in your Farm

            Get-SPTrustedSecurityTokenIssuer | select Name,RegisteredIssuerName | fl

image

  • This shows the Name, Registered Issuer Name for all registered security token issuers.  I had five of them.

  • The first one 00000005-0000-0000-c000-000000000000 is for Workflows.

  • Observe rest of the list, the correct token issuer should be of the format issuerID@Realm if you have a registration in there that’s missing the issuerID or Realm portion of the RegisteredIssuerName, you can see the 401 error. 

  • For us it is 29b0ebdd-791b-41c3-b1f7-a4152a1b7a8d@8165b002-8510-4d2d-b0f7-67b0a716a3f6. The portion before ‘@’ is our ‘issuerID’ and after is the ‘Realm’ (ref to the above screenshot).

  • The realm should be the same for any issuers that you registered manually, and it should be the same as your farm ID (use the below cmdlet to find that):

    Get-SPFarm | select Id

    And you can verify the Realm using the below cmdlet

    $spurl ="https://sp/sites/DevCenter"
    $spsite = Get-SPSite $spurl
    $realm = Get-SPAuthenticationRealm -ServiceContext $spsite
    Write $realm

  • If you see a token issuers that is not in correct format, that’s the killer and you must remove that (but don’t dare to remove the one for the workflows Smile). You can use the below PS to remove any SPTrustedSecurityTokenIssuer. Make sure to supply correct RegisteredIssuerName found above.

            Get-SPTrustedSecurityTokenIssuer | ?{$_.RegisteredIssuerName -eq "29b0ebdd-791b-41c3-b1f7-a4152a1b7a8d@8165b002-8510-4d2d-b0f7-            67b0a716a3f6"} | Remove-SPTrustedSecurityTokenIssuer 

  • You should also double-check that you are using the correct public key portion (the .CER file) for the private key (the .PFX file) that is on your app’s IIS server.  It is always worth verifying this step again. 
  • Then make sure that the issuerID that’s in the RegisteredIssuerName (before the “@” symbol) matches the value that you have in web.config. Open the web.config file of your App’s web project.

image 

  • Also navigate to the ‘Site App Permissions’ page and you will see all the App Identifier listed. Notice that your App Identifier is of the structure ClientID@Realm. Verify the clientId in the web.config (above step).;

image

  • Next, use Get-SPTrustedSecurityTokenIssuer and look at the certificate thumbprint for your issuer and compare it with the thumbprint of the certificate you used in PowerShell.

image

     3. I would recommend reviewing these blogs as well:

 

That was a lot of info, I'm gonna call it a day!

Cheers!